godot-dialogue-system

Dialogue System

データ駆動型のダイアログルーティング。初心者向けのタイプライター式チュートリアルではありません。

ダイアログシステムで絶対にしてはいけないこと

• ダイアログテキストを GDScript にハードコードしてはいけません — ローカライズできるよう、テキストは Resources / JSON / CSV に保存してください。
• プレイヤーがまだアンロックしていない選択肢を表示してはいけません — 条件付きの選択肢は非表示にするか、意図的にグレーアウトしてください。
• ノード遷移に、検証されていない任意の文字列を使ってはいけません — next_node_id の誤字は会話中に進行不能を引き起こします。ID をアサートするか、レジストリーで管理してください。
• スキップできないタイプライター演出を強制してはいけません — クリック／決定操作で、行の全文をすぐに表示できるようにしてください。
• 文字ごとの Timer / OS.delay_msec() でテキストの表示を制御してはいけません — visible_ratio / visible_characters と Tween を使用してください（typebox_effect.gd を参照）。
• ダイアログカーソルの状態を UI ノードだけに保存してはいけません — シーン変更でプレイヤーの進行状況が失われます。進行状況はマネージャーの Autoload / セッションオブジェクトに保持してください。
• NPC から Dialogue UI に get_node() でアクセスしてはいけません — マネージャーのシグナル（start_dialogue(res)）経由で開始してください。
• BBCode 用の正規表現を独自に作ってはいけません — RichTextLabel BBCode / カスタムエフェクトを優先してください。
• ダイアログノード Resource 内でセーブ／ロードしてはいけません — ノードはデータです。永続化は SaveSystem の役割です。
• ポートレートのパスをコードにハードコードしてはいけません — ノード Resources またはポートレートデータベースにテクスチャを割り当ててください。

---

判断フローチャート：制作エンジン

制作上の要件	エンジン	必須スクリプト	読み込まないもの
リポジトリ内でデザイナーが扱いやすい .tres グラフ	Resource Autoload graph	dialogue_resource.gd → dialogue_manager_singleton.gd → dialogue_ui_controller.gd → typebox_effect.gd	dialogue_engine.gd の JSON パス
外部ライター／スプレッドシート → JSON	JSON graph engine	dialogue_engine.gd（＋任意で dialogue_manager.gd）→ UI + typebox	Resource Autoload スタック
プロジェクト内のビジュアルノードエディター	GraphEdit authoring	ランタイムは Resource または JSON エクスポートを使用してください。GraphEdit はエディター専用ツールです	ランタイムのウォーカーとして GraphEdit を出荷すること
条件／クエストのゲート	どちらでも可	branching_condition_validator.gd	UI ボタン内にフラグチェックを埋め込むこと
ポートレート／表情	どちらでも可	dialogue_portrait_manager.gd	—
ローカライズキー	どちらでも可	localized_dialogue_resource.gd	言語ごとの if ツリーのハードコード
セリフからのクエスト／ゲームプレイフック	どちらでも可	dialogue_event_bridge.gd	UI コントローラー内の副作用

デフォルトの推奨構成： Resource Autoload → UI controller → typebox_effect。ランタイムエンジンは1 つだけ選び、Resource マネージャーと JSON エンジンを並行稼働させないでください。

利用可能なスクリプト（全カタログ）

ランタイム（推奨構成）

• dialogue_resource.gd — 会話ツリー Resource
• dialogue_node_data.gd — 1 行分のセリフ／話者／ポートレートのメタデータ
• dialogue_option_data.gd — 選択肢 + 条件
• dialogue_manager_singleton.gd — 必須 Autoload ウォーカー + シグナル
• dialogue_ui_controller.gd — 必須 ラベル／選択肢ボタン
• typebox_effect.gd — 必須 スキップ可能な Tween visible_ratio 表示

補助

• dialogue_event_bridge.gd — ノードからゲームプレイイベントを発火
• branching_condition_validator.gd — フラグ／ステータスの条件
• localized_dialogue_resource.gd — 翻訳キー
• dialogue_portrait_manager.gd — 表情の切り替え

代替エンジン（判断ツリーで指示された場合のみ読み込みます）

• dialogue_engine.gd — JSON グラフと BBCode [trigger:] タグ
• dialogue_manager.gd — データ駆動型の代替ウォーカー
• dialogue_graph_editor.gd — @tool の GraphEdit 監査ツール（エディター専用）
• dialogue_lipsync.gd — TTS 境界用リップシンクヘルパー
• dialogue_stat_logger.gd — 選択肢分析用 Logger

タイプライターの契約（スキップ対応）

typebox_effect.gd を使用します。text 全体を設定し、visible_ratio（または RichTextLabel の visible_characters）を 0→1 にトゥイーンします。スキップ入力があったら、トゥイーンを停止し、表示を完了状態にします。文字ごとに Timer を生成しないでください。

