Shop/dialog_texh.md

Paper における Dialog（ダイアログ）機能の使用 — ドキュメント

🎯 概要

• Dialog 機能は、Minecraft Java Edition 1.21.6 で導入された「画面中央に出すモーダル UI（メニュー／入力フォーム／確認ダイアログなど）」をサーバー／プラグイン側から出せる仕組み。(PaperMC Docs)
• Paper は 1.21.7 から Dialog API を提供し、プラグインから動的にダイアログを生成・表示できるようになっている。(PaperMC Docs)
• これは実験的機能（Experimental）扱い。今後仕様変更の可能性があることに注意。(PaperMC)

---

✅ Dialog API の主要機能

• サーバー／プラグインから任意のダイアログを生成・表示可能。(PaperMC Docs)

• 標準で「通知／確認ダイアログ」「複数アクション付きダイアログ」「リスト型ダイアログ」「サーバーリンクダイアログ」などが提供されている。(PaperMC)

• プレイヤーに表示する方法は主に二通り：

  1. コマンド経由 — /dialog show <players> <dialog> (PaperMC Docs)
  2. API 経由 — Audience#showDialog(Dialog) を使った直接呼び出し (PaperMC Docs)

• 動的生成も可能：Dialog.create(...) を通じて、コードでダイアログ内容を構築 → 表示。(PaperMC)

---

🧩 API の構成 — 主なクラス／インターフェース

パッケージ / クラス	概要
io.papermc.paper.dialog.Dialog	ダイアログ本体を表すクラス／インターフェース。Registry に登録されたダイアログも、動的生成ダイアログも扱える。(PaperMC)
io.papermc.paper.registry.data.dialog.type.DialogType	ダイアログの「型」を示す (例: notice, confirmation, multi-action, list など) (PaperMC)
io.papermc.paper.registry.data.dialog.body.DialogBody	ダイアログ本体に表示する内容（テキスト、アイテム表示など）
io.papermc.paper.registry.data.dialog.input.DialogInput	入力コントロール (テキスト入力、選択肢、トグルなど) を定義可能。(PaperMC)
io.papermc.paper.registry.data.dialog.action.DialogAction	ダイアログのボタン押下等で実行されるアクション (コマンド実行、カスタムコード、別ダイアログ呼び出し etc.) を定義。(Daydream)
DialogBase / DialogBase.Builder	ダイアログの基本情報（タイトル、外部タイトル、閉じられるか、表示後の動作など）を構築する。(PaperMC)

---

🔧 サンプルコード（Java） — シンプルな Notice ダイアログ

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)

---

⚠️ 注意点・既知の制限

• Dialog API は現時点で実験的 (@Experimental)。仕様や挙動が今後変わる可能性あり。(PaperMC)
• click イベントでダイアログを開く機能 (ClickEvent.openDialog) や、クリック時のカスタムアクション (DialogAction.customClick) を使えるが、後者は メモリリークの恐れ が指摘されている。特にコールバックを登録したままプレイヤーが離脱したりダイアログを閉じても無効化されず、リソースが解放されない可能性。(GitHub)
• クライアント側も Minecraft 1.21.6 以降である必要がある。古いクライアントではダイアログが正しく表示されない。これは、そもそも Dialog 機能自体がバニラ 1.21.6 からの新仕様。(PaperMC Docs)

---

✅ 利用例・応用用途

Paper サーバー + Dialog API を利用すると、以下のような用途に適している：

• サーバー参加時の規約同意画面、ウェルカム画面
• ミニゲームやワールド生成時の設定フォーム（オプション選択など）
• サーバー内メニュー、クイックアクション、サーバーリンク一覧
• NPC／テレポート／ワールド選択など、インタラクティブなメニュー
• 入力フォーム（テキスト、選択肢、トグルなど）を用いたカスタムフォーム

また、既存のプラグインライブラリとして FancyDialogs のようなものもあり、JSON 形式やコードでダイアログを定義できる。(Hangar)

---

📚 参考リソース

• Paper Dialog API ドキュメント — 「Dialog API」セクション (docs.papermc.io) (PaperMC Docs)
• Javadoc — io.papermc.paper.dialog, io.papermc.paper.registry.data.dialog.* パッケージ群 (PaperMC)
• 使用例プラグイン FancyDialogs (GitHub / Hangar) (Hangar)
• 警告: callback 系 API のメモリリーク問題に関する issue #13236 (GitHub)