KPM 情報ファイル （ kpm.yml ）
このページでは、 KPM 情報ファイルついて説明しています。
概要
KPM 情報ファイルは、プラグインについての注釈をKPM に与える機能です。プラグインの開発者が、自分のプラグインに埋め込んで使用します。
これにより、依存関係の適切な解決を行ったリ、サーバに未対応なプラグインのロードを防げます。
KPM 情報ファイルのスキーマ
KPM 情報ファイルの JSON スキーマはこちら から入手できます。 エディタ等でこのスキーマをインポートして使用してください。
KPM 情報ファイルを記述する
ステップ１： kpm.yml を作成する
プラグインのビルドのリソースディレクトリ直下に、 kpm.yml を作成します。通常、 src/main/resources/kpm.yml に作成します。
ビルドの成果物の直下に kpm.yml が配置される構成であれば問題ありません。
ステップ２： 必須 - KPM のバージョンを記述する
KPM 情報ファイルには、対応する KPM のバージョンの記述が必須です。 以下の機能早見表をもとに、対応する KPM のバージョンを記述してください。
| バージョン | リリース日 | 機能 |
|---|---|---|
| 3.0.0 | 2023/0X/0X | KPM 情報ファイル / KPM フック |
上の表に掲載されていないバージョンも記述可能です.
サーバにある KPM のバージョンが設定よりも低い場合、そのプラグインの読み込みはブロックされるか、インストール時に警告が表示されます。 また、バージョンの指定は Semantic Versioning に従ってください。
悪い例： v3, 3.0
KPM は後方互換性を保証しています。そのため、3.0.0 と記述した場合、 3.0.0 以上のバージョンの KPM であれば、プラグインは正常に読み込まれます。
kpm: "v3.0.0"
ステップ３： 任意 - プラグインの取得元を記述する
KPM を使用してプラグインを自動でアップデートするためには、プラグインを取得するためのクエリを記述します。
kpm: "v3.0.0"
update: "github>TeamKUN/ExamplePlugin"
以下の条件を全て満たす場合は、自動で取得元が特定されるため記述する必要はありません：
- TeamKUN の GitHub に公開されているプラグイン
- プラグイン名と GitHub のリポジトリ名が一致している
ステップ4： 任意 - 追加の KPM 情報を記述する
他に必要な情報がある場合、こちらを参考に必要な情報を記述してください。
KPM 情報ファイルに含められる情報
KPM 情報ファイルは kpm.yml という名前の YAML ファイルです。
KPM 情報ファイルの記述法やチュートリアルは、こちらを参照してください。
KPM 情報ファイルは、プラグインのルートディレクトリに配置してください。
また、名前は kpm.yml のみを受け入れます。
対応する KPM バージョン
プラグインがサーバの KPM に存在しない機能を使用している可能性を排除するために、KPM 情報ファイルには KPM のバージョンの指定が必須です。
KPM 版の Bukkit の api-version のようなものです。
サーバにある KPM のバージョンが設定よりも低い場合、そのプラグインの読み込みはブロックされるか、インストール時に警告が表示されます。 また、バージョンの指定は Semantic Versioning に従ってください。
悪い例： v3, 3.0
KPM は後方互換性を保証しています。そのため、3.0.0 と記述した場合、 3.0.0 以上のバージョンの KPM であれば、プラグインは正常に読み込まれます。
例
kpm: v3.0.0
プラグインの解決クエリ
プラグインのアップグレードを自動で行うために、 そのプラグインの解決クエリを指定できます。
例
# ...
update: "github>TeamKUN/TeamKUNPluginManager"
# ...
依存先プラグインの解決クエリ
依存関係を適切に解決するために、依存先プラグインの解決クエリを指定できます。この項目は任意です。
dependencies オブジェクトに、キーに依存先プラグインの名前、値にそのプラグインの解決クエリを指定します。
また、ここで指定しなくてもプラグインを解決できる場合は、明示的に記述する必要はありません。（エイリアスに登録されている場合など）
ですが、様々なサーバの環境に対応するために、使用する依存関係のクエリを明示的にすることをおすすめします。
例
# ...
dependencies:
ExamplePlugin: "github>TeamKUN/ExamplePlugin"
ExamplePlugin2: "github>TeamKUN/ExamplePlugin2"
# ...
KPM Hook リスナ
KPM Hook を受け取るリスナを登録します。KPM Hook は、プラグインのインストール時、アンインストール時等に呼び出されるコードのことです。
これを利用することで、対応したイベントの発生時にあなたのプラグインの任意コードを実行できます。
登録をするには、 Hook を作成し kpm.yml に フックリスナの完全修飾クラス名を記述します。
詳しくは以下のドキュメントを参照してください：
例
# ...
hooks:
- "net.kunmc.lab.example.ExampleKPMHooKListener"
# ...
プラグインのカスタムレシピ
プラグインが登録した（登録する予定の）カスタムレシピを指定します。
これを指定すると、プラグインが登録したカスタムレシピを KPM が認識し、アンインストール時に適切に削除します。
レシピの名前空間とプラグイン名が（大小問わず）同一である場合、KPM は既にそのレシピを認識しています。そのため、ここで明示的に登録する必要はありません。
これには、 new NamespacedKey(<Plugin インスタンス>, "<レシピ名>") で作成したレシピも含まれます。
カスタムレシピの指定には、以下の方式があります：
- 完全修飾名で指定する
Minecraft の
名前空間名:レシピ名(NamespacedKey) で指定します。
例： example:example_recipe
- レシピ名のみで指定する レシピ名のみで指定する場合、そのレシピ名を持つ全ての名前空間のレシピが対象となります。
例： example_recipe
- 名前空間名のみで指定する 名前空間名のみで指定する場合、その名前空間の全てのレシピが対象となります。
例： example_space
例
# ...
recipes:
- "example:example_recipe"
- "example_recipe"
- "example_namespace"
# ...
プラグインの手動インストールの禁止
プラグインを手動でインストールできないようにします。