配置系统:把内容变成有版本的可信输入
配置不是天然可信的数据
敌人生命、技能时间、关卡波次和道具定义适合放在配置里,因为它们需要频繁调整且不应散落在脚本常量中。但 JSON 能被解析,不代表业务上有效。负冷却、重复编号、找不到的敌人类型、百分比单位混乱,都可能在运行很久之后才暴露。后端开发者熟悉的输入验证,应同样应用于本地资源和远程配置。
先区分定义、运行状态和派生值。敌人定义包含基础生命和速度;敌人实例包含当前生命、位置和目标;秒伤、升级成本等派生值由确定公式计算。把当前生命写回共享敌人配置,会让所有同类敌人一起掉血。把派生值也分别保存并手动维护,则容易出现公式与表格不一致。尽量保持一个明确真相,其他数据有可追溯的推导过程。
配置的首要目标是可解释和可检查,不是让所有行为都可热更新。第一版用 TypeScript 常量或本地 JSON 都可以;规则很少时,类型化常量甚至更容易重构。需要策划表格、远程下发或非程序人员编辑时,再建立导入与校验流程。不要为三种敌人搭建完整低代码规则语言,也不要用字符串表达式执行任意脚本。
从边界校验到引用校验
type EnemyDef = Readonly<{ id: string; hp: number; speed: number }>;
function parseEnemy(value: unknown): EnemyDef {
if (!value || typeof value !== 'object') throw new Error('enemy: object required');
const x = value as Record<string, unknown>;
if (typeof x.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(x.id))
throw new Error('enemy.id: invalid');
if (typeof x.hp !== 'number' || !Number.isSafeInteger(x.hp) || x.hp <= 0)
throw new Error(`${x.id}.hp: positive integer required`);
if (typeof x.speed !== 'number' || !Number.isFinite(x.speed) || x.speed < 0)
throw new Error(`${x.id}.speed: nonnegative finite number required`);
return Object.freeze({ id: x.id, hp: x.hp, speed: x.speed });
}
这里的类型断言只为读取未知对象,不代替运行时检查。校验器还需要遍历集合检查编号唯一,再验证关卡引用的敌人确实存在。错误应包含文件、条目与字段,不能只抛“配置错误”。数组长度、波次总量和生成次数也要有合理上限,防止意外填入巨大数字导致主线程卡死或内存峰值失控。
单位要在字段或模式中明确。例如 windupSeconds 表示秒,speedUnitsPerSecond 表示每秒世界单位,probability 表示零到一。不要同时出现 attackInterval、attackSpeed 和 rate 却没有说明转换关系。百分比、倍率和百分点应分清,暴击率增加百分之十与增加十个百分点并不相同。编辑表格时也要防止公式结果被导出成字符串或空单元格被解释为零。
版本固定在一局开始
一局战斗开始时取得一个不可变配置快照,后续伤害、刷怪与奖励都使用该版本。远程配置更新可以在主菜单或下一局生效,不应在攻击发出与命中之间无声替换属性。日志记录配置版本与生成器版本,问题复现才有依据。版本号只表示身份,不自动说明兼容性,必要时增加模式版本与最低客户端版本。
远程配置还需要下载失败、超时、格式错误和版本回退策略。可以保留内置安全版本,验证成功后再替换当前候选。重要限制不能只依赖可修改的客户端配置;可信奖励与价格由服务端确认。HTTPS 保护传输并不代表客户端无法修改,签名也需要正确的信任与密钥管理,本章不把本地配置当作资产安全机制。
在 Cocos Creator 3.8.8 中,JsonAsset 的 json 属性承载解析后的数据,仍需经过自己的 schema 校验。资源加载成功也不表示内容适合当前客户端。可以在启动或进入关卡前完成转换,把引擎资源对象映射成只读领域配置,后续模型不需要知道它来自 Inspector、文件还是网络。释放资源时也避免使仍在运行的配置快照失效。
配置变更与存档兼容
配置删除了一个道具编号,旧存档仍可能引用它;降低最高等级,玩家可能已经超过新上限。应为这些情况规定迁移、替代、退款或保留旧内容的规则。不要在加载时默默删除无法识别的资产。给内容编号保持稳定,显示名称可以改,编号不应随本地化或数组排序变化。重大删除保留映射表与迁移原因,便于追溯。
多人协作时,配置表与规则公式一起审查。新增一列不一定只影响数值:例如攻击从单目标变为范围,会影响目标选择、伤害去重、表现和性能预算。用最小示例展示变更前后结果,帮助 AI 和人类发现联动。表格导入应在构建前运行,不把每个用户启动时才发现的内容错误当作正常流程。
常见错误与定位
“某一关才崩溃”检查间接引用与分支内容;“编辑器里改了没生效”检查资源路径、缓存版本和本局快照;“所有敌人一起变强”检查共享定义被写入;“数字变成无穷”检查指数增长与有限数校验;“微信上读不到配置”检查构建资源、分包与平台路径。先输出实际加载版本和关键字段,再判断是不是业务公式问题。
测试不必为每个字段重复实现同样逻辑,但应覆盖代表性的无效输入:重复编号、未知引用、零周期、负概率、空候选集和超大数量。对配置集执行整体校验,输出所有可修复错误比每次只报第一个更高效。运行时遇到坏数据要拒绝进入危险状态或回退,不能带着一半配置继续战斗。
区分内容变更和规则变更
把敌人生命从十改为十二通常是内容调整,把护甲从减法改为比例公式则是规则变化,后者可能影响全部配置。给变更记录写出受影响范围和代表性结果,避免沿用旧平衡表得出错误判断。配置审核也应检查默认值是否掩盖遗漏:新字段若对玩法关键,缺失时应失败,而不是自动补零后让整类技能失效。默认值只适合确实可选且语义稳定的字段。
给 AI 的任务与验收
任务示例:“将敌人、波次和升级参数移到本地 JSON,保留稳定编号。实现 unknown 到只读类型的运行时转换,检查唯一性、引用和数量上限;一局固定配置版本。错误包含路径,失败时回退内置配置并展示开发日志,不增加远程后台。”同时给出合法和非法配置各一份。
验收包括坏文件不会创建半局、未知敌人能定位到具体波次、运行中更新不影响当前局、下一局使用新版本、旧存档引用有明确兼容处理。比较迁移前后的同一种子结果,确认仅预期参数发生变化。继续阅读存档迁移,把配置版本与玩家数据版本分开维护。
来源与核查范围
- Cocos Engine v3.8.8 JsonAsset 源码,核查日期:2026-11-17。核对 json 数据入口;schema、版本和回退方案是本文设计。
- Cocos 3.8 Bundle API,核查日期:2026-11-17。用于资源加载路径和预加载边界,不代表项目已实现远程配置。