跳到主要内容

实现导读:从输入走到一帧画面

先确定两个代码所有者​

共享领域规则在 src/lab/arenaRules.ts,Cocos 工程中的 assets/scripts/rules.ts 由构建流程同步;引擎表现位于 examples/arena/assets/scripts/Arena.ts。前者拥有局级状态、角色数值、动作阶段、命中与波次;后者拥有键盘、触摸、节点、Label、固定步累积和本地存储。阅读或修改时保留这个方向:适配层调用规则,规则不回头查场景节点。

先在 rules 中看 ArenaInput、Enemy 与 Arena。输入只有方向向量和攻击意图,敌人保存编号、位置、生命及上次命中攻击编号;局内状态保存生命、位置、朝向、动作时间、无敌和波次等待。模型没有动画资源与组件引用,因此可以在 Node 测试中直接创建,不必启动编辑器。小规模数组扫描是为了可读性,并非已经证明适合大量实体。

一次开始如何建立初态​

createArena 返回 ready 状态,startArena 用它覆盖原状态,再设置 playing 和第一波。统一重置可以避免重试时遗漏旧攻击编号、击杀或波次等待。spawnWave 按波次生成固定分布的敌人,数量是二加波次;因此三波分别有三个、四个、五个。代码没有受控随机流,重试布局一致是固定公式的结果,不是种子管理已经完成。

Arena 组件的 onLoad 设置设计分辨率,创建 Graphics 和文字节点,读取本地最高分,注册输入与隐藏事件,并安装文本导出和手动推进钩子。onDestroy 对应解绑并删除钩子。这里体现生命周期配对:注册的位置与释放的位置可以不同,但所有者必须明确。若未来允许组件禁用后重新启用,还需重新检查是否应使用 onEnable 与 onDisable 组织订阅。

显示帧与逻辑步分开​

update 累积经过限制的显示时间,以六十分之一秒为固定步调用 tick,最后绘制。tick 汇总键盘、触摸方向与点击目标,形成 ArenaInput 后调用 stepArena;一次性 attack 标志随后清除。按住空格通过 keys 集合持续产生意图,所以能在空闲后续攻。输入采样、逻辑推进和绘制分开后,不同显示帧率更容易保持接近的规则节奏。

// 阅读顺序示意,实际函数位于案例源码。
// keyDown / touchStart → 输入状态
// update → 累积时间 → tick
// tick → stepArena(state, input, 1 / 60)
// stepArena → 移动、阶段、伤害、波次、胜负
// paint → Graphics 与 Label

规则入口自身也限制 dt 最大为三十分之一秒,这是异常输入保护,不是完整补帧器。直接调用 stepArena 一次并传入一秒,不会模拟一整秒,只会推进被截断的一小段。测试和手动推进应重复小步;不能把“输入的时间总量”与“规则真正接受的时间总量”混为一谈。恢复后台时则保持暂停,避免用隐藏时长补算战斗。

stepArena 的顺序就是规则​

只有 playing 才继续;然后推进时间与无敌,处理移动和朝向,接受空闲攻击,计算当前攻击阶段。随后遍历敌人:检查有效期命中与去重,扣血击退,存活敌人继续追击,再检查接触伤害。最后过滤死亡敌人、累计击杀,先判断失败,再处理清敌等待与下一波。改变顺序可能改变同帧结果,不能把它当成纯格式重构。

命中使用距离和朝向点积,attackId 与 hitAttack 防止同一次攻击在多个逻辑步重复扣血。击退直接改敌人坐标,没有调用物理引擎;敌人运动也是手写追击。因此加墙时必须同时处理运动约束与击退约束,只给场景添加 Collider 不会自动阻止这些坐标赋值。对新系统的依赖边界应从当前实现事实推导。

paint 负责如实显示​

paint 清空并重绘背景、格线、攻击扇形、敌人、玩家和按钮;文字通过 text 辅助函数只在字符串变化时赋值。HP、WAVE、KILLS 和动作阶段来自模型,覆盖层由局级 status 决定。画面不反向决定状态,所以即使关闭某个标签,击杀和胜负仍按规则发生。当前实现每帧绘制,适合小型几何案例,性能需要实际测量才能外推。

攻击扇形在前摇时较淡、有效期时更明显,玩家无敌期间换颜色,敌人生命变化通过颜色和血条表达。它们提供观察窗口,却不是完整的正式反馈设计;声音、动画、屏幕阅读支持和全部触摸设备适配没有因为出现图形就自动完成。正式美术接入时保留调试几何,验证视觉范围与规则范围一致。

跨会话与平台边界​

tick 检测 playing 转为 won 或 lost 时更新最高击杀并尝试写入 arena-best。存储失败被视为可容忍,不阻止当前局。hide 将运行局暂停并清理方向与移动目标,恢复由玩家继续。这里没有云端确认、账户生命周期或支付事务,扩展时应新建适配边界,不要在 paint 里加入业务请求。

render_game_to_text() 导出模型与最高分,适合对照画面;advanceTime(ms) 用小步手动推进,并切换为手动模式,便于自动化重放。进入手动模式后,正常 update 不再推进,测试结束应重新加载以恢复普通运行。调试钩子不是生产网络接口,不能据此推断多人同步或可信时间已经实现。

修改时怎样缩小影响面​

调参改共享规则常量,输入问题改适配层,文字和颜色改表现;新能力需要同时检查规则、表现、测试与规格。先保留当前行为快照,修改后重放原输入,解释哪些差异预期发生。不要在扩展敌人种类时顺手重写存档,也不要只修改 Cocos 同步副本而让下一次构建覆盖改动。职责明确能让 AI 输出更小、更可审查的变更。

给 AI 的任务与验收​

任务示例:“为当前代码添加攻击范围调试开关,规则和输入不变。说明具体修改函数,运行规则检查,并比较开关前后导出的模型快照。不要安装框架或改共享规则同步方向。”这类任务能检验 AI 是否真正理解表现不应改变状态。

验收时依次追踪输入、固定步、规则事件和画面,任何异常先确定发生在哪层。模型正确但画面错,检查 paint 与坐标转换;模型错误,检查 step 顺序与输入;重试后才异常,检查生命周期和重置。构建与真机证据统一见验证报告,扩展路径见配方。

为一次异常选择最短诊断路径​

例如玩家说攻击没有命中,先导出 attackPhase、attackId、玩家朝向和敌人坐标,计算距离与点积;若规则拒绝符合预期,再检查范围图形是否让人误解。若敌人已经掉血却没有明显反馈,则转到 paint 检查颜色和血条。不要先在输入、动画和伤害三个位置各加一次补丁,否则重复命中问题可能被暂时掩盖。文本状态是诊断入口,画面是最终需要如实表达的结果。

另一个例子是隐藏后角色继续移动:先确认 hide 是否到达,再看 keys、touches 与 target 是否被清空,最后检查恢复时是否重新采样输入。模型暂停只负责不推进,不会自动改变适配层集合。把问题放回正确所有者,修复通常更小,也更容易用原复现步骤证明有效。

来源与核查范围​

  • 本仓库共享规则、Arena 组件与 tests/rules.test.ts,核查日期:2026-11-17。本页是源码阅读说明,不把测试存在等同于测试已经执行。
  • Cocos 3.8 生命周期与事件机制,核查日期:2026-11-17。