1. 为什么我要用 TypeScript 重写经典RPG还顺手造了个编辑器把《仙剑奇侠传》用 TypeScript 从零重写成浏览器版是我给自己定的一次项目练习。如果只做几个演示场景我根本不会开这个坑真正让我想动手的是那个更麻烦的配套工具——可视化编辑器。因为经典RPG的内容量太大了几十张地图、上百条对话、几十场战斗就算照着攻略抄流程纯手写数据也会写到崩溃。我见过太多前端游戏项目地图画好了角色能走了然后就停住了。为什么因为大家把注意力全放在“引擎”上觉得把渲染、碰撞、动画写好就完事。可真正常见的情况是地图多到要一个个手配坐标NPC对话要用代码硬编码战斗数值改一次要在源码里翻半天。这种状态下的项目别说通关了连把第一章样例跑顺都费劲。我这次反着来先把数据模型想清楚再让游戏引擎和可视化编辑器共用它。做到后面发现可通关反而是水到渠成的事。1.1 内容量是大多数游戏项目的隐形杀手写业务代码的人都知道技术难点往往不可怕真正怕的是业务逻辑无穷无尽。RPG游戏更是这样。技术层面无非是地图渲染、贴图、碰撞检测、战斗计算本质上就是一组规则但“内容”不一样一个支线NPC、一段选项分支、一件关键道具这些都是内容。你可以把规则写得再好内容装不进去游戏依旧是空的。我的第一个版本犯过这个错直接在类里面写死地图和对话结果每加一个对话就要改代码、重新编译非常痛苦。后来我把所有内容抽成 JSON把游戏抽象成一个“解释器”后才意识到编辑器是必然产物。因为JSON虽然结构化但人脑不适合直接处理上百个节点。可视化编辑器本质上是给 JSON 套了一层友好的外壳让创作者不用关心x: 320, y: 240这种坐标而是直接在地图上拖拽一个NPC。你甚至可以把它看成“低代码平台”只不过表单字段是地图格子、对话文本、战斗数值最后导出的是一份完整的存档数据。当我决定做这个东西之后项目的主线才清晰起来游戏运行时是数据解释器编辑器是数据生成器两者之间靠一套严格的 TypeScript 接口保证不会跑偏。1.2 只做Demo没劲可通关才是试金石很多开发者的练习项目做完一个场景就扔了因为缺少一个“完成”的定义。我给自己定的完成标准非常明确玩家打开浏览器能从进入游戏到击败最终Boss看到制作人员名单中途不需要刷新页面。这听起来简单实际上逼着我把所有核心系统串起来。要做到可通关至少得有一条完整的主线循环开场剧情、进入第一张地图、触发一个无法绕过的战斗事件、拿到某个关键道具、解锁新区域、再打几场Boss、最后结算。这个链条里只要某一个模块不通游戏就卡死。比如战斗结束后的setFlag写错了下一个NPC就不出现地图切换时坐标算错了角色可能掉进虚空存档格式漏了一个字段读档就崩。所以可通关不是终点而是对系统设计最严格的验收方式。它强迫你面对那些Demo里根本不会出现的麻烦状态持久化、事件执行的时序、多场景资源切换、数值平衡。我后来在编辑器里加“一键试玩全流程”功能其实就是让程序自动跑一遍完整主线每次改完内容都能立刻知道有没有破坏通关路径。这么做以后项目的完成度提升非常快。1.3 编辑器不是玩具是给内容创作者的生产工具给非技术人员做编辑器最容易做成“看起来能用其实没人真用”。我很多教训都来自这里比如把技术命名直接暴露给用户用户看到storyFlags直接懵了比如没有实时校验用户随手删一个字段预览页面就白屏。所以编辑器早期设计时我就定了三条原则所见即所得、数据自动校验、所有操作可撤销。所见即所得是指你在编辑器中拖一下NPC位置预览画面立刻就能看到效果自动校验要求任何输入框失焦时都能判断合法性比如战斗掉落概率不能超过100%可撤销则是防止创作者手滑删掉一整条剧情线。这三条原则听起来简单每条实现起来都不轻松但它们才是编辑器真正能提高生产力的原因。我的编辑器最终不是给程序员用的而是给那些只知道“这段对话之后要打一场Boss”的内容策划用的越接近人的直觉越有价值。2. 整体架构让游戏引擎和可视化编辑器共用同一套数据模型我从一开始就不想让游戏运行时和编辑器各写一套逻辑。那样会出现最坑的情况编辑器中一个剧情明明编排好了但真跑到游戏里却对不上。解决这个问题只有一个办法两边都吃同一份数据模型都跑同一个解释器。2.1 模块划分core / data / editor 三层项目目录我按下面这样分src/ core/ # 游戏引擎渲染、输入、场景管理、事件解释器 data/ # 类型定义、默认数据、存档Schema、校验工具 editor/ # 可视化编辑器面板、画布、属性控件 runtime/ # 浏览器入口加载资源、启动游戏、挂载编辑器预览core不关心具体剧情是什么它只负责“如何根据数据来运行”。data是契约所有跨模块交互都通过这里的 TypeScript 接口。editor不直接操作引擎内部私有状态而是通过一套名为GameDataBinder的中间层去读写场景数据。为什么要这么分因为你一旦开始做大项目就会发现引擎和编辑器都非常容易膨胀。如果它们混在一起每次编辑器加个功能游戏引擎也会被迫跟着变。有一次我给编辑器加了一个“怪物巡逻路径预览”发现引擎层核心类被编辑器逻辑侵入了导致游戏里角色移动的 update 顺序被改动差点引入恶性 Bug。后来我强制规定编辑器只能通过数据接口更新场景绝对不能调用引擎内部方法。这个约束换来了长期的干净。2.2 统一数据 Schema 的具体设计所有内容数据都抽象成接口先看最核心的MapData和EventAction。我用的是偏“描述性”的写法而不是直接存某个引擎对象的状态。interface TileSet { id: string; image: string; tileWidth: number; tileHeight: number; collisionIndices: number[]; } interface GameMap { id: string; name: string; width: number; height: number; layers: number[][]; events: MapEvent[]; } interface MapEvent { id: string; type: trigger | item | teleport | npc; x: number; y: number; triggerWhen: walk | touch | talk; actions: EventAction[]; } type EventAction | { type: dialogue; dialogueId: string } | { type: battle; battleId: string } | { type: addItem; itemId: string; count: number } | { type: setFlag; flag: string; value: boolean } | { type: teleport; mapId: string; x: number; y: number };你可能注意到EventAction是一个可判别联合类型这很重要。因为 TypeScript 可以自动收窄它的类型在编辑器里做属性面板时编辑器可以根据action.type动态渲染对应字段。比如type为battle时表单里只显示战斗ID下拉框type为teleport时则显示地图ID和坐标。字段少了犯错概率就低。地图中的格子不是单一二维数组而是多个图层。底层可能只放草地、地面上层放树、墙壁这类遮挡物。碰撞层不直接存在于渲染数组中而是单独维护一份collision: boolean[][]。这样画地图的时候可以独立开关碰撞层避免玩家直接走到树顶上。剧情数据用节点树表示每个对话节点有speaker、text、next可选的choices实现选项分支。所有分支最终指向另一个节点 ID形成一个有向图。战斗数据则独立设计一场战斗就是一组敌方单位、一场奖励、一个胜负条件。2.3 游戏运行时与编辑器如何共用同一个解释器有了统一 Schema 后最关键的是写一个“事件解释器”它可以读取MapEvent里的actions然后逐条执行。游戏运行时使用它编辑器预览也使用它。唯一的差别是上下文。class EventExecutor { constructor( private state: GameState, private bus: EventBus ) {} async run(actions: EventAction[]): Promisevoid { for (const action of actions) { switch (action.type) { case dialogue: await this.bus.emit(dialogue, action.dialogueId); break; case battle: await this.bus.emit(battle, action.battleId); break; case addItem: this.state.inventory[action.itemId] action.count; this.bus.emit(inventoryChanged, this.state.inventory); break; case setFlag: this.state.storyFlags[action.flag] action.value; this.bus.emit(flagChanged, action.flag, action.value); break; case teleport: this.state.currentMapId action.mapId; this.state.player.x action.x; this.state.player.y action.y; this.bus.emit(mapChanged, action.mapId); break; } } } }这个执行器最大的特点是事件本身只表示“发生了什么”而真正做什么由总线上的订阅者决定。编辑器预览时订阅者可以是输出面板和日志游戏运行时订阅者才是渲染器和UI。这样同一个actions数组在两边行为完全一致。我再也没有遇到过“编辑器里看着正常跑到游戏里触发不了”的事情。3. 核心玩法模块拆解地图、对话、战斗与状态管理3.1 地图渲染从 Tile 到镜头跟随地图用 Canvas 2D 渲染每个 tile 尺寸是 32×32。定义GameMap之前需要先加载 TileSet 图片然后根据layers中的图块索引从图片上截取目标区域。渲染顺序上要先画底层再画上层遮挡最后画角色和NPC。如果是 40×30 的地图一次全量重绘足够流畅因为普通地图最多也就一千多个格子。碰撞检测采用网格阻挡加事件占位两层。角色移动时先把目标坐标转成网格坐标如果该格collision[x][y]为true就不能进入。除了地形碰撞大多数NPC也有碰撞体积但我不给NPC单独设碰撞体而是把“有NPC的地图格也标记成碰撞格”。这样更简单代价是NPC一旦移动碰撞状态必须同步刷新。我的NPC寻路没有做复杂AI只是按固定路径走每次移动后更新碰撞格。镜头跟随如果做不好角色会跑到屏幕边缘外。我用的做法是先计算镜头左上角坐标以主角为中心限制在地图尺寸内同时保证镜头不能露出地图外的黑色区域。计算方式是cameraX clamp(playerX - viewWidth / 2, 0, mapWidth - viewWidth); cameraY clamp(playerY - viewHeight / 2, 0, mapHeight - viewHeight);看起来很简单但第一次做时漏掉了地图小于屏幕的情况直接导致数组越界。所以后来加了mapWidth viewWidth的判断居中处理。3.2 对话与剧情把“剧情”变成可执行的数据对话系统的核心不是UI弹窗而是状态机。当触发一个对话节点后当前节点进入展示状态玩家按确认键会推进到next指向的节点如果存在choices则显示选项。每次推进都会重新读取当前节点数据这天然支持了分支和循环。我习惯把对话分成两类线性对话和分支对话。线性对话就是一句接一句分支对话则在关键节点使用choices。编辑器里可以直观看到某个节点有哪些选项、每个选项跳转到哪里。数据示例interface DialogueNode { id: string; speakerId: string; avatar?: string; text: string; next?: string; choices?: { text: string; next: string; needFlag?: string; }[]; }needFlag的加入让很多剧情条件变得容易处理。比如某段对话只有在玩家拿到了某个关键道具后才出现只需要在选项或节点上挂一个 flag 判断。解释器遇到needFlag时去storyFlags里找不满足就直接跳过这个分支。这比硬编码 if/else 清晰多了。3.3 战斗系统回合制逻辑与数值模拟回合制战斗拆成五个阶段选择指令、计算行动顺序、执行玩家行动、执行敌方行动、检查胜负。行动顺序由每个角色的agility决定我做的版本直接用 agility 从高到低排序没有用实时进度条。如果后续想支持“等待时间”类技能可以改成累加速度值。伤害公式要尽量简单可调。物理伤害我用的是damage max(1, floor((attack * 2 - defense) * rand(0.9, 1.1)))法术伤害我让技能本身带一个系数再乘角色属性值damage max(1, floor(skill.power * (magic / 100) * rand(0.95, 1.05)))这里的magic是角色当前灵力。所有数值都来自战斗数据接口。如果数值不平衡玩家要么秒杀Boss要么被小怪秒杀。我在调第一个Boss时把攻击力从 45 调到 42就发现原本必输的局变成险胜。可见这类经典游戏对数值容错其实很敏感不能随手乱填。战斗结算也需要做成一个标准事件流胜利后执行onWinActions比如加经验、掉落物品、设置Flag。注意经验升级、道具掉落这些操作必须等到战斗画面完全退出后再执行否则可能出现“战斗还没显示完剧情已经推进”的错乱。3.4 角色状态与道具用单一状态树管理全局数据一个RPG游戏里几乎所有系统都要访问状态移动需要知道当前坐标对话需要判断条件战斗需要读取队伍属性UI需要背包数据。如果状态分散在各个对象里后期一定改到怀疑人生。我用的是单一GameState对象整个游戏运行过程中只有一个实例interface GameState { currentMapId: string; player: { x: number; y: number; direction: up | down | left | right; moving: boolean; }; party: PartyMemberData[]; inventory: Recordstring, number; storyFlags: Recordstring, boolean; playTime: number; }所有修改只能通过dispatch(action)调用类似 Redux 的思路。这样做的好处是存档可以直接拿到GameState做 JSON 序列化编辑器预览时也能直接替换整个状态来测试不同进度。坏处是写起来稍微啰嗦但换来的是可预测性。上线后排查Bug时最常用的操作就是打开控制台打印一份完整的GameState然后看某个 flag 到底有没有被置位。4. 靠什么做到“可通关”最小闭环与存档机制4.1 最小闭环的搭建顺序我强烈建议不要从最复杂的场景开始。先把一条最简路径跑通再反过来完善内容。我当时定的路径是进入第一张地图 → 与主角同伴对话 → 拿到第一把武器 → 出门触发一次战斗 → 战斗胜利后自动设置flag: met_bandit→ 回到村子发现长老解锁新对话 → 拿到钥匙 → 打开最终通道 → 打最终Boss → 通关。这条路所有内容不超过两张地图、三场战斗、二十段对话但它完整覆盖了地图切换、事件触发、战斗、Flag、道具、通关这些核心循环。跑通后我再逐步往里面加支线、加更多地图。每加一次都要重新跑一遍自动化验收脚本确保之前的主线没有被破坏。实现主线进度时我定义了好几个storyFlags比如has_sword、met_bandit、gate_open。普通NPC的事件里会判断这些 flag不同阶段显示不同对话。Boss门前的守卫经典做法是只有has_sword为 true 才让玩家进入否则就弹一句“你还不能过去”。这个逻辑看起来简单却是很多游戏内容管理的基础。4.2 剧情事件与战斗事件的衔接方式玩家触发战斗不一定是主动对话很多时候是踩“暗雷”。我在地图数据中定义了encounterGroups每一组包含出现格子列表、可遇到的敌人池、遭遇概率。当角色在对应格子移动时每走一步生成一个随机数小于遭遇概率就进入战斗。战斗胜利后会返回触发战斗前的坐标而不是重置到地图入口不然玩家会非常沮丧。但在主线剧情中我更推荐使用“明雷”或“强制事件”。比如某个桥头放了事件triggerWhen: walk该事件动作列表第一个就是battle。这种按步触发的方式比随机遭遇更可控。战斗结束后自动执行下一个动作比如setFlag、dialogue这样剧情衔接非常紧密。编辑器里可以做“主线步骤预览”按顺序列出所有必须触发的事件一旦漏配立刻红字提示。4.3 存档与继续localStorage 与数据序列化浏览器的存档当然先想到 localStorage。我直接把当前GameState序列化成一个压缩过的 JSON 字符串。注意要额外存一个schemaVersion否则以后数据结构加了新字段老存档可能读不了。读取时我会先做一次“迁移”如果发现schemaVersion低于当前版本就补默认值而不是直接报错。存档操作本身要放在合适的时机。我的做法是每次地图切换和战斗结算后自动检查“是否到达可存档点”。也可以提供手动存档但手动存档的表单需要玩家输入档位名编辑器里要记得加保存选项。还有一个容易踩的坑localStorage 有大小限制如果将来物品、地图数据都放进去可能爆掉。所以我只存GameState不存资源文件。所有地图和剧情数据要么打包进代码要么走 CDN 加载但绝不放进入存档。5. 可视化编辑器从 JSON 手刷到可视化拖拽5.1 编辑器要解决什么问题编辑器最核心的价值是“降低内容创作门槛”。我最初用 JSON 写地图事件写五十个事件还行写到两百个就各种配错。这个错误还非常隐蔽少一个逗号不是最惨的最惨的是字段名拼错了也不报错运行时剧情完全不触发。编辑器要做的就是让这种低级错误不可能发生。面板设计上我采用了左侧资源树、中间画布、右侧属性面板、底部日志的经典布局。资源树列出所有地图、对话、战斗、道具画布显示当前地图和可编辑的事件点属性面板根据选中的对象自动渲染对应表单底部日志输出校验信息和预览执行记录。这样创作者的一整套工作流都在一个界面内完成不用来回切工具。5.2 地图编辑器画格子、摆事件地图编辑器的交互要尽量贴近绘图软件。左键选择当前笔刷在地图上点一下涂一个 tile右键擦除碰撞层用独立图层编辑图块上会画一个半透明的色块表示不可通行。事件点则用图标覆盖在地图上不能直接涂掉只能拖动位置。TileSet 支持多套图集编辑时通过下拉框切换。我建议把同一场景需要的图块合并到一张图片里像古早游戏那样用索引引用。这样加载时只需要加载一张图渲染时也很高效。碰撞层只是索引集合随便勾选哪几个图块会挡路。5.3 事件与对话编辑器用表单替代写代码事件编辑器是最能体现“低代码”价值的地方。左边选中一个事件后右边出现triggerWhen下拉框和actions列表。actions每一条都有类型选择battle后自动出现战斗下拉框选择dialogue后出现对话树预览选择teleport后出现地图、坐标输入。你根本不需要知道底层代码长什么样只要你理解“这个事件是让玩家走到这里后触发一场战斗”就能配出来。对话编辑器用树形列表展示节点分支选中节点后编辑台词、下一步、选项。每一条分支都可以设置needFlag我这里做了一个小标记图标如果 flag 还没定义会警告。选项目标节点也做了防环检测避免出现 A 选项跳到 BB 选项又跳回 A 的死循环。防环检测一开始没做结果测试时聊天框卡死非常尴尬。5.4 实时预览让编辑器直接跑游戏实时预览是编辑器的灵魂。做法是编辑器内嵌一个只读版本的运行时它加载当前数据快照。每当创作者修改地图、事件、战斗数值数据变更会触发预览刷新。比如拖动一个 NPC 坐标后预览画面里的 NPC 立刻移动把Boss血量从1000改成800预览里战斗的数值也会更新。这里要注意性能不能每改一次就重新加载整个地图。我用了“数据补丁”机制只更新变化的对象同时在编辑器内维护一个isDirty集合统一在下一帧应用。这样在地图上连续拖动一个NPC时不会产生几百次刷新。预览还有一个调试功能显示所有事件触发器包围盒以及下一步执行的事件列表。创作者不需要看代码只要看到“当前事件将在角色进入 (4,5) 时触发对话加道具设置Flag”就能确认逻辑正确。这个功能极大降低了内容的排错成本。6. 实操中踩过的坑与解决实录6.1 游戏加载白屏与资源预加载上线第一天我遇到的是“地图加载出来时角色已经掉进虚空”。原因是地图数据和资源图片同时异步加载角色更新逻辑先跑了而碰撞网格还没就绪。解决方式是给场景加载加一个 Promise 栅栏所有资源必须先预加载完成再启动角色逻辑await Promise.all(this.mapResources.map(res res.load()));加载过程中显示一个简单的进度条否则白屏时间稍微长一点用户会怀疑程序坏了。后来编辑器里也做了实时预览同样需要预加载不然拖一次 NPC 位置就闪一下。6.2 事件脚本的性能瓶颈地图事件多了以后每次玩家移动都要遍历该格子的所有事件并检查触发条件和 flag。这个开销原本不大但我初期把事件列表放在数组里每次遍历不用 O(n) 排序结果单张地图超过五十个事件后开始出现卡顿。后来我把事件按格子索引存成一个Mapstring, MapEvent[]键是x,y这样检测触发时只需要取当前格子的数组瞬间就快了。战斗的动画性能是另一个坑。伤害数字如果每个都创建一个 DOM 元素几十个数字同时飘就会卡。我把伤害数字的弹出改用 Canvas 绘制所有飘字在一个统一数组里更新每帧只重绘一个层。这样就算同时出现十个暴击数字也不会触发大量DOM操作。6.3 浏览器兼容与移动端适配桌面浏览器一般用键盘操作上下左右键加确认键。但换到手机就不行了没有键盘。我加了一套虚拟方向键和一个确认按钮。实现方式不复杂屏幕左侧一个方向摇杆右侧一个确认键。事件监听用 pointer 事件统一鼠标和触摸避免同时触发 click 和 touch 事件导致重复响应。还有一个容易被忽略的点音频自动播放策略。浏览器需要用户交互后才能播放声音如果游戏加载后立刻audio.play()会被浏览器拦截。我的处理是在正式开始界面放了一个“点击进入”按钮用户点击后才初始化音频上下文。这样既解决了自动播放限制也给玩家一个明确的开始动作。6.4 编辑器数据校验与撤销重做编辑器做得越多越需要防错。我用 TypeScript 写了一套校验器在导出 JSON 前做完整检查。校验内容包括每个dialogueId是否真实存在、每个battleId是否真实存在、所有 teleport 目标地图是否存在、掉落概率是否在 0~1 之间。只要出现错误导出按钮会变灰并显示具体错误创作者必须先修完才能导出。撤销重做则用命令模式实现。每个编辑动作都是{ do: Function, undo: Function }推入历史栈。操作一次就 push 一条命令撤销时执行undo并弹出重做则把命令再压回。这个方案的好处是任何操作都能统一撤销坏处是内存会涨。我限制了栈深度超过 100 条就丢最老的否则做复杂编辑的时候浏览器会卡。还要注意一个问题预览和编辑状态不能完全共享内存中的对象否则撤销时会把运行时对象也改了。我的办法是编辑器内只保存“数据快照”每次修改后用 immutable 方式生成新对象预览引擎只读取这些新快照。撤销时就把快照恢复到某个历史版本再重新渲染。7. 给想复刻经典的人几句掏心窝的话这个项目前后折腾了大概一个多月大部分时间花在编辑器上游戏引擎反而只占三成。如果你也想用 TypeScript 重写一款经典RPG我最大的建议是先画一张数据 Schema 的图想象如果不写代码、不写 JSON内容创作者会怎样描述一个新场景。顺着这个思路你会自然知道地图、事件、对话应该怎么组织。第二个建议是别追求大而全。编辑器刚开始只需要支持地图编辑、事件编辑、对话编辑、战斗数值编辑就够了。什么粒子特效编辑器、AI行为树编辑器统统往后放。核心是让主线内容能顺利填进去。最后关于素材和版权我全程使用自绘图占位素材没有使用游戏原始资源。重写引擎可以做但发布时要确保素材的合法性。如果你也想做练习完全可以自己画简单的方块先把整个逻辑跑通再考虑美术升级。技术上的成就感已经足够不必陷入素材版权纠纷里。如果未来继续扩展我会给编辑器加一个“自动剧情检查器”让它根据故事Flag自动标记“这里通不过”的点甚至用图搜索找出完整通关路径。编辑器发展到最后本质上就是一个为游戏定制的领域建模工具。这条路值得走下去。