visual-novel

ビジュアルノベル

ビジュアルノベル向けのプレイブックです。分岐するスクリプト、演出（テキストボックス、キャラクター、 背景）、選択肢、プレイヤーが期待する快適機能（いつでもセーブ、バックログ、 スキップ、自動送り）を扱います。これは構成的なスキルで、会話エンジンと UI レイヤーを動かします。 会話エンジンや UI ノードについて改めて説明するものではなく、VN を快適に読めるようにするスクリプトモデルと プレイヤー向けの便利機能を定義します。

使用する場面

• キャラクターアートや背景とともに、ゲームの大部分が分岐するテキストを読むことで構成される場合に使用します。 ビジュアルノベル、恋愛シミュレーション、分岐型インタラクティブフィクション、ストーリー選択型ゲームなどが該当します。
• 選択肢やルートの構成、ストーリーフラグ、または VN の便利機能（バックログ、 スキップ、自動送り、いつでもセーブ）を設計する場合に使用します。

使用しない場面： 大規模なゲームの一機能として会話を扱う場合 → dialogue-systems を使用する rpg。カード／ボードゲーム → 他のジャンルを使用します。分岐スクリプトエンジンそのものには、 dialogue-systems（Ink / Yarn Spinner）を使用します。

コアループ

1行読む → 進める →（分岐で）選択肢を選ぶ → フラグ／選択によってストーリーが分岐する → 読み進める → エンディングに到達する。 「ゲーム」の面白さは、分岐の形と選択に意味を感じられるかどうかにあります。 それ以外はすべて演出と利便性です。

必須システム

1. 分岐スクリプト — 順序付きの行＋選択肢＋ジャンプと、条件や変数（Ink/Yarn）。
2. テキストボックス — 話者名、本文、タイプライター表示、クリック／キー入力で進行。
3. キャラクター — 表情／ポーズの異なるスプライト、配置、表示／非表示のトランジション。
4. 背景＋トランジション — シーン画像、フェード／ディゾルブ。
5. 選択肢 — 選択肢を提示し、フラグによって一部を制限し、選択内容を記録します。
6. ストーリー状態 — スクリプトを分岐させ、コンテンツをアンロックするフラグ／変数。
7. セーブ／ロード（いつでもセーブ） — スクリプトの位置と状態をすべて保存。複数スロット、クイックセーブ。
8. VN の便利機能 — バックログ／履歴、スキップ（既読テキスト）、自動送り、テキスト速度設定。
9. オーディオ — シーンごとの音楽、効果音、任意のボイスクリップ。

設計上の調整項目

調整項目	効果	備考
テキスト速度／即時表示	読みやすさ	常に即時表示とスキップを可能にします。
自動送りの間隔	手放しで読める	調整可能にし、選択肢では一時停止します。
スキップの範囲	再読時の利便性	デフォルトでは既読テキストのみスキップします。
分岐の広さ／深さ	リプレイ性と制作コストのバランス	分岐が増えるほど、執筆／アート制作の作業も増えます。
フラグで制御するコンテンツ	過去の選択への反応	過去の決定を確認する行／選択肢。
ルート構成	ストーリーの形	分岐して合流する構成か、独立したルートか（参照）。
選択肢の表示	公平さ	選択不可の選択肢を表示するか、隠すか。
バックログの長さ	利便性	直近の文脈を読み返せるだけの量を保持します。

パターン

1. エンジンが読み進めるデータとしてのスクリプト

# Pseudocode. Lines, choices, and jumps as data — usually authored in Ink/Yarn and stepped
# through by that runtime. The engine asks the script for "the next thing to show".
node = script.current()
if node.kind == "line":
    show_text(node.speaker, node.text)        # wait for advance input
elif node.kind == "choice":
    options = [o for o in node.options if condition_met(o.condition, flags)]  # gate by flags
    show_choices(options)                      # wait for selection
elif node.kind == "set":
    flags[node.var] = eval_expr(node.expr, flags)
script.advance(selected_option_or_none)

2. スキップ可能なタイプライター表示＋進行

# Pseudocode. Reveal characters over time; a click first completes the line, then advances.
def show_text(speaker, text):
    name_label.text = speaker
    revealed = 0
    while revealed < len(text):
        if advance_pressed():                  # first press: reveal the whole line instantly
            revealed = len(text); break
        revealed += chars_per_second * dt
        body_label.text = text[:int(revealed)]
        push_to_backlog_when_complete(speaker, text)
    wait_for_advance()                          # second press: go to the next line

3. 選択肢でフラグを設定し、後のコンテンツを分岐させる

# Pseudocode. Choices write flags; later conditions read them — that is "reactivity".
def on_choice(option):
    if option.set: flags[option.set] = True     # e.g. flags["helped_npc"] = True
    script.jump(option.target)                   # follow the branch

# Elsewhere, a line/choice/ending checks the flag:
if flags.get("helped_npc"): play_route("good_ending") else: play_route("neutral_ending")

落とし穴／失敗パターン

• チェックポイントしか保存しないセーブ → VN にはいつでもセーブが必要です。正確なスクリプト位置と すべてのフラグ／変数（既読テキストのデータも含む）を保存し、ロード後に同じ行から再開できるようにします。
• 演出ロジックをスクリプトに埋め込む → 保守できなくなります。スクリプトにはコンテンツ（テキスト、選択肢）を、 エンジンレイヤーには見せ方（スプライト、トランジション）を保持します。
• スキップ／自動送り／バックログがない → 特に再プレイ時に、読者は閉じ込められたように感じます。これらは追加機能ではなく、 基本機能として期待されています。
• 未読テキストをスキップする → プレイヤーがコンテンツを見逃します。スキップは既読テキストのみを早送りするようにします。
• 結果に影響しない選択肢 → すぐに合流する分岐は、見せかけに感じられます。後の行、選択肢、エンディングに はっきりと変化をもたらすフラグを設定します。
• 組み合わせによる分岐の爆発 → リリースできなくなります。完全に独立したツリーではなく、いくつかのフラグ付きの バリエーションを含む分岐・合流型の構成を優先します（参照）。
• 読書の文脈が失われる → 直前の行を読み返すバックログがありません。履歴バッファーを保持します。
• 言語のハードコード → ローカライズできなくなります。翻訳用のキーを付けたデータとしてテキストを保持します。

構成（これらのスキルから構築）

• スクリプトエンジン： dialogue-systems（Ink / Yarn Spinner）— 分岐、条件、変数、ローカライズ用フック。
• プレゼンテーション： テキストボックス／選択肢メニューのレイアウト、スケーリング、安全領域には game-ui-ux を使用します。具体的なテキストボックス、選択肢メニュー、ネームプレート、バックログ UI には godot-ui-control を使用します。
• 永続化： 任意の場所でのセーブ用スロット、既読テキスト／スキップデータ、設定には save-systems を使用します。
• オーディオ： シーンごとの音楽、効果音、ボイス再生には audio-design を使用します。
• ビジュアル： スプライト／背景のトランジションにはエンジンのアニメーション／Tween スキルを使用し、ディゾルブには shader-programming を使用します。
• プロセス： アートを追加する前に、分岐構造をプレーンテキストでテストするには prototype-fast を使用します。

参考資料

• 分岐データモデル、ルート構造（分岐と合流／ルート）、フラグ／変数、任意の場所でのセーブとバックログ／スキップデータ、コンテンツとプレゼンテーションの分離については、 references/script-and-flow.md をお読みください。