137 lines
3.2 KiB
Markdown
137 lines
3.2 KiB
Markdown
# Paper / Bukkit Permission システム解説ドキュメント
|
||
|
||
## 1. 基本概念
|
||
|
||
### Permission（権限ノード）
|
||
- プレイヤーが「何を実行できるか」を判定するための文字列。
|
||
- 例: `myplugin.fly`, `myplugin.home.set`
|
||
- 権限ノードには以下の情報を持てる。
|
||
- 説明文（description）
|
||
- デフォルト値（default: OP / non-OP / true / false）
|
||
- 子権限（children）
|
||
|
||
Paper/Bukkit は `plugin.yml` またはコードによる動的生成で権限を登録できる。
|
||
|
||
---
|
||
|
||
## 2. 権限の定義方法
|
||
|
||
### (1) `plugin.yml` で定義
|
||
|
||
```yaml
|
||
permissions:
|
||
myplugin.fly:
|
||
description: "Allow /fly"
|
||
default: op
|
||
````
|
||
|
||
### (2) コードで動的に定義
|
||
|
||
```java
|
||
Permission perm = new Permission("myplugin.fly", "Allow fly", PermissionDefault.OP);
|
||
getServer().getPluginManager().addPermission(perm);
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 動的付与（PermissionAttachment）
|
||
|
||
### PermissionAttachment の役割
|
||
|
||
* 特定プレイヤーに対して一時的に権限を上書きする仕組み。
|
||
* **未定義の権限ノードでも自由に付与できる**。
|
||
|
||
```java
|
||
PermissionAttachment attachment = player.addAttachment(plugin);
|
||
attachment.setPermission("myplugin.fly", true);
|
||
```
|
||
|
||
### 特徴
|
||
|
||
* 未定義ノードでも `player.hasPermission("xxx")` が true になる。
|
||
* default や children などのメタ情報は存在しない。
|
||
* サーバー再起動やログアウトで消える一時的な扱い。
|
||
|
||
---
|
||
|
||
## 4. Children（子権限）
|
||
|
||
### 概要
|
||
|
||
* 「ある権限を true にした時、自動的に他の権限も true にする仕組み」。
|
||
|
||
```yaml
|
||
permissions:
|
||
myplugin.admin:
|
||
children:
|
||
myplugin.fly: true
|
||
myplugin.kick: true
|
||
```
|
||
|
||
### 挙動
|
||
|
||
* `myplugin.admin` を持つプレイヤーは
|
||
→ `myplugin.fly` と `myplugin.kick` も自動的に所持。
|
||
* 再帰的に適用され、深い階層の権限にも影響する。
|
||
* false を設定した場合は「明示的に無効」にできる。
|
||
|
||
### 動的 Permission に対しても有効
|
||
|
||
```java
|
||
perm.getChildren().put("myplugin.fly", true);
|
||
perm.recalculatePermissibles();
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Permission 判定の仕組み
|
||
|
||
`player.hasPermission("xxx")` の評価順序:
|
||
|
||
1. **PermissionAttachment のフラグ**
|
||
2. 登録済 Permission の children
|
||
3. Permission の default 値（OP / non-OP など）
|
||
4. 上記に該当しなければ false
|
||
|
||
attachment が最優先で反映される。
|
||
|
||
---
|
||
|
||
## 6. 未定義権限ノードの扱い
|
||
|
||
### 特徴
|
||
|
||
* 未定義でも `attachment.setPermission("xxx", true)` で有効化可能。
|
||
* ただし:
|
||
|
||
* children なし
|
||
* default なし
|
||
* description なし
|
||
* 権限管理プラグインで見づらい
|
||
|
||
### 必要に応じて動的登録を使う
|
||
|
||
体系的な管理が必要なら PluginManager で正式な Permission を登録することを推奨。
|
||
|
||
---
|
||
|
||
## 7. 推奨される運用方法
|
||
|
||
### (A) 権限の種類を柔軟に変更したい
|
||
|
||
→ **動的 Permission 定義**
|
||
|
||
* config.yml → 起動/リロード時に生成
|
||
|
||
### (B) プレイヤーごとの一時的な権限管理
|
||
|
||
→ **PermissionAttachment**
|
||
|
||
* 一時バフ的な権限付与に向く
|
||
|
||
### (C) 大規模な権限構造
|
||
|
||
→ **children の階層化**
|
||
|
||
* `myplugin.admin` → 配下の権限をまとめて管理できる
|