在浏览器里点开一个链接两三秒后背景音乐响起立绘从画面两侧滑入对话框里的字一个一个往外蹦——这就是HTML5 GalGame 引擎最直观的样子。它做的事情说穿了不复杂把原本需要打包安装的视觉小说变成一套纯前端就能跑的内容玩家不用下载客户端开发者不用为 Windows、macOS、Android 各维护一份构建。我最早接触这类引擎是帮一个做独立剧本的朋友把一段十万字的故事搬上网页当时以为改改 CSS 就完事结果在剧本解析、立绘排程、存档结构上连着栽了好几个跟头。这套 HTML5 视觉小说引擎解决的正是这些问题用一套自定义剧本语法描述演出引擎负责把文字、立绘、背景、音乐、分支、存档串成一条可回放的指令流。适合谁看如果你会一点 JavaScript、想做个文字冒险 Demo 或完整的视觉小说项目或者你手头已经有一套引擎但被存档丢失、移动端音频不响、切场景白屏这些问题折磨过下面这些内容应该能省你不少时间。我会从一个引擎骨架怎么搭讲起一路拆到剧本解析器、演出层排程、资源加载策略和踩坑速查表代码和参数都尽量给到能直接抄的程度。1. 从能玩倒推架构H5 视觉小说引擎的整体设计思路1.1 为什么是网页而不是原生客户端先把这个选择说清楚因为它决定了后面所有技术细节。视觉小说这类内容的特征是画面以静态图为主、互动以点击为主、计算量极低、但对资源体积和首次加载速度极其敏感。一套完整的商业级作品背景加上立绘加上 CG动辄几百 MB 到几个 GB。原生客户端的好处是资源躺在本地磁盘读图几乎零延迟网页的短板恰恰在这里玩家点开链接的第一秒什么都还没下载。那为什么还要选网页我自己的判断标准有三条。第一是分发成本。分享一个链接和让玩家下载一个安装包转化率差一个数量级尤其是短篇作品、试玩版、活动企划这种看一眼就走的场景。第二是迭代速度。剧本改一句台词、换一张立绘重新部署一次静态资源就完事不用发版、不用过审、不用让玩家重新下载。第三是跨端一致性。同一份代码在桌面浏览器、手机浏览器、平板、甚至嵌入式浏览器里都能跑虽然要做适配但比维护三套原生渲染管线便宜太多。代价也很明确加载策略必须重新设计不能像原生那样要用什么读什么得靠预加载队列把玩家即将看到的内容提前拉到内存里音频在移动端有自动播放限制必须等一次真实用户交互才能解锁图片解码在主线程上会卡顿大图要考虑createImageBitmap或者分帧加载。这些后面都会展开。1.2 引擎骨架的四个核心模块我习惯把这类引擎拆成四层从上到下依次是剧本层、演出层、资源层、持久层。这个分层不是学术意义上的架构图而是按改哪里会炸哪里划分的改剧本语法只动第一层调动画曲线只动第二层换图床或加 CDN 只动第三层动存档结构则要小心第四层的向后兼容。剧本层负责把人类可读的剧本文本翻译成引擎能执行的指令序列。它是整个引擎里最像编译器的部分词法分析切 token、语法分析建抽象语法树、再把它编译成一个扁平的指令数组。之所以要编译成扁平数组而不是直接解释 AST是因为视觉小说有大量跳回上一句跳到某个标签快进到已读位置的操作扁平数组加索引寻址比树形遍历好实现太多。演出层是舞台调度管的是这一帧画面上有什么。背景、立绘、对话框、选项按钮、特效层各自是独立的渲染单元由一条时间轴统一驱动。这里最容易被低估的是状态同步玩家从存档读进来的时候舞台必须瞬间还原成存档那一刻的样子包括哪几个角色站在哪个位置、表情是什么、BGM 播到哪儿。资源层管加载、缓存、释放。核心指标是首屏时间和峰值内存。视觉小说的内存峰值通常出现在连续切换大背景的时候前一张还没释放、后一张已经解码完两张 1920×1080 的位图就能吃掉几十 MB。持久层管存档、已读标记、设置项。它看起来最简单实际上是最容易埋雷的地方——引擎版本一升级老存档读不出来玩家几十小时的进度就没了。1.3 引擎与内容的边界该划在哪这个问题我在项目初期纠结了很久哪些东西写进引擎哪些留给剧本作者我的结论是——凡是会改变演出节奏的交给剧本凡是会改变渲染方式的交给引擎。举个具体例子。立绘从左边滑入用时 400 毫秒缓动曲线是 ease-out——这属于演出节奏应该写在剧本里作者可以自己调。而立绘滑入时用 CSS transform 还是 canvas 逐帧重绘——这属于渲染方式写死在引擎里作者不该关心。边界划不清的典型症状是剧本里出现大量魔法参数比如show yuki center normal 400 ease-out 0.8后面一串数字作者自己都记不住。我的做法是给常用组合起别名show yuki center用默认的 300ms 淡入需要特殊效果才写完整参数。这样剧本读起来像剧本不像配置文件。提示剧本语法的第一原则是作者写起来顺手不是程序解析起来优雅。宁可让解析器多写两百行兼容代码也不要让作者每天查语法手册。2. 剧本解析器把一段文本变成可执行的演出指令2.1 为什么自造脚本语言而不是直接写 JSON很多人第一反应是剧本用 JSON 存不就行了。我试过结论是短期内爽、长期痛苦。JSON 的问题在于信噪比太低一句台词要包成{type:say,speaker:yuki,text:早上好。}十万字剧本写下来满屏都是花括号和引号作者改一句话要在三层嵌套里找位置还得时刻担心少个逗号导致整个文件解析失败。自造脚本语言的好处是语法可以贴着写作习惯长。上面那句台词在我的引擎里就是一行雪早上好。冒号前的部分自动识别为说话人冒号后的部分是台词。再复杂一点bg classroom_day fade 500 bgm bgm_daily vol0.6 show yuki center normal 雪早上好。 雪(今天的她好像有点不一样。) choice - 回应她 - greet - 假装没听见 - ignore :greet 雪嗯早。 set affection_yuki 3 jump ch01_after这套语法里只有三类东西指令行以开头、台词行说话人内容、标签行以:开头以及选项行以-开头。剩下的全是普通文本作者写起来接近写剧本软件。代价是解析器要自己写而且要考虑错误提示。我的经验是解析出错时一定要报行号和原始行内容否则作者面对一份几千行的剧本根本找不到问题在哪。这一点比语法本身优雅重要十倍。2.2 一条指令的完整生命周期从文本到执行中间要过四道关。我用一个最小可用的实现来说明逻辑上分四步预处理、分词、构建指令对象、编译成扁平数组。第一步预处理主要是统一换行符、去掉行尾空白、把连续空行折叠、处理注释我用的注释符号是//独立成行才算。这一步不解析语义只做规整好处是后面所有步骤都可以假设输入是一行一条的干净文本。第二步分词按行首字符判断类型开头是指令:开头是标签-开头且处于选项块内是选项其余是台词。指令行再按空格切分成命令名和参数参数里要支持keyvalue形式。function tokenizeLine(raw, lineNo) { const line raw.trim(); if (!line || line.startsWith(//)) return null; if (line.startsWith()) { const body line.slice(1); const firstSpace body.indexOf( ); const name firstSpace -1 ? body : body.slice(0, firstSpace); const argStr firstSpace -1 ? : body.slice(firstSpace 1); return { type: cmd, name, args: parseArgs(argStr), lineNo }; } if (line.startsWith(:)) { return { type: label, name: line.slice(1).trim(), lineNo }; } if (line.startsWith(-)) { return { type: option, raw: line.slice(1).trim(), lineNo }; } const idx line.indexOf() ! -1 ? line.indexOf() : line.indexOf(:); if (idx 0) { return { type: say, speaker: line.slice(0, idx).trim(), text: line.slice(idx 1).trim(), lineNo }; } return { type: say, speaker: null, text: line, lineNo }; }注意那个中英文冒号的兼容判断。中文剧本作者用全角冒号是常态解析器必须两种都认否则会出现说话人识别不出来、整句被当成旁白的诡异 bug。这个坑我踩过一次排查了半小时才发现是输入法的问题。第三步构建指令对象把分词结果映射成带执行语义的对象同时做静态检查jump的目标标签是否存在、show的角色是否在角色表里注册过、选项块是否成对闭合。这一步能在加载阶段就把剧本错误暴露出来而不是等玩家玩到第三小时才崩。第四步编译成扁平数组把标签位置记录成索引映射表function compile(tokens) { const program []; const labels Object.create(null); let i 0; while (i tokens.length) { const t tokens[i]; if (t.type label) { labels[t.name] program.length; i; continue; } if (t.type option) { const options []; while (i tokens.length tokens[i].type option) { const m tokens[i].raw.match(/^(.*?)\s*-\s*(\S)$/); if (!m) throw new Error(第 ${tokens[i].lineNo} 行选项格式错误); options.push({ text: m[1].trim(), target: m[2] }); i; } program.push({ op: choice, options }); continue; } if (t.type cmd) { program.push(buildCommand(t)); i; continue; } program.push({ op: say, speaker: t.speaker, text: t.text, lineNo: t.lineNo }); i; } return { program, labels }; }扁平数组加标签映射表带来的直接好处是存档只需要存一个整数——当前执行到第几条指令。读档时把指针一设从那条指令往后重新跑一遍舞台还原就能回到存档瞬间。这个设计我在后面讲存档时会再提。2.3 变量、条件与好感度让分支真正有用纯线性的视觉小说用不上变量但只要有分支玩家就会期待我前面选的话有影响。最小可用的变量系统包含三样东西赋值、比较、条件跳转。赋值的写法我设计成set 变量名 运算符 值比如set affection_yuki 3。解析时要支持、、-三种值可以是数字、布尔或者字符串。别小看这个设计比先读再写少写一行剧本里几十个好感度累加点省下来的行数很可观。条件跳转用if加endif包住一段指令或者更简单的jumpif 条件 - 标签jumpif affection_yuki 10 - good_route jumpif has_key true - secret_room条件表达式的解析有两种走法。稳妥的是自己写一个极简表达式求值器只支持比较运算符和逻辑与或偷懒且危险的是直接new Function(vars, with(vars){return expr })。后者性能好、写法灵活但剧本文件如果来自不可信来源这就是一个任意代码执行的口子。我的建议是内部项目图省事可以用对外分发的内容一律用受限求值器白名单只放行变量名、数字、比较符和、||。还有一个细节容易被忽略变量作用域。全局变量跨章节共享没问题但临时变量比如某个小游戏的结果如果不隔离会在后面的章节里意外命中。我的做法是给变量加前缀约定g_开头是全局、t_开头是当前场景临时场景切换时清掉t_前缀的全部键。这是个土办法但比引入真正的作用域链省事得多。3. 演出层立绘、文字、转场到底怎么排程3.1 DOM 还是 Canvas这个选择要一次做对这是绕不开的第一个技术选型。两条路的差别很大而且改起来成本极高基本等于重写演出层。DOM 方案的思路是把背景、立绘、对话框都做成div或img转场和动画交给 CSS transition / animation。优点是上手快、文字渲染天然清晰、无障碍和选中复制免费、调试时可以直接在开发者工具里改样式看效果。缺点是元素一多合成层管理会失控尤其是多个立绘同时做滤镜和位移的时候移动端掉帧明显。Canvas 方案的思路是自己管绘制循环所有东西画到一个canvas上。优点是渲染完全可控、可以做复杂的图层混合和粒子特效、元素数量对性能影响小。缺点同样明显文字排版要自己处理换行、标点避头尾、字体加载文本选中和缩放适配都得手写。我的实战结论是混合方案最省心背景和立绘用 DOM CSS transformtranslate3d走 GPU 合成对话框文字也用 DOM而需要复杂特效的部分比如雨滴、樱花、胶片颗粒单独开一个 canvas 覆盖层只在需要的时候启用。具体参数上立绘容器的写法大概是.char-layer { position: absolute; inset: 0; pointer-events: none; will-change: transform, opacity; } .char { position: absolute; bottom: 0; height: 92%; transform: translate3d(-50%, 0, 0); transition: transform .3s cubic-bezier(.22,.61,.36,1), opacity .3s ease; backface-visibility: hidden; }will-change和translate3d是让浏览器提前把这个元素提升为独立合成层位移和透明度变化就不用重绘整页。但will-change别乱加常驻几十个元素都开显存会被吃光移动端直接闪退。我的做法是只在动画开始前动态加、结束后移除。3.2 打字机效果三种实现和它们的坑台词逐字显示是视觉小说的标志性效果看起来简单实现方式却直接影响体验。第一种是setInterval定时器每 30 毫秒追加一个字。最直观但问题一大堆标签页切到后台定时器被浏览器降频到 1 秒一次回来时文字卡住快速点击跳过时定时器没清干净新旧两个定时器同时往里塞字文字会乱序。第二种是requestAnimationFrame加时间累计。每帧算一次从开始到现在过了多少毫秒应该显示到第几个字然后一次性把字符串切到那个位置。这是我目前主用的方案理由是它天然对齐屏幕刷新率后台标签页会被自动暂停回来继续不会出现时间错乱。核心逻辑就几行let startTime 0; let shown 0; const SPEED 33; // 每字 33ms约 30 字/秒 function tick(now) { if (!startTime) startTime now; const target Math.min(text.length, Math.floor((now - startTime) / SPEED)); if (target ! shown) { shown target; textEl.textContent text.slice(0, shown); } if (shown text.length) rafId requestAnimationFrame(tick); }第三种是纯 CSS 方案把每个字包成span用animation-delay逐个触发 opacity 从 0 到 1。优点是零 JS 开销、动画流畅。缺点是 DOM 节点数量爆炸一段 200 字的台词就是 200 个 span而且点击后立刻显示全部需要额外写 CSS 覆盖跳字体验不干脆。我一般在短句或者标题演出上用长段台词还是走 rAF。方案流畅度跳字处理DOM 开销后台标签行为适用场景setInterval 追加一般需手动清定时器低被降频易错乱不推荐rAF 时间累计高直接设 shown长度低自动暂停恢复主用方案CSS 逐字动画高需覆盖样式高正常短句、标题注意跳过全部文字时除了把显示位置设到末尾还要记得清掉在跑的 rAF 句柄并置空。忘了这一步会出现跳过后又被定时器重写回去的经典 bug。3.3 转场的时间轴调度转场是视觉小说里最能体现质感的部分也是最容易写成面条代码的部分。我的做法是引入一个极简的时间轴队列所有演出动作淡入、位移、闪烁、震动都包装成「时长 进度回调」的对象统一压进队列由一个调度器串行执行。class Timeline { constructor() { this.queue []; this.running false; } push(action) { this.queue.push(action); return this; } async run() { if (this.running) return; this.running true; while (this.queue.length) { const act this.queue.shift(); await act(); } this.running false; } }每个 action 返回一个 Promise内部用 rAF 推动进度进度到 1 就 resolve。这样写的好处是时序关系一目了然先淡出旧背景400ms再淡入新背景400ms再显示立绘300ms三行代码读起来就是演出顺序。有个细节值得单独说可打断性。玩家等不及转场就点了下一步这时候你是让转场跑完还是立刻跳到终态我的选择是后者——玩家点击时立刻把所有正在跑的动画设到终点并 resolve然后继续执行后续指令。实现上就是给每个 action 加一个finish()方法调度器在收到跳过信号时挨个调用。不做这个处理玩家狂点之后会看到一堆动画叠在一起画面糊成一团。3.4 音频通道BGM、音效、语音不能挤在一条道上音频管理看着简单实际上通道划分决定了能不能做出音乐渐弱、语音打断这类效果。我的划分是BGM 通道只有一个切换时做 300 到 800 毫秒的交叉淡入淡出。视觉小说里音乐经常跨场景延续所以指令设计上要区分换 BGM和继续当前 BGM。环境音通道独立于 BGM比如雨声、风声、教室的嘈杂。允许和 BGM 同时存在。音效池短音效脚步声、开门声、翻页声用对象池管理同时最多 8 个实例超了就复用最早的。别每次new Audio()节点会越积越多。语音通道单独一条新语音进来时立刻打断上一条。这一条是硬需求玩家快速点击时如果语音排队播放会听到一堆叠在一起的台词。音量上要注意的是人耳感知不是线性的。滑块拉到 50%实际感知响度远不止一半。建议用gain Math.pow(slider, 2)做一次映射主观听感才接近线性。这是个小细节但设置面板做得好不好玩家一耳朵就能听出来。4. 资源管理与加载首屏三秒决定玩家走不走4.1 预加载队列该按什么顺序排视觉小说的资源加载不能要用了才去拉否则每次切场景都是一次白屏。但也不能一上来就把几百 MB 全拉下来手机流量用户会直接关掉页面。我的做法是三级队列。第一级是阻塞式加载首屏必需的背景、UI 图、字体、第一段 BGM没加载完不进场配一个进度条。第二级是当前场景的剩余资源进场之后立刻在后台拉当前章节的所有立绘表情和音效。第三级是下一场景的预取玩家进入到本章中段时开始预取下一章的首屏资源。优先级判断上除了静态的章节顺序还要加一条动态权重玩家最近两分钟内用过的角色立绘排到队伍前面。因为视觉小说的剧情往往集中在一两个角色身上把他们的所有表情都缓存住命中率能到八九成。const loader { queue: [], cache: new Map(), add(url, priority 0) { if (this.cache.has(url)) return Promise.resolve(this.cache.get(url)); return new Promise((resolve, reject) { this.queue.push({ url, priority, resolve, reject }); this.queue.sort((a, b) b.priority - a.priority); this.pump(); }); }, pump() { const CONCURRENCY 4; while (this.active CONCURRENCY this.queue.length) { const job this.queue.shift(); this.active; const img new Image(); img.onload () { this.cache.set(job.url, img); job.resolve(img); this.active--; this.pump(); }; img.onerror () { job.reject(new Error(job.url)); this.active--; this.pump(); }; img.src job.url; } } };并发数设 4 是个经验值。HTTP/1.1 下浏览器同域并发上限是 6留两个名额给接口和字体HTTP/2 下理论上可以更多但图片解码是主线程瓶颈开太多反而互相拖慢实测 4 到 6 之间最稳。4.2 图片格式与体积几个能立刻生效的参数资源体积是这类项目最大的成本项。下面这几个参数是我反复调过的效果直接。资源类型推荐格式尺寸上限单张体积目标说明背景WebP 有损 q821920×1080200–300 KB保留一份 JPEG 兜底立绘WebP 带透明 q85高 1100px150–250 KB别用 PNG透明通道体积翻倍CGWebP 有损 q881920×1080250–400 KB鉴赏模式才加载缩略图WebP q70480×27020–40 KB存档和画廊用BGMMP3 128kbps 或 OGG—1–2 MB/分钟长循环曲目可降码率语音OGG 单声道 64kbps—极低人声不需要立体声几个实测出来的经验立绘如果按 4K 出图再缩放手机上解码会卡顿几百毫秒直接按最终显示高度的 1.5 倍出图最划算背景图加一点点噪点或者纹理WebP 压缩后的体积反而更小因为大面积纯色渐变是压缩器的噩梦透明立绘的边缘如果有半透明羽化WebP 比 PNG 省一半以上体积而且视觉上看不出差别。4.3 缓存策略与版本号资源更新不能炸存档静态资源部署之后最头疼的是玩家浏览器里缓存着旧图。文件名加内容哈希是最稳的方案bg_classroom_day.a3f9c1.webp内容一变哈希就变天然避开缓存问题。代价是剧本里要引用带哈希的路径所以我在构建阶段做了一层映射剧本里写逻辑名bg_classroom_day构建时替换成真实路径。另一半问题是存档兼容。玩家存了档你更新了版本加了一个新角色、删了一个旧背景读档时怎么还原我的做法是存档里只存逻辑名和变量值不存资源路径读档时如果某个资源找不到用一张占位图代替并记一条警告而不是直接抛异常让整个存档作废。玩家看到一张灰色占位图总比看到存档损坏要好。再补一条存档格式要带版本号和迁移函数。我吃过一次亏中期改了一版存档结构把chars数组改成对象结果测试群里十几个人的进度全废了。后来加了migrate(save)函数按version字段逐级升级从此再没出过事。5. 存档、回放与分支最容易翻车的三块5.1 快照式存档和指令流存档的取舍存档有两种思路。快照式是把当前舞台的完整状态序列化下来背景是什么、立绘有谁站在哪、BGM 是哪首播到第几秒、所有变量当前的值、当前执行到第几条指令。指令流式只存一个起点和一个操作序列读档时重放。维度快照式指令流式存档体积大含全部舞台状态小几个索引读档速度快直接还原慢要重放兼容性结构一变就废剧本一改就错位实现难度中低适合场景商业项目、长期运营短篇、Demo我最终选的是混合式主体用快照但额外存一个指令索引和最近的 20 条台词历史。快照保证读档秒开指令索引用于从存档点回看剧情历史则用来填充回想界面的文本记录。存档结构大致长这样{ version: 3, saveId: slot_02, timestamp: 1730000000000, chapter: ch01, pointer: 482, stage: { bg: classroom_day, bgm: { name: bgm_daily, volume: 0.6 }, chars: [ { id: yuki, pos: center, expr: normal, alpha: 1 } ] }, vars: { g_affection_yuki: 12, g_has_key: true }, history: [ { speaker: yuki, text: 早上好。 } ] }注意stage.chars里存的是逻辑 id 和表情名不是图片路径。这一层间接让换美术素材不用动存档。5.2 已读标记、跳过与自动播放这三个功能玩家用得最多做不好被吐槽也最多。已读标记的核心是给每条台词一个稳定标识。用台词文本的哈希会出问题——改一个错别字整条记录就失效了玩家重玩时会发现这句明明读过却不算已读。我的做法是章节id 指令索引组合成键改文本不影响改结构才失效后者本来就不可避免。存储位置上localStorage的容量通常只有 5MB 左右一条记录按 20 字节算十万条台词就是 2MB勉强够用但很危险而且localStorage是同步 API读写会阻塞主线程。台词量大的项目我建议换 IndexedDB异步、容量大代价是首次要写一套 Promise 封装。跳过功能要区分跳过已读和跳过全部。前者是大多数玩家的默认需求后者一般只在选错路线时用。实现上跳过模式就是一个加速倍率把打字机速度设为 0、转场时长设为 0然后在每条指令执行完后检查这条是不是已读是就继续跳不是就停在原地等玩家确认。这里有个坑跳过时如果遇到选项必须强制停下否则会直接跳过分支节点剧情跑飞。自动播放的节奏控制是门玄学。固定延迟比如每句停 2 秒体验很差因为短句等太久、长句不够看。我的做法是按字数算基础时长再加一个固定尾巴delay 800 text.length * 60毫秒上限 6 秒。语音播放时则以语音时长为准播完再等 400 毫秒。5.3 分支与结局管理别让剧情变成一团毛线分支一多剧本维护就会失控。我见过最夸张的一个项目三十多个标签跳来跳去最后作者自己都说不清某个选项会通向哪里。我的做法是加一层章节清单用一个单独的配置描述章节之间的跳转关系export const chapters { ch01: { next: [ch02a, ch02b], entry: start }, ch02a: { next: [ch03], entry: start }, ch02b: { next: [ch03], entry: start }, ch03: { next: [], entry: start, endings: [good, normal, bad] } };这层清单不参与运行时逻辑只用于三件事加载时做完整性校验有没有指向不存在章节的跳转、做流程可视化自动生成一张章节关系图作者能一眼看出结构、做测试覆盖率统计哪些分支从来没被跑到过。第三点特别有用我一般在开发环境里跑一个自动化脚本把所有分支随机走几百遍把没覆盖到的标签列出来补测试的效率高很多。6. 常见问题与排查实录6.1 移动端音频不响八成是第一下点击没接住浏览器对自动播放的限制几乎是所有 H5 音频问题的根源。表现是桌面正常手机打开没声音或者第一句台词有声音、切场景之后没了。根本原因是音频上下文在没有用户手势的情况下处于 suspended 状态。解决办法是在首次真实点击touchend或click不要用touchstart时创建或唤醒音频上下文并播一个静音 buffer 解锁let unlocked false; document.addEventListener(touchend, async function once() { if (unlocked) return; const ctx new (window.AudioContext || window.webkitAudioContext)(); if (ctx.state suspended) await ctx.resume(); const buf ctx.createBuffer(1, 1, 22050); const src ctx.createBufferSource(); src.buffer buf; src.connect(ctx.destination); src.start(0); unlocked true; document.removeEventListener(touchend, once); }, { passive: true });另外iOS 上把手机调成静音模式时audio标签播放的媒体是静音的这条无解只能靠界面提示引导玩家关闭静音。还有一点切到后台再回来音频上下文可能又回到 suspended需要在visibilitychange里重新resume()。6.2 文字溢出与排版中文的换行比英文难搞英文有词边界中文没有所以标点避头尾就成了必须处理的问题。默认情况下句号、逗号可能出现在行首括号可能被拆成两半观感很差。CSS 层面加上这几行能解决大部分问题.dialogue-text { line-break: strict; word-break: normal; overflow-wrap: break-word; text-align: justify; text-justify: inter-ideograph; line-height: 1.75; }line-break: strict让浏览器按严格的避头尾规则断行。字体方面中文网页字体动辄十几 MB直接引入会让首屏时间翻倍。实用方案是系统字体栈优先只在标题等少量文字上用子集化的 WOFF2。做子集的时候别只截常用三千字剧本里出现的生僻字、人名用字要单独扫一遍加进去否则会出现某个角色名字显示成方框的尴尬情况。还有一个隐蔽的坑line-height设得刚好等于字号会让行间距显得挤中文尤其明显。我的经验值是字号的 1.7 到 1.8 倍阅读舒适度最好。6.3 常见问题速查表现象可能原因排查方向处理方式切场景白屏一闪图片未预加载看网络面板是否有新请求提前预取下一场景首屏资源读档后立绘位置错乱存档未记录舞台状态检查 stage 字段存档补全 chars 的 pos/alpha点击无响应遮罩层吃掉事件检查pointer-events装饰层统一设 none快速点击后文字乱序定时器未清理检查是否有多个 rAF跳字时统一清句柄存档读不出来版本结构变更对比存档 version写 migrate 逐级升级立绘边缘有白边预乘 Alpha 问题换 PNG 对比测试导出时关闭预乘或改用 WebP长台词滚动条出现容器高度写死检查 dialog 高度改成 max-height 内部滚动跳过时跑飞分支选项未拦截跳过检查 choice 指令遇到 choice 强制停跳提示排查这类问题最有效的手段是做一个调试面板把当前指针位置、变量值、舞台状态实时打印出来按一个键切换显示。比在控制台里一行行console.log快十倍而且上线前把开关关掉就行。6.4 几个只有做过才知道的经验第一条别在剧本里写绝对时间。wait 3000这种指令看着方便玩家开了二倍速之后就会变成必须干等三秒的折磨。等待时长应该由引擎的速度倍率统一缩放剧本里只写等一个节拍这种相对量。第二条资源加载失败要有兜底。网络抖动、CDN 抽风都是常态一张背景图挂了不该让整个游戏卡死在加载页。我的做法是图片 onerror 后重试两次仍失败就用同色系纯色块加文字说明代替并记录下来游戏继续。第三条测试要在真机上跑。桌面浏览器缩放窗口模拟移动端和真机完全是两回事尤其是 iOS Safari 的内存限制——一个页面占用超过几百 MBSafari 会直接刷新页面表现就是玩到一半突然回到开头。这个问题的排查成本极高预防手段是控制同时驻留的大图数量及时释放不可见章节的缓存。第四条给作者做一个预览工具。剧本作者不可能每次都构建部署再看效果我在引擎里加了一个开发模式支持单章热重载和标签跳转改一行剧本刷新就能看到作者的迭代速度提升非常明显。这个投入在项目中期就会回本。7. 部署与后续扩展的几点实操建议部署这块没什么花活静态资源扔到任意对象存储加 CDN 就能跑。几个参数值得调开启 Brotli 压缩文本资源能再省 20%给带哈希的静态资源设一年强缓存index.html设不缓存跨域隔离相关的响应头如果不需要 SharedArrayBuffer 就别开开了反而容易在嵌入场景里出问题。后续扩展上我觉得有三个方向性价比最高。一是多语言把台词抽到外部语言包引擎层只认 key切换语言时重新编译剧本。这件事前期做成本很低后期补就是灾难。二是云存档本地存档加一个可选的账号同步玩家换设备能接着玩实现上就是存档 JSON 传一份到服务端注意做冲突合并策略。三是数据埋点统计玩家在哪个选项停得最久、哪条路线走得最多这些数据对后续创作的参考价值远比想象中大。我个人在实际项目里最深的一点体会是这类引擎的复杂度不在技术本身而在使用它的作者。一个语法设计得再优雅作者用着别扭就是失败一个功能实现得再精巧作者不知道怎么调参数就是白做。所以每次加新特性之前我都会先问自己一句——这个东西是给玩家看的还是给作者用的如果是给作者用的那文档和默认值的重要性可能超过代码本身。最后分享一个小技巧给剧本解析器加一个严格模式开关开发时打开遇到未注册的角色、未定义的标签、拼错的指令名直接报错中断上线时关掉遇到问题降级成警告继续跑。这个开关帮我拦下过大量低级错误也让线上版本不至于因为一处笔误就整章崩掉。
在浏览器里点开一个链接两三秒后背景音乐响起立绘从画面两侧滑入对话框里的字一个一个往外蹦——这就是HTML5 GalGame 引擎最直观的样子。它做的事情说穿了不复杂把原本需要打包安装的视觉小说变成一套纯前端就能跑的内容玩家不用下载客户端开发者不用为 Windows、macOS、Android 各维护一份构建。我最早接触这类引擎是帮一个做独立剧本的朋友把一段十万字的故事搬上网页当时以为改改 CSS 就完事结果在剧本解析、立绘排程、存档结构上连着栽了好几个跟头。这套 HTML5 视觉小说引擎解决的正是这些问题用一套自定义剧本语法描述演出引擎负责把文字、立绘、背景、音乐、分支、存档串成一条可回放的指令流。适合谁看如果你会一点 JavaScript、想做个文字冒险 Demo 或完整的视觉小说项目或者你手头已经有一套引擎但被存档丢失、移动端音频不响、切场景白屏这些问题折磨过下面这些内容应该能省你不少时间。我会从一个引擎骨架怎么搭讲起一路拆到剧本解析器、演出层排程、资源加载策略和踩坑速查表代码和参数都尽量给到能直接抄的程度。1. 从能玩倒推架构H5 视觉小说引擎的整体设计思路1.1 为什么是网页而不是原生客户端先把这个选择说清楚因为它决定了后面所有技术细节。视觉小说这类内容的特征是画面以静态图为主、互动以点击为主、计算量极低、但对资源体积和首次加载速度极其敏感。一套完整的商业级作品背景加上立绘加上 CG动辄几百 MB 到几个 GB。原生客户端的好处是资源躺在本地磁盘读图几乎零延迟网页的短板恰恰在这里玩家点开链接的第一秒什么都还没下载。那为什么还要选网页我自己的判断标准有三条。第一是分发成本。分享一个链接和让玩家下载一个安装包转化率差一个数量级尤其是短篇作品、试玩版、活动企划这种看一眼就走的场景。第二是迭代速度。剧本改一句台词、换一张立绘重新部署一次静态资源就完事不用发版、不用过审、不用让玩家重新下载。第三是跨端一致性。同一份代码在桌面浏览器、手机浏览器、平板、甚至嵌入式浏览器里都能跑虽然要做适配但比维护三套原生渲染管线便宜太多。代价也很明确加载策略必须重新设计不能像原生那样要用什么读什么得靠预加载队列把玩家即将看到的内容提前拉到内存里音频在移动端有自动播放限制必须等一次真实用户交互才能解锁图片解码在主线程上会卡顿大图要考虑createImageBitmap或者分帧加载。这些后面都会展开。1.2 引擎骨架的四个核心模块我习惯把这类引擎拆成四层从上到下依次是剧本层、演出层、资源层、持久层。这个分层不是学术意义上的架构图而是按改哪里会炸哪里划分的改剧本语法只动第一层调动画曲线只动第二层换图床或加 CDN 只动第三层动存档结构则要小心第四层的向后兼容。剧本层负责把人类可读的剧本文本翻译成引擎能执行的指令序列。它是整个引擎里最像编译器的部分词法分析切 token、语法分析建抽象语法树、再把它编译成一个扁平的指令数组。之所以要编译成扁平数组而不是直接解释 AST是因为视觉小说有大量跳回上一句跳到某个标签快进到已读位置的操作扁平数组加索引寻址比树形遍历好实现太多。演出层是舞台调度管的是这一帧画面上有什么。背景、立绘、对话框、选项按钮、特效层各自是独立的渲染单元由一条时间轴统一驱动。这里最容易被低估的是状态同步玩家从存档读进来的时候舞台必须瞬间还原成存档那一刻的样子包括哪几个角色站在哪个位置、表情是什么、BGM 播到哪儿。资源层管加载、缓存、释放。核心指标是首屏时间和峰值内存。视觉小说的内存峰值通常出现在连续切换大背景的时候前一张还没释放、后一张已经解码完两张 1920×1080 的位图就能吃掉几十 MB。持久层管存档、已读标记、设置项。它看起来最简单实际上是最容易埋雷的地方——引擎版本一升级老存档读不出来玩家几十小时的进度就没了。1.3 引擎与内容的边界该划在哪这个问题我在项目初期纠结了很久哪些东西写进引擎哪些留给剧本作者我的结论是——凡是会改变演出节奏的交给剧本凡是会改变渲染方式的交给引擎。举个具体例子。立绘从左边滑入用时 400 毫秒缓动曲线是 ease-out——这属于演出节奏应该写在剧本里作者可以自己调。而立绘滑入时用 CSS transform 还是 canvas 逐帧重绘——这属于渲染方式写死在引擎里作者不该关心。边界划不清的典型症状是剧本里出现大量魔法参数比如show yuki center normal 400 ease-out 0.8后面一串数字作者自己都记不住。我的做法是给常用组合起别名show yuki center用默认的 300ms 淡入需要特殊效果才写完整参数。这样剧本读起来像剧本不像配置文件。提示剧本语法的第一原则是作者写起来顺手不是程序解析起来优雅。宁可让解析器多写两百行兼容代码也不要让作者每天查语法手册。2. 剧本解析器把一段文本变成可执行的演出指令2.1 为什么自造脚本语言而不是直接写 JSON很多人第一反应是剧本用 JSON 存不就行了。我试过结论是短期内爽、长期痛苦。JSON 的问题在于信噪比太低一句台词要包成{type:say,speaker:yuki,text:早上好。}十万字剧本写下来满屏都是花括号和引号作者改一句话要在三层嵌套里找位置还得时刻担心少个逗号导致整个文件解析失败。自造脚本语言的好处是语法可以贴着写作习惯长。上面那句台词在我的引擎里就是一行雪早上好。冒号前的部分自动识别为说话人冒号后的部分是台词。再复杂一点bg classroom_day fade 500 bgm bgm_daily vol0.6 show yuki center normal 雪早上好。 雪(今天的她好像有点不一样。) choice - 回应她 - greet - 假装没听见 - ignore :greet 雪嗯早。 set affection_yuki 3 jump ch01_after这套语法里只有三类东西指令行以开头、台词行说话人内容、标签行以:开头以及选项行以-开头。剩下的全是普通文本作者写起来接近写剧本软件。代价是解析器要自己写而且要考虑错误提示。我的经验是解析出错时一定要报行号和原始行内容否则作者面对一份几千行的剧本根本找不到问题在哪。这一点比语法本身优雅重要十倍。2.2 一条指令的完整生命周期从文本到执行中间要过四道关。我用一个最小可用的实现来说明逻辑上分四步预处理、分词、构建指令对象、编译成扁平数组。第一步预处理主要是统一换行符、去掉行尾空白、把连续空行折叠、处理注释我用的注释符号是//独立成行才算。这一步不解析语义只做规整好处是后面所有步骤都可以假设输入是一行一条的干净文本。第二步分词按行首字符判断类型开头是指令:开头是标签-开头且处于选项块内是选项其余是台词。指令行再按空格切分成命令名和参数参数里要支持keyvalue形式。function tokenizeLine(raw, lineNo) { const line raw.trim(); if (!line || line.startsWith(//)) return null; if (line.startsWith()) { const body line.slice(1); const firstSpace body.indexOf( ); const name firstSpace -1 ? body : body.slice(0, firstSpace); const argStr firstSpace -1 ? : body.slice(firstSpace 1); return { type: cmd, name, args: parseArgs(argStr), lineNo }; } if (line.startsWith(:)) { return { type: label, name: line.slice(1).trim(), lineNo }; } if (line.startsWith(-)) { return { type: option, raw: line.slice(1).trim(), lineNo }; } const idx line.indexOf() ! -1 ? line.indexOf() : line.indexOf(:); if (idx 0) { return { type: say, speaker: line.slice(0, idx).trim(), text: line.slice(idx 1).trim(), lineNo }; } return { type: say, speaker: null, text: line, lineNo }; }注意那个中英文冒号的兼容判断。中文剧本作者用全角冒号是常态解析器必须两种都认否则会出现说话人识别不出来、整句被当成旁白的诡异 bug。这个坑我踩过一次排查了半小时才发现是输入法的问题。第三步构建指令对象把分词结果映射成带执行语义的对象同时做静态检查jump的目标标签是否存在、show的角色是否在角色表里注册过、选项块是否成对闭合。这一步能在加载阶段就把剧本错误暴露出来而不是等玩家玩到第三小时才崩。第四步编译成扁平数组把标签位置记录成索引映射表function compile(tokens) { const program []; const labels Object.create(null); let i 0; while (i tokens.length) { const t tokens[i]; if (t.type label) { labels[t.name] program.length; i; continue; } if (t.type option) { const options []; while (i tokens.length tokens[i].type option) { const m tokens[i].raw.match(/^(.*?)\s*-\s*(\S)$/); if (!m) throw new Error(第 ${tokens[i].lineNo} 行选项格式错误); options.push({ text: m[1].trim(), target: m[2] }); i; } program.push({ op: choice, options }); continue; } if (t.type cmd) { program.push(buildCommand(t)); i; continue; } program.push({ op: say, speaker: t.speaker, text: t.text, lineNo: t.lineNo }); i; } return { program, labels }; }扁平数组加标签映射表带来的直接好处是存档只需要存一个整数——当前执行到第几条指令。读档时把指针一设从那条指令往后重新跑一遍舞台还原就能回到存档瞬间。这个设计我在后面讲存档时会再提。2.3 变量、条件与好感度让分支真正有用纯线性的视觉小说用不上变量但只要有分支玩家就会期待我前面选的话有影响。最小可用的变量系统包含三样东西赋值、比较、条件跳转。赋值的写法我设计成set 变量名 运算符 值比如set affection_yuki 3。解析时要支持、、-三种值可以是数字、布尔或者字符串。别小看这个设计比先读再写少写一行剧本里几十个好感度累加点省下来的行数很可观。条件跳转用if加endif包住一段指令或者更简单的jumpif 条件 - 标签jumpif affection_yuki 10 - good_route jumpif has_key true - secret_room条件表达式的解析有两种走法。稳妥的是自己写一个极简表达式求值器只支持比较运算符和逻辑与或偷懒且危险的是直接new Function(vars, with(vars){return expr })。后者性能好、写法灵活但剧本文件如果来自不可信来源这就是一个任意代码执行的口子。我的建议是内部项目图省事可以用对外分发的内容一律用受限求值器白名单只放行变量名、数字、比较符和、||。还有一个细节容易被忽略变量作用域。全局变量跨章节共享没问题但临时变量比如某个小游戏的结果如果不隔离会在后面的章节里意外命中。我的做法是给变量加前缀约定g_开头是全局、t_开头是当前场景临时场景切换时清掉t_前缀的全部键。这是个土办法但比引入真正的作用域链省事得多。3. 演出层立绘、文字、转场到底怎么排程3.1 DOM 还是 Canvas这个选择要一次做对这是绕不开的第一个技术选型。两条路的差别很大而且改起来成本极高基本等于重写演出层。DOM 方案的思路是把背景、立绘、对话框都做成div或img转场和动画交给 CSS transition / animation。优点是上手快、文字渲染天然清晰、无障碍和选中复制免费、调试时可以直接在开发者工具里改样式看效果。缺点是元素一多合成层管理会失控尤其是多个立绘同时做滤镜和位移的时候移动端掉帧明显。Canvas 方案的思路是自己管绘制循环所有东西画到一个canvas上。优点是渲染完全可控、可以做复杂的图层混合和粒子特效、元素数量对性能影响小。缺点同样明显文字排版要自己处理换行、标点避头尾、字体加载文本选中和缩放适配都得手写。我的实战结论是混合方案最省心背景和立绘用 DOM CSS transformtranslate3d走 GPU 合成对话框文字也用 DOM而需要复杂特效的部分比如雨滴、樱花、胶片颗粒单独开一个 canvas 覆盖层只在需要的时候启用。具体参数上立绘容器的写法大概是.char-layer { position: absolute; inset: 0; pointer-events: none; will-change: transform, opacity; } .char { position: absolute; bottom: 0; height: 92%; transform: translate3d(-50%, 0, 0); transition: transform .3s cubic-bezier(.22,.61,.36,1), opacity .3s ease; backface-visibility: hidden; }will-change和translate3d是让浏览器提前把这个元素提升为独立合成层位移和透明度变化就不用重绘整页。但will-change别乱加常驻几十个元素都开显存会被吃光移动端直接闪退。我的做法是只在动画开始前动态加、结束后移除。3.2 打字机效果三种实现和它们的坑台词逐字显示是视觉小说的标志性效果看起来简单实现方式却直接影响体验。第一种是setInterval定时器每 30 毫秒追加一个字。最直观但问题一大堆标签页切到后台定时器被浏览器降频到 1 秒一次回来时文字卡住快速点击跳过时定时器没清干净新旧两个定时器同时往里塞字文字会乱序。第二种是requestAnimationFrame加时间累计。每帧算一次从开始到现在过了多少毫秒应该显示到第几个字然后一次性把字符串切到那个位置。这是我目前主用的方案理由是它天然对齐屏幕刷新率后台标签页会被自动暂停回来继续不会出现时间错乱。核心逻辑就几行let startTime 0; let shown 0; const SPEED 33; // 每字 33ms约 30 字/秒 function tick(now) { if (!startTime) startTime now; const target Math.min(text.length, Math.floor((now - startTime) / SPEED)); if (target ! shown) { shown target; textEl.textContent text.slice(0, shown); } if (shown text.length) rafId requestAnimationFrame(tick); }第三种是纯 CSS 方案把每个字包成span用animation-delay逐个触发 opacity 从 0 到 1。优点是零 JS 开销、动画流畅。缺点是 DOM 节点数量爆炸一段 200 字的台词就是 200 个 span而且点击后立刻显示全部需要额外写 CSS 覆盖跳字体验不干脆。我一般在短句或者标题演出上用长段台词还是走 rAF。方案流畅度跳字处理DOM 开销后台标签行为适用场景setInterval 追加一般需手动清定时器低被降频易错乱不推荐rAF 时间累计高直接设 shown长度低自动暂停恢复主用方案CSS 逐字动画高需覆盖样式高正常短句、标题注意跳过全部文字时除了把显示位置设到末尾还要记得清掉在跑的 rAF 句柄并置空。忘了这一步会出现跳过后又被定时器重写回去的经典 bug。3.3 转场的时间轴调度转场是视觉小说里最能体现质感的部分也是最容易写成面条代码的部分。我的做法是引入一个极简的时间轴队列所有演出动作淡入、位移、闪烁、震动都包装成「时长 进度回调」的对象统一压进队列由一个调度器串行执行。class Timeline { constructor() { this.queue []; this.running false; } push(action) { this.queue.push(action); return this; } async run() { if (this.running) return; this.running true; while (this.queue.length) { const act this.queue.shift(); await act(); } this.running false; } }每个 action 返回一个 Promise内部用 rAF 推动进度进度到 1 就 resolve。这样写的好处是时序关系一目了然先淡出旧背景400ms再淡入新背景400ms再显示立绘300ms三行代码读起来就是演出顺序。有个细节值得单独说可打断性。玩家等不及转场就点了下一步这时候你是让转场跑完还是立刻跳到终态我的选择是后者——玩家点击时立刻把所有正在跑的动画设到终点并 resolve然后继续执行后续指令。实现上就是给每个 action 加一个finish()方法调度器在收到跳过信号时挨个调用。不做这个处理玩家狂点之后会看到一堆动画叠在一起画面糊成一团。3.4 音频通道BGM、音效、语音不能挤在一条道上音频管理看着简单实际上通道划分决定了能不能做出音乐渐弱、语音打断这类效果。我的划分是BGM 通道只有一个切换时做 300 到 800 毫秒的交叉淡入淡出。视觉小说里音乐经常跨场景延续所以指令设计上要区分换 BGM和继续当前 BGM。环境音通道独立于 BGM比如雨声、风声、教室的嘈杂。允许和 BGM 同时存在。音效池短音效脚步声、开门声、翻页声用对象池管理同时最多 8 个实例超了就复用最早的。别每次new Audio()节点会越积越多。语音通道单独一条新语音进来时立刻打断上一条。这一条是硬需求玩家快速点击时如果语音排队播放会听到一堆叠在一起的台词。音量上要注意的是人耳感知不是线性的。滑块拉到 50%实际感知响度远不止一半。建议用gain Math.pow(slider, 2)做一次映射主观听感才接近线性。这是个小细节但设置面板做得好不好玩家一耳朵就能听出来。4. 资源管理与加载首屏三秒决定玩家走不走4.1 预加载队列该按什么顺序排视觉小说的资源加载不能要用了才去拉否则每次切场景都是一次白屏。但也不能一上来就把几百 MB 全拉下来手机流量用户会直接关掉页面。我的做法是三级队列。第一级是阻塞式加载首屏必需的背景、UI 图、字体、第一段 BGM没加载完不进场配一个进度条。第二级是当前场景的剩余资源进场之后立刻在后台拉当前章节的所有立绘表情和音效。第三级是下一场景的预取玩家进入到本章中段时开始预取下一章的首屏资源。优先级判断上除了静态的章节顺序还要加一条动态权重玩家最近两分钟内用过的角色立绘排到队伍前面。因为视觉小说的剧情往往集中在一两个角色身上把他们的所有表情都缓存住命中率能到八九成。const loader { queue: [], cache: new Map(), add(url, priority 0) { if (this.cache.has(url)) return Promise.resolve(this.cache.get(url)); return new Promise((resolve, reject) { this.queue.push({ url, priority, resolve, reject }); this.queue.sort((a, b) b.priority - a.priority); this.pump(); }); }, pump() { const CONCURRENCY 4; while (this.active CONCURRENCY this.queue.length) { const job this.queue.shift(); this.active; const img new Image(); img.onload () { this.cache.set(job.url, img); job.resolve(img); this.active--; this.pump(); }; img.onerror () { job.reject(new Error(job.url)); this.active--; this.pump(); }; img.src job.url; } } };并发数设 4 是个经验值。HTTP/1.1 下浏览器同域并发上限是 6留两个名额给接口和字体HTTP/2 下理论上可以更多但图片解码是主线程瓶颈开太多反而互相拖慢实测 4 到 6 之间最稳。4.2 图片格式与体积几个能立刻生效的参数资源体积是这类项目最大的成本项。下面这几个参数是我反复调过的效果直接。资源类型推荐格式尺寸上限单张体积目标说明背景WebP 有损 q821920×1080200–300 KB保留一份 JPEG 兜底立绘WebP 带透明 q85高 1100px150–250 KB别用 PNG透明通道体积翻倍CGWebP 有损 q881920×1080250–400 KB鉴赏模式才加载缩略图WebP q70480×27020–40 KB存档和画廊用BGMMP3 128kbps 或 OGG—1–2 MB/分钟长循环曲目可降码率语音OGG 单声道 64kbps—极低人声不需要立体声几个实测出来的经验立绘如果按 4K 出图再缩放手机上解码会卡顿几百毫秒直接按最终显示高度的 1.5 倍出图最划算背景图加一点点噪点或者纹理WebP 压缩后的体积反而更小因为大面积纯色渐变是压缩器的噩梦透明立绘的边缘如果有半透明羽化WebP 比 PNG 省一半以上体积而且视觉上看不出差别。4.3 缓存策略与版本号资源更新不能炸存档静态资源部署之后最头疼的是玩家浏览器里缓存着旧图。文件名加内容哈希是最稳的方案bg_classroom_day.a3f9c1.webp内容一变哈希就变天然避开缓存问题。代价是剧本里要引用带哈希的路径所以我在构建阶段做了一层映射剧本里写逻辑名bg_classroom_day构建时替换成真实路径。另一半问题是存档兼容。玩家存了档你更新了版本加了一个新角色、删了一个旧背景读档时怎么还原我的做法是存档里只存逻辑名和变量值不存资源路径读档时如果某个资源找不到用一张占位图代替并记一条警告而不是直接抛异常让整个存档作废。玩家看到一张灰色占位图总比看到存档损坏要好。再补一条存档格式要带版本号和迁移函数。我吃过一次亏中期改了一版存档结构把chars数组改成对象结果测试群里十几个人的进度全废了。后来加了migrate(save)函数按version字段逐级升级从此再没出过事。5. 存档、回放与分支最容易翻车的三块5.1 快照式存档和指令流存档的取舍存档有两种思路。快照式是把当前舞台的完整状态序列化下来背景是什么、立绘有谁站在哪、BGM 是哪首播到第几秒、所有变量当前的值、当前执行到第几条指令。指令流式只存一个起点和一个操作序列读档时重放。维度快照式指令流式存档体积大含全部舞台状态小几个索引读档速度快直接还原慢要重放兼容性结构一变就废剧本一改就错位实现难度中低适合场景商业项目、长期运营短篇、Demo我最终选的是混合式主体用快照但额外存一个指令索引和最近的 20 条台词历史。快照保证读档秒开指令索引用于从存档点回看剧情历史则用来填充回想界面的文本记录。存档结构大致长这样{ version: 3, saveId: slot_02, timestamp: 1730000000000, chapter: ch01, pointer: 482, stage: { bg: classroom_day, bgm: { name: bgm_daily, volume: 0.6 }, chars: [ { id: yuki, pos: center, expr: normal, alpha: 1 } ] }, vars: { g_affection_yuki: 12, g_has_key: true }, history: [ { speaker: yuki, text: 早上好。 } ] }注意stage.chars里存的是逻辑 id 和表情名不是图片路径。这一层间接让换美术素材不用动存档。5.2 已读标记、跳过与自动播放这三个功能玩家用得最多做不好被吐槽也最多。已读标记的核心是给每条台词一个稳定标识。用台词文本的哈希会出问题——改一个错别字整条记录就失效了玩家重玩时会发现这句明明读过却不算已读。我的做法是章节id 指令索引组合成键改文本不影响改结构才失效后者本来就不可避免。存储位置上localStorage的容量通常只有 5MB 左右一条记录按 20 字节算十万条台词就是 2MB勉强够用但很危险而且localStorage是同步 API读写会阻塞主线程。台词量大的项目我建议换 IndexedDB异步、容量大代价是首次要写一套 Promise 封装。跳过功能要区分跳过已读和跳过全部。前者是大多数玩家的默认需求后者一般只在选错路线时用。实现上跳过模式就是一个加速倍率把打字机速度设为 0、转场时长设为 0然后在每条指令执行完后检查这条是不是已读是就继续跳不是就停在原地等玩家确认。这里有个坑跳过时如果遇到选项必须强制停下否则会直接跳过分支节点剧情跑飞。自动播放的节奏控制是门玄学。固定延迟比如每句停 2 秒体验很差因为短句等太久、长句不够看。我的做法是按字数算基础时长再加一个固定尾巴delay 800 text.length * 60毫秒上限 6 秒。语音播放时则以语音时长为准播完再等 400 毫秒。5.3 分支与结局管理别让剧情变成一团毛线分支一多剧本维护就会失控。我见过最夸张的一个项目三十多个标签跳来跳去最后作者自己都说不清某个选项会通向哪里。我的做法是加一层章节清单用一个单独的配置描述章节之间的跳转关系export const chapters { ch01: { next: [ch02a, ch02b], entry: start }, ch02a: { next: [ch03], entry: start }, ch02b: { next: [ch03], entry: start }, ch03: { next: [], entry: start, endings: [good, normal, bad] } };这层清单不参与运行时逻辑只用于三件事加载时做完整性校验有没有指向不存在章节的跳转、做流程可视化自动生成一张章节关系图作者能一眼看出结构、做测试覆盖率统计哪些分支从来没被跑到过。第三点特别有用我一般在开发环境里跑一个自动化脚本把所有分支随机走几百遍把没覆盖到的标签列出来补测试的效率高很多。6. 常见问题与排查实录6.1 移动端音频不响八成是第一下点击没接住浏览器对自动播放的限制几乎是所有 H5 音频问题的根源。表现是桌面正常手机打开没声音或者第一句台词有声音、切场景之后没了。根本原因是音频上下文在没有用户手势的情况下处于 suspended 状态。解决办法是在首次真实点击touchend或click不要用touchstart时创建或唤醒音频上下文并播一个静音 buffer 解锁let unlocked false; document.addEventListener(touchend, async function once() { if (unlocked) return; const ctx new (window.AudioContext || window.webkitAudioContext)(); if (ctx.state suspended) await ctx.resume(); const buf ctx.createBuffer(1, 1, 22050); const src ctx.createBufferSource(); src.buffer buf; src.connect(ctx.destination); src.start(0); unlocked true; document.removeEventListener(touchend, once); }, { passive: true });另外iOS 上把手机调成静音模式时audio标签播放的媒体是静音的这条无解只能靠界面提示引导玩家关闭静音。还有一点切到后台再回来音频上下文可能又回到 suspended需要在visibilitychange里重新resume()。6.2 文字溢出与排版中文的换行比英文难搞英文有词边界中文没有所以标点避头尾就成了必须处理的问题。默认情况下句号、逗号可能出现在行首括号可能被拆成两半观感很差。CSS 层面加上这几行能解决大部分问题.dialogue-text { line-break: strict; word-break: normal; overflow-wrap: break-word; text-align: justify; text-justify: inter-ideograph; line-height: 1.75; }line-break: strict让浏览器按严格的避头尾规则断行。字体方面中文网页字体动辄十几 MB直接引入会让首屏时间翻倍。实用方案是系统字体栈优先只在标题等少量文字上用子集化的 WOFF2。做子集的时候别只截常用三千字剧本里出现的生僻字、人名用字要单独扫一遍加进去否则会出现某个角色名字显示成方框的尴尬情况。还有一个隐蔽的坑line-height设得刚好等于字号会让行间距显得挤中文尤其明显。我的经验值是字号的 1.7 到 1.8 倍阅读舒适度最好。6.3 常见问题速查表现象可能原因排查方向处理方式切场景白屏一闪图片未预加载看网络面板是否有新请求提前预取下一场景首屏资源读档后立绘位置错乱存档未记录舞台状态检查 stage 字段存档补全 chars 的 pos/alpha点击无响应遮罩层吃掉事件检查pointer-events装饰层统一设 none快速点击后文字乱序定时器未清理检查是否有多个 rAF跳字时统一清句柄存档读不出来版本结构变更对比存档 version写 migrate 逐级升级立绘边缘有白边预乘 Alpha 问题换 PNG 对比测试导出时关闭预乘或改用 WebP长台词滚动条出现容器高度写死检查 dialog 高度改成 max-height 内部滚动跳过时跑飞分支选项未拦截跳过检查 choice 指令遇到 choice 强制停跳提示排查这类问题最有效的手段是做一个调试面板把当前指针位置、变量值、舞台状态实时打印出来按一个键切换显示。比在控制台里一行行console.log快十倍而且上线前把开关关掉就行。6.4 几个只有做过才知道的经验第一条别在剧本里写绝对时间。wait 3000这种指令看着方便玩家开了二倍速之后就会变成必须干等三秒的折磨。等待时长应该由引擎的速度倍率统一缩放剧本里只写等一个节拍这种相对量。第二条资源加载失败要有兜底。网络抖动、CDN 抽风都是常态一张背景图挂了不该让整个游戏卡死在加载页。我的做法是图片 onerror 后重试两次仍失败就用同色系纯色块加文字说明代替并记录下来游戏继续。第三条测试要在真机上跑。桌面浏览器缩放窗口模拟移动端和真机完全是两回事尤其是 iOS Safari 的内存限制——一个页面占用超过几百 MBSafari 会直接刷新页面表现就是玩到一半突然回到开头。这个问题的排查成本极高预防手段是控制同时驻留的大图数量及时释放不可见章节的缓存。第四条给作者做一个预览工具。剧本作者不可能每次都构建部署再看效果我在引擎里加了一个开发模式支持单章热重载和标签跳转改一行剧本刷新就能看到作者的迭代速度提升非常明显。这个投入在项目中期就会回本。7. 部署与后续扩展的几点实操建议部署这块没什么花活静态资源扔到任意对象存储加 CDN 就能跑。几个参数值得调开启 Brotli 压缩文本资源能再省 20%给带哈希的静态资源设一年强缓存index.html设不缓存跨域隔离相关的响应头如果不需要 SharedArrayBuffer 就别开开了反而容易在嵌入场景里出问题。后续扩展上我觉得有三个方向性价比最高。一是多语言把台词抽到外部语言包引擎层只认 key切换语言时重新编译剧本。这件事前期做成本很低后期补就是灾难。二是云存档本地存档加一个可选的账号同步玩家换设备能接着玩实现上就是存档 JSON 传一份到服务端注意做冲突合并策略。三是数据埋点统计玩家在哪个选项停得最久、哪条路线走得最多这些数据对后续创作的参考价值远比想象中大。我个人在实际项目里最深的一点体会是这类引擎的复杂度不在技术本身而在使用它的作者。一个语法设计得再优雅作者用着别扭就是失败一个功能实现得再精巧作者不知道怎么调参数就是白做。所以每次加新特性之前我都会先问自己一句——这个东西是给玩家看的还是给作者用的如果是给作者用的那文档和默认值的重要性可能超过代码本身。最后分享一个小技巧给剧本解析器加一个严格模式开关开发时打开遇到未注册的角色、未定义的标签、拼错的指令名直接报错中断上线时关掉遇到问题降级成警告继续跑。这个开关帮我拦下过大量低级错误也让线上版本不至于因为一处笔误就整章崩掉。
