StateTree Debug Overlay

StateTree Debug Overlay 用于把某个 StateTree 状态下的短文本画在 Actor 上方，帮助你在 PIE 中确认“当前状态是否真的进入、绑定文本是否按预期变化、退出状态后是否清理”。它是本地只读 HUD 诊断，不是复制状态，也不是 Shipping UI。

相关文档：StateTree 接入见接入 StateTree 与 Blackboard，项目设置见项目设置与 Blackboard，运行时面板见 GameplayDebugger。

使用条件

Debug Overlay 只在 Editor + debug drawing 构建条件下编译绘制代码。运行时还需要同时开启两个控制台变量：

plaintext

1gais.DebugOverlay.Enable 1
2gais.DebugOverlay.StateTree 1

关闭任一开关都会停止绘制。它不会复制到其他客户端，也不会作为游戏 UI 状态保存；多人调试时每个本地客户端只看到自己 HUD 上的绘制结果。

StateTree Task

在 StateTree 中添加 Task: Debug Overlay Text：

字段	说明
`Text`	静态文本，适合写状态名或短诊断，例如 `Charge`、`Holding Cover`。
`BindableText`	运行时可绑定文本，会追加在静态文本之后。适合绑定目标名、计数或 reason。
`ReferenceActor`	作为世界空间锚点的 Actor；为空时使用 StateTree execution owner。

如果 ReferenceActor 是 Controller，绘制时会解析到当前 Pawn；如果是 Pawn 或普通 Actor，则直接以该 Actor 为锚点。Task 进入状态时注册一条文本，退出状态时注销这条文本。它返回 Running，且 bConsideredForCompletion 被关闭，所以不会参与 StateTree 完成判定。

项目设置

以下设置位于 UGAIS_DeveloperSettings 的 Debug Overlay 分类，只在 Editor 数据中存在：

设置	用途
`DebugOverlayOffset`	文本相对 Actor 的世界空间偏移。
`DebugOverlayFontScale`	HUD 文本缩放。
`DebugOverlayColor`	文本颜色。
`DebugOverlayPawnClassFilters`	可选 Pawn 类过滤器；为空时所有 Actor 都可绘制，非空时只绘制匹配 Pawn 类。

过滤器只作用于最终绘制 Actor。Controller 先解析成 Pawn，再按 Pawn class 过滤。

验证与排错

症状	检查
没有任何文本	是否在 Editor/debug drawing 构建条件下，两个 cvar 是否都为 1。
进入状态后仍不显示	`Text` 与 `BindableText` 是否都为空，`ReferenceActor` 或 StateTree owner 是否有效。
绑定 Controller 不显示	Controller 当前是否有 Pawn，Pawn 是否被 class filter 拦掉。
文本位置不对	调整 `DebugOverlayOffset`，确认锚点是 Pawn 而不是 Controller。
退出状态后文本残留	StateTree 是否真正触发 ExitState，或是否有另一条状态文本仍然 active。

需要观察系统快照时仍使用 GameplayDebugger；需要看每个 Tactical Source 产出的明细时使用 Visual Logger。Debug Overlay 的职责只是在本地画出 StateTree 状态文本。

目录