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-treesAbout 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, contexts | Architecture, Execution Contexts |
| Writing a task | Tasks |
| Writing a condition or gating a transition | Conditions |
| Utility scoring, "pick the best child state" | Considerations |
| Feeding world data into the tree | Evaluators, External Data |
| When and how states change | Transitions, State Types and Selection |
| Tag-driven signals into the tree | Events |
| Reacting to a C++ callback instead of polling | Delegates |
| Restricting which nodes an asset may use | Schemas |
| Running a tree on an actor or AI controller | Component and AI Setup |
| Reducing tick cost / sleeping trees | Scheduled Tick |
| Thousands of entities | Mass Entity Integration |
| Finishing work from a callback or another thread | Async 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.
| Type | Role |
|---|---|
UStateTree | The compiled asset. IsReadyToRun() reports link success |
FStateTreeInstanceData | Persistent runtime storage — hold this, not the context |
FStateTreeExecutionContext | Full read/write context; construct per tick |
FStateTreeReference | UStateTree* plus overridden global parameters |
EStateTreeRunStatus | Running, 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.
| Context | Gets you | Typical use |
|---|---|---|
FStateTreeReadOnlyExecutionContext | GetOwner, GetWorld, GetStateTree, HasEventToProcess, IsValid | GetDebugInfo overrides, gameplay debugger |
FStateTreeMinimalExecutionContext | adds SendEvent, ScheduleNextTick, scheduled-tick requests | sending an event from outside the tick |
FStateTreeExecutionContext | adds Start/Stop/Tick, instance data, external data, FinishTask, BindDelegate | everything inside a node |
FStateTreeWeakExecutionContext | weak handles captured for later | lambdas, latent actions, timers |
FStateTreeStrongExecutionContext | resolved access from a weak context | inside the callback, via MakeStrongExecutionContext() |
FStateTreeMinimalExecutionContext derives from `FStateTreeRe