Unreal Behavior Trees, EQS and StateTree
Author NPC decision-making in UE5: a Behavior Tree reads a Blackboard, decorators gate branches, services keep keys fresh, EQS picks locations or targets, and an AIController runs it all. StateTree is the alternative for mode-based AI. Targets UE 5.8.
When to use
- Creating or fixing
BT_/BB_assets, decorators, services, customBTTask/BTService/BTDecoratorC++ nodes, or the AIController that runs the tree. - Writing or debugging EQS queries (
EQS_assets, Run EQS Query, the EQS Testing Pawn). - Building AI with StateTree (
ST_assets,UStateTreeAIComponent) or mixing it with a BT.
When not to use: writing your own behavior-tree or utility-AI runtime, outside Unreal's
assets → ai-behavior-trees-utility-ai. Choosing an AI architecture or engine-neutral
steering and pathfinding → game-ai. The pawn and controller classes themselves →
unreal-cpp-gameplay.
Behavior Tree or StateTree?
Both ship in UE 5.8 and Behavior Trees are not deprecated. Default: keep whatever the
project already uses. For a new AI, pick StateTree when the behavior is a set of modes with
explicit transitions (patrol, alert, combat), and a Behavior Tree when it is a priority list
that must re-evaluate when Blackboard values change. They also combine: the BT task
Run State Tree (UBTTask_RunStateTree) runs a StateTree inside a branch, and StateTree has
its own Run Env Query task for EQS. StateTree on an AI needs the StateTree and
GameplayStateTree plugins and a UStateTreeAIComponent on the AIController, with an asset
that uses the StateTree AI Component schema. Ask before adding a second system beside the
first.
Workflow
- Read the project first. Check
EngineAssociationin the.uproject(this skill targets 5.8). List existing AI assets and classes so you extend them instead of duplicating:find Content -name "BT_*" -o -name "BB_*" -o -name "EQS_*" -o -name "ST_*"andgrep -rn "AAIController\|RunBehaviorTree\|UStateTreeAIComponent" Source. C++ AI code needs"AIModule"in the module's*.Build.cs. - Blackboard (
BB_) first. One typed key per fact the AI remembers (TargetActor,LastKnownLocation,bIsInvestigating). The tree references this asset. - Run it from the controller. The pawn's AIController calls
RunBehaviorTree(BT)inOnPossess; that also initializes the Blackboard. Set the pawn's Auto Possess AI to "Placed in World or Spawned" and its AI Controller Class. - Shape the tree. Root Selector for priorities (combat, else investigate, else patrol); Sequences for steps that must all succeed. Put a Blackboard decorator on each priority branch and set Observer Aborts so a key change interrupts the running branch.
- Keep keys fresh with services on the branch that needs them (perception, distance checks). A service ticks only while its branch is active.
- Use EQS for "where" and "which" questions (cover point, nearest pickup): add a Run EQS Query task, set its Query Template and the Blackboard key that receives the best item, and pass parameters through Query Config.
- Write custom nodes in C++ only when the built-ins can't do it; read the reference below.
- Check it (see Verify).
Patterns
AIController that runs the tree (C++)
void AEnemyAIController::OnPossess(APawn* InPawn)
{
Super::OnPossess(InPawn);
if (BehaviorTree) // UPROPERTY(EditAnywhere) TObjectPtr<UBehaviorTree>
{
RunBehaviorTree(BehaviorTree); // also initializes the Blackboard the BT references
}
}
void AEnemyAIController::SetTarget(AActor* Target)
{
if (UBlackboardComponent* BB = GetBlackboardComponent())
{
BB->SetValueAsObject(TEXT("TargetActor"), Target); // must match the BB key name
}
}
// BB->ClearValue(TEXT("TargetActor")) drops the tree back to a lower-priority branch.A reactive priority tree
ROOT
└── Selector
├── Sequence [Blackboard: TargetActor Is Set, Observer Aborts: Both]
│ ├── MoveTo (TargetActor)
│ └── Attack
├── Sequence [Blackboard: LastKnownLocation Is Set, Observer Aborts: Lower Priority]
│ ├── MoveTo (LastKnownLocation)
│ └── Wait 3s, then clear the key
└── Sequence (patrol)
├── Run EQS Query (EQS_NextPatrolPoint -> PatrolLocation)
└── MoveTo (PatrolLocation)Both on the combat branch means: start combat the moment TargetActor is set, and leave it
the moment it is cleared.
Verify
Say which of these you actually ran; reading the assets is not a test.
- Compile the module (Windows:
Engine/Build/BatchFiles/Build.bat <Project>Editor Win64 Development -Project="<path>.uproject" -WaitMutex; Linux and macOS useEngine/Build/BatchFiles/Linux/Build.shorMac/Build.shwith the matching platform) and fix every error and warning in your files. - Validate assets:
UnrealEditor-Cmd <Project>.uproject -run=DataValidation -unattendedruns the project's asset validators; fix every error it reports. - Prove behavior with a functional test. In a small test map, place the NPC, a target and
a Functional Test actor whose test waits a few seconds and then checks the Blackboard key or
the NPC's distance to the target before calling
FinishTest. Run it headless and read the exit status and report:UnrealEditor-Cmd <Project>.uproject -ExecCmds="Automation RunTest Project.Functional Tests;Quit" -unattended -nullrhi -ReportExportPath="<dir>". Run-ExecCmds="Automation List;Quit"first if the test path is unclear. The Functional Testing Editor plugin must be enabled. If the map won't run without a renderer, swap-nullrhifor-RenderOffscreen(needs a GPU). - When a run in the editor is needed, ask the user to start PIE, press the apostrophe key for the Gameplay Debugger (or open the Behavior Tree editor while PIE runs), and report which branch is highlighted and the live Blackboard values. EQS results also show in the Visual Logger.
- Optional: if Epic's
unreal-mcpskill is installed and the editor's MCP server is running, you can inspect the BT and StateTree assets live through it. The checks above do not need it.
Gotchas
- AI never starts: the pawn isn't possessed by your AIController (Auto Possess AI, AI
Controller Class), or
RunBehaviorTreenever ran. MoveTofails instantly: no navmesh (add a Nav Mesh Bounds Volume and rebuild paths), or the goal is off the navmesh.- The tree ignores a key change: the decorator's Observer Aborts is
None.Selfaborts its own branch when the condition fails,Lower Prioritylets it interrupt branches to its right,Bothdoes both. - A task hangs the tree: it returned
InProgressand never calledFinishLatentTask, or its abort path never finishes. - Bugs appear only with several NPCs: a custom task keeps run state in member variables. Non-instanced nodes are shared by every AI using the asset; keep per-AI state in node memory.
- Blackboard key typo:
SetValueAsObject("Taget", ...)does nothing, silently. Use aFBlackboardKeySelectoror one shared constant for the key name. - Sequence vs Selector swapped: Sequence stops at the first failure (AND), Selector stops at the first success (OR).
- EQS returns odd results: only the left-most generator connected to the root runs. Debug with an EQS Testing Pawn in the level before blaming the tree.
- EQS missing on clients: EQS is server-side AI. In 5.8 a query asset can be stripped from
client builds (
bStripFromClientBuilds), so client code must not run it. - StateTree edits don't show in PIE: 5.8 compiles StateTrees through a queue and the editor marks out-of-date trees; recompile the asset before testing.
References
- Read
references/custom-bttask.mdbefore writing a C++UBTTaskNode: instant and latent tasks, per-AI node memory,AbortTask, typed Blackboard access, key selectors, and the base classes for custom services and decorators. - Epic docs: Behavior Trees, EQS user guide, StateTree, Functional Testing.
Related skills
ai-behavior-trees-utility-ai: hand-written BT and utility AI runtimes, any engine.game-ai: choosing FSM, BT, steering or pathfinding.unreal-cpp-gameplay: the AIController and pawn classes, module setup.fps-shooter,tower-defense: genres that compose enemy AI.
Version notes
Last verified: 2026-11-11.
- Current release: UE 5.8 (5.8.4 hotfix, October 2026). UE 5.9 is in Preview (the MegaJam Preview, November 2026); do not move a project to it without a copy.
- 5.8: StateTree gained starting states, a compiler manager with queued compilation, and
out-of-date tracking;
UEnvQuerygainedbStripFromClientBuilds. - 5.9 Preview: StateTrees can be edited from Blueprint or Python scripts; the navmesh can build progressively.
- Sources: UE 5.8 release notes, UE 5.9 Preview release notes, GameplayStateTreeModule API, Run Automation Tests.