godot-genre-visual-novel

ジャンル：ビジュアルノベル

分岐する物語、意味のある選択肢、快適にプレイするための機能がビジュアルノベルの特徴です。

基本のゲームループ

1. 読む → セリフ／ナレーション
2. 決める → 選択の場面
3. 分岐する → フラグまたはルートの変更
4. 結果が生じる → 直後のセリフの変化、および／または持続するフラグ
5. 結末を迎える → 複数あるエンディングのいずれか

絶対に避けること（上級者向けアンチパターン）

物語と進行

• 「選択の錯覚」だけで済ませることは絶対に避けてください。後で物語が合流する場合でも、直後のセリフの変化またはフラグの変更を必ず設けてください。
• 必須の快適機能を省略することは絶対に避けてください。リプレイ性を高めるため、オートプレイ、早送り、バックログ／履歴を必ず実装してください。
• 「テキストの壁」を表示することは絶対に避けてください。読者を圧倒しないよう、セリフボックスは最大3～4行にしてください。
• GDScript にセリフを直接ハードコードすることは絶対に避けてください。調整しやすいよう、物語のスクリプトは必ず外部ファイル（JSON、CSV、またはカスタム Resource）に保存してください。
• ロールバックの仕組みを無視することは絶対に避けてください。プレイヤーが誤クリックを取り消したり、読み飛ばしたセリフを読み返したりできるよう、必ず履歴スタックを維持してください。

技術と UI

• 感情的な場面にプレーンテキストを使うことは絶対に避けてください。視覚的な効果を加えるため、必ず RichTextLabel BBCode（例：[shake]、[wave]）を使用してください。
• 大きな物語ファイルをメインスレッドで解析することは絶対に避けてください。遷移時のカクつきを防ぐため、必ず ResourceLoader.load_threaded_request() を使用してください。
• 頻繁に参照するゲームフラグに通常の String を使うことは絶対に避けてください。辞書の検索を高速化するため、必ず StringName（&"met_alice"）を使用してください。
• 1文字ずつ表示するアニメーションに _process を使うことは絶対に避けてください。滑らかでフレームレートに依存しない表示には、必ず visible_ratio を Tween でアニメーションさせてください。
• キャラクターの描画順をおろそかにすることは絶対に避けてください。視覚的に分かりやすくなるよう、アクティブな話者を必ず前面に表示してください。
• 入力処理が必要な場合に、Control ノードの優先順位を z_index で制御することは絶対に避けてください。描画順と入力伝播を一致させるため、必ず move_to_front() を使用してください。
• キャラクタースプライトの位置を絶対ピクセル値で指定することは絶対に避けてください。画面サイズに応じて拡大縮小できるよう、必ず アンカーとパーセントベースのオフセットを使用してください。
• プレイヤーがスキップしている間もテキストアニメーションを続けることは絶対に避けてください。入力があったら、必ず即座に visible_ratio を 1.0 に設定してください。
• キャラクタースプライトを孤立させたままにすることは絶対に避けてください。メモリリークを防ぐため、アクターがステージを退出したときは必ず queue_free() を使用してください。
• ロールバック状態をスナップショットする前にフラグを変更することは絶対に避けてください。必ず履歴を追加してから選択肢を適用してください。

---

🛠 上級コンポーネント（scripts/）

アンドゥ／分岐／演出を実装する前に必ず確認してください：

1. vn_rollback_manager.gd — 履歴スタック（フラグ／背景／インデックス）
2. story_manager.gd — フラグを考慮したダイアログ制御
3. dialogue_ui.gd — タイプライターと選択肢 UI
4. visual_novel_patterns.gd — BBCode、選択肢のフィルタリング、スプライトの重ね合わせ

カタログ（重複排除済み）

• story_manager.gd - フラグを考慮したダイアログ制御。分岐ロジックとキャラクター状態の保持に対応します。
• dialogue_ui.gd - 表示レイヤー：タイプライターの Tween（visible_ratio）と選択肢ウィンドウの生成。
• vn_rollback_manager.gd - 状態をロールバックするための履歴スタック（フラグ／背景／インデックス）。
• visual_novel_patterns.gd - 再利用可能な BBCode 効果、フラグによる選択肢のフィルタリング、スプライトの重ね合わせ。

---

決定木: スクリプト保存 vs プラグイン

アプローチ	選ぶべきとき	備考
JSON / CSV スクリプト	ライターが Godot の外で編集する。高速なイテレーション	FileAccess またはスレッド化された ResourceLoader で読み込み、StoryManager でスキーマを検証する
カスタム Resource ダイアログツリー	デザイナーが Inspector で編集、型付きフィールド	関連: godot-resource-data-patterns、MANDATORY story_manager.gd
Dialogic (プラグイン)	エディターツールを備えた完全な VN スイート(タイムライン、キャラクター、テーマ)	大規模なルートグラフを素早くリリースする場合に推奨。ただしロールバックとフラグの規律は維持すること。Dialogic がすでにタイムラインを所有している場合は、2 つ目の StoryManager を構築しないこと
軽量なカスタムを構築	小さなキネティックノベル / 学習プロジェクト	このスキルのスクリプトを使用すること。StoryManager をインラインで再スタブしないこと

不完全な JSON StoryManager のデモを貼り付けないこと — MANDATORY story_manager.gd から実装してください。

---

ゴールデンパス(順序が重要)

