StateTree 调度系统

StateTree Stack 与 StateTree Queue 都运行 StateTree，但服务于不同层次的问题。Stack 负责“现在由哪一层 AI 拥有控制权”，Queue 负责“已经决定要做的多步任务怎样执行、替换与完成”。它们让 Unit 基础行为、小队行为、玩家命令和任务序列可以组合，而不必塞进一棵难以维护的巨大 StateTree。

这个系统解决什么问题

复杂 AI 经常同时需要巡逻、编队、警戒、玩家命令、连招和失败回退。如果每种状态都在同一棵 StateTree 中互相抢转移，优先级会变得不透明：命令来了是否应立刻盖过小队行为，命令结束后回到哪里，连招中断后谁来清理，都难以稳定维护。

GAIS 把问题拆开：Stack 管理长期行为层的控制权与回退；Queue 管理一段已经决定的短期执行计划。命令系统只负责接受、校验与追踪命令执行；当它选择 StateTree 后端时，Stack 才负责把该命令放到保留的 Command 层。

这个系统能做什么

能力	用途示例
行为层覆盖与回退	Unit 正在巡逻，小队进入警戒后覆盖为 Squad 层；命令结束后安全回到原有低层。
命令接管 AI	移动、攻击或交互命令通过 Command 层暂时接管 AI，而非直接破坏 Unit/Squad 行为树。
已决定任务串行执行	将“移动到掩体 → 等待 → 释放 Ability”作为 Queue Dispatch 执行并得到终结结果。
任务追加或替换	对现有计划追加收尾动作，或用新的 Dispatch 完整替换旧计划。
观察实际行为状态	用 Requested/Applied 区分“策略希望切换到什么”和“执行器实际正在运行什么”。
向 StateTree 提供命令上下文	Command 层通过 Blackboard 暴露命令定义、变体、目标、范围与执行 Pawn。

它不替代 Tactical Assignment 的“谁应做什么”匹配，也不替代 CommandSystem 的命令账本，更不是通用任务队列。Tactical Assignment 产生或选择命令，CommandSystem 接受并维护命令生命周期，Stack 决定行为优先级，Queue 执行已决定计划。

Stack、Queue 与命令如何协作

UGAIS_StateTreeStackComponent 是决策层控制权拥有者。SetLayerStateTree 和 ClearLayer 处理 Unit、Squad 等非 Command 层；Command 层只由具有精确命令身份的执行路由建立或撤销。真正层切换时，Stack 会清理不再适用的 Queue 工作，避免旧计划在新行为层继续运行。

UGAIS_StateTreeQueueComponent 是可选执行器。Dispatch 是正式计划：它会替换当前计划、产生 Handle，并为该 Handle 提交 result/reason。Enqueue 仅追加工作；有活跃 Dispatch 时会延后其完成，没有时只是匿名工作。因此需要等待完成时，必须跟踪 Dispatch Handle，而不能只看 Queue 是否短暂 Idle。

Requested 与 Applied

Stack 为一次执行同时保存 Requested 与 Applied：Requested 是当前策略选中的目标层与完整 StateTree 引用，Applied 是已经物理安装到执行器的真实状态。安全切换、同层 StateTree 替换期间两者可以不同。

用 GetRequestedLayer / GetRequestedStateTree 观察策略下一步想要什么。
用 GetAppliedLayer / GetAppliedStateTree 判断当前实际行为。
用 HasPendingLayerTransition 与原因标签诊断尚未完成的切换。
同层资产替换应监听 OnActiveLayerStateTreeReplaced；真正层变化监听 OnActiveLayerChanged。

每次替换有独立 generation。旧 StateTree、旧 Command 或旧 Queue 的迟到回调不能结算已经替换后的执行。

Blackboard 与命令执行

默认 UGAIS_CommandExecutionDefinition_StateTree 把已接受命令路由到 Command 层。Stack 将命令 Definition、变体 Index、目标 Actor/位置、范围、HomeLocation 与执行 Pawn 写入项目设置指定的 Blackboard Key；Command StateTree 读取已验证上下文并在成功、失败或取消时回报。

若项目改了 Blackboard Key，必须同步更新 UGAIS_DeveloperSettings、Blackboard 资产和所有 StateTree 读取端。只改一侧会造成“命令已进入 Command 层，但 Tree 没有可用上下文”。

什么时候使用 Stack，什么时候使用 Queue

需求	应使用
选择当前应听 Unit、Squad 还是 Command	Stack。
在同一行为层内执行连续的已知步骤	Queue。
让命令结束后恢复先前 AI	CommandSystem + Stack Command 层。
让系统按候选、目标与容量决定谁执行命令	Tactical Assignment。
单个 Pawn 的移动、技能或动画实际实现	Command StateTree、Ability 或项目后端。

接入步骤见接入 StateTree 与 Blackboard，字段与 Handle 参考见StateTree 队列与调度参数，命令关系见命令系统。

目录