GDevelop Dialogue Tree 扩展的解析引擎：bondage.js 的安装、CLI 与 Runner API 实战指南

GDevelop Dialogue Tree 扩展的解析引擎bondage.js 的安装、CLI 与 Runner API 实战指南【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelopbondage.js 是一个用 JavaScript 实现的 Yarn 对话脚本解析器与 YarnSpinner 同源同构负责把 Yarn 编写、导出为 JSON 格式的对话树数据解析为可逐行消费的对话流。本指南以 GDevelop 仓库中随 Dialogue Tree 扩展一起分发的 bondage.js/README.md 为主体结合 bondage.js 的类型定义、GDevelop 扩展声明 与 运行时封装 dialoguetools.ts 中的真实集成代码带你掌握 bondage.js 的三种使用形态Web 工具、命令行、Node 库、Runner核心 API、三种对话结果类型以及 Yarn 语法在 JSON 数据中的真实表达方式。bondage.js 是什么Yarn 脚本的 JavaScript 解析器bondage.js 定位非常明确Yarn parser for Javascript即把 Yarn 对话编辑器产出的对话数据解析为 JavaScript 运行时可直接消费的结构其设计思路与 YarnSpinner 一脉相承。所谓 YarnYarn Spinner是一套以节点node/ 分支branch为基本单位的对话脚本体系一段对话由若干分支组成每个分支包含正文文本、可跳转链接、快捷选项、变量与命令最终编译/导出为 JSON 数组。在 GDevelop 中bondage.js 被 Dialogue Tree 扩展以固定版本内置见 bondage.js/version.txt其中明确说明当前构建基于 bondage.js 仓库 commit3c63e21。也就是说你在 GDevelop 中通过 Dialogue Tree 扩展编写、加载的对话底层正是由这份 bondage.js 源码完成解析与推进的。从 bondage.d.ts 的类型声明可以清晰看出其 API 全貌declare namespace bondage { export class Runner { yarnNodes: any; // 已加载的节点集合 variables: any; // 对话状态变量存储 functions: any; // 注册的自定义函数 visited: any; // 分支访问记录 load(data: any[]): void; // 加载节点数组 setVariableStorage(storage: any): void; // 替换变量存储 registerFunction(name: string, func): void; // 注册自定义函数 run(startNode: string): any; // 从指定节点启动返回迭代器 // ... 内部求值方法 } export class Result {} export class TextResult extends Result { text: string; data: any; lineNum: number; } export class CommandResult extends Result { text: string; data: any; lineNum: number; } export class OptionsResult extends Result { options: string[]; lineNum: number[]; selected: number; select(index: number): void; } }Runner是使用 bondage.js 的入口load()载入对话数据run()返回一个可迭代的对话流遍历该迭代器即可逐条获得TextResult普通对白、OptionsResult选项分支或CommandResult命令三种结果。三种使用方式作为 Web 工具在线试玩bondage.js 提供了浏览器端在线编译体验打开官方在线页面把 Yarn 数据粘贴到输入框并点击 compile即可在浏览器中直接运行对话、查看解析结果。这种方式适合快速验证一段 Yarn 脚本的语法与流程是否正确无需搭建本地环境。作为命令行工具CLI全局安装即可获得bondage命令npm install -g bondage安装后可用bondage命令在命令行中运行 Yarn 文件支持一次加载一个或多个文件。当同时加载多个文件、且两个节点出现同名时后加载的节点会覆盖先加载的节点这一行为在使用模块化对话文件拆分大型剧情时尤其需要注意命名冲突。常用命令示例命令中的yarnfile.json即 Yarn 编辑器导出的 JSON 对话数据# 从默认起始节点名为 Start运行单个文件 bondage run yarnfile.json # 从指定节点运行单个文件 bondage run -s StartNode yarnfile.json # 从指定节点运行多个文件 bondage run -s StartNode yarnfile1.json yarnfile2.json ... # 查看编译后的 AST抽象语法树 bondage compile --ast yarnfile.json # 查看词法分析tokenized后的输入 bondage compile --tokens yarnfile.json其中compile --ast与compile --tokens是排查对话数据语法问题的利器前者展示解析器对脚本建立的语法树结构后者展示分词结果两者结合可以快速定位脚本中括号不匹配、命令格式错误等隐患。作为库Node.js / 浏览器浏览器端在 HTML 中引入dist/bondage.min.js当前仓库内路径为 Extensions/DialogueTree/bondage.js/dist/bondage.min.jsbondage变量即挂载到全局作用域之后即可通过bondage.Runner等使用全部能力。GDevelop 的 Dialogue Tree 扩展正是通过这种方式引入它在 JsExtension.js 与第 81 行扩展为相关动作声明了 include 文件Extensions/DialogueTree/bondage.js/dist/bondage.min.js游戏导出的运行时因此会自动带上这份解析器。Node.js 端安装后按 CommonJS 方式引入npm install bondageconst fs require(fs); const bondage require(bondage); const runner new bondage.Runner(); const yarnData JSON.parse(fs.readFileSync(yarnFile.json)); runner.load(yarnData); // 从名为 Start 的节点开始遍历整个对话流 for (const result of runner.run(Start)) { if (result instanceof bondage.TextResult) { // 普通对白文本 console.log(result.text); } else if (result instanceof bondage.OptionsResult) { // 选项结果既适用于节点间的 [[链接]]也适用于快捷选项shortcut console.log(result.options); // 按选项在数组中的索引进行选择 // 若不做选择对话将直接跳过这些选项继续向后推进 result.select(1); } else if (result instanceof bondage.CommandResult) { // 包裹在 here 中的文本会以 CommandResult 形式返回 // 可按照你的需要任意使用如触发游戏事件 console.log(result.text); } } // 手动推进对话获取迭代器后逐次调用 next() const d runner.run(Start) let result d.next().value; let nextResult d.next().value; // 以此类推……这段示例揭示了 bondage.js 的核心设计run()返回一个生成器generator迭代器对话流是惰性求值的——每次next()才推进到下一句。OptionsResult的select(index)决定进入哪个分支如果一直不调用select对话会忽略选项继续往后走。类型判定则通过instanceof针对三种Result子类分发处理逻辑这套模式也正是 GDevelop 运行时封装所遵循的详见后文。结合源码看三种结果类型的真实流转GDevelop 的 dialoguetools.ts 是 bondage.js 在真实游戏引擎中的集成范本其内部维护了dialogueData变量类型正是bondage.TextResult | bondage.CommandResult | bondage.OptionsResult第 15–19 行并在startFrom()第 517–570 行中用instanceof依次判断结果类型、据此设置dialogueDataType为text、options或commandfunction _isLineTypeText() { return dialogueData instanceof bondage.TextResult; } function _isLineTypeOptions() { return dialogueData instanceof bondage.OptionsResult; } function _isLineTypeCommand() { return dialogueData instanceof bondage.CommandResult; }而核心推进函数goToNextDialogueLine()第 590–670 行则完整复刻了 README 中手动推进的迭代器用法dialogue runner.run(startDialogueNode)后每次通过dialogue.next().value取出下一条结果按类型分别刷新对白文本TextResult、选项列表OptionsResult记录options与optionsCount或命令队列CommandResult把cmd param拆分为{ cmd, params, time }压入commandCalls。也就是说README 中那段 30 行左右的库调用示例正是引擎级对话系统的最小可用实现。Yarn 数据格式与语法要素仓库测试数据佐证bondage.js 消费的是 Yarn 导出的 JSON 数组每个元素是一个分支节点结构如下取自 bondage.js/tests/links.json[ { title: ThreeNodes, tags: , body: This is a test line\nThis is another test line[[Option1]]\n[[Option2]], position: { x: 449, y: 252 }, colorID: 0 }, { title: Option1, tags: , body: This is Option1s test line, position: { x: 770, y: 84 }, colorID: 0 } ]title分支名Runner.run(title)以它作为对话起点tags分支标签可附带参数如tags(param1,param2)GDevelop 端通过branchContainsTag条件配合getTagParameter表达式读取body分支正文其中混排 Yarn 语法position/colorIDYarn 编辑器用于节点画布布局的元数据运行时解析可忽略。结合 tests 下的五个测试数据文件可以归纳出 bondage.js与 YarnSpinner 一致的核心语法要素1. 节点链接links——links.json直接链接[[Option1]]显示文本与目标分支同名命名链接[[First choice|Option1]]|前为显示文本后为目标分支单个链接自动穿越OneLinkPassthrough分支中First test line后接[[Option1]]运行到链接时直接进入目标分支链接可与快捷选项共存LinkAfterShortcuts先渲染两个-快捷选项再渲染两个[[...|...]]链接。2. 快捷选项shortcuts——shortcuts.json基础写法- Option 1后换行以制表符缩进\t写出选中后播放的文本嵌套- shortcut1下再缩进一层写- nestedshortcut1形成多级选择树条件化选项- Option 2 if 1 0条件为假时该选项不出现。3. 变量赋值assignment——assignment.jsonset $testvar -123.4赋数值set $testvar Variable String赋字符串set $testvar true赋布尔值支持表达式set $testvar (1 2) * -3 4.3、字符串拼接Variable String Appended、布尔逻辑(true || false) (false || !false)以及变量引用set $secondvar $firstvar、-4.3 $firstvar。变量以$前缀标识存储在Runner.variables中。4. 条件分支conditions——conditions.jsonif $testvar 321…endif单分支if ...…else…endif双分支elseif ...多级判断可在判断内嵌套[[链接]]与set如Objective分支所示构成完整的分支剧情逻辑测试中还展示了visited(NodeName)函数式判断节点是否访问过。5. 命令与函数commands and functions——commandsandfunctions.jsoncommand、command with space触发命令stop终止对话callFunction()、callFunctionWithParam(test,true,1,12.5,[2,3])调用函数支持字符串、布尔、数值、数组参数if testfunc(firstarg, secondarg)允许函数作为条件判断。这些语法完全向后兼容 YarnSpinner 的文档约定——README 明确指出 YarnSpinner 文档中的用法在这里同样适用若有出入则以 issue 反馈。在 GDevelop 中集成从 Yarn JSON 到游戏对话GDevelop 的 Dialogue Tree 扩展把上述 bondage.js 能力封装成了可视化动作、条件与表达式入口都在 JsExtension.js加载对话数据Load dialogue tree from a scene variablegdjs.dialogueTree.loadFromSceneVariable把存放于场景变量的 Yarn JSON 字符串交给runner.load()Load dialogue tree from a JSON filegdjs.dialogueTree.loadFromJsonFile则通过游戏的 JsonManager 异步加载 JSON 资源后再runner.load()。两者均可传入起始分支名为空则只加载不启动见 dialoguetools.ts 第 35–89 行。推进对话goToNextDialogueLinegdjs.dialogueTree.goToNextDialogueLine对应迭代器的next()IsDialogueLineType条件用text / options / command三种取值区分当前行类型让事件表可以按类型分支渲染。选项交互selectNextOption/selectPreviousOption/selectOption改变选中项confirmSelectOption调用OptionsResult.select()并推进到下一节点对应 dialoguetools.ts 第 364–393 行。对话状态持久化saveState/loadState/clearState序列化runner.variables.data与runner.visited到全局变量使玩家选择可以写入游戏存档dialoguetools.ts 第 853–891 行。命令驱动游戏逻辑IsCommandCalled条件配合getCommandParameter表达式把command withParameter拆解为游戏事件wait命令还会自动暂停文本滚动配合Scroll clipped text动作即可实现打字机效果。这套封装的运行依赖关系在 JsExtension.js 中写得很直白每个加载动作都同时 includedialoguetools.js与bondage.js/dist/bondage.min.js——前者是 GDevelop 的封装层后者是本文主角 bondage.js 解析器本体。版本与兼容性注意事项本仓库内置的 bondage.js 构建来自上游仓库 commit3c63e21见 version.txt与 NPM 最新版可能存在差异加载 Yarn JSON 时要求数据结构为Runner.load(data: any[])所需的节点数组格式即上文的{title, tags, body, ...}结构多个文件合并加载时同名节点后者覆盖前者README 明示拆分对话文件时请保证分支名全局唯一若发现 bondage.js 的解析行为与 YarnSpinner 文档不符README 建议向 bondage.js 仓库提交 issue 反馈。综上bondage.js 以极小的 API 面一个Runner、三种Result子类、一个生成器式run()覆盖了 Yarn 对话脚本从解析到推进的全部运行时需求而 GDevelop 的 Dialogue Tree 扩展与bondage.js/tests中的测试数据则为它在浏览器、Node 与游戏引擎三种环境下的真实用法提供了可对照、可复现的完整样例。【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考