エリート向けの追加事項

• GraphEdit 監査ツール： dialogue_graph_editor.gd（@tool） — 実行時向けに Resource/JSON へエクスポートします。
• 音声駆動のセリフ： dialogue_lipsync.gd — TTS の境界に対応します。スキップも引き続き可能にしてください。
• 分析： dialogue_stat_logger.gd — [CHOICE] ログプレフィックスを使用します。個人を特定できる情報は含めません。

GraphEdit ツール、TTS/リップシンク、分析、移動したインラインのマネージャー/UI チュートリアルでは、elite-dialogue-patterns.md が必須です。Resource Autoload のゴールデンパスのみの場合は読み込まないでください。

リファレンス

段階的開示：特定の API を調べる場合にのみ公式ドキュメントのリンクを開き、関連分野へ振り分ける場合にのみ関連スキルを読み込みます。関連スキル全体を事前に読み込まないでください。

公式ドキュメント

• リソース — 対話グラフをスクリプト内のハードコードされた文字列ではなく、Resource / .tres データとして扱う理由。
• RichTextLabel の BBCode — 独自パーサーを作成せずに、話者の強調、カスタムタグ、エフェクトを実現するネイティブのマークアップ。
• RichTextLabel — タイプライター表示やポートレートのために、対話 UI が制御する visible_characters / 画像ヘルパーと BBCode API。
• ゲームの国際化 — 各ロケールでセリフのテキストをキーで管理するための tr() / TranslationServer ワークフロー。
• スプレッドシートを使ったローカライズ — 対話の text_key フィールドに対応させやすい CSV 翻訳テーブル。
• 翻訳のインポート — ローカライズされた対話リソースを実行時に解決できるよう、Godot が CSV/PO をインポートする方法。
• シグナルの使用 — 行／選択肢／終了イベントを上位へ送信し、UI、クエスト、音声がマネージャー内部を直接参照しないようにします。
• シングルトン（Autoload） — シーン変更後も存続し、進行状態を管理する DialogueManager を登録します。
• Tween — メインスレッドをブロックせずに、visible_ratio / 文字の表示タイミングを制御します。
• テキスト読み上げ — 仮の VO やリップシンクに関連するタイミングに使う DisplayServer の TTS コールバック。
• GraphEdit — .tres のリストが扱いにくくなった場合に、分岐する対話グラフを作成するエディター画面。
• JSON — Resource より JSON を好むデザイナー向けに、外部の対話グラフファイルを解析します。

関連スキル

前提条件

• godot-project-foundations — オートロードの登録、進行／スキップ用の入力、会話 UI シーンを組み込むプロジェクト構成です。
• godot-gdscript-mastery — 分岐エンジンや UI ブリッジを構築する前に、型付き Resource、シグナル、await、Callable が必要です。
• godot-resource-data-patterns — DialogueLine／グラフ Resource、エクスポート、変更可能な状態の重複を避けるための標準的なパターンです。
• godot-autoload-architecture — シーン切り替え後も存続するグローバルな DialogueManager のための、シングルトンの所有権と起動順序です。

補完項目

• godot-signal-architecture — line_displayed、選択肢の選択、ナラティブイベントブリッジにおける、シグナルで上げて呼び出しで下ろす契約です。
• godot-ui-rich-text — タイプライター UI で使う基本機能を超えた、RichTextLabel の BBCode、カスタムエフェクト、画像の埋め込みです。
• godot-ui-containers — Control のサイズ調整やフォーカスとの兼ね合いに悩まずに、選択肢ボタンや会話パネルをレイアウトできます。
• godot-tweening — キャラクターの表示、ポートレートの登場、パネルの遷移に使える、スキップに対応した Tween です。
• godot-audio-systems — ボイスラインのプレーヤー、会話中のバスダッキング、音声と字幕の同期です。
• godot-quest-system — 条件付き選択肢を制御し、会話イベントブリッジから発火させるクエストフラグと目標です。
• godot-save-load-systems — 会話フラグ／既読ノードの状態を UI ノードの外部に保存し、再読み込み後も進行状況を維持します。

下流／利用側

• godot-genre-visual-novel — 完全なビジュアルノベルの演出ループで、このスキルのグラフ探索、ポートレート、選択肢 UI のパターンを利用します。
• godot-inventory-system — 会話の効果でアイテムを付与／要求することがよくあります。付与ロジックはライン Resource 内ではなく、インベントリに置いてください。
• godot-monte-carlo-balancer — ナラティブの条件や報酬経路のバランス調整が必要な場合に、スキルチェック／分岐する選択肢のツリーをシミュレーションします。

マスター

• godot-master — ライブラリのルーターおよび対応するモジュールのエントリです。ナラティブ、UI、クエストの懸念事項をどのドメインスキルが担当しているか確認するときに開いてください。