GameplayDebugger

GameplayDebugger 是排查 GAIS 运行时链路的第一入口。它把一个被调试 Pawn/AIController 当前的控制状态压成几个高信号面板：谁在控制、当前层是什么、命令有没有进入 Command 层、队列有没有任务、战术分配有没有候选和失败原因、小队和阵型是否收敛。参数含义和配置规则继续查阅对应参数参考。

相关文档：常见排查路径见排错流程，队伍和调试字段见队伍身份与调试参数，命令字段见命令定义与下发参数，Tactical Assignment 字段见 Tactical Assignment 参数。

第一眼先看摘要行

选中调试目标后先看摘要行，再按摘要信号展开相关 section。

摘要信号	含义	下一步
Controller / Pawn	当前调试目标是否是你以为的 AI。	如果为空或不对，先重新选择目标。
Team / TeamSource	队伍身份来自哪里。	队伍态度异常时，先看 ProjectPolicy 和 TeamAgent。
Layer / Stack	当前 StateTreeStack 激活层和已应用层。	有命令但不在 Command 层时，优先看 Stack。
Queue	StateTreeQueue 是否有当前任务、等待任务或失败结果。	命令被接收但行为不动时展开 Queue。
Command	当前命令名称。	为空说明命令未进入 CommandSystem 或已结束。
Problem	调试器自动汇总的缺失组件和控制链异常。	先处理 Problem，再看细节。
Trace	Command -> Stack -> Queue 的简短链路。	用来判断断点在哪一层。

如果 Problem 显示 No Blackboard、No Stack、No Queue 或 No CommandSystem，先修组件/控制器接入。若显示 Current command without Command layer，说明 CommandSystem 有当前命令，但 StateTreeStack 尚未进入 Command 层；优先检查命令的 ExecutionDefinition 与执行路由。

面板导航

GAIS category 中各 section 可按需展开。常用顺序如下：

Command：确认命令是否进入 Current、Last 和 Queue。
Stack：确认 Command 层是否成为活动层。
Queue：确认 Command 层任务是否被派发、运行、完成或超时。
Tactical Assignment：确认 AI 自动分配是否有候选、命令和目标。
Formation / Squad：确认小队、角色、槽位和 Movement Intent。
Blackboard：确认 StateTree 或命令上下文写入的 key 是否符合预期。

调试输出过多时，不要同时看所有面板。先根据症状展开一个面板，确定阶段，再跳到相邻面板。

CommandSystem 面板怎么看

CommandSystem 面板显示 Current、Last、Queue、LastResult 和 ReasonTag。

你看到的情况	说明	下一步
Current 是 `None`	没有当前命令，或命令已立即结束。	回到下发侧检查 `Definition`、目标和 `Issue Command` 调用。
Current 有命令但单位不动	CommandSystem 已接收，执行层没推进。	展开 Stack/Queue，看是否进入 Command 层和任务。
LastResult 是 Failed/Canceled	命令结束但结果异常。	看 ReasonTag，再回到 `CanObeyCommand`、`IsValidTarget` 或执行回调。
Queue 有多条命令但当前不推进	当前命令未结束或处理策略不允许替换。	检查命令执行层是否回调结果，或命令处理策略是否符合预期。
Index 不符合预期	MultiVariant 选择了错误变体。	检查 UI、Tactical Assignment resolver 或 `FGAIS_CommandReference`。
Target/Loc 与玩家点击不一致	载荷构造或预览吸附与最终命令目标不一致。	以 `FGAIS_CommandData` 为准，回查输入/预览层。

Stack 与 Queue 面板怎么看

Stack 面板回答“当前哪个行为层拥有控制权”。Queue 面板回答“这个层里的任务有没有被派发和完成”。

常见判断：

CommandSystem 有 Current，但 Stack 的 Requested/Applied 层仍停留在其他层：命令没有通过有效 ExecutionDefinition 建立 Command 路由。若使用 StateTree 执行配置，再检查其 StateTree 引用与上下文。
Stack 在 Command 层，但 Queue 没有 CurrentTask：Command 层已激活，但任务没有入队或 StateTree task 没派发。
Queue 有 CurrentTask 但一直不完成：任务执行层没有回报完成、失败或取消。
Queue 最新结果有 reason tag：先沿 reason tag 查对应 StateTree task、Blackboard key 或命令目标。

Tactical Assignment 面板怎么看

