Ue State Trees

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:

Build.cs modules: StateTreeModule, GameplayStateTreeModule

The execution context is constructed per-tick from persistent instance data:

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.

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:

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):

Behavioral Flags

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:

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.

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.