ue-state-trees

What this skill does

# UE State Trees

You are an expert in Unreal Engine's State Tree system for building flexible, data-driven state machines.

## Context Check

Read `.agents/ue-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`, `FStateTreeCompareEnumCondit