在 Unreal Engine 中用 State Tree…

当需要在 UE 中实现可数据驱动的分层状态机、AI 行为或对海量 Mass Entity 逐帧求值状态逻辑时，用 UStateTree 资产配合 Tasks/Transitions/Conditions/Evaluators 组织状态逻辑。

适用场景

解决思路

1. 先读取 `.agents/ue-project-context.md`，确认 `StateTreeModule`、`GameplayStateTreeModule` 插件是否启用，是否需要 Mass Entity 集成（`MassEntity`、`MassAIBehavior`），现有 AI 框架（行为树、自定义 FSM）以及所用/自定义的 Schema 类型。
2. 实现前澄清需求：用途（AI 行为、游戏逻辑、UI 状态、实体处理）、规模（单 Actor 用 `UStateTreeComponent` vs 数千 Mass entity）、复杂度（简单线性 FSM vs 带 linked subtree 的分层状态）、是否有行为树需迁移、任务需要哪些外部数据（actor 引用、subsystem、世界状态）。
3. 按架构组织 `UStateTree` 数据资产：包含 `UStateTreeSchema`（定义允许的 context/external data）、`States[]`（每个状态带 Tasks、Transitions、Conditions）、全局 `Evaluators[]` 和 `Parameters`（`FInstancedPropertyBag` 默认输入）。
4. 理解运行时每帧流程：1) Evaluators 先 tick；2) 从当前活动叶子向根检查 Transitions；3) 若 transition 触发，先对旧任务调用 ExitState，再对新任务调用 EnterState；4) 活动任务 tick。
5. 使用关键类：`UStateTree`（数据资产，执行前调用 `IsReadyToRun()`）、`FStateTreeExecutionContext`（每帧构造，不持久化）、`FStateTreeInstanceData`（跨帧持久的运行时状态）、`UStateTreeComponent`（管理树生命周期）、`EStateTreeRunStatus`（`Running`/`Stopped`/`Succeeded`/`Failed`/`Unset`）。
6. 在 Build.cs 中加入模块依赖：`StateTreeModule`、`GameplayStateTreeModule`。
7. 每帧重建执行上下文以分离可变状态与无状态逻辑：`FStateTreeInstanceData InstanceData;` 持久保存，每帧 `FStateTreeExecutionContext Context(Owner, *StateTree, InstanceData); Context.Tick(DeltaTime);`，便于 Mass Entity 并行求值。
8. 通过 Schema 约束可访问的上下文数据与合法节点，把错误提前到编辑期：`UStateTreeComponentSchema`（Actor + BrainComponent，暴露 `ContextActorClass`）、`UStateTreeAIComponentSchema`（额外提供 `AIControllerClass`）、`UMassStateTreeSchema`（Mass entity 上下文）。
9. 需要项目专用约束时自定义 Schema：继承 `UStateTreeSchema`，重写 `IsStructAllowed`、`IsExternalItemAllowed`、`GetContextDataDescs`（声明上下文对象供编辑器校验属性绑定），并在 `WITH_EDITOR` 下按需重写 `AllowEvaluators`、`AllowMultipleTasks`、`AllowGlobalParameters`。
10. 用 Task 作为状态中的主要工作单元：Task 是 USTRUCT（非 UObject），运行时不可变（所有虚函数为 `const`）。关键虚函数：`EnterState`（返回 `EStateTreeRunStatus`，默认 Running）、`ExitState`、`Tick`（返回运行状态）、`StateCompleted`（子状态完成时按逆序调用）、`TriggerTransitions`（仅当 `bShouldAffectTransitions` 时调用）。
11. 按需设置 Task 行为标志：`bShouldStateChangeOnReselect`（默认 true，转到同一状态时 Exit+Enter）、`bShouldCallTick`（默认 true）、`bShouldCallTickOnlyOnEvents`（默认 false）、`bShouldCopyBoundPropertiesOnTick`（默认 true）、`bShouldAffectTransitions`（默认 false）。纯 fire-and-forget 任务设 `bShouldCallTick = false`。
12. 用实例数据模式存放可变状态：定义 `FMyTaskInstanceData` 结构，并在 Task 中 `typedef FMyTaskInstanceData FInstanceDataType;`（框架据此分配存储），在虚函数中通过 `Context.GetInstanceData(*this)` 读写。
13. 允许 `AllowMultipleTasks()` 时，一个状态可并行运行多个 Task：任一 Task 返回 `Failed` 立即失败，全部返回 `Succeeded` 状态才算成功。
14. 用 Condition 门控 transition：继承 `FStateTreeConditionBase` 实现 `TestCondition(FStateTreeExecutionContext&) const`（默认 false）；用 `Operand`（`And`/`Or`/`Copy`）和 `DeltaIndent` 缩进层级组合逻辑（如同一缩进级一起求值，实现 `(A AND B) OR (C AND D)` 而无需嵌套）。
15. 优先复用内置 Condition：`FStateTreeCompareIntCondition`、`FStateTreeCompareFloatCondition`、`FStateTreeCompareEnumCondition`、`FGameplayTagMatchCondition`、`FStateTreeObjectIsValidCondition`、`FStateTreeCompareDistanceCondition`，并通过属性绑定传入输入。
16. 用 Evaluator 作为全局数据提供者，每帧在 transition 与 task tick 之前运行：继承 `FStateTreeEvaluatorBase` 重写 `TreeStart`、`TreeStop`、`Tick`（注意 preselection 时 DeltaTime 为 0），使用与 Task 相同的 `FInstanceDataType` 模式，并把实例数据属性绑定到 Task/Condition 输入。数据每帧变化（最近敌人、世界时间）用 Evaluator；稳定引用（所属 actor、subsystem）用 external data handle。
17. 配置 Transition：每个状态的 Transitions 按从上到下的顺序求值，第一个匹配的触发。触发器 `EStateTreeTransitionTrigger` 为位掩码，可取 `OnStateSucceeded`(1)、`OnStateFailed`(2)、`OnStateCompleted`(3, 1|2)、`OnTick`(4)、`OnEvent`(8)、`OnDelegate`(16)。
18. 设置 Transition 优先级与属性：优先级 `Low`/`Normal`/`Medium`/`High`/`Critical`，子状态高优先级 transition 先于父状态低优先级求值；`bConsumeEventOnSelect`（默认 true，触发后从队列移除事件）、`bTransitionEnabled`（默认 true，可禁用而不删除）、`bReactivateTargetState`（默认 false，强制对当前状态也 Exit+Enter）。
19. 选择 Transition 目标：GotoState（指定命名状态）、NextState（下一个兄弟状态）、Succeeded/Failed（以该状态完成父状态），或指向树根的 Succeeded/Failed 以完成整棵树。
20. 按用途选择状态类型：`State`（普通状态）、`Group`（容器，无自身任务）、`Linked`（引用同一树内状态）、`LinkedAsset`（引用另一 `UStateTree` 资产中的状态，用于跨 AI 原型共享巡逻/调查/逃跑等行为）、`Subtree`（内嵌另一 `UStateTree` 作为子节点）。
21. 用 `EStateTreeStateSelectionBehavior` 控制进入时子状态选择：`TryEnterState`、`TrySelectChildrenInOrder`（自上而下第一个有效者）、`TrySelectChildrenAtRandom`、`TrySelectChildrenWithHighestUtility`、`TrySelectChildrenAtRandomWeightedByUtility`、`TryFollowTransitions`；注意 `FStateTreeActiveStates::MaxStates = 8`，活动层级深度不得超过。
22. 用基于 GameplayTag 的事件系统解耦通信：`FStateTreeEvent` 含 `FGameplayTag Tag`、`FInstancedStruct Payload`（可选类型化数据）、`FName Origin`（可选调试来源）。从外部用 `TreeComp->SendStateTreeEvent(...)`，从 Task 内部用 `Context.SendEvent(...)`；`FStateTreeEventQueue` 每帧最多 `MaxActiveEvents = 64` 个事件，在 transition 求值时处理，保持 `bConsumeEventOnSelect = true` 防止同一事件触发多个 transition。
23. 用 external data 提供树外对象的类型化引用：在 struct 中声明 `TStateTreeExternalDataHandle<FMyActorContext, EStateTreeExternalDataRequirement::Required>` 等句柄，在 `Link(FStateTreeLinker&)` 中 `Linker.LinkExternalData(Handle)`，运行时用 `Context.GetExternalData(Handle)`（Required，返回引用）或 `Context.GetExternalDataPtr(Handle)`（Optional，返回指针）；Schema 的 `CollectExternalData` 在树启动时填充句柄并在 link 期校验。
24. 用 `UStateTreeComponent`（继承 `UBrainComponent`）管理 Actor 上的整棵树生命周期：可调用 `SetStateTree`、`SetStateTreeReference`、`SendStateTreeEvent`、`GetStateTreeRunStatus`，监听 `OnStateTreeRunStatusChanged`（BlueprintAssignable），设置 `bStartLogicAutomatically = true`。
25. 用 `FStateTreeReference` 包装 `UStateTree*` 并做参数覆盖：`SetStateTree`、`SyncParameters`、`GetParameters().SetValueFloat(TEXT("AggroRange"), 1500.f)`；用 `FStateTreeReferenceOverrides` 按 tag 在运行时换树：`AddOverride(Tag, TreeRef)` / `RemoveOverride(Tag)`。
26. 如需自定义上下文，继承 `UStateTreeComponent` 并重写 `SetContextRequirements(FStateTreeExecutionContext&, bool bLogErrors)` 与 `CollectExternalData(...)`。
27. AI 集成：使用 `UStateTreeAIComponentSchema`（额外提供 `AIControllerClass`），在 AIController 构造函数中创建 `UStateTreeComponent`、设 `bStartLogicAutomatically = true`，在控制器默认值里指定 `UStateTree` 资产，并把 Schema 的 `ContextActorClass` 设为 Pawn 类以便编辑器绑定其组件。
28. 选型参考：State Tree 适合数据驱动 FSM、Mass entity、扁平逻辑（Evaluators + 属性绑定替代黑板）；Behavior Tree 适合深层层级决策与复杂 abort/decorator。新 AI 若需 Mass 扩展或数据驱动 transition 优先用 State Tree。
29. Mass Entity 集成：`UMassStateTreeSchema` 约束为 Mass 兼容节点（`FMassStateTreeTaskBase` 等），`UMassStateTreeSubsystem` 管理池化实例数据（`AllocateInstanceData`/`FreeInstanceData`），`UMassStateTreeProcessor` 每帧逐 entity 求值，`FMassStateTreeExecutionContext` 提供 `SetEntity`/`GetEntity`，Mass 专用 Task 重写 `GetDependencies(UE::MassBehavior::FStateTreeDependencyBuilder&)` 声明 fragment 读写需求。
30. 避免以下常见错误：不要跨帧保存 `FStateTreeExecutionContext`（每帧从持久 `FStateTreeInstanceData` 重建）；不要直接修改 Task struct（运行时 const，必须用 `FInstanceDataType`）；Condition 不得有副作用（`TestCondition` 每帧可能多次调用，必须是纯函数）；Evaluator 不要每帧做重活（结果缓存到实例数据，仅在输入变化时刷新）；嵌套层级不要超过 `MaxStates = 8`（超限会静默失败，用 linked state 或 subtree 拍平）；必须为所有声明的 external data handle 调用 `Link()`（Required 未链接会运行时断言，Optional 会静默返回 nullptr）；除非确实要广播，保持 `bConsumeEventOnSelect = true` 以免同一事件一帧触发多个 transition。

适用边界 · 注意事项

• 需要深层层级决策逻辑、复杂 abort/decorator 模式的场景，Behavior Tree 更合适。
• 不需要 Mass Entity 扩展且已有成熟行为树体系、迁移成本高于收益时不建议改用 State Tree。
• 活动状态嵌套会超过 `FStateTreeActiveStates::MaxStates = 8` 且无法用 linked state/subtree 拍平的设计。