permits-lib/AGENT.md

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 で定義

permissions:
  myplugin.fly:
    description: "Allow /fly"
    default: op

(2) コードで動的に定義

Permission perm = new Permission("myplugin.fly", "Allow fly", PermissionDefault.OP);
getServer().getPluginManager().addPermission(perm);

---

3. 動的付与（PermissionAttachment）

PermissionAttachment の役割

• 特定プレイヤーに対して一時的に権限を上書きする仕組み。
• 未定義の権限ノードでも自由に付与できる。

PermissionAttachment attachment = player.addAttachment(plugin);
attachment.setPermission("myplugin.fly", true);

特徴

• 未定義ノードでも player.hasPermission("xxx") が true になる。
• default や children などのメタ情報は存在しない。
• サーバー再起動やログアウトで消える一時的な扱い。

---

4. Children（子権限）

概要

• 「ある権限を true にした時、自動的に他の権限も true にする仕組み」。

permissions:
  myplugin.admin:
    children:
      myplugin.fly: true
      myplugin.kick: true

挙動

• myplugin.admin を持つプレイヤーは → myplugin.fly と myplugin.kick も自動的に所持。
• 再帰的に適用され、深い階層の権限にも影響する。
• false を設定した場合は「明示的に無効」にできる。

動的 Permission に対しても有効

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