Unreal Behavior Trees
Author NPC decision-making in UE5 with Behavior Trees driven by a Blackboard: structure the
tree with composites, gate branches with decorators, keep state current with services, and run
it from an AIController. Targets UE 5.8.
When to use
- Use when building enemy/NPC AI: creating a
BT_/BB_ asset pair, structuring
Selector/Sequence branches, adding decorators (conditions) and services (periodic updates),
writing custom BTTask/BTService nodes, or wiring an AIController to run the tree.
- Use when the project has Behavior Tree (
BT_) and Blackboard (BB_) assets and an
AAIController.
When not to use: the concept of AI (FSM vs BT vs steering, cross-engine) →
game-ai. Pure navigation/pathing math is engine navmesh (BT's MoveTo uses it). Simple
one-off logic may be cheaper as a small state machine than a full tree.
Behavior Tree or StateTree? UE 5.8 ships both, and Behavior Trees are not deprecated.
StateTree is Epic's general-purpose hierarchical state machine: it combines BT-style
selection with explicit States and Transitions. If the project already uses StateTree
assets, or the AI is naturally a set of modes with clear transitions (patrol → alert →
combat), check with the user before adding a Behavior Tree next to it. Keep using Behavior
Trees where the project already has BT_/BB_ assets.
Core workflow
- Create the pair: a Blackboard (
BB_) holds typed keys (the AI's memory: TargetActor,
LastKnownLocation, bIsInvestigating); a Behavior Tree (BT_) references that Blackboard.
- Possess and run. An
AAIController possesses the pawn and calls RunBehaviorTree(BT),
which also initializes the referenced Blackboard.
- Structure with composites. Selector runs children left→right until one succeeds
(priority/fallback: "attack, else chase, else patrol"). Sequence runs children until one
fails (do-all: "move to cover → reload → peek"). Simple Parallel runs one main task
alongside a secondary.
- Gate branches with Decorators that read Blackboard keys (e.g. "Has Target?" guards the
combat branch). Set Observer Aborts so the tree re-evaluates when the key changes.
- Keep the Blackboard current with Services attached to a branch — they tick periodically
(e.g. update
TargetActor via a sight check) only while that branch is active.
- Do work in Tasks, which return
Succeeded, Failed, or InProgress (latent tasks like
MoveTo finish later).
- Verify with the Behavior Tree debugger during PIE — it highlights the running node and
shows live Blackboard values, so you see exactly which branch executes.
Patterns
1. AIController that runs the tree (C++)
void AEnemyAIController::OnPossess(APawn* InPawn)
{
Super::OnPossess(InPawn);
if (BehaviorTree) // UPROPERTY(EditAnywhere) TObjectPtr<UBehaviorTree>
RunBehaviorTree(BehaviorTree); // initializes & uses the Blackboard the BT references
}
2. A priority tree (node structure)
ROOT
└── Selector (try combat, else investigate, else patrol)
├── Sequence [Decorator: Blackboard 'TargetActor' Is Set, Observer Aborts: Both]
│ ├── Task: MoveTo (TargetActor) // latent: returns InProgress then Succeeded
│ └── Task: Attack
├── Sequence [Decorator: 'LastKnownLocation' Is Set]
│ ├── Task: MoveTo (LastKnownLocation)
│ └── Task: Wait (3s) + clear key
└── Task: Patrol (BTTask_FindPatrolPoint -> MoveTo)
Observer Aborts: Both makes the combat branch interrupt patrol the instant TargetActor is
set, and bail out when it's cleared — this is what makes the AI feel reactive.
3. Updating the Blackboard from code (e.g. on seeing the player)
void AEnemyAIController::SetTarget(AActor* Target)
{
if (UBlackboardComponent* BB = GetBlackboardComponent())
BB->SetValueAsObject(TEXT("TargetActor"), Target); // key name must match the BB asset
}
// Clear with BB->ClearValue(TEXT("TargetActor")); to drop back to a lower-priority branch.
Pitfalls
- AI never starts — the pawn isn't possessed (set the Pawn's Auto Possess AI to "Placed
in World or Spawned" and assign the AIController), or
RunBehaviorTree was never called.
MoveTo instantly fails — no NavMesh in the level (add a Nav Mesh Bounds Volume), or the
target is off the navmesh.
- Branch doesn't react to changes — the gating Decorator's Observer Aborts is set to
None; set it to Self/Lower Priority/Both so the tree re-evaluates when the key changes.
- A task hangs the tree — a custom task returned
InProgress and never calls
FinishLatentTask. Always complete latent tasks.
- AI behaves strangely only when several NPCs share a tree — a custom task stores run state
in member variables. Task nodes are shared by every AI using the asset unless instanced; keep
per-AI state in node memory (see the reference).
- Blackboard key typos —
SetValueAsObject("Taget", ...) silently does nothing; match the
key name and type exactly, or use a cached FBlackboardKeySelector.
- Sequence vs Selector confusion — Sequence = AND (stops on first failure); Selector = OR
(stops on first success). Swapping them inverts the behaviour.
References
- For a custom C++
UBTTaskNode (instant and latent ExecuteTask returning EBTNodeResult,
per-AI node memory, AbortTask, and a FBlackboardKeySelector), read
references/custom-bttask.md.
- Primary docs: "Behavior Trees in Unreal Engine"
(
https://dev.epicgames.com/documentation/en-us/unreal-engine/behavior-trees-in-unreal-engine).
Related skills
game-ai — engine-agnostic AI design (FSM, BT, steering, pathfinding choices).
unreal-cpp-gameplay — the AIController and pawn classes in C++.
fps-shooter / tower-defense — genres that compose enemy AI.
1---2name: unreal-behavior-trees3description: >4 Build NPC AI in Unreal Engine 5 with Behavior Trees and Blackboards: composites5 (Selector/Sequence), tasks, decorators, services, and running the tree from an AIController.6 Use when creating enemy/NPC AI, BT_/BB_ assets, custom BTTask or BTService nodes, or when7 the user mentions Behavior Tree, Blackboard, AIController, BTTask, decorator, or service.8metadata:9 source: https://skillmd.com/skills/junmystery/unreal-behavior-trees10---1112# Unreal Behavior Trees1314Author NPC decision-making in UE5 with Behavior Trees driven by a Blackboard: structure the15tree with composites, gate branches with decorators, keep state current with services, and run16it from an AIController. Targets **UE 5.8**.1718## When to use1920- Use when building enemy/NPC AI: creating a `BT_`/`BB_` asset pair, structuring21 Selector/Sequence branches, adding decorators (conditions) and services (periodic updates),22 writing custom `BTTask`/`BTService` nodes, or wiring an AIController to run the tree.23- Use when the project has Behavior Tree (`BT_`) and Blackboard (`BB_`) assets and an24 `AAIController`.2526**When *not* to use:** the *concept* of AI (FSM vs BT vs steering, cross-engine) →27`game-ai`. Pure navigation/pathing math is engine navmesh (BT's `MoveTo` uses it). Simple28one-off logic may be cheaper as a small state machine than a full tree.2930**Behavior Tree or StateTree?** UE 5.8 ships both, and Behavior Trees are not deprecated.31StateTree is Epic's general-purpose hierarchical state machine: it combines BT-style32selection with explicit States and Transitions. If the project already uses StateTree33assets, or the AI is naturally a set of modes with clear transitions (patrol → alert →34combat), check with the user before adding a Behavior Tree next to it. Keep using Behavior35Trees where the project already has `BT_`/`BB_` assets.3637## Core workflow38391. **Create the pair:** a Blackboard (`BB_`) holds typed keys (the AI's memory: `TargetActor`,40 `LastKnownLocation`, `bIsInvestigating`); a Behavior Tree (`BT_`) references that Blackboard.412. **Possess and run.** An `AAIController` possesses the pawn and calls `RunBehaviorTree(BT)`,42 which also initializes the referenced Blackboard.433. **Structure with composites.** **Selector** runs children left→right until one *succeeds*44 (priority/fallback: "attack, else chase, else patrol"). **Sequence** runs children until one45 *fails* (do-all: "move to cover → reload → peek"). **Simple Parallel** runs one main task46 alongside a secondary.474. **Gate branches with Decorators** that read Blackboard keys (e.g. "Has Target?" guards the48 combat branch). Set **Observer Aborts** so the tree re-evaluates when the key changes.495. **Keep the Blackboard current with Services** attached to a branch — they tick periodically50 (e.g. update `TargetActor` via a sight check) only while that branch is active.516. **Do work in Tasks**, which return `Succeeded`, `Failed`, or `InProgress` (latent tasks like52 `MoveTo` finish later).537. **Verify** with the Behavior Tree debugger during PIE — it highlights the running node and54 shows live Blackboard values, so you see exactly which branch executes.5556## Patterns5758### 1. AIController that runs the tree (C++)5960```cpp61void AEnemyAIController::OnPossess(APawn* InPawn)62{63 Super::OnPossess(InPawn);64 if (BehaviorTree) // UPROPERTY(EditAnywhere) TObjectPtr<UBehaviorTree>65 RunBehaviorTree(BehaviorTree); // initializes & uses the Blackboard the BT references66}67```6869### 2. A priority tree (node structure)7071```text72ROOT73└── Selector (try combat, else investigate, else patrol)74 ├── Sequence [Decorator: Blackboard 'TargetActor' Is Set, Observer Aborts: Both]75 │ ├── Task: MoveTo (TargetActor) // latent: returns InProgress then Succeeded76 │ └── Task: Attack77 ├── Sequence [Decorator: 'LastKnownLocation' Is Set]78 │ ├── Task: MoveTo (LastKnownLocation)79 │ └── Task: Wait (3s) + clear key80 └── Task: Patrol (BTTask_FindPatrolPoint -> MoveTo)81```8283`Observer Aborts: Both` makes the combat branch interrupt patrol the instant `TargetActor` is84set, and bail out when it's cleared — this is what makes the AI feel reactive.8586### 3. Updating the Blackboard from code (e.g. on seeing the player)8788```cpp89void AEnemyAIController::SetTarget(AActor* Target)90{91 if (UBlackboardComponent* BB = GetBlackboardComponent())92 BB->SetValueAsObject(TEXT("TargetActor"), Target); // key name must match the BB asset93}94// Clear with BB->ClearValue(TEXT("TargetActor")); to drop back to a lower-priority branch.95```9697## Pitfalls9899- **AI never starts** — the pawn isn't possessed (set the Pawn's *Auto Possess AI* to "Placed100 in World or Spawned" and assign the AIController), or `RunBehaviorTree` was never called.101- **`MoveTo` instantly fails** — no NavMesh in the level (add a Nav Mesh Bounds Volume), or the102 target is off the navmesh.103- **Branch doesn't react to changes** — the gating Decorator's **Observer Aborts** is set to104 None; set it to Self/Lower Priority/Both so the tree re-evaluates when the key changes.105- **A task hangs the tree** — a custom task returned `InProgress` and never calls106 `FinishLatentTask`. Always complete latent tasks.107- **AI behaves strangely only when several NPCs share a tree** — a custom task stores run state108 in member variables. Task nodes are shared by every AI using the asset unless instanced; keep109 per-AI state in node memory (see the reference).110- **Blackboard key typos** — `SetValueAsObject("Taget", ...)` silently does nothing; match the111 key name and type exactly, or use a cached `FBlackboardKeySelector`.112- **Sequence vs Selector confusion** — Sequence = AND (stops on first failure); Selector = OR113 (stops on first success). Swapping them inverts the behaviour.114115## References116117- For a **custom C++ `UBTTaskNode`** (instant and latent `ExecuteTask` returning `EBTNodeResult`,118 per-AI node memory, `AbortTask`, and a `FBlackboardKeySelector`), read119 `references/custom-bttask.md`.120- Primary docs: "Behavior Trees in Unreal Engine"121 (`https://dev.epicgames.com/documentation/en-us/unreal-engine/behavior-trees-in-unreal-engine`).122123## Related skills124125- `game-ai` — engine-agnostic AI design (FSM, BT, steering, pathfinding choices).126- `unreal-cpp-gameplay` — the AIController and pawn classes in C++.127- `fps-shooter` / `tower-defense` — genres that compose enemy AI.