claude-code-arcane 2.3.0 → 2.5.0

package/skills/ue-state-trees/SKILL.md

@@ -0,0 +1,489 @@
+---
+name: ue-state-trees
+description: "State Tree, state machines, StateTreeTask, StateTreeCondition, StateTreeEvaluator"
+category: "gamedev"
+argument-hint: "[state tree o behavior]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# UE State Trees
+
+You are an expert in Unreal Engine's State Tree system for building flexible, data-driven state machines.
+
+Ask before writing: this skill edits StateTree assets, tasks, conditions and evaluators. Propose the change and get approval before using Write or Edit.
+
+## Context Check
+
+Read `docs/unreal/project-context.md` to determine:
+- Whether `StateTreeModule` and `GameplayStateTreeModule` plugins are enabled
+- If Mass Entity integration is needed (`MassEntity`, `MassAIBehavior` plugins)
+- Existing AI frameworks — behavior trees, custom FSMs to migrate from
+- Schema types in use and any custom schemas
+
+## Information Gathering
+
+Before implementing, clarify:
+1. What is the use case? (AI behavior, game logic, UI state, entity processing)
+2. What scale? (single actor with `UStateTreeComponent` vs thousands of Mass entities)
+3. How complex? (simple linear FSM vs hierarchical states with linked subtrees)
+4. Are there existing behavior trees to migrate from?
+5. What external data do tasks need? (actor references, subsystems, world state)
+
+---
+
+## StateTree Architecture
+
+A State Tree is a hierarchical finite state machine authored as a `UStateTree` data asset:
+
+```
+UStateTree (UDataAsset)
+  ├── UStateTreeSchema         ← defines allowed context/external data
+  ├── States[]                 ← hierarchical state tree
+  │     ├── Tasks[]            ← work performed while state is active
+  │     ├── Transitions[]      ← rules for leaving this state
+  │     └── Conditions[]       ← gates on transitions
+  ├── Evaluators[]             ← global data providers (tick before transitions)
+  └── Parameters               ← FInstancedPropertyBag default inputs
+```
+
+**Runtime flow per tick:** 1) Evaluators tick, 2) Transitions checked from active leaf up to root, 3) If transition fires: ExitState on old tasks then EnterState on new, 4) Active tasks tick.
+
+**Key classes:**
+
+| Class | Role |
+|-------|------|
+| `UStateTree` | Data asset — call `IsReadyToRun()` before execution |
+| `FStateTreeExecutionContext` | Per-tick context — constructed each frame, NOT persisted |
+| `FStateTreeInstanceData` | Persistent runtime state — survives across ticks |
+| `UStateTreeComponent` | Actor component that manages tree lifecycle |
+| `EStateTreeRunStatus` | `Running`, `Stopped`, `Succeeded`, `Failed`, `Unset` |
+
+**Build.cs modules**: `StateTreeModule`, `GameplayStateTreeModule`
+
+The execution context is constructed per-tick from persistent instance data:
+```cpp
+FStateTreeInstanceData InstanceData;  // persists across frames
+// Each tick:
+FStateTreeExecutionContext Context(Owner, *StateTree, InstanceData);
+Context.Tick(DeltaTime);
+```
+
+This separates mutable state (`FStateTreeInstanceData`) from stateless execution logic, making State Trees safe for parallel evaluation in Mass Entity scenarios.
+
+---
+
+## Schema System
+
+Schemas define what context data a State Tree can access, constraining valid tasks and conditions. This prevents authoring errors at edit time rather than runtime.
+
+| Schema | Context Provided | Use Case |
+|--------|-----------------|----------|
+| `UStateTreeComponentSchema` | Actor + BrainComponent | General actor logic |
+| `UStateTreeAIComponentSchema` | Above + `AIControllerClass` | AI behavior |
+| `UMassStateTreeSchema` | Mass entity context | Mass Entity processing |
+
+`UStateTreeComponentSchema` exposes `ContextActorClass` (`TSubclassOf<AActor>`) so the editor knows which components are available for property binding. `UStateTreeAIComponentSchema` extends it with `AIControllerClass` (`TSubclassOf<AAIController>`).
+
+### Custom Schemas
+
+Subclass `UStateTreeSchema` for project-specific trees:
+
+```cpp
+UCLASS()
+class UMyGameSchema : public UStateTreeSchema
+{
+    GENERATED_BODY()
+public:
+    virtual bool IsStructAllowed(const UScriptStruct* InStruct) const override;
+    virtual bool IsExternalItemAllowed(const UStruct& InStruct) const override;
+    virtual TConstArrayView<FStateTreeExternalDataDesc> GetContextDataDescs() const override;
+
+#if WITH_EDITOR
+    virtual bool AllowEvaluators() const override { return true; }
+    virtual bool AllowMultipleTasks() const override { return true; }
+    virtual bool AllowGlobalParameters() const override { return true; }
+#endif // WITH_EDITOR
+};
+```
+
+Override `GetContextDataDescs()` to declare context objects (actor refs, subsystems). The editor uses this to validate property bindings.
+
+---
+
+## Tasks
+
+Tasks are the primary work units in a state. They are USTRUCTs (not UObjects), making them lightweight and cache-friendly.
+
+### FStateTreeTaskBase API
+
+Key virtuals (all `const` — tasks are immutable at runtime):
+
+| Virtual | Returns | Called When |
+|---------|---------|-------------|
+| `EnterState(Context, Transition)` | `EStateTreeRunStatus` (default: Running) | State becomes active |
+| `ExitState(Context, Transition)` | `void` | State is exited |
+| `Tick(Context, DeltaTime)` | `EStateTreeRunStatus` (default: Running) | Each frame (if `bShouldCallTick`) |
+| `StateCompleted(Context, Status, CompletedStates)` | `void` | Child state completes (REVERSE order) |
+| `TriggerTransitions(Context)` | `void` | Only if `bShouldAffectTransitions` |
+
+### Behavioral Flags
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `bShouldStateChangeOnReselect` | `true` | Exit+Enter when transitioning to same state |
+| `bShouldCallTick` | `true` | Enable per-frame Tick calls |
+| `bShouldCallTickOnlyOnEvents` | `false` | Tick only when events are pending |
+| `bShouldCopyBoundPropertiesOnTick` | `true` | Refresh property bindings each tick |
+| `bShouldAffectTransitions` | `false` | Enable `TriggerTransitions` calls |
+
+Set `bShouldCallTick = false` for fire-and-forget tasks that only need `EnterState`/`ExitState`.
+
+### Instance Data Pattern
+
+Tasks are `const` at runtime — mutable per-instance state lives in a separate struct via the `typedef FInstanceDataType` pattern:
+
+```cpp
+USTRUCT()
+struct FMyTaskInstanceData
+{
+    GENERATED_BODY()
+    float ElapsedTime = 0.f;
+};
+
+USTRUCT(meta=(DisplayName="My Custom Task"))
+struct FMyTask : public FStateTreeTaskBase
+{
+    GENERATED_BODY()
+    typedef FMyTaskInstanceData FInstanceDataType;  // required — framework allocates storage
+
+    virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context,
+        const FStateTreeTransitionResult& Transition) const override
+    {
+        FInstanceDataType& Data = Context.GetInstanceData(*this);
+        Data.ElapsedTime = 0.f;
+        return EStateTreeRunStatus::Running;
+    }
+
+    virtual EStateTreeRunStatus Tick(FStateTreeExecutionContext& Context,
+        float DeltaTime) const override
+    {
+        FInstanceDataType& Data = Context.GetInstanceData(*this);
+        Data.ElapsedTime += DeltaTime;
+        return Data.ElapsedTime >= Duration
+            ? EStateTreeRunStatus::Succeeded : EStateTreeRunStatus::Running;
+    }
+
+    UPROPERTY(EditAnywhere, Category = "Parameter")
+    float Duration = 2.0f;
+};
+```
+
+See `references/state-tree-patterns.md` for complete task, condition, and evaluator templates.
+
+### Multiple Tasks Per State
+
+When `AllowMultipleTasks()` is true, a state runs several tasks simultaneously. Any task returning `Failed` fails the state immediately; all must return `Succeeded` for the state to succeed.
+
+---
+
+## Conditions
+
+Conditions gate transitions — evaluated to determine whether a transition should fire.
+
+```cpp
+USTRUCT(meta=(Hidden))
+struct FStateTreeConditionBase : public FStateTreeNodeBase
+{
+    virtual bool TestCondition(FStateTreeExecutionContext& Context) const;  // default: false
+    EStateTreeExpressionOperand Operand = EStateTreeExpressionOperand::And;
+    int8 DeltaIndent = 0;  // indent level for logical grouping
+    EStateTreeConditionEvaluationMode EvaluationMode = EStateTreeConditionEvaluationMode::Evaluated;
+};
+```
+
+**Operands:** `And` (both must be true), `Or` (either), `Copy` (hidden/internal). `DeltaIndent` creates logical grouping — conditions at the same indent level are evaluated together, enabling `(A AND B) OR (C AND D)` without nesting.
+
+**Built-in conditions:** `FStateTreeCompareIntCondition`, `FStateTreeCompareFloatCondition`, `FStateTreeCompareEnumCondition`, `FGameplayTagMatchCondition`, `FStateTreeObjectIsValidCondition`, `FStateTreeCompareDistanceCondition`. Bind inputs via property bindings.
+
+---
+
+## Evaluators
+
+Evaluators run globally (not per-state) and execute **before** transitions and task ticks each frame. They inject external world data into the tree via property bindings, decoupling tasks from direct world queries.
+
+```cpp
+USTRUCT(meta=(Hidden))
+struct FStateTreeEvaluatorBase : public FStateTreeNodeBase
+{
+    virtual void TreeStart(FStateTreeExecutionContext& Context) const;
+    virtual void TreeStop(FStateTreeExecutionContext& Context) const;
+    virtual void Tick(FStateTreeExecutionContext& Context, float DeltaTime) const;
+    // Note: DeltaTime is 0 during preselection
+};
+```
+
+Evaluators use the same `FInstanceDataType` typedef pattern as tasks. Their instance data properties can be bound to task/condition inputs in the editor: Evaluator populates data, tasks/conditions read it.
+
+**When to use evaluators vs external data:** Evaluators for data that changes every frame (nearest enemy, world time). External data handles for stable references (owning actor, subsystem).
+
+---
+
+## Transitions
+
+Transitions define how and when states change. Each state has an ordered list evaluated top-to-bottom — the first matching transition fires.
+
+### Trigger Types
+
+`EStateTreeTransitionTrigger` is a bitmask (`ENUM_CLASS_FLAGS`, supports bitwise OR):
+
+| Trigger | Value | Fires When |
+|---------|-------|------------|
+| `OnStateSucceeded` | 1 | Active state returns Succeeded |
+| `OnStateFailed` | 2 | Active state returns Failed |
+| `OnStateCompleted` | 3 | Either Succeeded or Failed (1\|2) |
+| `OnTick` | 4 | Every frame (gate with conditions) |
+| `OnEvent` | 8 | Matching event in the queue |
+| `OnDelegate` | 16 | Bound delegate fires |
+
+### Priorities and Properties
+
+`EStateTreeTransitionPriority`: `Low`, `Normal`, `Medium`, `High`, `Critical`. Higher-priority transitions on child states evaluate before lower-priority ones on parents.
+
+| Property | Default | Purpose |
+|----------|---------|---------|
+| `bConsumeEventOnSelect` | `true` | Remove event from queue when transition fires |
+| `bTransitionEnabled` | `true` | Disable without removing |
+| `bReactivateTargetState` | `false` | Force Exit+Enter even if target is current state |
+
+**Targets:** GotoState (specific named state), NextState (next sibling), Succeeded/Failed (complete parent with that status), or tree-root Succeeded/Failed to complete the entire tree.
+
+---
+
+## State Types and Selection
+
+### State Types
+
+| Type | Purpose |
+|------|---------|
+| `State` | Normal state with tasks, conditions, transitions |
+| `Group` | Container for child states — no tasks of its own |
+| `Linked` | References another state within the same tree |
+| `LinkedAsset` | References a state in a different `UStateTree` asset |
+| `Subtree` | Embeds another `UStateTree` as a child |
+
+`LinkedAsset` is useful for sharing common behavior patterns (patrol, investigate, flee) across AI archetypes.
+
+### Selection Behavior
+
+`EStateTreeStateSelectionBehavior` controls how child states are chosen on entry:
+
+| Behavior | Effect |
+|----------|--------|
+| `TryEnterState` | Enter this state directly |
+| `TrySelectChildrenInOrder` | Try children top-to-bottom, first valid wins |
+| `TrySelectChildrenAtRandom` | Random child selection |
+| `TrySelectChildrenWithHighestUtility` | Utility-based selection (highest score) |
+| `TrySelectChildrenAtRandomWeightedByUtility` | Weighted random by utility score |
+| `TryFollowTransitions` | Follow transition chain |
+
+`FStateTreeActiveStates::MaxStates = 8` — maximum depth of active state hierarchy. Stay within this limit.
+
+---
+
+## Events
+
+State Trees use a GameplayTag-based event system for decoupled communication.
+
+`FStateTreeEvent` contains: `FGameplayTag Tag`, `FInstancedStruct Payload` (optional typed data), `FName Origin` (optional sender name for debugging).
+
+```cpp
+// From outside via UStateTreeComponent
+TreeComp->SendStateTreeEvent(FGameplayTag::RequestGameplayTag("AI.Alert"));
+
+// With payload
+FMyAlertData AlertData;
+AlertData.ThreatLevel = 5;
+TreeComp->SendStateTreeEvent(
+    FGameplayTag::RequestGameplayTag("AI.Alert"),
+    FConstStructView::Make(AlertData), TEXT("PerceptionSystem"));
+
+// From inside a task via execution context
+Context.SendEvent(Tag, FConstStructView::Make(ResultData), TEXT("MyTask"));
+```
+
+`FStateTreeEventQueue` holds up to `MaxActiveEvents = 64` events per tick. Events are processed during transition evaluation. Use `bConsumeEventOnSelect = true` (default) to prevent one event triggering multiple transitions.
+
+---
+
+## External Data
+
+External data provides typed references to objects outside the tree (actors, components, subsystems) without going through evaluators.
+
+```cpp
+// Declare handles in your task/condition/evaluator struct
+TStateTreeExternalDataHandle<FMyActorContext, EStateTreeExternalDataRequirement::Required> ActorHandle;
+TStateTreeExternalDataHandle<FMySubsystemContext, EStateTreeExternalDataRequirement::Optional> SubsystemHandle;
+
+// Link in the Link override
+virtual bool Link(FStateTreeLinker& Linker) override
+{
+    Linker.LinkExternalData(ActorHandle);
+    Linker.LinkExternalData(SubsystemHandle);
+    return true;
+}
+
+// Access at runtime
+auto& ActorCtx = Context.GetExternalData(ActorHandle);       // Required — reference
+auto* SubsystemCtx = Context.GetExternalDataPtr(SubsystemHandle);  // Optional — pointer
+```
+
+The schema's `CollectExternalData` populates these handles at tree start, validating at link time rather than runtime.
+
+---
+
+## UStateTreeComponent
+
+`UStateTreeComponent` extends `UBrainComponent` and manages the full tree lifecycle on an actor.
+
+```cpp
+void SetStateTree(UStateTree* NewStateTree);
+void SetStateTreeReference(FStateTreeReference NewStateTreeRef);
+void SendStateTreeEvent(const FStateTreeEvent& Event);
+void SendStateTreeEvent(FGameplayTag Tag, FConstStructView Payload, FName Origin);
+EStateTreeRunStatus GetStateTreeRunStatus() const;
+// Delegate — fires when run status changes
+FStateTreeRunStatusChanged OnStateTreeRunStatusChanged;  // BlueprintAssignable
+bool bStartLogicAutomatically = true;  // EditAnywhere
+```
+
+### FStateTreeReference
+
+`FStateTreeReference` wraps a `UStateTree*` with parameter overrides:
+```cpp
+FStateTreeReference TreeRef;
+TreeRef.SetStateTree(MyStateTreeAsset);
+TreeRef.SyncParameters();
+TreeRef.GetParameters().SetValueFloat(TEXT("AggroRange"), 1500.f);
+```
+
+`FStateTreeReferenceOverrides` swaps tree references at runtime by tag:
+```cpp
+Overrides.AddOverride(Tag_CombatVariant, CombatTreeRef);
+Overrides.RemoveOverride(Tag_CombatVariant);
+```
+
+Subclass `UStateTreeComponent` to customize context via `SetContextRequirements(FStateTreeExecutionContext&, bool bLogErrors)` and `CollectExternalData(...)`.
+
+---
+
+## AI Integration
+
+`UStateTreeAIComponentSchema` adds `AIControllerClass` to the component schema, making the AI controller available as context data for property bindings.
+
+```cpp
+AMyAIController::AMyAIController()
+{
+    StateTreeComp = CreateDefaultSubobject<UStateTreeComponent>(TEXT("StateTree"));
+    StateTreeComp->bStartLogicAutomatically = true;
+}
+```
+
+Assign the `UStateTree` asset in the controller defaults. Set the schema's `ContextActorClass` to your Pawn class so the editor can bind to its components.
+
+### State Tree vs Behavior Tree
+
+| Aspect | State Tree | Behavior Tree |
+|--------|-----------|---------------|
+| Structure | Hierarchical FSM with transitions | Tree of composites, decorators, tasks |
+| Data flow | Evaluators + property bindings (typed) | Blackboard (string-keyed, loosely typed) |
+| Conditions | First-class on transitions | Decorators on tree nodes |
+| Mass Entity | Native via `UMassStateTreeSchema` | No Mass support |
+| Best for | Data-driven FSMs, Mass entities, flat logic | Deep decision hierarchies, complex aborts |
+
+Prefer State Trees for new AI needing Mass Entity scaling or data-driven transitions. Keep Behavior Trees for deeply nested decision logic with complex abort/decorator patterns.
+
+---
+
+## Mass Entity Integration
+
+State Trees integrate natively with Mass Entity for processing thousands of entities. See `references/state-tree-mass-integration.md` for complete setup.
+
+Key concepts:
+- `UMassStateTreeSchema` constrains trees to Mass-compatible node types (`FMassStateTreeTaskBase`, etc.)
+- `UMassStateTreeSubsystem` manages pooled instance data (`AllocateInstanceData`/`FreeInstanceData`)
+- `UMassStateTreeProcessor` evaluates trees per entity each frame
+- `FMassStateTreeExecutionContext` wraps execution context with `SetEntity`/`GetEntity`
+- Mass-specific tasks override `GetDependencies(UE::MassBehavior::FStateTreeDependencyBuilder&)` to declare fragment read/write requirements
+
+For Mass Entity architecture details, see `/ue-mass-entity`.
+
+---
+
+## Common Mistakes
+
+**Persisting FStateTreeExecutionContext across frames:**
+```cpp
+// WRONG — context is per-tick, NOT persistent
+FStateTreeExecutionContext* SavedContext;  // dangling after tick
+
+// RIGHT — reconstruct each tick from persistent instance data
+FStateTreeExecutionContext Context(Owner, *StateTree, InstanceData);
+Context.Tick(DeltaTime);
+```
+
+**Mutating task struct directly instead of using instance data:**
+```cpp
+// WRONG — task structs are const at runtime
+virtual EStateTreeRunStatus Tick(...) const override {
+    Timer += DeltaTime;  // compile error — 'this' is const
+}
+
+// RIGHT — use FInstanceDataType typedef
+typedef FMyInstanceData FInstanceDataType;
+virtual EStateTreeRunStatus Tick(...) const override {
+    auto& Data = Context.GetInstanceData(*this);
+    Data.Timer += DeltaTime;
+}
+```
+
+**Conditions with side effects:** `TestCondition` may be called multiple times per frame during transition evaluation. Never modify state in conditions — they must be pure functions.
+
+**Evaluators doing heavy work every tick:** Evaluators run every frame before transitions. Cache results in instance data and only refresh when inputs change.
+
+**Exceeding MaxStates depth:** `FStateTreeActiveStates::MaxStates = 8`. Deeply nested hierarchies silently fail. Flatten with linked states or subtrees.
+
+**Forgetting to link external data:** Unlinked Required handles assert at runtime; Optional handles silently return nullptr. Always link all declared handles in `Link()`.
+
+**Not consuming events:** With `bConsumeEventOnSelect = false`, the same event can trigger multiple transitions in one frame. Leave default `true` unless broadcast behavior is intended.
+
+---
+
+## Related Skills
+
+- `/ue-ai-navigation` — Behavior tree patterns, AI controller setup, perception system
+- `/ue-mass-entity` — Mass Entity architecture, processors, fragments, traits
+- `/ue-gameplay-abilities` — Ability-driven state transitions, GAS integration
+- `/ue-gameplay-framework` — Game state machines, controller/pawn lifecycle
+- `/ue-actor-component-architecture` — Component setup for `UStateTreeComponent`
+- `/ue-cpp-foundations` — USTRUCT patterns, delegates, subsystem access
+
+---
+
+## Checklist
+
+Validate before considering the work done:
+
+- [ ] Tasks are single-purpose and reusable across states
+- [ ] Transitions are driven by conditions and events, not by side effects in tasks
+- [ ] The schema chosen matches the owner type of the tree
+- [ ] Conventions in `docs/unreal/project-context.md` were read and followed
+- [ ] The Common Mistakes section of this skill was reviewed against the change
+
+**PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
+
+## Next Steps
+
+- `/ue-mass-entity` — evaluate Mass if the same behavior runs at scale
+- `/code-review` — architectural and quality review of the change
+- `/commit` — conventional commit once the change is verified

