98 lines
7.0 KiB
Markdown
98 lines
7.0 KiB
Markdown
# Paper における Dialog（ダイアログ）機能の使用 — ドキュメント
|
||
|
||
## 🎯 概要
|
||
|
||
* Dialog 機能は、Minecraft Java Edition 1.21.6 で導入された「画面中央に出すモーダル UI（メニュー／入力フォーム／確認ダイアログなど）」をサーバー／プラグイン側から出せる仕組み。([PaperMC Docs][1])
|
||
* Paper は 1.21.7 から **Dialog API** を提供し、プラグインから動的にダイアログを生成・表示できるようになっている。([PaperMC Docs][1])
|
||
* これは実験的機能（Experimental）扱い。今後仕様変更の可能性があることに注意。([PaperMC][2])
|
||
|
||
---
|
||
|
||
## ✅ Dialog API の主要機能
|
||
|
||
* サーバー／プラグインから任意のダイアログを生成・表示可能。([PaperMC Docs][1])
|
||
* 標準で「通知／確認ダイアログ」「複数アクション付きダイアログ」「リスト型ダイアログ」「サーバーリンクダイアログ」などが提供されている。([PaperMC][2])
|
||
* プレイヤーに表示する方法は主に二通り：
|
||
|
||
1. コマンド経由 — `/dialog show <players> <dialog>` ([PaperMC Docs][1])
|
||
2. API 経由 — `Audience#showDialog(Dialog)` を使った直接呼び出し ([PaperMC Docs][1])
|
||
* 動的生成も可能：`Dialog.create(...)` を通じて、コードでダイアログ内容を構築 → 表示。([PaperMC][5])
|
||
|
||
---
|
||
|
||
## 🧩 API の構成 — 主なクラス／インターフェース
|
||
|
||
| パッケージ / クラス | 概要 |
|
||
| ----------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||
| `io.papermc.paper.dialog.Dialog` | ダイアログ本体を表すクラス／インターフェース。Registry に登録されたダイアログも、動的生成ダイアログも扱える。([PaperMC][5]) |
|
||
| `io.papermc.paper.registry.data.dialog.type.DialogType` | ダイアログの「型」を示す (例: notice, confirmation, multi-action, list など) ([PaperMC][2]) |
|
||
| `io.papermc.paper.registry.data.dialog.body.DialogBody` | ダイアログ本体に表示する内容（テキスト、アイテム表示など） |
|
||
| `io.papermc.paper.registry.data.dialog.input.DialogInput` | 入力コントロール (テキスト入力、選択肢、トグルなど) を定義可能。([PaperMC][6]) |
|
||
| `io.papermc.paper.registry.data.dialog.action.DialogAction` | ダイアログのボタン押下等で実行されるアクション (コマンド実行、カスタムコード、別ダイアログ呼び出し etc.) を定義。([Daydream][7]) |
|
||
| `DialogBase` / `DialogBase.Builder` | ダイアログの基本情報（タイトル、外部タイトル、閉じられるか、表示後の動作など）を構築する。([PaperMC][6]) |
|
||
|
||
---
|
||
|
||
## 🔧 サンプルコード（Java） — シンプルな Notice ダイアログ
|
||
|
||
```java
|
||
import io.papermc.paper.dialog.Dialog;
|
||
import io.papermc.paper.dialog.DialogResponseView;
|
||
import io.papermc.paper.registry.data.dialog.type.DialogType;
|
||
import net.kyori.adventure.text.Component;
|
||
import org.bukkit.entity.Player;
|
||
|
||
public void showNotice(Player player) {
|
||
Dialog dialog = Dialog.create(builder -> builder
|
||
.empty()
|
||
.base(DialogBase.builder(Component.text("重要なお知らせ")).build())
|
||
.type(DialogType.notice())
|
||
);
|
||
|
||
player.showDialog(dialog);
|
||
}
|
||
```
|
||
|
||
このコードは、タイトルだけの「OK ボタン付き通知ダイアログ」をプレイヤーに表示します。([PaperMC Docs][1])
|
||
|
||
---
|
||
|
||
## ⚠️ 注意点・既知の制限
|
||
|
||
* Dialog API は現時点で実験的 (`@Experimental`)。仕様や挙動が今後変わる可能性あり。([PaperMC][2])
|
||
* click イベントでダイアログを開く機能 (`ClickEvent.openDialog`) や、クリック時のカスタムアクション (`DialogAction.customClick`) を使えるが、後者は **メモリリークの恐れ** が指摘されている。特にコールバックを登録したままプレイヤーが離脱したりダイアログを閉じても無効化されず、リソースが解放されない可能性。([GitHub][8])
|
||
* クライアント側も Minecraft 1.21.6 以降である必要がある。古いクライアントではダイアログが正しく表示されない。これは、そもそも Dialog 機能自体がバニラ 1.21.6 からの新仕様。([PaperMC Docs][1])
|
||
|
||
---
|
||
|
||
## ✅ 利用例・応用用途
|
||
|
||
Paper サーバー + Dialog API を利用すると、以下のような用途に適している：
|
||
|
||
* サーバー参加時の規約同意画面、ウェルカム画面
|
||
* ミニゲームやワールド生成時の設定フォーム（オプション選択など）
|
||
* サーバー内メニュー、クイックアクション、サーバーリンク一覧
|
||
* NPC／テレポート／ワールド選択など、インタラクティブなメニュー
|
||
* 入力フォーム（テキスト、選択肢、トグルなど）を用いたカスタムフォーム
|
||
|
||
また、既存のプラグインライブラリとして FancyDialogs のようなものもあり、JSON 形式やコードでダイアログを定義できる。([Hangar][9])
|
||
|
||
---
|
||
|
||
## 📚 参考リソース
|
||
|
||
* Paper Dialog API ドキュメント — 「Dialog API」セクション (docs.papermc.io) ([PaperMC Docs][1])
|
||
* Javadoc — `io.papermc.paper.dialog`, `io.papermc.paper.registry.data.dialog.*` パッケージ群 ([PaperMC][5])
|
||
* 使用例プラグイン FancyDialogs (GitHub / Hangar) ([Hangar][9])
|
||
* 警告: callback 系 API のメモリリーク問題に関する issue #13236 ([GitHub][8])
|
||
|
||
[1]: https://docs.papermc.io/paper/dev/dialogs/?utm_source=chatgpt.com "Dialog API"
|
||
[2]: https://jd.papermc.io/paper/1.21.8/io/papermc/paper/registry/data/dialog/type/package-summary.html?utm_source=chatgpt.com "Package io.papermc.paper.registry.data.dialog.type - Javadocs"
|
||
[3]: https://papermc.io/news/1-21-7/?utm_source=chatgpt.com "1.21.7"
|
||
[4]: https://github.com/PaperMC/Paper?utm_source=chatgpt.com "PaperMC/Paper: The most widely used, high performance ..."
|
||
[5]: https://jd.papermc.io/paper/1.21.7/io/papermc/paper/dialog/class-use/Dialog.html?utm_source=chatgpt.com "Uses of Interface io.papermc.paper.dialog.Dialog - Javadocs"
|
||
[6]: https://jd.papermc.io/paper/1.21.10/io/papermc/paper/registry/data/dialog/DialogBase.html?utm_source=chatgpt.com "DialogBase (paper-api 1.21.10-R0.1-SNAPSHOT API)"
|
||
[7]: https://daydream.caramel.moe/io/papermc/paper/registry/data/dialog/action/package-summary.html?utm_source=chatgpt.com "Package io.papermc.paper.registry.data.dialog.action"
|
||
[8]: https://github.com/PaperMC/Paper/issues/13236?utm_source=chatgpt.com "Callback API can quickly lead to memory leaks #13236"
|
||
[9]: https://hangar.papermc.io/Oliver/FancyDialogs?utm_source=chatgpt.com "FancyDialogs - Minecraft Plugin - Hangar"
|