自动关联目录：Visual Logger 与 Gameplay Debugger

1. 定位

这两个工具解决"AI/游戏逻辑没按我想的做"——这类问题的共同点是：看代码觉得对，跑起来就不对，而且常常是偶发的。

一句话定位：Gameplay Debugger 看"现在"，Visual Logger 看"过去"。偶发问题必须用后者。

2. Gameplay Debugger（看现在）

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

页签	内容
Basic	AI 基本信息
Behavior Tree	活跃节点与黑板键值
EQS	查询与评分结果
Perception	感知到的目标与刺激
NavMesh	路径与导航状态
Ability System	GAS 相关（配合 `showdebug abilitysystem`）

标准用法：AI 不攻击 → 打开 → 看黑板目标键是否为空 → 看哪个分支活跃。

命令	作用
`showdebug abilitysystem`	GAS 的 Attribute/Tag/Ability/GE 一览
`showdebug animation`	当前 AnimBP 状态
`showdebug <类别>`	其它调试信息
`DisplayAll <Class> <Property>`	实时显示某类对象属性

3. Visual Logger（看过去）

用 UE_VLOG 系列宏在代码里打点，记录后在 Visual Logger 窗口逐帧回放。

UE_VLOG(Owner, LogMyGame, Verbose, TEXT("Found target: %s"), *GetNameSafe(Target));
UE_VLOG_LOCATION(Owner, LogMyGame, Verbose, Location, 20, FColor::Green, TEXT("MoveTo"));
UE_VLOG_SEGMENT(Owner, LogMyGame, Verbose, Start, End, FColor::Red, TEXT("Trace"));

宏	用途
`UE_VLOG`	文本日志（带对象关联）
`UE_VLOG_LOCATION`	在世界中记录一个点
`UE_VLOG_SEGMENT`	记录一条线段
`UE_VLOG_BOX` / `UE_VLOG_CAPSULE`	形状

为什么它比普通日志强：记录与时间轴和对象绑定，可以回放"第 37 帧这个 AI 在想什么"，还能在场景里看到它当时的位置与射线。

4. 两者配合

实时看到现象 → Gameplay Debugger 定位当前状态
                    │
                    ├─ 状态对了但结果不对 → 逻辑问题
                    └─ 状态本身就不对 → 谁写错了这个状态？
                                          │
偶发/事后需要 → 在关键路径加 UE_VLOG → Visual Logger 回放

排查"偶尔发生一次"的标准做法：先加 UE_VLOG 打点，再等它复现，然后回放。

5. 代价与权衡

设计	收益	代价	什么时候不该用
Gameplay Debugger	零成本接入、实时	只在运行时看，不留档	偶发问题要用 Visual Logger
Visual Logger	可回放、带空间信息	需要预先打点，没打就看不到	关键路径应提前埋点
打点过多	信息全	数据量大、有轻微开销	用 Verbose 级别控制
打点过少	开销小	出问题时信息不足	关键决策点必须打

6. 踩坑与排查

坑	现象	怎么验证
偶发问题复现不了	无从下手	加 `UE_VLOG` 打点，等复现后回放
开了 Gameplay Debugger 但页签不对	看不到想要的信息	数字键切换页签
Visual Logger 没内容	没打点或分类未启用	检查 `UE_VLOG` 与日志分类级别
打点用了 LogTemp	无法过滤	建独立分类
打点太密	回放卡顿	用 Verbose，按需开启
只在编辑器测	打包后行为不同	打包版本也要能收集（或保留日志）
状态对了结果不对	逻辑问题	进对应逻辑分支排查

7. 排查顺序

1. 实时现象 → Gameplay Debugger 看当前状态
2. 状态不对 → 追"谁写错了这个状态"（配合日志/断点）
3. 状态对但结果不对 → 逻辑问题
4. 偶发/事后 → UE_VLOG 打点 + Visual Logger 回放
5. 网络相关 → 两端都要看（showdebug abilitysystem 等）

参考

AI 调试与性能 · 日志与断言体系 · 崩溃与 Dump
Debug（可视化工具总览）