做这个项目的念头来自一个很普通的深夜。电脑里还躺着二十年前的老存档我忽然想如果在浏览器里打开一个网页就能从头把《仙剑奇侠传》完整通关一遍而且所有剧情、地图、战斗数据都能像改配置文件一样随时调整那会是什么体验于是我给自己立了个规矩用 TypeScript 从零重写不套现成引擎不模拟器套壳。核心目标只有两个——第一从拜月教主开场到最终决战整条主线能一路打通第二配套一个可视化编辑器不需要改一行代码就能给游戏写新地图、新对白、新战斗。这篇文章就把整个项目的架构思路、核心系统拆解、编辑器设计以及通关路上踩过的坑完整记录下来。适合想用 Web 技术做 RPG 的开发者也适合好奇“游戏内容如何脱离代码”的策划型读者。1. 逼自己从零手写不是复刻画面而是数据驱动的 RPG 引擎1.1 为什么不好好复刻画面要重新写一套引擎很多人听说我要重写这款经典游戏第一反应都是“你直接用模拟器加载 ROM 不就行了吗”。技术上确实能跑但模拟器方案有三个绕不开的问题第一版权风险。直接分发原版镜像属于明确的侵权哪怕不商用也不行。第二学习价值几乎为零。模拟器是别人写的游戏逻辑是原版二进制里的你除了会按 F12 打开“运行”什么也学不到。第三也是最致命的——我没法改内容。原版游戏的数据是打包在二进制文件里的想做可视化编辑器等于要把整个数据格式逆向工程一遍改错一个字节都可能死机。所以我决定走一条更苦但更值钱的路只保留故事结构和核心玩法设计所有代码、所有资源、所有数据格式全部自己定义。美术资源一开始用程序生成的像素占位图不碰原版素材。这种做法的意义在于当一切内容都在你自己定义的格式里时你才真正拥有这个游戏。1.2 技术选型为什么是 TypeScript Canvas 2D Vite选 TypeScript 几乎是必然的。RPG 游戏有大量互相引用的数据结构——角色属性、物品列表、对话节点、战斗公式、剧情分支如果全部用纯 JavaScript 写改着改着就会因为一个undefined属性在半夜崩溃。TypeScript 的类型系统能在编译期拦住一大批低级错误尤其当编辑器要和引擎共享数据定义时一套类型两边用的优势非常明显。渲染层我选了 Canvas 2D没有碰 WebGL。原因很朴素这是一个瓦片地图为主的 2D RPG单屏瓦片数量最多一两百个Canvas 2D 的drawImage性能完全够用。WebGL 带来的绘制批次管理、纹理打包、Shader 编写对这个项目来说都是过度设计。后期如果要做全屏滤镜或粒子特效再考虑局部引入 WebGL 也不迟。构建工具用的是 Vite。它最打动我的点是开发服务器启动快、热更新干净而且对 TypeScript 零配置。整个项目结构保持得很简单src/game/游戏引擎核心地图、战斗、状态管理、事件系统src/editor/可视化编辑器src/shared/编辑器与引擎共享的类型定义、数据校验器、存档迁移逻辑content/游戏内容包全部是 JSON 文件1.3 一次“内容即数据”的架构冲动这个项目最核心的设计决策是强行把所有游戏内容都定义为纯数据。地图是 JSON对话是 JSON物品是 JSON战斗敌人的出手逻辑也是 JSON。举个例子一个宝箱事件长这样interface GameEvent { id: string; trigger: EventTrigger; // 触发器何时发生 conditions: Condition[]; // 条件满足才执行 actions: EventAction[]; // 动作按顺序执行 }{ id: evt_chest_01, trigger: { type: touch, x: 12, y: 8 }, conditions: [{ type: flag_not_set, flag: chest_01_taken }], actions: [ { type: add_item, itemId: heal_grass, count: 2 }, { type: set_flag, flag: chest_01_taken }, { type: show_message, text: 获得两株止血草。 } ] }引擎本身只是一个“解释器”它不知道《仙剑奇侠传》是什么也不关心剧情讲的是谁。它只负责根据事件表、地图数据、角色配置机械地执行逻辑。可视化编辑器则是另一种“解释器”——它把这些 JSON 渲染成可视化的地图画布和对话连线图让非程序员也能操作。这一步走完之后我意识到游戏本体其实已经不重要了重要的是那套“数据格式”。只要换一套 JSON 内容包这套引擎可以跑出任何剧情、任何地图、任何数值体系的 RPG。2. 引擎拆分地图、碰撞、寻路与回合制战斗的落地细节2.1 瓦片地图与四层渲染从绘制到遮挡关系的处理地图系统是所有 RPG 的地基。我采用了一种很经典的瓦片矩阵方案每个地图由二维数组组成每个格子存一个瓦片 ID。地图分四层地面层草地、砖地、水面等所有角色踩在这一层上面物件层树木、建筑、宝箱、告示牌等遮挡层用于处理树冠、屋檐这类需要盖住角色的物体碰撞层不可见标记哪些格子不能走四层的原因是为了解决一个经典问题当玩家走到一棵树的“下方”时树冠应该把玩家上半身挡住产生纵深错觉。如果在同一层里画树和玩家就会出现玩家把整棵树遮住的反直觉画面。我的做法是先把地面层和物件层画在画布底层然后单独画一个“遮挡层列表”——记录所有需要盖住角色的瓦片区域。每一帧先绘制玩家然后遍历遮挡区域当玩家包围盒与遮挡区域相交时就把遮挡区域的瓦片绘制在玩家坐标之后并让玩家对应部分变为半透明。实际效果大约多花 20 行代码但 RPG 的立体感一下就有了。2.2 碰撞检测轴分离移动与 NPC、怪物的 A* 寻路碰撞层的数据结构很简单一个二维数组0表示可通行1表示不可通行。玩家移动时我采用的是“轴分离碰撞检测”——把横向移动和纵向移动分开处理而不是一次性计算整段位移。function tryMove(actor: Actor, dx: number, dy: number): boolean { // 先尝试横向移动 if (!isBlocked(actor.x dx, actor.y)) { actor.x dx; } // 再尝试纵向移动 if (!isBlocked(actor.x, actor.y dy)) { actor.y dy; } }这么做的好处是不会出现“斜着走被墙角的两个方块同时卡住”的尴尬情况。实际手感上分开检测后角色贴墙滑行非常流畅。NPC 和怪物的移动则用 A* 寻路。因为我用的是统一瓦片网格A* 实现起来非常标准把整个地图看成节点图起始格子到目标格子之间搜索最短路径。需要注意的细节是怪物检索路径的间隔要加冷却时间不能每帧都跑 A*否则地图一大、怪物一多性能会迅速恶化。我实测 100 只怪物、50×50 地图间隔 500ms 的寻路频率完全无压力。2.3 回合制战斗行动条、AI 与演出状态的机器战斗系统是我花时间最多的一块。它本质上是“多角色轮流行动”的状态机。我的核心数据结构是BattleState它记录了所有参战者、当前行动者、技能结算队列。战斗流程拆成了三个子状态selectCommand等待玩家选择攻击、技能、道具、逃跑executeAction播放技能演出执行伤害结算roundEnd检查胜负发放经验决定下一个行动者最让我纠结的是行动顺序。一开始用简单的“速度值排序”但立即发现一个问题如果某个角色速度永远比敌人高他每回合都能先手战斗策略变得单调。后来我引入了“行动条累积”机制每个角色有一个initiative值每帧按速度增加达到阈值即可行动行动后扣除阈值。这样速度快的角色行动频率高但不会简单到“永远先手”。敌方 AI 也用数据驱动。每个怪物有一条aiPattern格式大致是{ id: boss_water, hp: 1800, atk: 120, speed: 85, ai: [ { when: hp_percent_above_50, skills: [water_blast] }, { when: hp_percent_below_50, skills: [water_blast, fury_swipe] } ] }没有单独的智能算法就是根据血量百分比、异常状态、回合数在技能池里做加权随机。实践证明对回合制 RPG 来说这种简单的规则 AI 足够产生好玩的变化不需要复杂的“策略树”。2.4 事件系统对话、宝箱、机关和区域触发都是同一种东西老式 RPG 里对话、宝箱、机关、剧情演出看起来是不同系统其实本质都是一样的——某个条件满足后执行一串动作。我把触发器分成了四类touch玩家踩到某个格子talk玩家与某个 NPC 互动auto进入地图后自动触发item_used对某个目标使用特定道具动作类型则有对话、加物品、改标志位、播放动画、切地图、设置机关状态、增减血量、游戏结束等十余种。整套系统用前面提到的GameEvent结构统一表达。这里有个经验值得分享剧情和战斗最好是用“标志位”而不是用对象引用。比如“打败某个 Boss 之后回村找村长对话”不要在事件里直接写“Boss 已死亡”而是写set_flag(boss_01_defeated, true)然后在村长对话的条件里检查这个标志位。标志位方案的最大优点是可序列化——游戏存档只需要保存一堆布尔值和变量不用担心对象引用断链。3. 一个“能通关”的游戏到底需要一个怎样的状态机3.1 用全局 GameState 管住一切玩家数据、背包、剧情标志位RPG 游戏的状态多到吓人玩家当前坐标、等级经验、已学技能、背包物品、每个村庄的机关状态、每条支线做到第几步、每个 Boss 是否已击败……我一开始犯过“把状态分散在各个模块里”的错结果存档模块要到处拿数据改起来像在做外科手术。后来我做了彻底的全局状态集中——整个游戏只有一个GameState对象所有可变的游戏数据都挂在它底下interface GameState { player: PlayerState; party: CharacterState[]; inventory: InventoryEntry[]; flags: Recordstring, boolean | number; quests: Recordstring, QuestProgress; currentMapId: string; position: { x: number; y: number }; }游戏的每次变化本质上是某个模块对GameState做了一次修改。存档就是把这个对象完整序列化为 JSON读档就是整体替换。这个设计避免了一个非常隐蔽的 Bug玩到后期如果某块状态没存进存档读档后玩家会发现“明明打过这个 Boss剧情却让我再打一次”。3.2 任务队列把对话和战斗演出变成可中断的“剧本”游戏里几乎所有的演出——NPC 说三句话、角色走到某个位置、切换视角、播放音乐——都是严格的顺序操作。初学者最容易写出地狱级嵌套回调先播放第一句话回调里再播放第二句话第二句话结束后再启动战斗……我从 Unity 的协程思路里得到启发设计了一个极简的任务队列。每个事件动作不是立即执行而是被包装成任务塞进队列引擎按顺序执行任务之间可以等待动画结束、等待用户点击、等待战斗完成。type GameTask | { type: show_message; text: string; waitForClick: boolean } | { type: move_actor; actorId: string; path: Point[] } | { type: start_battle; enemyGroupId: string } | { type: wait; durationMs: number } | { type: run_script; scriptId: string };这个设计最大的好处是“可中断”。玩家在对话中打开菜单、存档退出任务队列可以被安全挂起下次读档时从断点继续。如果用的是多层嵌套回调要做到这种可恢复性得把整个调用栈都序列化难度完全不在一个量级。3.3 场景栈与转场地图、战斗、菜单和剧情的共存关系游戏里同时存在好几种“场景”大地图、战斗演出、对话框、系统菜单。它们不是互相替代而是层层叠放。我用了一个场景栈来管理它们。栈底是地图场景战斗场景压在上面对话框是一个浮层场景菜单又是另一层。当玩家按“打开菜单”时菜单场景入栈关闭时出栈回到继续移动的地图。当敌人遭遇战斗时战斗场景入栈地图场景暂时冻结战斗结束出栈。场景栈的好处是状态切换非常干净每个场景只负责自己的更新和渲染场景管理器只处理入栈、出栈、暂停。项目做到后期我加了“剧情回放”功能就是直接往栈里推一个回放场景关掉后恢复原场景。这套架构让所有玩法模式之间的跳转都变得像浏览器 history 一样自然。3.4 存档与读档把 GameState 序列化成可迁移的版本化 JSON存档是数据驱动架构的终极考验。因为游戏内容在迭代数据结构在变旧存档必须无损迁移到新版本。我做的第一件事是给存档加version字段。每次结构性变更就写一个迁移函数function migrateSaveData(oldData: SaveDataV1): SaveDataV2 { return { version: 2, player: oldData.player, // 旧版没有 quests补一个空对象 quests: {}, }; }加载时根据版本号逐级升级从 v1 升到 v2从 v2 升到 v3直到最新版。这套方案比“直接读最新格式然后报错”体验好得多。真正有难度的是迁移后要跑一遍校验函数确认数据完整性。我在存档系统里实现了validateSave(save)检查每个物品 ID 是否存在于物品表、角色 ID 是否合法等防止老存档引用了被删除的资源。4. 可视化编辑器让策划脚本脱离代码变成可点击、可拖拽的资产4.1 引擎与编辑器共享同一套类型系统这正是做编辑器的底气很多人以为编辑器是引擎做完之后的“附加功能”但我恰恰相反——因为我把所有内容都定义成了 TypeScript 类型和 JSON 数据编辑器才能自然地诞生。编辑器不是独立的应用它和引擎跑在同一个代码库里共享同一套shared目录下的类型定义。编辑器界面我没有用 Canvas而是直接用 DOM CSS 实现。游戏引擎用 Canvas 渲染是因为它需要高性能和高自由度编辑器要的是按钮、下拉框、拖拽手柄、交互表单这些事情 DOM 天生擅长。引擎和编辑器是两个入口打包成两个页面但它们读写的游戏内容是同一套 JSON。这种“共享类型”带来的好处是决定性的在地图编辑器里放置一个 NPC保存出来的数据包含了角色 ID、坐标、朝向、对话脚本 ID。引擎读到同一个类型不需要做任何字段映射或数据结构转换。编辑时的类型检查和运行时的类型检查是同一个函数这意味着——编辑器里没报错游戏里运行时大概率也不会因为数据结构问题崩溃。4.2 地图编辑器刷格子、放置 NPC、划定触发区域地图编辑器的交互逻辑其实就是“画图”逻辑。左边是图块选择面板中间是地图画布右边是属性面板。核心功能按使用频率排列画笔工具在地面层刷地形图块快捷键 B 切换阻挡层开关在“可通行/不可通行”之间切换用半透明红格子显示阻挡区域NPC 放置从资源库拖一个人物到地图上属性面板可以绑定它的对话事件宝箱/机关放置同样拖拽放置属性面板里选择触发方式和动作传送点设置点选一个区域作为出口再点选目标地图上的一个位置作为落点地图尺寸调整支持运行时扩容比较有技术含量的一个功能是“传送点可视化连线”。当我在一张地图上设置了一个通向另一张地图的传送点后编辑器会在两张地图之间画一条虚线点击虚线可以直接跳转到目标地图。这个功能对检查地图连接完整性特别有用——我通关之后回来排查“某个任务无法完成”多半是某张地图的传送点指向了错误位置。4.3 剧情编辑器用节点连线代替手写脚本剧情是这款游戏最重要的部分也是编辑器里交互最复杂的模块。手写对话 JSON 非常痛苦方括号、逗号、转义符错一个符号整个剧情断掉。所以我做了一个基于节点的剧情编辑器。每个节点是一个剧情步骤节点之间有连线。节点类型包括对话节点显示一段文本可以设置说话人、头像、声音分支节点根据变量或标志位跳转到不同的后续节点事件动作节点执行加物品、切地图、改变量等操作结束节点标记整个剧情结束编辑操作非常直觉化双击画布空白处创建对话节点从一个节点底部拖出连线到另一个节点右键编辑节点属性。界面我用 SVG 画节点连线节点拖动时所有关联连线实时重画。这个编辑器有一次改变了我对“写脚本”这件事的看法。以前我在 JSON 里写分支逻辑脑子得把逻辑树折叠成线性代码现在在画布上画分支图一眼就能看到剧情的所有走向。做完这个功能之后我再也不想回到手写 JSON 的时代了。4.4 数据校验与热更新编辑完立刻在游戏里跑一遍编辑器最大的价值在于“闭环”。如果编辑完数据还要靠人工检查是否出错那还不如写代码。我在shared层写了一套校验器引擎和编辑器都用它function validateGameData(contentPack: ContentPack): ValidationError[];校验器检查的对象包括地图引用的瓦片 ID 是否存在、NPC 对话引用的事件是否存在、事件动作里的物品 ID 是否在物品表里、传送点目标地图是否存在、Boss 掉落表里有没有缺失的属性……每类检查都是一条规则返回明确的错误信息和坐标定位。更爽的是热更新联动。编辑器有一个“运行预览”按钮点击后自动把当前内容包写进 IndexedDB然后引擎检测到数据变更直接重新加载当前地图。整个流程不超过 3 秒。这意味着我在地图编辑器里画一条路、放一个宝箱切到游戏页面刷新一下就能亲自走上去踩一下验证。这个闭环让我的调试效率提升了一个数量级。5. 通关路上的调试日常五个让我记忆犹新的 BUG5.1 树荫遮挡 Bug 与“画序”这件事第一个记忆犹新的 Bug是树荫遮挡。第一次实现遮挡层时我把遮挡区域存成了一个巨大的矩形数组判断“玩家是否在树冠下方”用的是矩形碰撞。结果玩家绕着大树走的时候树冠忽而遮挡、忽而消失像动画片里的背景穿帮。排查半天问题出在矩形碰撞对半格走位的敏感度太高。一棵树的树冠矩形只覆盖了树本身的四格瓦片当玩家站在树的正下方一个像素时碰撞刚好成立再往右移一步就立刻消失。改成“玩家包围盒中心点与遮挡矩形中心点比较且距离小于 1.5 格”之后遮挡过渡变得平滑。不过这种问题没有标准答案只有不断调整阈值找到视觉上最舒服的临界值。5.2 随机数导致对局复现不了种子的力量回合制战斗里每次技能伤害都要用随机数浮动。一开始我直接调用Math.random()结果出现一个极其折磨人的问题战斗中触发了一个 Bug但我存档后再读档重打这场战斗Bug 不出现了——因为随机数完全不同伤害数值、敌人技能选择、暴击结果都不一样我根本无法复现。解决办法是彻底移除Math.random()换成可种子的伪随机数生成器。我在工具函数里实现了一个简单但够用的mulberry32function mulberry32(seed: number): () number { let a seed 0; return function () { a | 0; a (a 0x6D2B79F5) | 0; let t Math.imul(a ^ (a 15), 1 | a); t (t Math.imul(t ^ (t 7), 61 | t)) ^ t; return ((t ^ (t 14)) 0) / 4294967296; }; }每个战斗开始前用“地图 ID 遭遇战次数 全局随机种子”生成一个局部种子初始化随机数发生器。存档只存一个全局随机种子读档后种子恢复下一场战斗的随机序列也完全一致。这个改动让所有战斗类 Bug 变得可复现调试难度直接下降一个量级。5.3 对话到一半卡死异步任务队列里的死锁有段时间我频繁遇到“NPC 对话说到第三句游戏彻底卡死”的 Bug。不是画面卡死是玩家还能走动但对话不继续也弹不出下一句。查了很久发现是一个异步死锁。我的对话任务是这样执行的显示文本后任务队列等待一个clickToContinue的信号玩家点击后信号发出任务继续。但在某个特定事件里文本已经显示了我却在show_message动作里忘了注册信号监听器导致任务队列永远在等待一个永远不会来的点击事件。排查方法很笨但很有效我给每个任务队列的等待动作加了一个超时机制如果超过 15 秒没有收到信号就打印当前的队列状态栈。这样一跑卡死的任务上下文完整地呈现在控制台里一眼就看到了缺失的信号监听器。后来我把“等待点击”封装成了一个统一函数所有对话都调用它不再允许各处手写监听。5.4 存档读完变成空白一次 JSON Schema 迁移事故游戏后期我增加了一个新系统“支线任务”玩家可以同时追踪多个任务进度。这个系统需要把原本存储在新数组里的questId升级成{ id, status, progress }对象。我没有仔细考虑旧存档的迁移直接在读取时从save.quests[id]变成了save.quests[id].status结果所有老存档一读支线任务相关的界面全部白屏。排查到根因后我写了专门的迁移函数检测到save.quests[id]是字符串时转换为对象结构。经历了这次事故我才真正理解存档迁移的核心原则迁移逻辑必须和版本号一起存在而不是依赖“养成先改代码”的习惯。从那以后每次数据结构变更我都会在同一份代码里提交迁移函数并留一条旧档测试用例。5.5 性能从 40fps 到 60fpsDrawImage 不是随便说说游戏功能都完成之后我遇到一个“能玩但不够流畅”的性能瓶颈大地图上怪物多、NPC 多、遮挡瓦片也多帧率掉到了 40 帧上下。用浏览器性能面板一看Canvas 的绘制调用次数每帧达到惊人的 1800 多次。罪魁祸首是细节的过度绘制——每个宝箱、每棵树的阴影、每个 NPC 的投影我都在每帧重新调用drawImage。60 帧意味着每秒至少 10 万次绘制调用Canvas 2D 顶不住很正常。优化方案分三步。第一把静态地图的地面层和物件层预渲染成离屏 Canvas每帧只需要把这张静态背景整体绘制一次省掉了上千次小图绘制。第二对会动的 NPC 和怪物只在它们移动时更新对应区域静止时直接复用上一帧的离屏图层。第三遮挡层瓦片做了排序去重相邻的同类瓦片合并成一个更大的drawImage调用。三管齐下帧率稳定回到 60而且代码改动量不大。6. 从“跑通流程”到“真正能通关”我的一套验证方法6.1 用黄金路径回放把所有关键节点录成回放“能通关”这三个字光靠人工打一遍远远不够。每改动一次数据或代码都可能引入一个“某个 Boss 打过后回来发现剧情触发不了”的暗坑。所以我专门做了黄金路径测试。黄金路径指的是主线流程从开局到通关的必经之路拿到第一个物品、打败第一个 Boss、触发所有关键剧情、拿到最后一把钥匙、打败最终 Boss。我把每一步提炼成一条操作序列录制成 JSON 脚本{ actions: [ { t: tick, frames: 240 }, { t: move, to: { x: 15, y: 20 } }, { t: talk, npcId: village_chief }, { t: select_menu, option: 战斗 }, { t: use_skill, skillId: sword_strike } ] }测试时引擎读入这段脚本自动模拟玩家输入。每执行到一个节点断言当前GameState符合预期。这个方法让我在大改系统后用 20 分钟就能确认整条主线没有被弄断。6.2 固定随机种子与自动化冒烟跑图黄金路径只能覆盖主线地图上的支线、隐藏宝箱、敌人遭遇战很难全部人工验证。于是我又写了一个“冒烟测试 Agent”——它不是验证剧情而是像一个“头铁玩家”一样在地图上到处逛遍历地图的所有传送点确保没有传送到虚空和每个 NPC 至少对话一次确保不会触发异常对每个可战斗的格子触发一场战斗用固定 AI 打一回合打开系统菜单检查所有界面不报错测试全程使用固定的随机种子所以同样的问题必然同样出现。这套冒烟测试虽然没有验证通关但把“地图断链”“事件 ID 引用错误”“战斗卡死”这类问题基本都扫了一遍。配合黄金路径测试二者加起来的信心比人工测试强得多——毕竟人工测试大概率会因为玩家偷懒而漏掉一张地图。6.3 编辑器带来的最大红利换一套内容包就是另一款 RPG项目做到最后可视化编辑器带来的红利超出预期。原本我以为它只是“给游戏做内容的工具”后来才发现它实际上把游戏从“一个作品”变成了“一套创作平台”。因为有编辑器我可以一小时内画出一张新地图、配好对话、放好宝箱和敌人因为所有内容都是数据驱动的我可以把整个游戏打包成一个内容包。想做个完全不同题材的 RPG不需要改动引擎一行代码只需要换一套内容包——新角色、新地图、新剧情、新战斗数值全部通过编辑器生成。有个周末我试着用编辑器做了一款“现代都市题材”的迷你 RPG主角是个外卖骑手在电子地图上送单、与客户对话、选择最佳路线。整个过程我真正写的代码不到 50 行大部分时间都在编辑器和游戏之间切来切去。那一刻我突然意识到数据驱动 可视化编辑器这套组合其实可以泛化到很多内容创作场景不仅仅是 RPG。最后聊一点个人体会。这个项目最让我意外的是做完之后我对“游戏引擎”这个词的理解变了。以前觉得引擎是渲染引擎、物理引擎那些底层技术现在我认为对内容型游戏来说真正的引擎是你定义的那套数据格式、状态流转和事件模型。所以如果你也要做一个浏览器版 RPG我的建议非常明确从第一天起就把“内容即数据”当作最高优先级来设计哪怕初期多写一些类型定义和校验函数也值得。当你能用编辑器拖出一段剧情、一个宝箱、一场敌袭当你能用回放测试从开局一口气打穿到最终 Boss那种“一切都可控”的感觉会让所有加过的班都变得值当。