1. 定位

AI 的问题通常不是"崩了"，而是"没按我想的做"——所以 AI 调试的关键是让内部状态可见。

一句话定位：两个工具解决 90% 的 AI 问题：Gameplay Debugger（看现在）和 Visual Logger（看过去）。

2. 两个核心工具

工具	看什么	什么时候用
Gameplay Debugger	当前 AI 的实时状态：黑板、行为树、感知、路径、EQS 查询	实时排查
Visual Logger	记录一段时间内的 AI 行为，可回放逐帧查看	事后排查（尤其是偶发问题）

Gameplay Debugger

在 PIE 中按 '（引号键）唤出，用数字键切换页签：

页签	内容
Basic	AI 基本信息
Behavior Tree	当前行为树的活跃节点与黑板键值
EQS	查询与评分结果
Perception	感知到的目标与刺激
NavMesh	路径与导航状态

排查"AI 为什么不攻击"的标准动作：打开 Gameplay Debugger → 看黑板里的目标键是否为 None → 看行为树哪个分支活跃。

Visual Logger

用 UE_VLOG 系列宏在代码里打点
记录后可在 Visual Logger 窗口里逐帧回放
适合排查"偶尔发生一次"的问题

3. 常用调试手段

手段	用途
`Show > Navigation`	显示 NavMesh
感知调试绘制	显示视野锥与感知范围
`ai.debug.*` 类 CVar	各类 AI 调试绘制
`Log LogBehaviorTree Verbose` / `Log LogAIPerception Verbose`	行为树与感知日志
EQS 测试场景（EQS Testing Pawn）	单独验证一个 EQS 查询
`stat ai` / 相关统计	AI 耗时

4. 性能：AI 的成本在哪

成本项	说明
感知	视觉检测最贵，随目标数与频率线性上升
行为树 tick	每帧重新求值装饰器与服务
EQS 查询	每次查询都要采样与测试，频繁查询很贵
导航	动态重建最贵；路径搜索次之
避让	个体数越多越贵
动画	每个 AI 都要跑 AnimInstance（见动画性能）

5. 优化手段

手段	说明
AI LOD / 更新频率	远处 AI 降低更新频率（与动画性能的 URO 配合）
感知降频	远处 AI 减少视觉检测频率
EQS 节流	不要每帧查询，缓存结果
导航模式	能用 Static 就别用 Dynamic（见导航系统）
大规模用 Mass	见 StateTree 与 Mass
Significance 联动	见 Significance Manager

AI 优化的第一刀通常是"更新频率"，而不是"算法"——远处 AI 每 3 帧更新一次，玩家几乎察觉不到。

6. 代价与权衡

手段	收益	代价	什么时候不该用
Gameplay Debugger	实时、零成本接入	只在运行时看，不留档	偶发问题要用 Visual Logger
Visual Logger	可回放	需要预先打点	没打点就看不到
AI LOD / 降频	收益大	远处 AI 反应变慢	近处/关键 AI 不该降
EQS 节流	省查询成本	决策略有延迟	需要即时反应的查询不该节流
Mass	规模可控	心智模型不同	数量少时不必

7. 踩坑与排查

坑	现象	怎么验证
不知道 AI 在想什么	无从下手	先开 Gameplay Debugger 看黑板
偶发问题复现不了	—	加 `UE_VLOG` 打点，用 Visual Logger 回放
AI 卡住	不动	看 NavMesh 页签：有没有路径
AI 不感知	无目标	看 Perception 页签
大量 AI 卡顿	帧率掉	先看是感知/行为树/导航/动画哪一项
EQS 每帧查	性能差	加节流与缓存
导航动态重建	周期性尖峰	见导航篇
只在编辑器测	打包后不同	测打包版本

8. 排查顺序

1. Gameplay Debugger 看黑板 + 活跃分支 → 定位是哪个系统给出的问题
2. 感知问题 → Perception 页签（见感知篇）
3. 移动问题 → NavMesh 页签（见导航篇）
4. 选点问题 → EQS 页签 + EQS Testing Pawn
5. 偶发问题 → UE_VLOG 打点 + Visual Logger 回放
6. 性能问题 → stat ai + 分项（感知/行为树/EQS/导航/动画）逐个关掉对比

参考

导航系统 · 感知系统 · 行为树 · EQS
StateTree 与 Mass · 动画性能 · Significance Manager