unreal-behavior-trees

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

1. Create the pair: a Blackboard (BB_) holds typed keys (the AI's memory: TargetActor, LastKnownLocation, bIsInvestigating); a Behavior Tree (BT_) references that Blackboard.
2. Possess and run. An AAIController possesses the pawn and calls RunBehaviorTree(BT), which also initializes the referenced Blackboard.
3. 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.
4. 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.
5. 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.
6. Do work in Tasks, which return Succeeded, Failed, or InProgress (latent tasks like MoveTo finish later).
7. 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.