Tuesday JS事件系统揭秘：dialog_end、script_loaded回调如何让你扩展引擎

Tuesday JS事件系统揭秘：dialog_end、script_loaded回调如何让你扩展引擎

【免费下载链接】tuesday-jssimple web-based, free and open-source visual novel editor that can be used in a web browser. It is written in JavaScript without using any third party libraries and thus does not require additional software installation. The engine uses standard HTML document elements such as div and img.项目地址: https://gitcode.com/gh_mirrors/tu/tuesday-js

Tuesday JS是一个用纯 JavaScript 编写的免费开源网页视觉小说引擎，不依赖任何第三方库，用标准的div、img等 HTML 元素渲染内容。本文带你深入它的事件系统：借助dialog_end（对话框文字播完）与script_loaded（剧情脚本加载完成）这两个核心回调，你无需改动引擎源码，就能注入自己的逻辑、写出专属插件。

一、Tuesday JS 视觉小说引擎为什么好扩展？

它把扩展性做进了设计底层，主要靠三点支撑：

• 纯 JS、零依赖：引擎本体只有一个tuesday.js文件，全部源码可读可查
• 基于标准 HTML 渲染：界面都是真实 DOM 元素，可以直接用原生 JS 修改
• 事件回调机制⚡：引擎在关键节点主动派发事件，你用标准的addEventListener监听即可接管时机

二、快速获取 Tuesday JS 项目文件（git clone 步骤）

git clone https://gitcode.com/gh_mirrors/tu/tuesday-js

克隆完成后，重点关注这三个模块：

三、Tuesday JS 事件系统原理：一个元素，统管所有回调

事件系统的精髓在于：所有事件都派发在同一个元素上——即页面中id="tuesday"的div。你只需要拿到这个元素，用标准 DOM 监听就能收到回调：

var tuesday = document.getElementById("tuesday"); tuesday.addEventListener("dialog_end", function (event) { // 在这里写你的扩展逻辑 });

完整事件清单（详见doc_runetime.html的 Events 章节）：

💡进阶细节：剧情块一开始，引擎还会自动派发一个与块名同名的事件（tuesday.js第 316 行）。例如名为Bank_robbery的块开始时就会触发Bank_robbery事件，相当于给"进入某场景"免费挂了个钩子。

四、script_loaded 回调：剧情加载完成的第一时机

script_loaded由tuesday.js中的load_story()函数在 JSON 读取成功、基础界面构建完毕后派发（data与file两种加载模式都会触发，见第 47 行和第 56 行）。此刻story_json变量已经就绪，适合做：

• 读取项目参数并动态注入 CSS
• 改造默认的控制按钮
• 触摸 / 键盘等插件的初始化

官方插件 plugins/touch_show.js 就是标准示范，它的第一行正是：

tuesday.addEventListener("script_loaded", function () { // 注入光标动画样式，再注册触摸事件 });

五、dialog_end 回调：文字播完的精准时机

dialog_end在对话框的打字机文字完全显示之后派发（tuesday.js第 834 行）。官方文档明确说：可用于判断角色说话动画的结束时刻。

tuesday.addEventListener("dialog_end", function (event) { play_effect("character_blink"); });

常见用法：

• 让口型 / 音效动画与文字出现节奏精确同步
• 最后一段台词播完后自动推进剧情
• 说明文字结束后才弹出选择项

六、用事件系统扩展引擎的 3 个实战技巧

技巧 1：自定义事件——在 JSON 里埋一个触发点

在剧情脚本的任意对话中加一个"event"字段（tuesday.js第 655 行负责处理），脚本走到这里就会派发同名事件：

"dialogs": [ { "text": "你发现了一个秘密…", "event": "secret_found" } ]

再用 JS 监听它：

tuesday.addEventListener("secret_found", function () { showHint(); });

这样"剧情进度"与"代码逻辑"彻底解耦：编剧只负责埋点，程序员负责绑定效果。

技巧 2：变量事件——监听数值变化（_add / _set）

变量被修改时，引擎会自动派发"变量名 + 后缀"的事件（tuesday.js第 650、652 行）：

tuesday.addEventListener("health_points_set", function () { updateHUD(); // 血量变化，立即刷新血条 });

技巧 3：把回调写成独立插件

引擎没有任何封闭性——新建一个.js文件、写好addEventListener，在页面里用<script>引入即可。plugins/screen_control.js就是范例：它在script_loaded时接管按钮行为，在鼠标抬起时推进剧情，全程只靠事件系统，零侵入。

七、常见坑与最佳实践

• 🎯 监听正确的元素：所有事件都在tuesday元素上，而不是document。监听错了元素，回调会"静默失效"
• ⏱ 注意触发顺序：script_loaded（脚本已读）→script_executed（界面已建）→creation_dialog（对话已建）→dialog_end（文字播完）。要操作界面，至少等到script_executed
• ✍ 自定义事件名用英文：DOM 事件名区分大小写，建议小驼峰命名，避免与保留字冲突
• ⚠dialog_end要轻量：它每显示完一段文字就会触发一次，适合做触发信号，别塞重逻辑

写在最后

Tuesday JS 证明了一件事：小引擎不等于封闭引擎。dialog_end与script_loaded两个回调，让这套免费开源的视觉小说引擎成为一块可以随意扩展的画布。不妨从一行打印日志的监听器写起——说不定下一个官方插件，就出自你手。

【免费下载链接】tuesday-jssimple web-based, free and open-source visual novel editor that can be used in a web browser. It is written in JavaScript without using any third party libraries and thus does not require additional software installation. The engine uses standard HTML document elements such as div and img.项目地址: https://gitcode.com/gh_mirrors/tu/tuesday-js