AI 角色、NPC、动画对象卡在原地不动:四层判定图与排查顺序 | 杨元超的世界

读者是谁

这篇写给所有做每帧更新的人:游戏单位、动画角色、地图标记、看板卡片、大屏上的移动点位,只要它「本来应该自己动,现在却停住了」,下面的查法都能直接用。你不需要读过这个项目的代码,也不需要知道它用什么引擎。先看这张表,找到自己该从哪节开始:

读者 带走什么 拿它做什么 从哪节开始读
做过实时交互、遇到过「对象该动没动」的开发者 四层判定图 下次遇到按层查,不从头翻代码 2
被这类问题卡了很久的人 二分排查法 先判「没决定动」还是「动了没生效」,把范围砍一半 2
想给团队留一份排查手册的人 可打印的四层表 放进值班文档,按现象对号入座 6
只想看一次真实排查过程的人 完整走查 看四层怎么在一个例子里落地 7

0 本文讲什么

这篇只讲一件事:对象该动却没动时,按什么顺序查。它不绑定某个项目,也不要求你先把整套代码读完。核心产出是一张四层判定图,和一条能立刻执行的二分动作。下面这张表说明每节讲什么、读它能得到什么:

小节 讲什么 读它能得到什么
1 先把「动」拆成四步 知道该在哪一步找断点
2 二分:没决定动,还是动了没生效 一条能把搜索空间砍半的判据
3 上游三种常见原因 该动却没产生移动意图时查什么
4 下游四种常见原因 有意图但位置不变时查什么
5 外部约束 分清「坏了」和「本来就不许动」
6 四层判定表 一张可打印的对照表
7 一次真实走查 看四层怎么连起来用

1 先说清上下文:这里的「动」指什么

设想一个关卡类游戏:玩家在地图上推进,己方单位平时会自动寻找目标、绕开障碍、走到射程内停下来开火。玩家不直接操控每一个单位,所以「它站着不动」不是画面小问题,而是整场战斗卡住。

这类对象每帧都要跑同一段流程,可以拆成四步:决定要不要动 → 算出往哪动、多快 → 把位置更新上去 → 被外部条件允许。四步串成一条链,任何一环断掉,用户看到的现象都一样:它站着不动。

本帧开始
   │
   ├─ 1 要不要动?  目标、距离、状态
   │       │ 否 → 结束(画面:站着)
   │       ▼ 是
   ├─ 2 往哪动?    朝向、速度、路径
   │       │ 失败 → 结束(画面:站着)
   │       ▼
   ├─ 3 写位置      本帧位移
   │
   └─ 4 外部允许?  拾取、暂停、关卡规则、服务器校正

后面拿一个关卡类游戏里的单位举例,但四层判定对任何每帧更新的对象都成立:列表项的自动滚动、动画角色的待机位移、地图标记的巡航,断点都落在这四步里。

2 第一步永远是二分:是没决定动,还是动了没生效

不要一上来就从入口函数往下读。先回答一个问题:这一帧有没有产生「朝某方向、多少速度」的输出。

判据只有一个:把「本帧意图」和「本帧位置」同时打出来。这段探针(往代码里临时加的一段打印,用来观察某个量)不需要 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,偶尔有值 意图是间歇产生的 先确认采样间隔,别只看一帧

这一步最值钱的地方不是找到原因,而是把搜索空间砍一半。没有它,你会在「目标判定」和「位置更新」之间反复横跳。

3 上游:该动却没决定动(三种常见原因)

这一层的共同点是:位置更新的代码根本没被执行,因为前面就返回了。三种原因按出现频率排。

目标判定不成立

距离或条件判定写反、边界写错

状态卡在某个不动的状态里

4 下游:决定了动,但位置没变

这一层已经有移动意图,日志里能看到非 0 的速度,但位置就是不动。按下面四种依次排除。

朝向没定,速度算出来是 0

很多实现是「先转身,再前进」:转向没完成时,前进速度被置为 0。转向一旦失败,就永远不走。

路径没找到

更新被早退跳过

被外部系统覆盖

5 外部约束:它其实被允许不动

排完上下游,仍有一类情况:链路没坏,只是规则不允许它动。这类最容易被误判成 bug,因为现象完全一样。

6 四层判定表(可打印)

把前面几节压成一张表。值班时先按「现象特征」找到行,再按「先查什么」动手,最后用「怎么确认」收口。下表可以直接打印贴出来:

层级 现象特征 先查什么 常见写错 怎么确认
1 要不要动 完全没有移动意图 目标是否存在、是否可达 找不到目标当正常待机 打印目标与可达标记
1 要不要动 差一点才动 距离与阈值两个数 大于/大于等于写反、单位混用 两数并排打印
1 要不要动 停在某个状态不出来 当前状态、谁负责切走 等待不会再来的事件 打印状态与切换条件
2 往哪动 有意图、速度为 0 朝向误差、最终速度 转向死区、零向量 打印误差与速度
2 往哪动 有速度、位置不动 路径点数量 目标不可达返回空 打印路径长度
3 写位置 更新代码没执行 更新前是否到达 提前返回截断 更新前打点
3 写位置 写完又被改回 本帧两次位置 两个系统都写位置 写后与渲染前各打一次
4 外部约束 逻辑正常但不许动 持有、暂停、关卡阶段、服务器坐标 把规则当故障 逐项打印布尔量与阶段

7 一个真实例子的完整走查

背景是一个关卡类游戏:己方单位进入漫游后应该持续移动,实际却常常站在原地。采样 22.7 秒、191 次更新,二分把每次观察落到对应层,最后查出四处断点。

下面这张表按四层顺序列出这次走查的四次观察,每一行都是「看到什么 → 查哪层 → 判断出什么 → 怎么改」:

观察到的现象 按哪层查 判断出什么 怎么改
反复进入漫游分支 380 次,距离返回值 380 次全是 0,378 次路径长度为 0 第 2 层:往哪动 目标点被判不可达,寻路安静地返回空 把「路径为空」当异常暴露,不当正常待命
路径修好后走几步又停;完成回调短时间内重入 380 次,190 次被再入判断拦住 第 3 层:写位置 完成回调重入,状态被覆盖 给完成回调加再入判断,流程没结束不重入
个别单位路径与速度正常却不动;恢复时旧引用写着「正在移动」 第 1 层:要不要动 让路恢复用了旧状态快照,新调度不再来 恢复时重读当前对象,不沿用旧快照
走到了停靠距离却不开火;停靠与开火各写一份阈值 第 4 层:外部约束 它认为自己已经到了,不是不动 停靠与开火共用一个数,谁需要谁读

这四次观察的现象都是「站着」,断点却分散在四层。二分把每一次的搜索范围压到一层,剩下的只是打印对应的那一个量。

最后用两个判据收口:不再出现卡死与报错;12 秒内位移超过设定阈值。前者防止回归,后者直接对应「该动有没有动」。

还能怎么改进

这套方法当前仍有几个做不到的地方,值得在团队里提前说清:

下一步能做什么

  1. 挑一个你手上「该动却没动」的对象,先只打印「本帧意图」和「本帧位置」两个量,完成一次二分。
  2. 把第 6 节的四层表抄进值班文档,下次按现象行对号入座,而不是从入口函数读起。
  3. 检查你的等待状态是否有超时出口,没有就补一个;这是把偶发卡死变成可观测问题的最低成本改动。

这些内容来自哪里

这些内容来自一个真实项目里对「该动却没动」这类现象的连续排查:同一类问题在几周内反复出现,每次都用二分法定位到某一层,最后归纳成一张四层判定图。文中的案例与走查步骤都来自当时的真实排查记录。

相关文章