1. 変更前にスナップショット — すべての進行/選択で、MANDATORY vn_rollback_manager.gd がフラグ書き込みの前に {line_index, flags, background, music} をプッシュします。
2. タイプライター + スキップ — dialogue_ui.gd: Tween で visible_ratio を 0→1 に。スキップ/進行入力時に visible_ratio = 1.0 を設定し、Tween を kill します。
3. フラグによる選択肢のフィルタリング — requires の StringName フラグが通過するオプションのみを提示し、選択を適用 → フラグを変更 → ラベルへジャンプ(visual_novel_patterns.gd + story_manager.gd)。
4. 話者フォーカス — Control アクターに move_to_front() を適用(z_index だけに頼らない) + 非アクティブを暗くする。
5. 重量級の CG/BG — 背景には ResourceLoader.load_threaded_request を使用し、巨大なスクリプトをメインスレッドで同期パースしないこと。

# Choice handler shape (flags after snapshot)
func make_choice(choice_id: StringName) -> void:
    rollback_manager.push_snapshot()  # BEFORE mutate
    match choice_id:
        &"be_nice":
            flags[&"relationship_alice"] = int(flags.get(&"relationship_alice", 0)) + 1
            story_manager.jump_to_label(&"alice_happy")
        &"be_mean":
            flags[&"relationship_alice"] = int(flags.get(&"relationship_alice", 0)) - 1
            story_manager.jump_to_label(&"alice_sad")

---

よくある落とし穴

1. テキストの壁 — ダイアログは 3〜4 行に抑えること。
2. 選択の幻想 — 収束するプロットであっても、常にセリフやフラグを変化させること。
3. QoL の欠如 — Auto / Skip / Backlog / Save はジャンル必須の機能です。
4. 壊れたロールバック — スナップショット前にフラグを変更すると、アンドゥが嘘をつくことになります。

詳細レシピ(必要に応じて)

トピック	参照 / スクリプト
ストーリードライバーとタイプライター UI	architecture-overview.md
分岐 / ロールバック / フォーカス	key-mechanics.md
RichText / 非同期読み込み	godot-tips.md

参照

段階的開示: 公式ドキュメントのリンクは、特定の API を調査するときのみ開いてください。関連スキルは、ピア領域へルーティングするときに読み込んでください — ラティス全体を事前に読み込まないでください。

公式ドキュメント

• RichTextLabel の BBCode — shake/wave BBCode と append_text を使って、通常の Label で画面を埋め尽くすことなく、感情豊かな会話を表現できます。
• サイズとアンカー — パーセントオフセットとアンカーを使うことで、キャラクタースプライトやダイアログボックスをさまざまな解像度に合わせて拡大縮小できます。
• GUI コンテナ — 絶対座標によるピクセル単位のレイアウトではなく、VBox/HBox を使って選択肢の行やダイアログの装飾要素を配置できます。
• バックグラウンド読み込み — ResourceLoader.load_threaded_request を使うと、重い CG や背景の切り替えでタイプライター表示が停止するのを防げます。
• ゲームの保存 — フラグ、履歴スタック、複数スロットのビジュアルノベルセーブに使える FileAccess のパターンを紹介します。
• リソース — 壊れやすいハードコードされた JSON 文字列に代わる、型付きの会話／選択肢 Resource を作成できます。
• ゲームの国際化 — tr() / CSV キーを使うことで、スクリプト内のセリフをローカライズに対応させられます。
• オーディオストリーム — BGM のクロスフェードや、セリフ送りに合わせた任意のボイス音声を実装できます。
• InputEvent の使用 — skip/advance/ui_accept の処理を使って、visible_ratio を即座に最後まで表示できます。
• シングルトン（Autoload） — チャプターのシーン切り替えをまたいで、フラグや履歴を保持できます。
• シグナル — StoryManager と DialogueUI 間で line_advanced / options_presented を接続できます。
• Tween — RichTextLabel.visible_ratio を tween_property で動かし、フレームレートに依存しないタイプライター表示を実現できます。

関連スキル

前提条件

• godot-project-foundations — StoryManager ドライバーを接続する前に、シーンツリー、Autoload、インポートの基本を学べます。
• godot-ui-rich-text — ダイアログボックス向けに、RichTextLabel の BBCode、visible_ratio、append_text のパフォーマンスを学べます。
• godot-ui-containers — 絶対座標によるピクセル単位の配置を使わず、レスポンシブな選択肢パネルやダイアログの装飾要素を作成できます。
• godot-signal-architecture — 型付きシグナルを使って、UI の表示処理を分岐ロジックから切り離せます。

補完

• godot-dialogue-system — ジャンル別のビジュアルノベルで特化させる、再利用可能な会話ランナーと台詞データの形式です。
• godot-tweening — AnimationPlayerを使いすぎずに、タイプライター風のトゥイーン、スプライトのフェード、背景のクロスフェードを実現します。
• godot-resource-data-patterns — Resourceベースの会話ツリーと、変更可能なフラグ状態のためのduplicate(true)を扱います。
• godot-input-handling — Controlのフォーカスと競合せずに、スキップ、自動進行、バックログの入力アクションを扱います。
• godot-audio-systems — 台詞や選択肢のタイミングに同期するBGMバスとボイスダッキングを扱います。
• godot-ui-theming — 名前プレート、選択肢ボタン、バックログのUI装飾に適用するテーマの型バリエーションを扱います。
• godot-monte-carlo-balancer — 出荷前に好感度のしきい値とエンディングの分布をシミュレーションし、分岐の重みを調整します。

下流／利用側

• godot-save-load-systems — ConfigFileのデモを超える、フラグや履歴向けのマルチスロット対応・スレッド化されたセーブを扱います。
• godot-genre-romance — VNのフラグ、ロールバック、選択肢のフィルタリングを再利用する、恋愛シミュレーションの好感度ループを扱います。

マスター

• godot-master — スキルを横断して見つけるためのライブラリルーター兼、ミラー化されたモジュールのエントリです。