visual-novel

视觉小说

视觉小说实用指南——涵盖分支脚本、呈现方式（文本框、角色、背景）、选项，以及玩家期待的便利功能（随时存档、回看记录、跳过、自动播放）。这是一项组合式技能：它驱动对话引擎和 UI 层。它不会重新讲解对话引擎或 UI 节点，而是定义脚本模型和让视觉小说更易读的玩家便利功能。

适用场景

• 当游戏主要由可分支的文本阅读构成，并配有角色美术和背景时使用：视觉小说、恋爱模拟、分支互动小说、剧情选择类游戏。
• 设计选项／路线结构、剧情标记或视觉小说便利功能（回看记录、跳过、自动推进、随时存档）时使用。

不适用场景： 对话只是大型游戏中的一个功能 → 使用 rpg 并结合 dialogue-systems。卡牌／棋盘游戏 → 使用其他类型。若要使用分支脚本引擎本身， 请使用 dialogue-systems（Ink / Yarn Spinner）。

核心循环

阅读一行 → 推进 →（遇到分支时）做出选择 → 故事根据标记／选项分支 → 继续阅读 → 抵达结局。 “游戏”的核心在于分支的形态，以及选项是否让人感到有影响；其他一切都是呈现和便利功能。

必备系统

1. 分支脚本——有序文本行 + 选项 + 跳转，并包含条件和变量（Ink/Yarn）。
2. 文本框——说话者名称、正文、打字机效果显示、点击／按键推进。
3. 角色——带有表情／姿势的立绘、位置、显示／隐藏过渡效果。
4. 背景 + 过渡效果——场景图像、淡入／淡出。
5. 选项——展示选项、根据标记限制部分选项、记录玩家选择。
6. 剧情状态——用于分支脚本和解锁内容的标记／变量。
7. 存档／读档（随时存档）——完整保存脚本位置 + 状态；多个存档位；快速存档。
8. 视觉小说便利功能——回看记录／历史、跳过（已读文本）、自动推进、文本速度设置。
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")

常见问题／失效模式

• 存档只记录检查点 → 视觉小说需要随时存档。保存精确的脚本 位置以及所有标记／变量（以及已读文本数据），这样读档后才能从同一行继续。
• 将呈现逻辑写死在脚本中 → 难以维护。将内容（文本、选项） 保留在脚本中，将呈现方式（立绘、过渡效果）放在引擎层。
• 没有跳过／自动播放／回看记录 → 玩家会觉得受困，尤其是在重玩时。这些都是预期的 基本功能，不是额外功能。
• 跳过未读文本 → 玩家会错过内容。跳过应只快速推进已读文本。
• 选项没有影响 → 很快就汇合的分支会让人觉得虚假。设置标记，让后续文本行、 选项或结局明显发生变化。
• 分支组合爆炸 → 无法顺利发布。优先采用分支后汇合并加入少量标记变化的结构， 而非完全独立的树状结构（参见资料）。
• 失去阅读上下文 → 没有回看记录，无法重读最近的文本行。保留历史记录缓冲区。
• 语言写死在代码中 → 无法本地化。将文本存储为带键的数据，以便翻译。

组合（使用这些技能构建）

• 脚本引擎： dialogue-systems（Ink / Yarn Spinner）——分支、条件、变量、本地化钩子。
• 演示： 使用 game-ui-ux 设计文本框／选项菜单的布局、缩放和安全区域；使用 godot-ui-control 实现具体的文本框、选项菜单、姓名牌和回溯 UI。
• 持久化： 使用 save-systems 实现随时存档槽位、已读文本／跳过数据和设置。
• 音频： 使用 audio-design 播放每个场景的音乐、音效和语音。
• 视觉效果： 使用引擎动画／Tween 技能实现精灵／背景转场；使用 shader-programming 实现溶解效果。
• 流程： 使用 prototype-fast，在添加美术素材前先用纯文本测试分支结构。

参考资料

• 有关分支数据模型、路线结构（分支与汇合式结构和多路线）、标记／变量、 随时存档 + 回溯／跳过数据，以及内容／演示的拆分，请阅读 references/script-and-flow.md。