这篇写给所有做每帧更新的人:游戏单位、动画角色、地图标记、看板卡片、大屏上的移动点位,只要它「本来应该自己动,现在却停住了」,下面的查法都能直接用。你不需要读过这个项目的代码,也不需要知道它用什么引擎。先看这张表,找到自己该从哪节开始:
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 做过实时交互、遇到过「对象该动没动」的开发者 | 四层判定图 | 下次遇到按层查,不从头翻代码 | 2 |
| 被这类问题卡了很久的人 | 二分排查法 | 先判「没决定动」还是「动了没生效」,把范围砍一半 | 2 |
| 想给团队留一份排查手册的人 | 可打印的四层表 | 放进值班文档,按现象对号入座 | 6 |
| 只想看一次真实排查过程的人 | 完整走查 | 看四层怎么在一个例子里落地 | 7 |
这篇只讲一件事:对象该动却没动时,按什么顺序查。它不绑定某个项目,也不要求你先把整套代码读完。核心产出是一张四层判定图,和一条能立刻执行的二分动作。下面这张表说明每节讲什么、读它能得到什么:
| 小节 | 讲什么 | 读它能得到什么 |
|---|---|---|
| 1 | 先把「动」拆成四步 | 知道该在哪一步找断点 |
| 2 | 二分:没决定动,还是动了没生效 | 一条能把搜索空间砍半的判据 |
| 3 | 上游三种常见原因 | 该动却没产生移动意图时查什么 |
| 4 | 下游四种常见原因 | 有意图但位置不变时查什么 |
| 5 | 外部约束 | 分清「坏了」和「本来就不许动」 |
| 6 | 四层判定表 | 一张可打印的对照表 |
| 7 | 一次真实走查 | 看四层怎么连起来用 |
设想一个关卡类游戏:玩家在地图上推进,己方单位平时会自动寻找目标、绕开障碍、走到射程内停下来开火。玩家不直接操控每一个单位,所以「它站着不动」不是画面小问题,而是整场战斗卡住。
这类对象每帧都要跑同一段流程,可以拆成四步:决定要不要动 → 算出往哪动、多快 → 把位置更新上去 → 被外部条件允许。四步串成一条链,任何一环断掉,用户看到的现象都一样:它站着不动。
本帧开始
│
├─ 1 要不要动? 目标、距离、状态
│ │ 否 → 结束(画面:站着)
│ ▼ 是
├─ 2 往哪动? 朝向、速度、路径
│ │ 失败 → 结束(画面:站着)
│ ▼
├─ 3 写位置 本帧位移
│
└─ 4 外部允许? 拾取、暂停、关卡规则、服务器校正
后面拿一个关卡类游戏里的单位举例,但四层判定对任何每帧更新的对象都成立:列表项的自动滚动、动画角色的待机位移、地图标记的巡航,断点都落在这四步里。
不要一上来就从入口函数往下读。先回答一个问题:这一帧有没有产生「朝某方向、多少速度」的输出。
判据只有一个:把「本帧意图」和「本帧位置」同时打出来。这段探针(往代码里临时加的一段打印,用来观察某个量)不需要 npm install 安装任何库,只用语言自带的打印能力;放在「算出怎么走」之后、「写位置」之前,连续打几十帧就够:
// 放在「算出怎么走之后、真正写位置之前」
// intent 是这一帧算出的移动意图:方向 + 速度
const intent = computeMoveIntent(unit);
if (frame % 30 === 0) {
console.log('[move]', {
id: unit.id,
speed: intent.speed,
dirX: intent.dirX,
dirZ: intent.dirZ,
x: unit.x,
z: unit.z,
});
}
读这行日志只需看两个量:speed 是不是 0,以及两帧之间 x/z 有没有变。上面这段是示意:把「算出方向与速度」和「读取当前位置」换成你项目里的对应调用即可,名字不用照抄。
| 日志表现 | 结论 | 下一步 |
|---|---|---|
| speed 为 0,位置不变 | 没决定动 | 查第 3 节(上游) |
| speed 大于 0,位置不变 | 动了没生效 | 查第 4 节(下游) |
| speed 大于 0,位置在变,但用户看到没动 | 被覆盖或渲染没跟上 | 查第 4、5 节 |
| speed 偶尔为 0,偶尔有值 | 意图是间歇产生的 | 先确认采样间隔,别只看一帧 |
这一步最值钱的地方不是找到原因,而是把搜索空间砍一半。没有它,你会在「目标判定」和「位置更新」之间反复横跳。
这一层的共同点是:位置更新的代码根本没被执行,因为前面就返回了。三种原因按出现频率排。
这一层已经有移动意图,日志里能看到非 0 的速度,但位置就是不动。按下面四种依次排除。
很多实现是「先转身,再前进」:转向没完成时,前进速度被置为 0。转向一旦失败,就永远不走。
排完上下游,仍有一类情况:链路没坏,只是规则不允许它动。这类最容易被误判成 bug,因为现象完全一样。
把前面几节压成一张表。值班时先按「现象特征」找到行,再按「先查什么」动手,最后用「怎么确认」收口。下表可以直接打印贴出来:
| 层级 | 现象特征 | 先查什么 | 常见写错 | 怎么确认 |
|---|---|---|---|---|
| 1 要不要动 | 完全没有移动意图 | 目标是否存在、是否可达 | 找不到目标当正常待机 | 打印目标与可达标记 |
| 1 要不要动 | 差一点才动 | 距离与阈值两个数 | 大于/大于等于写反、单位混用 | 两数并排打印 |
| 1 要不要动 | 停在某个状态不出来 | 当前状态、谁负责切走 | 等待不会再来的事件 | 打印状态与切换条件 |
| 2 往哪动 | 有意图、速度为 0 | 朝向误差、最终速度 | 转向死区、零向量 | 打印误差与速度 |
| 2 往哪动 | 有速度、位置不动 | 路径点数量 | 目标不可达返回空 | 打印路径长度 |
| 3 写位置 | 更新代码没执行 | 更新前是否到达 | 提前返回截断 | 更新前打点 |
| 3 写位置 | 写完又被改回 | 本帧两次位置 | 两个系统都写位置 | 写后与渲染前各打一次 |
| 4 外部约束 | 逻辑正常但不许动 | 持有、暂停、关卡阶段、服务器坐标 | 把规则当故障 | 逐项打印布尔量与阶段 |
背景是一个关卡类游戏:己方单位进入漫游后应该持续移动,实际却常常站在原地。采样 22.7 秒、191 次更新,二分把每次观察落到对应层,最后查出四处断点。
下面这张表按四层顺序列出这次走查的四次观察,每一行都是「看到什么 → 查哪层 → 判断出什么 → 怎么改」:
| 观察到的现象 | 按哪层查 | 判断出什么 | 怎么改 |
|---|---|---|---|
| 反复进入漫游分支 380 次,距离返回值 380 次全是 0,378 次路径长度为 0 | 第 2 层:往哪动 | 目标点被判不可达,寻路安静地返回空 | 把「路径为空」当异常暴露,不当正常待命 |
| 路径修好后走几步又停;完成回调短时间内重入 380 次,190 次被再入判断拦住 | 第 3 层:写位置 | 完成回调重入,状态被覆盖 | 给完成回调加再入判断,流程没结束不重入 |
| 个别单位路径与速度正常却不动;恢复时旧引用写着「正在移动」 | 第 1 层:要不要动 | 让路恢复用了旧状态快照,新调度不再来 | 恢复时重读当前对象,不沿用旧快照 |
| 走到了停靠距离却不开火;停靠与开火各写一份阈值 | 第 4 层:外部约束 | 它认为自己已经到了,不是不动 | 停靠与开火共用一个数,谁需要谁读 |
这四次观察的现象都是「站着」,断点却分散在四层。二分把每一次的搜索范围压到一层,剩下的只是打印对应的那一个量。
最后用两个判据收口:不再出现卡死与报错;12 秒内位移超过设定阈值。前者防止回归,后者直接对应「该动有没有动」。
这套方法当前仍有几个做不到的地方,值得在团队里提前说清:
这些内容来自一个真实项目里对「该动却没动」这类现象的连续排查:同一类问题在几周内反复出现,每次都用二分法定位到某一层,最后归纳成一张四层判定图。文中的案例与走查步骤都来自当时的真实排查记录。