Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

ue-state-trees

Use when writing or debugging State Tree logic in Unreal Engine C++ — tasks, conditions, evaluators, considerations, schemas, transitions, events or Mass behaviours. Also use when the user mentions 'StateTree', 'state tree', 'FStateTreeTaskBase', 'FStateTreeExecutionContext', 'GetInstanceDataType', 'FInstanceDataType', 'UStateTreeComponent', 'UStateTreeAIComponent', 'FStateTreeReference', 'SendStateTreeEvent', 'EStateTreeRunStatus', 'StateTree schema', 'utility selection', 'scheduled tick', 'FinishTask', or 'Mass StateTree'. For behaviour trees, perception and navigation, see ue-ai-navigation; for Mass processors and fragments, see ue-mass-entity; for USTRUCT basics, see ue-cpp-foundations.

quodsoler · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add quodsoler/unreal-engine-skills --skill ue-state-trees

About this skill


name: ue-state-trees description: "Use when writing or debugging State Tree logic in Unreal Engine C++ — tasks, conditions, evaluators, considerations, schemas, transitions, events or Mass behaviours. Also use when the user mentions 'StateTree', 'state tree', 'FStateTreeTaskBase', 'FStateTreeExecutionContext', 'GetInstanceDataType', 'FInstanceDataType', 'UStateTreeComponent', 'UStateTreeAIComponent', 'FStateTreeReference', 'SendStateTreeEvent', 'EStateTreeRunStatus', 'StateTree schema', 'utility selection', 'scheduled tick', 'FinishTask', or 'Mass StateTree'. For behaviour trees, perception and navigation, see ue-ai-navigation; for Mass processors and fragments, see ue-mass-entity; for USTRUCT basics, see ue-cpp-foundations." metadata: version: "2.0.0" engine: "5.8"

UE State Trees

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

State Tree is a data-driven hierarchical state machine authored as a UStateTree data asset and executed from C++ through an execution context. Runtime types live in the StateTreeModule (plugin StateTree); actor-facing components and schemas live in GameplayStateTreeModule (plugin GameplayStateTree). Mass-entity behaviours add MassAIBehavior (plugin MassAI, Experimental in 5.8) plus MassEntity, MassCore and MassSignals. Add the modules you use to PublicDependencyModuleNames in your .Build.cs.

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

Request is about…Go to
What the runtime looks like, instance data, contextsArchitecture, Execution Contexts
Writing a taskTasks
Writing a condition or gating a transitionConditions
Utility scoring, "pick the best child state"Considerations
Feeding world data into the treeEvaluators, External Data
When and how states changeTransitions, State Types and Selection
Tag-driven signals into the treeEvents
Reacting to a C++ callback instead of pollingDelegates
Restricting which nodes an asset may useSchemas
Running a tree on an actor or AI controllerComponent and AI Setup
Reducing tick cost / sleeping treesScheduled Tick
Thousands of entitiesMass Entity Integration
Finishing work from a callback or another threadAsync Completion

Architecture

UStateTree (UDataAsset)          IsReadyToRun() must be true before execution
  ├── UStateTreeSchema           which nodes and context data are allowed
  ├── States                     hierarchy of States/Groups/Linked/Subtree
  │     ├── Tasks                work performed while the state is active
  │     ├── EnterConditions      gate on selecting the state
  │     ├── Considerations       utility score used by selection behaviours
  │     └── Transitions          rules for leaving the state
  ├── Evaluators                 global data providers, tick before transitions
  └── Parameters                 FInstancedPropertyBag global parameters

Nodes are USTRUCTs, not UObjects, and every node virtual is const. Mutable per-instance state lives in a separate instance-data struct owned by FStateTreeInstanceData, which is what persists across frames. The execution context is a short-lived view constructed over that instance data.

TypeRole
UStateTreeThe compiled asset. IsReadyToRun() reports link success
FStateTreeInstanceDataPersistent runtime storage — hold this, not the context
FStateTreeExecutionContextFull read/write context; construct per tick
FStateTreeReferenceUStateTree* plus overridden global parameters
EStateTreeRunStatusRunning, Stopped, Succeeded, Failed, Unset
// MyTreeRunner.h — persistent storage on the owner
UPROPERTY(Transient)
FStateTreeInstanceData InstanceData;

// .cpp — one context per tick over the same instance data
FStateTreeExecutionContext Context(*this, *StateTreeAsset, InstanceData);
Context.SetCollectExternalDataCallback(
    FOnCollectStateTreeExternalData::CreateUObject(this, &UMyTreeRunner::CollectExternalData));

FStateTreeExecutionContext::FStartParameters StartParams;
StartParams.RandomSeed = 1234;
Context.Start(StartParams);
// later frames
Context.Tick(DeltaTime);

Tick can be split when transitions must be evaluated after other systems have run: call TickUpdateTasks(DeltaTime) first and TickTriggerTransitions() afterwards.

Execution Contexts

5.8 splits the context by capability. Pick the narrowest one that compiles.

ContextGets youTypical use
FStateTreeReadOnlyExecutionContextGetOwner, GetWorld, GetStateTree, HasEventToProcess, IsValidGetDebugInfo overrides, gameplay debugger
FStateTreeMinimalExecutionContextadds SendEvent, ScheduleNextTick, scheduled-tick requestssending an event from outside the tick
FStateTreeExecutionContextadds Start/Stop/Tick, instance data, external data, FinishTask, BindDelegateeverything inside a node
FStateTreeWeakExecutionContextweak handles captured for laterlambdas, latent actions, timers
FStateTreeStrongExecutionContextresolved access from a weak contextinside the callback, via MakeStrongExecutionContext()

FStateTreeMinimalExecutionContext derives from `FStateTreeRe

Read the complete source ↗