godot-genre-visual-novel

类型：视觉小说

分支叙事、有意义的选择和提升体验的功能，是视觉小说的核心特色。

核心循环

1. 阅读 → 对话 / 旁白
2. 抉择 → 选择时刻
3. 分支 → 标记或路线发生变化
4. 后果 → 对话立即出现变化和／或留下持久标记
5. 结局 → 多个结局之一

绝对不要做（专家级反模式）

叙事与流程

• 绝对不要只营造“选择的假象”；即使剧情之后会汇合，也必须提供即时对话变化或标记变更。
• 绝对不要跳过必备的体验优化功能；必须实现自动播放、快进和回顾／历史记录，以便重玩。
• 绝对不要显示“文字墙”；对话框必须严格限制在最多 3-4 行，以免令读者望而却步。
• 绝对不要将对话文本硬编码在 GDScript 中；叙事脚本必须存放在外部文件（JSON、CSV 或自定义资源）中，以便迭代。
• 绝对不要忽略回退机制；必须维护历史记录栈，让玩家可以撤销误点或重读错过的台词。

技术与 UI

• 绝对不要用纯文本呈现情绪起伏；必须使用 RichTextLabel BBCode（例如 [shake]、[wave]）增强视觉表现力。
• 绝对不要在主线程解析大型叙事文件；必须使用 ResourceLoader.load_threaded_request()，避免场景切换卡顿。
• 对频繁访问的游戏标记，绝对不要使用标准 String；必须使用 StringName（&"met_alice"），以加快字典查找速度。
• 绝对不要使用 _process 实现逐字动画；必须对 visible_ratio 使用 Tween，实现平滑且与帧率无关的显示效果。
• 绝对不要忽视角色的绘制顺序；必须确保当前发言者显示在最前方，以便清晰辨识。
• 如果需要处理输入，绝对不要使用 z_index 设置 Control 节点的优先级；必须使用 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 - 演示层：打字机缓动（visible_ratio）和选择窗口生成。
• vn_rollback_manager.gd - 用于状态回退的历史记录栈（标记／背景／索引）。
• visual_novel_patterns.gd - 可复用的 BBCode 特效、按标记筛选选择项、精灵分层。

---

决策树：脚本存储还是插件

方案	适用场景	备注
JSON / CSV 脚本	编剧在 Godot 外编辑；快速迭代	通过 FileAccess 或线程化 ResourceLoader 加载；在 StoryManager 中验证架构
自定义 Resource 对话树	设计师在 Inspector 中编辑、使用类型化字段	参考同级项目 godot-resource-data-patterns；MANDATORY story_manager.gd
Dialogic（插件）	需要完整的 VN 套件（时间线、角色、主题）和编辑器工具	需要快速交付大型路线图时优先选择；仍需遵循回滚和标记纪律。如果 Dialogic 已管理时间线，则不要再构建第二个 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。
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. 缺少生活质量功能——自动 / 跳过 / 回顾 / 保存都是必备的类型功能。
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 保存标记、历史记录堆栈和多槽位视觉小说存档。
• 资源 — 使用类型化的对话/选项 Resource，替代脆弱的硬编码 JSON 字符串。
• 游戏国际化 — 使用 tr() / CSV 键，让脚本台词随时可进行本地化。
• 音频流 — 实现 BGM 交叉淡变，并将可选语音台词与台词推进关联。
• 使用 InputEvent — 处理跳过/推进/ui_accept，让 visible_ratio 立即显示全部内容。
• 单例（Autoload） — 在章节场景切换时持久保存标记和历史记录。
• 信号 — 在 StoryManager 和 DialogueUI 之间连接 line_advanced / options_presented。
• Tween — 对 RichTextLabel.visible_ratio 使用 tween_property，实现不受帧率影响的打字机显示效果。

相关技能

前置条件

• godot-project-foundations — 在连接 StoryManager 驱动程序之前，了解场景树、自动加载和导入基础知识。
• 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 — 用于姓名牌、选项按钮和回看记录界面的主题类型变体。
• godot-monte-carlo-balancer — 在发布分支权重前，模拟好感度阈值和结局分布。

下游／使用者

• godot-save-load-systems — 支持多存档位和多线程的存档，适用于超出 ConfigFile 示例范围的标记／历史记录。
• godot-genre-romance — 复用视觉小说标记、回滚和选项筛选机制的恋爱模拟好感度循环。

主索引

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。