StateTree is a general hierarchical state machine: states hold tasks (do work, report
Running / Succeeded / Failed), enter conditions gate selection, transitions move between
states on completion, tick, events or delegates, and evaluators / global tasks feed data.
ue-ai-and-navigation covers the AI use (UStateTreeAIComponent on an AIController). This
skill covers the rest: a tree that sequences a game's flow, screens and cutscenes, written as
in a 48-hour UE 5.9 game-jam project (2026-11) whose whole game flow (title, intro, three
chapters, a final choice, two endings) ran on one UStateTreeComponent.
When to use this skill
- A game-flow / screen-flow / cutscene-sequencing state machine on an actor.
- Writing C++ StateTree tasks or conditions that wrap your own subsystem.
- A tree that behaves oddly on loops: tasks re-entered, widgets rebuilt, openers replayed.
- Editing StateTree assets or
StateTreeComponentreferences from editor Python. - A StateTree-using module that compiles in the editor and fails the Game / Shipping / web target.
Mental model
- Nodes are structs, data lives in instance data. A task struct is
constat run time; everything that changes lives in itsFInstanceDataTypestruct, fetched withContext.GetInstanceData(*this). Never store run state in the node struct. - The schema decides what a tree may contain and what context it gets.
UStateTreeComponentSchema(GameplayStateTree) gives an Actor context; a customUStateTreeSchemacan allow only your nodes and no context. Deriving nodes from the*CommonBasestructs makes them legal under both. - The subsystem holds the truth, the tree sequences. Keep game state in a subsystem or component; nodes read and drive it. Then the tree can be restarted, resumed from a save, or replaced without losing state.
- Completion is a transition trigger. A state completes when its tasks considered for
completion finish;
OnStateCompleted/OnStateSucceeded/OnStateFailedtransitions fire then. A task that never completes and is excluded from completion runs "in the background" (a widget, a music bed). - Completed states are re-created. With the default selection rules
(
EStateTreeStateSelectionRules::DefaultincludesCompletedTransitionStatesCreateNewStates;Noneis labelled "Previous (UE 5.6) rules"), a completed state that a transition selects again is new: its tasks getExitStatethenEnterState(change type Changed).bShouldStateChangeOnReselect = falsedoes not prevent this; it only covers the Sustained case.
Setup
- Plugins:
StateTreeandGameplayStateTree(component and component schema); the jam also enabledPropertyBindingUtils. Restart the editor after enabling them. Build.cs: runtime modules"StateTreeModule","GameplayStateTreeModule"(plus"GameplayTags"when you send or match events by tag)."StateTreeEditorModule"(and"PropertyBindingUtils") only for editor targets, and only if you build or compile trees in code (tests).- The runtime modules start no threads and cooked and ran in a Wasm (browser) build. (jam)
C++ patterns
A task with parameters and outputs
#include "StateTreeTaskBase.h"
#include "StateTreeExecutionContext.h"
USTRUCT()
struct FMyShowScreenTaskInstanceData
{
GENERATED_BODY()
UPROPERTY(EditAnywhere, Category = "Parameter") // set in the asset or bound
TSoftClassPtr<UUserWidget> WidgetClass;
UPROPERTY(EditAnywhere, Category = "Input") // must be bound
int32 ZOrder = 10;
UPROPERTY(VisibleAnywhere, Category = "Output") // other nodes can bind to it
TObjectPtr<UUserWidget> Widget = nullptr;
};
USTRUCT(meta = (DisplayName = "Show Screen", Category = "MyGame"))
struct FMyShowScreenTask : public FStateTreeTaskCommonBase
{
GENERATED_BODY()
using FInstanceDataType = FMyShowScreenTaskInstanceData;
FMyShowScreenTask()
{
bShouldCallTick = false; // event-driven, no Tick
bShouldCopyBoundPropertiesOnTick = false;
bShouldStateChangeOnReselect = false; // keep the widget on a sustained reselect
#if WITH_EDITORONLY_DATA
bConsideredForCompletion = false; // runs in the background; others end the state
bCanEditConsideredForCompletion = false;
#endif
}
virtual const UStruct* GetInstanceDataType() const override { return FInstanceDataType::StaticStruct(); }
virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransitionResult& Transition) const override;
virtual void ExitState(FStateTreeExecutionContext& Context, const FStateTreeTransitionResult& Transition) const override;
};
EStateTreeRunStatus FMyShowScreenTask::EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransitionResult&) const
{
FInstanceDataType& Data = Context.GetInstanceData(*this);
UWorld* World = Context.GetWorld();
// ... create Data.Widget, add to viewport. A missing class must not stall the flow: log and keep running.
return EStateTreeRunStatus::Running;
}
- Instance-data
UPROPERTYcategories are the binding contract:Parameter(set or optionally bound),Input(must be bound),Output(bindable by later nodes),Context(auto-bound from the schema). Read byUE::StateTree::GetUsageFromMetaData. - Give every node an instance data type, even an empty
USTRUCT(): in 5.9 a node without one failed compilation ("missing instance value"). (jam) bConsideredForCompletionisWITH_EDITORONLY_DATA. It feeds the completion mask baked into the asset at compile time. Set it unguarded and the editor builds, but the Game, Shipping and Wasm targets fail witherror C2065: 'bConsideredForCompletion': undeclared identifier. Guard it, and build a non-editor target early. (jam; same declaration in 5.8)
A task that completes from a delegate
EStateTreeRunStatus FMyWaitForActionTask::EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransitionResult&) const
{
FInstanceDataType& Data = Context.GetInstanceData(*this);
UMyFlowSubsystem* Flow = ResolveFlow(Context);
if (!Flow) { return EStateTreeRunStatus::Failed; }
if (Flow->HasAlreadyHappened()) { return EStateTreeRunStatus::Succeeded; } // never wait for a past event
const FStateTreeWeakExecutionContext Weak = Context.MakeWeakExecutionContext();
Data.Handle = Flow->OnActionNative.AddLambda([Weak]()
{
const FStateTreeStrongExecutionContext Strong = Weak.MakeStrongExecutionContext();
if (FInstanceDataType* Ptr = Strong.GetInstanceDataPtr<FInstanceDataType>())
{
Strong.FinishTask(EStateTreeFinishTaskType::Succeeded);
}
});
Data.Flow = Flow;
return EStateTreeRunStatus::Running;
}
// ExitState: Data.Flow->OnActionNative.Remove(Data.Handle);
- Capture a
FStateTreeWeakExecutionContext, never the context or instance-data reference: the state may have exited before the delegate fires. - Check the condition on enter as well. An event that fired before the task entered (while a cutscene played, for example) is never broadcast again; in the jam a run hung on a screen until the wait finished at once when the state it waited for already held.
- One action may fire several delegates: let the first one finish the task and ignore the rest.
Condition
USTRUCT(meta = (DisplayName = "Beat Is", Category = "MyGame"))
struct FMyBeatIsCondition : public FStateTreeConditionCommonBase
{
GENERATED_BODY()
using FInstanceDataType = FMyBeatIsConditionInstanceData;
virtual const UStruct* GetInstanceDataType() const override { return FInstanceDataType::StaticStruct(); }
virtual bool TestCondition(FStateTreeExecutionContext& Context) const override;
UPROPERTY(EditAnywhere, Category = "Parameter")
bool bInvert = false;
};
Evaluators derive from FStateTreeEvaluatorCommonBase (TreeStart, Tick, TreeStop).
Editor descriptions: override GetDescription(...) inside #if WITH_EDITOR.
Custom schema (trees without an actor, tests, C++ drivers)
UCLASS(meta = (DisplayName = "My Flow"))
class UMyFlowStateTreeSchema : public UStateTreeSchema
{
GENERATED_BODY()
virtual bool IsStructAllowed(const UScriptStruct* InScriptStruct) const override; // allow the *CommonBase families
virtual bool IsClassAllowed(const UClass* InClass) const override; // allow the Blueprint node bases
virtual bool IsExternalItemAllowed(const UStruct& InStruct) const override { return false; }
};
Run it with FStateTreeExecutionContext Exec(*Owner, *Tree, InstanceData) then Exec.Start() and
Exec.Tick(DeltaTime); the owner can be any UObject (a subsystem).
Tree shape for game flow
Flow
Start Start Run (resumes a loaded save)
[Beat Is Chapter] -> Play ; [Beat Is Ending] -> Ending ; else -> Intro
Intro Enter Beat(Intro, LS_Intro) -> Chapters
Chapters Show Screen(WBP_HUD) (parent: up once for all children)
Chapter1 Enter Beat(Chapter1) -> Play
Play Wait For Player Action
[Final Choice Made] -> Ending ; [Beat Is Chapter2, opener pending] -> Chapter2 ; else -> Play
Ending
Win enter [Result Win] Enter Beat(Ending, LS_Win) -> Succeeded
Lose enter [Result Lose] Enter Beat(Ending, LS_Lose) -> Failed
- Widgets on parents, loops in children. Under the 5.9 rules a looping child that completes is re-created every time; a widget task on that same state would be torn down and rebuilt after every player action (open tabs, selection and a drag in progress lost). On the parent it stays up.
- One-shot content must be idempotent. A state with "Enter Beat" looping to itself entered the beat 31 times in 6 ticks in a test. Record "opener played" in the subsystem and make the task a no-op the second time; gate the transitions into opener states with "only if pending".
- Route resumes in the first state. A loaded save can be mid-flow; transitions cannot go
backwards, so
Startroutes to the right state. - Movement between beats goes through the subsystem's public API so every listener sees each step.
Starting, holding and replacing the tree
UStateTreeComponent::SetStartLogicAutomatically(false)(call beforeBeginPlay, for example in the game mode'sStartPlaybeforeSuper::StartPlay) holds the tree behind a title screen; laterSetStartLogicAutomatically(true)thenStartLogic().SetStateTree/SetStateTreeReferenceare ignored while the logic runs.StateTreeRefis protected and has no public getter in 5.9; read it by reflection (FindFProperty<FStructProperty>(UStateTreeComponent::StaticClass(), TEXT("StateTreeRef"))) if you must check that a placed component has a tree. The jam logged a warning and assigned a fallback tree from code when a placed component's reference was empty.- Events:
SendStateTreeEvent(FStateTreeEvent)(tag, optional payload, origin) forOnEventtransitions;GetStateTreeRunStatus()andOnStateTreeRunStatusChangedfor the end state. - Linked trees: a state of type
Linked(a subtree in the same asset) orLinkedAsset(another asset);AddLinkedStateTreeOverrides(Tag, Ref)swaps a linked asset at run time.
Editor Python: what works and what kills the editor
-
Never call
StateTreeComponent.set_state_tree()on a Blueprint component template (a template reached throughSubobjectDataSubsystem): the editor fatals withNull assigned to TNotNull. Write the reference property instead, on the template and on placed instances (a placed copy keptNoneafter a Blueprint recompile): (jam)ref = comp.get_editor_property("state_tree_ref") ref.import_text('(StateTree="/Game/Flow/ST_Flow.ST_Flow",Parameters=(Value=None),PropertyOverrides=)') comp.set_editor_property("state_tree_ref", ref) -
Transitions (
FStateTreeTransition, editor-only data onUStateTreeState) have no script-callable "add transition"; the C++AddTransitionis not aUFUNCTION. The jam wrote them withStateTreeTransition.import_text(a fresh transition ID per transition, the target state'sID,LinkType=GotoState); writing the result into the state'stransitionsarray is the remaining step:t = unreal.StateTreeTransition() t.import_text('(Trigger=OnStateCompleted,State=(Name="Investigate",ID=%s,LinkType=GotoState),ID=%s)' % (target_state.get_editor_property("id").to_string(), unreal.GuidLibrary.new_guid().to_string())) # not unreal.Guid(): that is all zeros ts = list(state.get_editor_property("transitions")); ts.append(t) state.set_editor_property("transitions", ts) # write a new list backThen mark the asset modified and compile it. Transition conditions were added with a third-party tool in the jam; the engine route is untested (see Unverified).
-
UStateTree::EditorDatais a bareUPROPERTY()underWITH_EDITORONLY_DATA, sotree.get_editor_property("editor_data")fails.UStateTreeEditorData::GetEditorData(StateTree)isBlueprintCallable; Epic's 5.9 StateTreeToolset reaches the data through it. -
Epic's StateTreeToolset (5.9, experimental) wraps the editing API as AI tools:
compile,get_editor_data,get_root_states,get_all_states,get_children,get_tasks,get_transitions,add_child_state,add_task,add_enter_condition,add_global_task,add_evaluator,set_node_instance_data, ... It cannot create a StateTree asset with a schema (UStateTreeFactory::SetSchemaClassis not aUFUNCTION) and has no transition writer.
Testing a tree in code
Editor-only tests can build a tree with UStateTreeEditorData, compile it with FStateTreeCompiler
and run it with FStateTreeExecutionContext and EStateTreeRecordTransitions::Yes, without any
asset or world. The jam's suite ran a full game ten times per seed this way. Pattern, helpers and
what to assert: references/build-and-test-in-code.md.
Gotchas
- Run state in the node struct instead of instance data: shared by every instance, and the node is
constat run time anyway. - A task that waits for an event that already happened waits forever. Check on enter.
- Expecting
bShouldStateChangeOnReselect = falseto keep a looping state alive: completed states are re-created in 5.9 regardless. Move the persistent task to a parent. - An editor-only member (
bConsideredForCompletion) set unguarded: editor builds, game targets fail. SetStateTreewhile running: ignored. Hold the logic, set, then start.- A widget task on a missing class should log and keep running; a missing UI must not stall the flow.
set_state_tree()on a Blueprint template from Python: editor crash. Useimport_text.
Unverified
- The array write-back above (
set_editor_property("transitions", ...)): the jam notes record theimport_textform only. In a headless 5.9 editor thatimport_textcall returnedTrueand the transition exported back with the trigger, target and IDs set,unreal.GuidLibrary.new_guid()returned a non-zero guid andunreal.Guid()all zeros; writing the array into a real state and compiling was not run. - Adding transition conditions from Python with engine API only (
UStateTreeStatehasAddEnterConditionas aUFUNCTION, transitions have no equivalent; the jam used a third-party plugin). unreal.StateTreeEditorData.get_editor_data(tree)from a plain script: the function exists in 5.9 Python (checked in a headless editor) and Epic's toolset calls it; it was not called on a tree.- Whether
set_state_tree()is also fatal on a placed (non-template) component in the editor world.
References & source material
Engine source (UE 5.9):
Engine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeTaskBase.h—FStateTreeTaskCommonBase, flags, editor-onlybConsideredForCompletionEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeConditionBase.h—FStateTreeConditionCommonBase::TestConditionEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeEvaluatorBase.h—TreeStart,Tick,TreeStopEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeNodeBase.h—GetInstanceDataType,GetDescriptionEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeExecutionContext.h—GetInstanceData,MakeWeakExecutionContext,SendEvent,TNotNullownerEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeAsyncExecutionContext.h— weak / strong contexts,FinishTask,GetInstanceDataPtrEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeTypes.h—EStateTreeStateSelectionRules,EStateTreeTransitionTrigger,EStateTreeStateType,EStateTreePropertyUsageEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeSchema.h—IsStructAllowed,IsClassAllowedEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeReference.h—FStateTreeReference(StateTree,Parameters,PropertyOverrides)Engine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTreeEvents.h—FStateTreeEventEngine/Plugins/Runtime/StateTree/Source/StateTreeModule/Public/StateTree.h—EditorData(editor-only, not script-visible)Engine/Plugins/Runtime/StateTree/Source/StateTreeEditorModule/Public/StateTreeState.h—FStateTreeTransition,UStateTreeState::Transitions,AddTransition(C++ only)Engine/Plugins/Runtime/StateTree/Source/StateTreeEditorModule/Public/StateTreeEditorData.h—GetEditorDataEngine/Plugins/Runtime/StateTree/Source/StateTreeEditorModule/Public/StateTreeCompiler.h—FStateTreeCompilerEngine/Plugins/Runtime/GameplayStateTree/Source/GameplayStateTreeModule/Public/Components/StateTreeComponent.h—SetStateTree,SetStateTreeReference,SetStartLogicAutomatically,SendStateTreeEvent,StateTreeRefEngine/Plugins/Runtime/GameplayStateTree/Source/GameplayStateTreeModule/Public/Components/StateTreeComponentSchema.h— the component schema
Epic's 5.9 StateTreeToolset (Python): Engine/Plugins/Experimental/Toolsets/StateTreeToolset/Content/Python/state_tree_toolset/state_tree.py.
Related skills: ue-ai-and-navigation (StateTree for AI), ue-subsystems (where flow state lives),
ue-automation-and-testing, ue-sequencer-and-cinematics (sequences the flow plays).