Cocos Creator 逻辑解耦脚手架

解决什么问题

Cocos Creator 3.x 项目开发中有三个反复出现的痛点。

第一，逻辑与渲染耦合。游戏规则代码直接 import cc，导致离线无法用 node 跑单元测试或平衡验证——你必须打开编辑器才能确认一段伤害计算逻辑是否正确。

第二，场景 JSON 手写容易出错。Cocos 场景文件的 __id__ 字段是数组下标而非 uuid，插入或删除节点会导致整条引用链错位，报错信息如 [Scene] child._onBatchCreated is not a function 让人摸不着头脑。

第三，设计分辨率与坐标系不匹配。H5 原型的左上原点坐标系与 Cocos 的中心原点 y-up 坐标系差异大，直接搬过来会出现基地跑到画布外的情况。

核心能力与关键步骤

纯逻辑解耦架构是这个脚手架的核心。游戏规则（伤害计算、升级、出售、攻击）放进不依赖 cc 的模块，例如 BattleSim.ts，只操作纯数据。渲染、输入、UI 放在 ui/ 目录下，职责是「读 sim 状态 → 画」。这样编译成 CommonJS 后可以直接用 node 跑自动测试。

离线静态校验靠 cc 桩实现。在 /tmp/cchk/cc.ts 里导出一个宽松的 cc 命名空间（Node、Component、Graphics 等 class 和 instantiate 函数），配合 tsconfig.json 用 tsc 编译。注意脚本要保持 core/、ui/ 子目录结构，否则相对路径会解析错乱。

场景文件处理有一个致命坑：__id__ 引用的是顶层数组下标（整数），不是 uuid。正确做法是复制 Cocos 自带的 scene-2d.scene 当底座，自定义节点追加到数组末尾，保持原始模板下标不动。节点自己的 _id 字段必须是不含纯数字串的合法 Cocos 字符串。

程序化矢量美术省去图片资源：敌人用 Graphics 画圆加 Label 显示名字，路径用 moveTo/lineTo 连线 stroke，特效用临时节点 tween 淡出后销毁。

适用边界

cc 桩只能抓「明显类型错误」，比如组件上误调 getComponent 或字段不存在。运行时 Cocos API 的真实行为仍需编辑器首开确认。

场景 JSON 的节点插入/删除操作必须遵守「追加到末尾」原则，否则引用链错位。写完后建议用 node 跑一遍校验脚本，递归检查所有 __id__ 引用是否都在合法范围内且指向 cc.Node。

平衡验证 harness 的「自动玩家」逻辑是一个参考实现，覆盖 5 个元素、升最高 DPS、有钱升基地。它验证的是「逻辑能通关」，不等同于「人类体验好」——实际手感仍需人工调参。