godot-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 使用 get_node() 访问对话 UI——通过管理器信号启动（start_dialogue(res)）。
• 绝对不要自行编写 BBCode 正则表达式——优先使用 RichTextLabel BBCode / 自定义效果。
• 绝对不要在对话节点 Resource 中保存／加载数据——节点是数据；持久化应由 SaveSystem 负责。
• 绝对不要在代码中硬编码头像路径——在节点 Resources 或头像数据库中分配纹理。

---

决策树：创作引擎

创作需求	引擎	必需脚本	不要加载
在仓库中使用便于设计人员操作的 .tres 图表	Resource Autoload 图表	dialogue_resource.gd → dialogue_manager_singleton.gd → dialogue_ui_controller.gd → typebox_effect.gd	dialogue_engine.gd JSON 路径
外部作者／电子表格 → JSON	JSON 图表引擎	dialogue_engine.gd（+ 可选的 dialogue_manager.gd）→ UI + typebox	Resource Autoload 栈
项目内的可视化节点编辑器	GraphEdit 创作	运行时保留 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 控制器 → typebox_effect。选择一个运行时引擎；不要并行运行 Resource 管理器和 JSON 引擎。

可用脚本（目录汇总）

运行时（推荐路径）

• dialogue_resource.gd — 对话树 Resource
• dialogue_node_data.gd — 单句／说话者／头像元数据
• 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] 日志前缀；不记录 PII。

使用 GraphEdit 工具、TTS/口型同步、分析，以及迁移后的内联管理器/UI 教程时，必须查阅：elite-dialogue-patterns.md。仅使用 Resource Autoload 黄金路径时，不要加载。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；需要转向相邻领域时再加载相关技能——不要预先加载整个技能网络。

官方文档

• Resources — 说明为什么对话图应存放在 Resource / .tres 数据中，而不是硬编码在脚本字符串中。
• BBCode in RichTextLabel — 用于说话人强调、自定义标签和效果的原生标记，无需自行编写解析器。
• RichTextLabel — 对话 UI 应驱动的 visible_characters / 图片辅助方法和 BBCode API，可用于打字机效果和肖像。
• Internationalizing games — 使用 tr() / TranslationServer 工作流，让台词文本在不同区域设置中保持基于键的形式。
• Localization using spreadsheets — CSV 翻译表可与对话的 text_key 字段自然对应。
• Importing translations — 介绍 Godot 如何导入 CSV/PO，使本地化对话资源能在运行时解析。
• Using signals — 向上发出台词/选项/结束事件，让 UI、任务和音频无需直接引用管理器内部实现。
• Singletons (Autoload) — 注册一个能跨场景切换保留并管理遍历状态的 DialogueManager。
• Tween — 驱动 visible_ratio / 字符显示时序，而不阻塞主线程。
• Text-to-speech — 用于占位语音和口型同步相关时序的 DisplayServer TTS 回调。
• GraphEdit — 当 .tres 列表变得难以管理时，用于创作分支对话图的编辑器界面。
• JSON — 当设计师倾向于使用 JSON 而不是 Resources 时，解析外部对话图文件。

相关技能

前置条件

• godot-project-foundations — 对话 UI 场景接入所需的 Autoload 注册、前进／跳过输入和项目布局。
• godot-gdscript-mastery — 构建分支引擎和 UI 桥接前所需的类型化 Resources、信号、await 和 Callables。
• godot-resource-data-patterns — DialogueLine／图结构 Resources、导出变量以及避免重复可变状态的规范模式。
• godot-autoload-architecture — 全局 DialogueManager 在场景切换后仍需存续时所需的单例所有权和启动顺序。

补充技能

• godot-signal-architecture — 用于 line_displayed、选项选择和叙事事件桥接的信号上行／调用下行约定。
• godot-ui-rich-text — 超越打字机 UI 基础功能的 RichTextLabel BBCode、自定义效果和图像嵌入。
• godot-ui-containers — 布局选项按钮和对话面板，同时避免与 Control 尺寸和焦点机制冲突。
• godot-tweening — 用于角色显现、肖像入场和面板过渡且可安全跳过的 Tweens。
• godot-audio-systems — 语音台词播放器、对话期间的总线闪避，以及字幕与语音的同步。
• godot-quest-system — 用于限制条件选项并由对话事件桥接触发的任务标记和目标。
• godot-save-load-systems — 在 UI 节点之外持久化对话标记／已查看节点状态，使进度在重新加载后得以保留。

下游／使用方

• godot-genre-visual-novel — 完整的 VN 呈现流程会使用此技能中的图遍历、肖像和选项 UI 模式。
• godot-inventory-system — 对话效果通常会授予或要求物品；应将授予逻辑保留在库存系统中，而不是放进台词 Resources。
• godot-monte-carlo-balancer — 当叙事门槛或奖励路径需要平衡调整时，模拟技能检定／分支选项树。

主技能

• godot-master — 技能库路由器和镜像模块入口；需要确认哪个领域技能负责叙事、UI 或任务相关问题时，请打开此项。