游戏开发【免费下载链接】dialogic Create Dialogs, Visual Novels, RPGs, and manage Characters with Godot to create your Game!项目地址https://gitcode.com/gh_mirrors/dia/dialogic点击查看免费下载Dialogic 2 是一套运行在 Godot 引擎中的对话与叙事系统插件用于创建对话、视觉小说Visual Novel、RPG 交互并集中管理角色Characters及其立绘。本文以仓库根目录的 README.md 为主线结合 addons/dialogic 下的源码与 Tests 测试用例从安装激活、版本要求、架构组成、事件与时间线系统、角色资源、测试体系到源码协作约定逐层拆解这套插件的实际工作原理帮助读者在项目中正确安装、调用与扩展 Dialogic 2。一、项目定位Dialogic 2 能做什么Dialogic 2 的定位非常聚焦在 Godot 中创建对话、视觉小说、RPG 对话流程并集中管理游戏角色。它不是一个通用的游戏框架而是一套对话即资源、流程即事件的叙事管线。从 DialogicGameHandler.gd 的类注释可以看出插件核心是一个名为Dialogic的 Autoload 单例它负责持有 Dialogic 当前运行状态的全部关键信息向所有子系统Subsystem提供统一访问入口提供启动/结束时间线Timeline的方法。这套设计决定了 Dialogic 2 的使用方式开发者通过编辑器可视化搭建时间线在游戏运行时通过Dialogic.start_timeline(...)等 API 驱动对话流程由各个子系统分工协作完成文本显示、角色立绘、音频、选择分支、变量与存档等职责。二、版本要求至少 Godot 4.5README 明确给出硬性约束Dialogic 2requires at least Godot 4.5至少需要 Godot 4.5。plugin.cfg 中记录的当前插件版本为2.0-Alpha-21 WIP (Godot 4.5)属于 Alpha 阶段迭代版本这意味着 API 仍可能随版本调整。同时 README 指出若使用 Godot 3.x应寻找Dialogic 1.x旧版本分支在 Alpha / Beta 阶段代码可能在任何一次 Release 中变化以优化设计更新日志会说明如何同步调整代码。因此将项目迁移到 Dialogic 2 前请先确认引擎版本不低于 Godot 4.5。三、安装与激活从 AssetLib 到自动更新3.1 安装步骤README 指引读者参考官方Getting Started文档中的安装与激活章节核心流程是从 Godot 的 AssetLib资源库搜索并下载 Dialogic将addons/dialogic目录放入项目的addons/文件夹在Project Settings → Plugins中启用 Dialogic 插件。3.2 启用插件时发生了什么从 plugin.gd 的源码可以看到插件启用_enter_tree时执行了多项关键注册动作源码位置说明注册 Autoload 单例add_autoload_singleton(PLUGIN_NAME, PLUGIN_HANDLER_PATH)将addons/dialogic/Core/DialogicGameHandler.gd注册为名为Dialogic的全局单例实例化主编辑面板MainPanel.instantiate()把 Dialogic 编辑器主界面挂到 Godot 编辑器主屏幕注册导出插件add_export_plugin(export_plugin)参与游戏导出流程export_plugin.gd注册检查器插件add_inspector_plugin(inspector_plugin)为时间线等资源提供 Inspector 面板Editor/Inspector/inspector_plugin.gd其中 Autoload 的注册非常关键运行时Dialogic单例即 DialogicGameHandler 实例所有子系统都以它的子节点形式挂载见 DialogicGameHandler.gd 的_collect_subsystems()与add_subsystem()。3.3 自动创建的默认输入映射插件启用时还会调用add_dialogic_default_action()plugin.gd 第 130-148 行若项目尚未存在input/dialogic_default_action设置则自动写入一个名为dialogic_default_action的输入动作包含Enter键鼠标左键空格键X键手柄 A 键JOY_BUTTON_A。该动作的deadzone为0.5是对话推进继续下一句/跳过文本的默认触发输入后续可在文本设置页中替换为其他输入动作对应项目设置dialogic/text/input_action默认值即dialogic_default_action见 subsystem_input.gd 与 settings_text.gd。3.4 内置自动更新器README 特别提到Dialogic 自带自动更新器auto-updater插件启用后可以直接在插件界面内安装后续版本无需手动重新下载覆盖。对应实现位于 Editor/Common/update_manager.gd 与 update_install_window.gd。四、文档与类参考README 提示读者可以查阅两部分官方资料Dialogic 官方文档涵盖从入门到进阶的完整使用指南Class Reference类参考面向开发者的 API 索引。同时仓库源码本身就是最准确的文档所有公开类均带有详细的 GDScript 注释。例如 DialogicGameHandler.gd、Dialogic_Subsystem.gd、event.gd 都以##注释描述了每个成员的作用与调用约定供 IDE 悬浮提示直接展示。五、运行时架构Dialogic 单例与子系统体系5.1 状态机DialogicGameHandler定义了对话运行时的状态枚举DialogicGameHandler.gd 第 13-19 行状态含义IDLE等待输入以推进对话REVEALING_TEXT正在逐字显示文本ANIMATING正在播放动画AWAITING_CHOICE等待玩家选择选项WAITING等待某件事完成状态变化会发出state_changed(new_state)信号方便 UI 或外部系统感知对话当前阶段。5.2 子系统清单DialogicGameHandler通过 Indexer 机制自动收集各模块的子系统见下文当前仓库注册的子系统及其入口脚本如下子系统通过Dialogic.xxx访问脚本Dialogic.AnimationsModules/Core/subsystem_animation.gdDialogic.AudioModules/Audio/subsystem_audio.gdDialogic.BackgroundsModules/Background/subsystem_backgrounds.gdDialogic.ChoicesModules/Choice/subsystem_choices.gdDialogic.ExpressionsModules/Core/subsystem_expression.gdDialogic.GlossaryModules/Glossary/subsystem_glossary.gdDialogic.HistoryModules/History/subsystem_history.gdDialogic.InputsModules/Core/subsystem_input.gdDialogic.JumpModules/Jump/subsystem_jump.gdDialogic.PortraitContainersModules/Character/subsystem_containers.gdDialogic.PortraitsModules/Character/subsystem_portraits.gdDialogic.SaveModules/Save/subsystem_save.gdDialogic.SettingsModules/Settings/subsystem_settings.gdDialogic.StylesModules/Style/subsystem_styles.gdDialogic.TextModules/Text/subsystem_text.gdDialogic.TextInputModules/TextInput/subsystem_text_input.gdDialogic.VARModules/Variable/subsystem_variables.gdDialogic.VoiceModules/Voice/subsystem_voice.gdDialogic.WaitModules/Wait/subsystem_wait.gd5.3 子系统的基类契约所有子系统都继承自 Dialogic_Subsystem.gd 中的DialogicSubsystem。该基类定义了一套可覆写的生命周期方法_post_install()所有子系统挂载完成后调用一次_clear_state(clear_flag)清空子系统状态在DialogicGameHandler就绪、clear()以及加载存档前调用_pause()/_resume()随Dialogic.paused切换而暂停/恢复_load_state(load_flag)/_pack_extra_state()配合状态保存。值得注意的机制是子系统的export变量会被视为存档状态的一部分保存时自动打包、加载时自动解包见 Dialogic_Subsystem.gd 的pack_exported_state()与unpack_state()额外状态如场景节点上的数据则通过_pack_extra_state()收集。这正是Dialogic.get_full_state()/load_full_state()返回DialogicSaveState能够完整还原对话现场的基础。5.4 模块的 Indexer 注册机制Dialogic 2 采用模块 文件夹 index.gd的组织方式。index_class.gd 定义了DialogicIndexer基类每个模块目录下的index.gd继承它并声明本模块包含的内容例如 Modules/Audio/index.gd 就返回了事件脚本、子系统与设置页func _get_events() - Array: return [this_folder.path_join(event_audio.gd)] func _get_subsystems() - Array: return [{name:Audio, script:this_folder.path_join(subsystem_audio.gd)}] func _get_settings_pages() - Array: return [this_folder.path_join(settings_audio.tscn)]Indexer 可声明的内容包括事件_get_events、子系统_get_subsystems、编辑器_get_editors、设置页_get_settings_pages、角色编辑器分区_get_character_editor_sections、文本效果与修饰器_get_text_effects/_get_text_modifiers、特殊资源_get_special_resources、布局部件与风格预设_get_layout_parts/_get_style_presets等。这意味着扩展 Dialogic 只需要新增一个带index.gd的模块文件夹无需改动核心代码。六、时间线与事件系统对话如何跑起来6.1 时间线资源.dtl时间线Timeline是 Dialogic 的核心数据载体对应资源类DialogicTimelinetimeline.gd文件扩展名为.dtl。一个时间线本质上是一系列事件的文本列表from_text(text)把多行文本按行切分为事件字符串数组process()把字符串逐个解析为DialogicEvent资源实例通过事件缓存DialogicResourceUtil.get_event_cache()匹配各事件的is_valid_event()缩进驱动分支事件如Choice、Condition会提升缩进层级process()依据缩进自动插入EndBranch事件从而形成分支结构as_text()把事件数组还原为文本用于保存。6.2 事件基类与 shortcode所有事件继承自 event.gd 的DialogicEvent。每个事件通过短代码shortcode格式存取例如[choice text选项文本 [if 条件]]事件执行的通用流程execute()→call_deferred(_execute)→finish()由基类统一处理event_started/event_finished信号驱动DialogicGameHandler的handle_event()推进到下一条事件。事件还内置了翻译 ID、编辑器字段描述editor_list、build_event_editor()与代码补全支持。6.3 文本事件最常用的对话单元文本事件类DialogicTextEventevent_text.gd是最核心的事件。它的文本格式非常直观角色名 (立绘名): 台词内容例如Jane (happy): 你好冒险者。解析规则from_text()中的正则支持角色名: 台词指定说话角色角色名 (立绘名): 台词同时指定立绘角色名用_表示无说话者角色名用{表达式}表示运行时动态解析角色。执行时_execute()文本事件会依次切换说话者与立绘Portraits.change_speaker、更新名字标签与打字音效 mood、处理角色风格切换、逐段显示文本并在结束时根据情况触发下一句指示器或选择分支。文本内容支持 BBCode 与自定义文本效果例如[speed2]、[pause0.5]、[signal自定义信号]、[mood愤怒]文本修饰器还支持随机选择A/B/C语法与[br]换行见 subsystem_text.gd 的parse_text_effects()与modifier_random_selection()。6.4 选择事件与分支选择事件DialogicChoiceEventevent_choice.gd允许在文本后追加多个选项支持condition条件表达式、else_action条件不成立时的行为隐藏/禁用/跟随全局设置、disabled_text、extra_data。选项事件可包含子事件即玩家选择后执行的对话分支由 subsystem_choices.gd 统一管理显示、延迟、热键与焦点。6.5 跳转与标签跳转事件DialogicJumpEventevent_jump.gd支持切换到另一条时间线timeline参数在当前/目标时间线内跳到指定标签label_name参数对应Label事件。6.6 在代码中启动对话在游戏脚本中启动对话的标准做法API 见 DialogicGameHandler.gd# 启动时间线并确保布局场景存在推荐 Dialogic.start(timeline_name) # 或跳转到时间线中的某个标签 Dialogic.start(timeline_name, my_label) # 或不附加布局场景直接启动 Dialogic.start_timeline(timeline_name)start()与start_timeline()都接受时间线资源或路径也支持label_or_idx参数直接跳到标签或事件索引。对话结束时默认会播放一条只含[clear]事件的dialog_ending_timeline来清理现场见 DialogicGameHandler.gd 第 184-185 行。6.7 清空与状态Dialogic.clear()配合ClearFlags枚举可精确控制清理范围DialogicGameHandler.gd 第 21-26 行标志值行为FULL_CLEAR0清空所有子系统KEEP_VARIABLES1清空除变量外的全部内容TIMELINE_INFO_ONLY2不清空子系统仅重置当前时间线与索引七、角色资源从 .dch 到立绘管理7.1 角色资源.dch角色在 Dialogic 中是独立的资源文件扩展名.dch对应 character.gd 的DialogicCharacter包含display_name显示名称可翻译nicknames昵称列表用于自动着色匹配color角色主题色自动给名字上色时使用scale、offset、mirror立绘变换参数default_portrait与portraits默认立绘与立绘字典custom_info自定义信息如style、sound_moods打字音效情绪。Tests/Resources/unit_test_character.dch 展示了角色资源的真实 JSON 存储格式例如display_name、nicknames、portraits等字段。7.2 唯一标识Unique IdentifierDialogic 不要求文件名作为引用键而是通过 DialogicResourceUtil.gd 维护唯一标识 → 文件路径的目录映射dialogic/directories/dch_directory、dialogic/directories/dtl_directory。时间线、事件与代码中都优先使用标识符而非路径这样重命名或移动文件不会破坏引用。运行时创建的角色还可通过register_runtime_resource()注册为临时资源。7.3 立绘与角色风格立绘由 subsystem_portraits.gd 管理支持加入/离开场景、切换立绘、移动与动画每个角色可通过custom_info.style指定专属对话风格文本事件执行时会自动切换见 event_text.gd 的Handle style changes段落角色名称还可开启自动着色项目设置dialogic/text/autocolor_names为true时subsystem_text.gd 会用角色颜色包裹对话文本中的角色名与昵称。八、布局与风格把对话画到屏幕上Dialogic 2 把界面拆分为布局Layout与风格Style两个概念布局Layout由布局部件Layout Part组合而成例如文本框、立绘层、选项层、历史层、输入层等风格Style决定整体视觉主题角色可以绑定专属风格。仓库内置的布局部件位于 Modules/DefaultLayoutParts每个部件目录包含一个part_config.cfg元数据文件例如 Base_Default/part_config.cfg[style] type Layout Base name Default Layout Base author Dialogic description A very simple base for layouts. scene default_layout_base.tscn布局部件由 DefaultLayoutParts/index.gd 通过scan_for_layout_parts()统一扫描注册开发者也可以按同样格式制作自己的布局部件与风格预设。文本显示、名字标签、下一句指示器、打字音效等节点通过节点组如dialogic_dialog_text、dialogic_name_label、dialogic_next_indicator、dialogic_type_sounds被子系统识别和控制详见 subsystem_text.gd。九、文本行为与输入从逐字显示到自动前进9.1 文本子系统行为设置settings_text.gd 集中了文本相关的项目设置均以dialogic/text/为前缀常用项包括项目设置默认值说明dialogic/text/letter_speed0.01单个字符出现所需时间秒dialogic/text/input_actiondialogic_default_action推进对话的输入动作dialogic/text/initial_text_reveal_skippabletrue文本是否允许跳过逐字显示dialogic/text/text_reveal_skip_delay0.1跳过显示前的输入拦截时长dialogic/text/advance_delay0.1文本显示完毕后到可推进的延迟dialogic/text/autocolor_namesfalse是否自动用角色色着色名字dialogic/text/split_at_new_linesfalse是否按换行把一条文本拆成多个段落dialogic/text/autoadvance_enabledfalse是否启用自动前进dialogic/text/autoadvance_fixed_delay1自动前进的固定延迟秒dialogic/text/autoskip_time_per_event0.1自动跳过时每个事件停留时间dialogic/text/autopauses{}标点自动暂停映射如?!.,;:dialogic/text/absolute_autopausesfalse自动暂停是否忽略速度倍率9.2 输入子系统推进、自动前进与跳过subsystem_input.gd 中的Dialogic.Inputs统一处理输入提供三组能力manual_advance手动推进点击/按键继续auto_advance自动前进固定延迟或按字数/字符数延迟支持忽略字符auto_skip自动跳过用于已读剧情跳过功能。输入流转的核心是handle_input()它会先停止遇到用户输入即取消的自动前进/自动跳过再依次发出dialogic_action_priority与dialogic_action信号供各子系统消费。9.3 文本显示信号文本子系统对外暴露了完整的显示生命周期信号subsystem_text.gd 第 7-49 行about_to_show_text(info)文本事件到达、即将显示text_started(info)文本开始显示在文本框动画之后text_finished(info)文本逐字显示完毕speaker_updated(character)说话者变更textbox_visibility_changed(visible)文本框显隐变化。info字典包含text、character、portrait、append等键可用于实现打字机、立绘同步、历史记录等自定义逻辑。文本事件执行时还会通过 History 子系统把内容记入对话历史store_simple_history_entry。十、变量、条件与翻译叙事逻辑的基石10.1 变量系统变量子系统Dialogic.VAR见 Modules/Variable/subsystem_variables.gd支持在对话文本中直接引用变量{变量路径}。变量字典由项目设置dialogic/variables定义嵌套字典可通过点路径访问类型包括字符串、浮点、整数与布尔见 DialogicUtil.gd 的VarTypes与list_variables()。文本解析顺序中变量解析优先级最高order 30先于文本效果与自动着色执行。10.2 条件与表达式条件事件DialogicConditionEventModules/Condition/event_condition.gd用于条件分支选择事件与更多字段也支持条件表达式。表达式由Dialogic.Expressions子系统Modules/Core/subsystem_expression.gd执行甚至可以在文本事件中动态指定角色名{表达式}语法见 event_text.gd。10.3 翻译体系Dialogic 2 内置翻译机制角色与事件的文本属性可标记为可翻译can_be_translated()/_get_translatable_properties()每个可翻译资源在需要时获得一个十六进制翻译 IDDialogicUtil.get_next_translation_id()启用项目设置dialogic/translation/enabled后显示文本会优先取翻译键无翻译时回退原文见 character.gd 与 event.gd。事件文本的翻译 ID 会以#id:xxxx后缀的形式持久化在时间线文件中。十一、测试体系用 gdUnit4 保证核心逻辑README 明确说明 Dialogic 使用单元测试Unit Tests保障特定模块按预期工作测试会在每次 push 与 pull request 时自动运行。测试框架为gdUnit4测试文件位于仓库的 Tests/Unit 目录。11.1 本地运行测试从 Godot 的 AssetLib 安装gdUnit4插件打开测试目录 Tests/Unit 中的测试脚本使用 gdUnit4 的运行入口执行测试。建议先阅读仓库已有的测试文件再按照 gdUnit4 的文档创建自己的第一条测试。11.2 现有测试示例Tests/Unit/glossary_resource_test.gd 测试了词条资源DialogicGlossary的增删改查try_add_entry、replace_entry_key、remove_entry以及重复添加防护func test_add_entry() - void: var glossary: DialogicGlossary DialogicGlossary.new() assert(glossary.try_add_entry(SAMPLE_ENTRY.duplicate()), Unable to add entry.) assert(glossary.entries.size() ALTERNATIVE_ENTRIES.size() 1, Glossary should have 1 entry) assert(not glossary.get_entry(NAME_ENTRY).is_empty(), Entry index cannot be found via entry name.)Tests/Unit/test_auto_advance.gd 则验证自动前进Auto-Advance的正确启停其中第二个用例专门回归了一个 Bug直到用户输入的自动前进在用户输入后不应继续运行func test_disable_auto_advance() - void: Dialogic.Inputs.auto_advance.enabled_until_user_input true Dialogic.Inputs.handle_input() var is_enabled: bool Dialogic.Inputs.auto_advance.is_enabled() assert(is_enabled false, Auto-Advance is still running after input)这两个测试分别对应词条资源Modules/Glossary/glossary_resource.gd与输入子系统Modules/Core/subsystem_input.gd体现了测试直接针对源码行为的项目实践。Tests 目录下还包含角色资源样例 Tests/Resources/unit_test_character.dch 供测试使用。十二、源码交互约定下划线前缀即私有README 对希望阅读或扩展源码的开发者给出了重要约定源码中所有以下划线_开头的方法或变量都被视为私有例如_remove_character()。这意味着你仍然可以调用它们但它们可能在版本迭代中改变行为或签名导致代码在升级后失效大多数私有方法都在公开方法内部被调用遇到问题时优先查阅公开 API 文档公开的方法与变量以Class Reference类参考为准。在 DialogicGameHandler.gd 中可以看到这种约定公开入口如start()、start_timeline()、end_timeline()、clear()而_collect_subsystems()、_cleanup_previous_event()等内部逻辑均以下划线命名。同样Dialogic_Subsystem.gd 中的_clear_state()、_load_state()、_pack_extra_state()都是供子类覆写的私有钩子。十三、授权与致谢13.1 开源许可Dialogic 2 以MIT License开源见仓库根目录 LICENSE允许自由使用、修改与分发需保留版权声明。13.2 字体资源许可插件自带的示例字体Roboto遵循Apache License 2.0许可文本位于 addons/dialogic/Example Assets/Fonts/LICENSE.txt。在发布使用示例资源的产品时应保留相应的许可证声明。13.3 维护与社区README 致谢了主要作者与众多贡献者、赞助者。需要帮助或反馈问题时README 提供的渠道包括 Discord 社群、GitHub Issues 与 GitHub Discussions均可从 README 顶部的徽章与链接进入。十四、总结与上手路线Dialogic 2 的价值在于把对话叙事从散落的脚本中抽象成一套完整的资源与子系统管线。基于仓库现状可以总结出以下上手路线确认引擎版本不低于 Godot 4.5当前插件版本为2.0-Alpha-21 WIP见 plugin.cfg安装并启用插件让DialogicAutoload 与编辑器面板自动就绪阅读官方文档与类参考同时对照 README.md、DialogicGameHandler.gd 与 event.gd 的注释理解公开 API在编辑器中创建时间线.dtl与角色.dch用文本事件、选择事件、跳转事件搭建剧情在代码中调用Dialogic.start(...)驱动对话通过Dialogic.Text、Dialogic.Inputs、Dialogic.Choices等子系统与信号接入自定义 UI 和玩法逻辑善用单元测试本地安装 gdUnit4参考 Tests/Unit 为自定义模块补充测试遵循下划线私有约定编写扩展代码通过新增带index.gd的模块文件夹接入自定义事件、子系统、文本效果与布局部件同时留意 Alpha 阶段的 API 变动日志。赞分享游戏开发【免费下载链接】dialogic Create Dialogs, Visual Novels, RPGs, and manage Characters with Godot to create your Game!项目地址https://gitcode.com/gh_mirrors/dia/dialogic点击查看免费下载相关推荐Home Assistant Companion for Android车辆应用开发车载智能家居控制的完整指南Home Assistant Companion for Android车辆应用开发车载智能家居控制的完整指南 Home Assistant Companio移动开发智能家居终极指南5步掌握暗黑破坏神2存档编辑神器d2s-editor终极指南5步掌握暗黑破坏神2存档编辑神器d2s editor 暗黑破坏神2存档编辑器d2s editor是一款功能强大的开源工具专为《暗黑破坏神2》玩家设计游戏开发Dialogic 2角色编辑器深度解析打造栩栩如生的游戏角色Dialogic 2角色编辑器深度解析打造栩栩如生的游戏角色 Dialogic 2是Godot引擎中功能强大的对话系统其角色编辑器为开发者提供了创建和管理游游戏开发上一篇CANN/cannbot-skills TileLang-Ascend精度标准体系下一篇Flexprice 弹性税务系统深入解析分层税率、多税种快照与发票生命周期集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考