package/skills/ue-state-trees/references/state-tree-mass-integration.md

@@ -0,0 +1,184 @@
+# State Tree Mass Entity Integration
+
+How State Trees integrate with Mass Entity for processing thousands of entities efficiently. For core Mass Entity architecture, see `/ue-mass-entity`.
+
+**Build.cs modules**: `StateTreeModule`, `GameplayStateTreeModule`, `MassEntity`, `MassAIBehavior`
+
+---
+
+## UMassStateTreeSchema
+
+`UMassStateTreeSchema` constrains a `UStateTree` asset to only allow Mass-compatible node types:
+- `FMassStateTreeTaskBase` (not `FStateTreeTaskBase`)
+- `FMassStateTreeConditionBase` (not `FStateTreeConditionBase`)
+- `FMassStateTreeEvaluatorBase` (not `FStateTreeEvaluatorBase`)
+
+Select this schema when creating a `UStateTree` intended for Mass Entity processing. Regular State Tree nodes will not appear in the editor dropdown.
+
+---
+
+## Mass-Specific Node Base Classes
+
+### FMassStateTreeTaskBase
+
+Extends `FStateTreeTaskBase` with Mass fragment dependency declarations:
+
+```cpp
+USTRUCT(meta=(DisplayName="My Mass Task"))
+struct FMyMassTask : public FMassStateTreeTaskBase
+{
+    GENERATED_BODY()
+    typedef FMyMassTaskInstanceData FInstanceDataType;
+
+    // Declare which fragments this task reads/writes
+    // The processor uses these to build its execution requirements
+    virtual void GetDependencies(UE::MassBehavior::FStateTreeDependencyBuilder& Builder) const override
+    {
+        Builder.AddReadWrite<FTransformFragment>();
+        Builder.AddReadOnly<FMassVelocityFragment>();
+    }
+
+    virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context,
+        const FStateTreeTransitionResult& Transition) const override
+    {
+        // Access entity via FMassStateTreeExecutionContext
+        const FMassStateTreeExecutionContext& MassContext =
+            static_cast<const FMassStateTreeExecutionContext&>(Context);
+        FMassEntityHandle Entity = MassContext.GetEntity();
+        // Use entity with Mass subsystem APIs...
+        return EStateTreeRunStatus::Running;
+    }
+};
+```
+
+### FMassStateTreeConditionBase
+
+Same pattern — extends `FStateTreeConditionBase`, adds `GetDependencies()`:
+
+```cpp
+USTRUCT(meta=(DisplayName="My Mass Condition"))
+struct FMyMassCondition : public FMassStateTreeConditionBase
+{
+    GENERATED_BODY()
+
+    virtual void GetDependencies(UE::MassBehavior::FStateTreeDependencyBuilder& Builder) const override
+    {
+        Builder.AddReadOnly<FMassHealthFragment>();
+    }
+
+    virtual bool TestCondition(FStateTreeExecutionContext& Context) const override
+    {
+        const auto& MassCtx = static_cast<const FMassStateTreeExecutionContext&>(Context);
+        // Check fragment data on the entity...
+        return true;
+    }
+};
+```
+
+### FMassStateTreeEvaluatorBase
+
+Extends `FStateTreeEvaluatorBase` with the same `GetDependencies(UE::MassBehavior::FStateTreeDependencyBuilder& Builder) const` override for fragment access.
+
+---
+
+## Entity Configuration
+
+### UMassStateTreeTrait
+
+Add `UMassStateTreeTrait` to a `UMassEntityConfigAsset` to assign a State Tree to entities of that archetype:
+
+```cpp
+// In Mass Entity Config asset (data-driven):
+// Add StateTree Trait → assign UStateTree asset with UMassStateTreeSchema
+```
+
+The trait adds required fragments to the archetype:
+- `FMassStateTreeInstanceFragment` — per-entity instance data handle
+- `FMassStateTreeSharedFragment` — shared tree reference (one per archetype)
+
+### Fragments
+
+| Fragment | Scope | Contains |
+|----------|-------|----------|
+| `FMassStateTreeInstanceFragment` | Per-entity | Handle to pooled `FStateTreeInstanceData` |
+| `FMassStateTreeSharedFragment` | Per-archetype (shared) | `FStateTreeReference` to the `UStateTree` asset |
+
+---
+
+## UMassStateTreeSubsystem
+
+Manages pooled State Tree instance data for Mass entities. Pooling avoids per-entity allocation overhead.
+
+```cpp
+// Allocate instance data for an entity
+FMassStateTreeInstanceHandle Handle =
+    MassStateTreeSubsystem->AllocateInstanceData(StateTree);
+
+// Access instance data for execution
+FStateTreeInstanceData* Data = MassStateTreeSubsystem->GetInstanceData(Handle);
+
+// Free when entity is destroyed
+MassStateTreeSubsystem->FreeInstanceData(Handle);
+```
+
+The subsystem handles allocation/deallocation automatically through the trait lifecycle. Manual calls are only needed for custom processors.
+
+---
+
+## FMassStateTreeExecutionContext
+
+Wraps `FStateTreeExecutionContext` with entity access:
+
+```cpp
+// 4-param constructor (UE 5.5+): Owner, StateTree, InstanceData, MassExecutionContext
+FMassStateTreeExecutionContext MassContext(
+    Owner, *StateTree, InstanceData, MassExecContext);
+
+MassContext.SetEntity(EntityHandle);    // set current entity before Tick
+FMassEntityHandle Entity = MassContext.GetEntity();  // access in tasks
+```
+
+`MassExecContext` is the `FMassExecutionContext&` available inside a Mass processor's `Execute()` method. The old 6-param form `(Owner, *StateTree, InstanceData, EntityManager, SignalSubsystem, MassExecContext)` is deprecated since UE 5.6.
+
+The processor calls `SetEntity()` before ticking each entity's tree, making the entity handle available to all tasks and conditions via the context.
+
+---
+
+## UMassStateTreeProcessor
+
+Evaluates State Trees for all entities with `FMassStateTreeInstanceFragment`. Created dynamically — one processor per unique set of fragment requirements (hashed from all tasks' `GetDependencies()`).
+
+The processor:
+1. Queries entities with matching fragments
+2. For each entity: constructs `FMassStateTreeExecutionContext`, calls `SetEntity()`, ticks the tree
+3. Handles transition signals and state changes
+
+Fragment requirements declared in `GetDependencies()` from all tasks in the tree are merged into the processor's query, so a tree with tasks reading `FTransformFragment` and `FMassVelocityFragment` will produce a processor that requires both.
+
+---
+
+## Mass Signals
+
+Mass signals coordinate State Tree execution with other Mass processors:
+
+| Signal | Purpose |
+|--------|---------|
+| `StateTreeActivate` | Activates a dormant State Tree on an entity |
+| `NewStateTreeTaskRequired` | Signals that the current task needs re-evaluation |
+| `DelayedTransitionWakeup` | Wakes an entity for a delayed transition check |
+
+Send signals via `UMassSignalSubsystem`:
+```cpp
+SignalSubsystem.SignalEntity(Entity, UE::Mass::Signals::StateTreeActivate);
+```
+
+---
+
+## Performance Notes
+
+- **Keep tasks minimal:** Each entity ticks its tree every frame. Expensive operations (pathfinding, overlap queries) should be throttled with intervals or event-driven rather than per-tick.
+- **Fragment access matters:** `GetDependencies()` determines processor parallelism. Minimize `ReadWrite` fragments; prefer `ReadOnly` to allow concurrent execution with other processors.
+- **Pool instance data:** Always use `UMassStateTreeSubsystem` for allocation. Direct `FStateTreeInstanceData` construction per entity defeats the pooling optimization.
+- **Shallow trees:** `FStateTreeActiveStates::MaxStates = 8` is the depth limit. Mass trees should be especially shallow (2-3 levels) since depth adds per-entity overhead.
+- **Profile early:** Use `stat MassEntity` and Unreal Insights to identify expensive State Tree tasks. A single heavy task across 10,000 entities multiplies its cost dramatically.
+- **Batch signals:** Prefer `SignalEntities()` (plural) over individual `SignalEntity()` calls when signaling multiple entities to reduce subsystem overhead.