StateTree 队列与调度参数

本页记录 StateTreeStack 和 StateTreeQueue 的主要运行时表面。Stack 负责行为层控制权，Queue 负责已决定任务的执行序列。两者经常一起使用，但参数含义不能混在一起理解。

相关文档：功能说明见 StateTree 调度系统，接入流程见接入 StateTree 与 Blackboard，调试入口见 GameplayDebugger。

Stack

Stack 的字段和函数围绕“哪一层 StateTree 当前生效”展开。它适合处理 Unit、Squad、Command 等层级覆盖，不适合当成任务列表使用。

表面	用途
`LayerStateTrees`	当前各层绑定的 StateTree 引用。
`SetLayerStateTree`	设置某一层 StateTree。
`ClearLayer`	清除层并允许回退；Command 路由由其精确 execution 生命周期处理。
`GetRequestedLayer` / `GetRequestedStateTree`	查询 Stack 策略当前选择的请求。
`GetAppliedLayer` / `GetAppliedStateTree`	查询实际已安装到执行器的决策层与 StateTree。
`OnActiveLayerChanged`	层变化事件。
`OnActiveLayerStateTreeReplaced`	激活层不变但 StateTree 被替换事件。
`HasPendingLayerTransition` / `GetPendingReasonTag`	Requested 与 Applied 尚未收敛时查询待切换状态和原因。

Queue

Queue 的字段和函数围绕“当前 dispatch 里有哪些任务、执行到哪里、结果是什么”展开。它适合承接一段已决定的执行计划，不适合决定长期 AI 控制权。

表面	用途
`EnqueueTask(s)`	追加任务；有 active dispatch 时延后它的完成，无 active dispatch 时为匿名工作。
`DispatchTask` / `DispatchTasks`	替换当前队列并返回正式 `FGAIS_StateTreeDispatchHandle`，适合等待完成或精确取消。
`CancelDispatch`	仅取消仍匹配 active handle 的正式 dispatch。
`ClearQueue`	清空执行工作；active dispatch 会以 Canceled 完成。
`GetLastDispatchCompletion`	查询最近一次已提交的正式 dispatch 结果。

事件

事件	用途
`OnDispatchCompleted`	唯一正式 dispatch 完成事件；状态先提交，匿名 Enqueue 工作不会广播。

StateTree 辅助入口

FGAIS_STE_Context 用于解析 Pawn、AIController、Blackboard、命令组件、小队组件、单位组件和队列组件。FGAIS_STE_EvalBBAsActor_Data 与 FGAIS_STE_EvalBBVAsActor 是 Blackboard Actor 读取相关入口。队列 Task 包括 Enqueue、Dispatch 和 Track Queue 类任务。

常见误配

现象	常见原因
命令覆盖后没有回到原 AI	Command execution 没有完成/取消，或低层 StateTree 没有保持有效引用。
Queue 任务在层切换后仍被误以为有效	没有理解层切换会清理 Queue；应重新 Dispatch 新层的任务。
一个 StateTree 变得巨大难维护	把层级决策、任务执行、连招分支和战术选择全部塞进同一颗 StateTree；应拆到 Stack 层、Queue 任务和 Tactical Assignment。