Tactical Assignment 面板是排查 AI 自动分配的主入口。运行 PIE 后打开 GameplayDebugger，启用 GenericAISystem category，选择由 AIController 控制的 Pawn，然后按 Shift+7 切换 Tactical Assignment section。GAIS 的其他 section 使用 Shift+1 到 Shift+6；面板顶端会显示当前快捷键导航。

先看总览，再看 batch。

信号	含义
Sessions / Plan / Run / Replans	当前是否有活跃 session，以及本轮计划是否在重评估。
Sources A/T	本轮用了多少 Assignee Source 和 Target Source。
Pool A/T	Source 收集后的 Actor/Target 候选总数。
ExternalUsage	其他 session 或前序批次已经占用的目标数量。
Actors before -> after	Actor Filter 是否把候选过滤掉。
Targets before -> after	Target Filter 是否把目标过滤掉。
Candidates	Intent resolve、命令校验、目标校验和评分之后还剩多少候选配对。
Selected	Allocator 最终选中了多少配对。
Assigned / Unassigned	每个 Actor 的 State、Outcome、Command、Target、Score 和 Reason。

看到 NoResolvedCommand，查 Unit 的 CommandIntentMappings 或自定义 IGAIS_CommandIntentResolver。看到 CannotObeyCommand，查命令执行者需求和标签。看到 InvalidTarget，查命令 TargetType、目标数据、阵营和目标标签。看到 Candidates 有值但 Selected 为 0，查 Allocator、目标容量和 ExistingTargetUsage。

面板中的 SourceTag 用来确认目标进入候选池的来源。若 Source 数正确但 Pool T 为 0，检查 Gather/EQS；若 Pool T 有值但 Targets before -> after 归零，检查当前 Batch 的 Target Filter，尤其是 SourceTag、Team Attitude 与 Has Actor/No Actor。SourceTag 相同或不同都不会改变物理目标容量键。

需要结合生命周期日志时，可临时在控制台执行 Log LogGAIS_Tactical Verbose，它用于 Session 生命周期、重规划和提交结果。GameplayDebugger 显示当前 Session/Batch 快照；每个 Source 的 Actor/Target 明细当前通过 Visual Logger 的 UE_VLOG 输出。诊断结束后执行 Log LogGAIS_Tactical Log。若需要跨启动保留，在项目 [Core.Log] 中设置 LogGAIS_Tactical=Verbose。

Formation 与 Squad 面板怎么看

Formation 面板回答“阵型资产和槽位是否在运行时可用”。Squad 面板回答“小队成员、角色、槽位、Movement Intent 是否收敛”。

症状	优先信号
小队看起来没有初始化	Squad 的 Definition、Initialized、FormationStatus、Capacity。
必需角色没出现	Role 的 Current/Max、Required、Status。
单位站错槽位	Unit 的 Role、SlotId、SlotTags 和 slot assignment diagnostics。
单位有槽位但不移动	DesiredLocation、DesiredSpeed、bShouldMove、MovementIntentDriverName。
槽位在 NavMesh 上异常	Formation 的 `QuerySlots` 结果、World Transform、导航投射偏移和槽位分配解释。
调整 slot scoring 后结果不对	slot assignment diagnostics 中的 tag、distance、weight、stable score 贡献。

槽位分配成功后，位移还需要项目移动系统或 UGAIS_UnitMovementIntentDriver 执行。槽位和 Movement Intent 提供的是空间目标与移动建议。

Blackboard 面板怎么看

Blackboard 面板适合验证 StateTree 或命令上下文是否写入了执行层需要的 key。命令合法性请查看 CommandSystem；这里集中观察执行层拿到的上下文。

常见用法：

命令进入 Command 层后，确认命令定义、目标 Actor、目标 Location、Index、HomeLocation 等 key 是否有值。
Tactical Assignment 提交成功后，确认执行层读取到分配出的最终目标；旧目标或空目标说明上下文同步仍有问题。
Queue 有任务但行为不动时，确认任务依赖的 key 名称和类型是否与 StateTree 配置一致。

使用原则

调试时按“上游请求 -> GAIS 契约 -> 执行层”走：

CommandSystem 看命令是否被接收。
Stack/Queue 看执行权是否切换并派发。
Blackboard 看执行上下文是否写入。
Tactical Assignment 看自动分配是否产生命令。
Squad/Formation 看组织和空间建议是否收敛。

如果某个面板为空，不要立刻改文档或资产，先确认目标 Actor 是否真的拥有对应组件。GameplayDebugger 只显示当前调试目标能采集到的运行时状态。

目录