# 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` → 配下の権限をまとめて管理できる