Behavior Trees & Utility AI
Two complementary ways to structure NPC decision-making, plus how to combine them. A
behavior tree (BT) expresses structured, prioritized, reactive logic as a tree that is
"ticked" each step. Utility AI answers "how much do I want each option right now?" by
scoring actions with normalized curves and picking the best. Ship believable agents by using a
BT for structure and Utility AI where graded trade-offs matter.
This skill is the implementation companion to game-ai (which helps you choose between
FSM / BT / steering / pathfinding). Read game-ai to pick a model; read this to build the
runtime.
When to use
- Use to build a reusable BT runtime: a
Blackboard, Node base, action/condition leaves,
Sequence/Selector/Parallel composites, and decorators (Inverter, Cooldown, Repeat).
- Use to build a Utility AI decider: response curves, considerations, and an evaluator that
scores and selects actions (max, softmax, or weighted-random for variety).
- Use to build hybrid AI — a BT whose leaf delegates the "which attack / which target"
choice to a utility evaluator.
When not to use: to choose between FSM, BT, steering, or pathfinding, and for A*/navmesh
routing, use game-ai. For Unreal's asset-based BehaviorTree/Blackboard, BTTask/BTService
and AIController, use unreal-behavior-trees. For the navmesh agent that moves the NPC, use
unity-navmesh or the engine's navigation node.
Core workflow
- Pick the model. Structured, prioritized, interruptible behavior → BT. Continuous
"score every option" decisions (targeting, needs, item choice) → Utility. Both → hybrid.
- Design the Blackboard first. One typed key/value store per agent is the shared memory that
decouples nodes; leaves read/write it and never hold references to each other.
- Write leaves. Conditions return
Success/Failure immediately; actions return
Running across frames until they finish. Keep leaves small and side-effect-explicit.
- Compose.
Selector = OR/fallback (first non-failure wins); Sequence = AND (stop at first
non-success); Parallel for concurrent branches. Wrap with decorators for policy (invert,
cooldown, repeat, force-success).
- For Utility: enumerate considerations, map each raw fact through a normalized 0..1 curve,
combine (weighted product with compensation, or weighted sum), then select the max — add
hysteresis so agents don't flip-flop on ties.
- Tick deliberately. Tick the tree/evaluator once per decision step (often slower than
render). Preserve
Running state between ticks; verify by drawing the active path and the
per-action scores on screen while tuning.
Architecture at a glance
A behavior tree evaluates top-down, left-to-right; each node returns a status up to its parent:
flowchart TD
Root["Selector (root)"] --> Combat["Sequence: Combat"]
Root --> Patrol["Action: Patrol"]
Combat --> See["Condition: CanSeePlayer?"]
Combat --> InRange{"Selector: Reach"}
Combat --> Attack["Action: Attack (Running)"]
InRange --> Close["Condition: InAttackRange?"]
InRange --> MoveTo["Action: MoveToPlayer (Running)"]
Utility AI is a scoring pipeline — every candidate action is scored, then one is selected:
facts (distance, health, ammo…)
│ each fact → a normalized 0..1 response curve (consideration)
▼
score(action) = weight · combine(consideration_1 … consideration_n) # product+compensation or sum
▼
select: argmax · or softmax / weighted-random for variety · + hysteresis to avoid jitter
Status is a three-value enum shared by every node — this is the contract that makes the tree
composable:
public enum Status { Success, Failure, Running }
public abstract class Node
{
public abstract Status Tick(Blackboard bb, float dt);
public virtual void Reset() { } // called when a parent abandons this subtree
}
// Selector = fallback/OR: return the first child that is not Failure.
// `Current` (from Composite) remembers a Running child so the next tick resumes there.
public sealed class Selector : Composite
{
public override Status Tick(Blackboard bb, float dt)
{
for (; Current < Children.Count; Current++)
{
var s = Children[Current].Tick(bb, dt);
if (s == Status.Running) return Status.Running; // resume here next tick
if (s == Status.Success) { Current = 0; return Status.Success; }
}
Current = 0;
return Status.Failure; // every child failed
}
}
The reciprocal Sequence (AND — stop at first non-Success), the reactive variants that let a
higher-priority branch interrupt a running one, Parallel, the Blackboard, the leaf base
classes, and every decorator are in references/behavior-tree-core.md. The leaves use Unity's
Vector2 member names (magnitude, normalized, sqrMagnitude); in Godot C# use Length(),
Normalized() and LengthSquared().
Utility scoring in one snippet
// A consideration maps one raw fact to 0..1 through a response curve.
float Score(Blackboard bb)
{
float distance01 = Curves.InverseLerp01(bb.Get<float>("distToPlayer"), 20f, 2f); // near = 1
float health01 = Curves.Sigmoid(bb.Get<float>("health01"), k: 8f, mid: 0.4f); // hurt = low
// A 0 in any factor still vetoes the action; compensation stops each extra
// consideration from dragging every score toward 0. No allocation per call.
return Curves.Compensate(distance01 * health01, count: 2);
}
The full curve library (linear, quadratic, exponential, logistic/sigmoid, smoothstep), the
Consideration/UtilityAction types, and the UtilityEvaluator selection strategies are in
references/utility-ai-system.md.
Pitfalls
- Re-ticking a
Running action from the root every frame restarts it. Return Running and
resume where you left off; only Reset() a subtree when a parent actually abandons it.
- Deep trees re-evaluated wholesale each tick waste time and cause thrash. Prefer shallow
trees and conditional aborts (a higher-priority condition can interrupt a lower branch).
- A guard condition stops being checked once the action after it is
Running. A memory
Sequence resumes at the running child, so [CanSeePlayer?, Chase] keeps chasing after sight
is lost. Use a ReactiveSequence (re-checks from the first child each tick) or have the action
itself fail when its blackboard input disappears.
- A cooldown that clears on
Reset() lets an agent bypass it by flickering between branches.
Keep the ready-time when the branch is aborted.
- Un-normalized considerations. If one curve outputs 0..100 and another 0..1, the big one
dominates. Every consideration must return 0..1.
- Utility jitter on near-ties. Add hysteresis: give the currently-running action a small bonus
so the agent commits instead of oscillating.
- Allocating nodes, closures, or arrays every tick creates GC spikes. Build the tree once at
spawn; keep per-tick work allocation-free.
References
references/behavior-tree-core.md — Blackboard, Node/leaf base classes, action & condition
leaves, Sequence/Selector/Parallel, and the decorator library (full C#).
references/utility-ai-system.md — response-curve library, Consideration, UtilityAction,
and the UtilityEvaluator (argmax, softmax, weighted-random, hysteresis).
references/practical-examples.md — a guard Patrol→Combat BT, a villager needs-based Utility
AI, and a hybrid agent, as drop-in templates.
references/best-practices-and-pitfalls.md — memory management, profiling, avoiding deep trees,
event-driven aborts, and combining Utility AI with BTs (hybrid architecture).
Related skills
game-ai — choose between FSM / BT / steering; A* and navmesh pathfinding.
unreal-behavior-trees — Unreal's asset-based BT/Blackboard, tasks, decorators, services.
unity-navmesh — the NavMeshAgent that carries out "move to" intents.
physics-tuning — agent radius, movement, and collision response for the motion layer.
tower-defense, fps-shooter, rpg — genres that compose this decision layer.
1---2name: ai-behavior-trees-utility-ai3description: >4 Build a production behavior-tree runtime (Blackboard, action/condition leaves,5 sequence/selector/parallel composites, decorators) and a Utility AI system (response6 curves — linear, exponential, sigmoid, quadratic — considerations, and action evaluators),7 plus hybrid BT-drives-Utility agents. Use when implementing a reusable behavior-tree or8 utility-based decision system, or tuning enemy/NPC decisions beyond a simple FSM, or when9 the user mentions behavior tree, blackboard, decorator, selector, sequence, tick status,10 utility AI, response/scoring curve, or consideration. For choosing between FSM/BT/steering11 or for pathfinding, use game-ai; for Unreal's BehaviorTree/Blackboard assets, use12 unreal-behavior-trees.13metadata:14 source: https://skillmd.com/skills/junmystery/ai-behavior-trees-utility-ai15---1617# Behavior Trees & Utility AI1819Two complementary ways to structure NPC decision-making, plus how to combine them. A20**behavior tree (BT)** expresses *structured, prioritized, reactive* logic as a tree that is21"ticked" each step. **Utility AI** answers *"how much do I want each option right now?"* by22scoring actions with normalized curves and picking the best. Ship believable agents by using a23BT for structure and Utility AI where graded trade-offs matter.2425This skill is the **implementation** companion to `game-ai` (which helps you *choose* between26FSM / BT / steering / pathfinding). Read `game-ai` to pick a model; read this to build the27runtime.2829## When to use3031- Use to build a **reusable BT runtime**: a `Blackboard`, `Node` base, action/condition leaves,32 `Sequence`/`Selector`/`Parallel` composites, and decorators (Inverter, Cooldown, Repeat).33- Use to build a **Utility AI** decider: response curves, considerations, and an evaluator that34 scores and selects actions (max, softmax, or weighted-random for variety).35- Use to build **hybrid AI** — a BT whose leaf delegates the "which attack / which target"36 choice to a utility evaluator.3738**When *not* to use:** to *choose* between FSM, BT, steering, or pathfinding, and for A*/navmesh39routing, use `game-ai`. For Unreal's asset-based `BehaviorTree`/`Blackboard`, `BTTask`/`BTService`40and `AIController`, use `unreal-behavior-trees`. For the navmesh agent that *moves* the NPC, use41`unity-navmesh` or the engine's navigation node.4243## Core workflow44451. **Pick the model.** Structured, prioritized, interruptible behavior → **BT**. Continuous46 "score every option" decisions (targeting, needs, item choice) → **Utility**. Both → **hybrid**.472. **Design the Blackboard first.** One typed key/value store per agent is the shared memory that48 decouples nodes; leaves read/write it and never hold references to each other.493. **Write leaves.** *Conditions* return `Success`/`Failure` immediately; *actions* return50 `Running` across frames until they finish. Keep leaves small and side-effect-explicit.514. **Compose.** `Selector` = OR/fallback (first non-failure wins); `Sequence` = AND (stop at first52 non-success); `Parallel` for concurrent branches. Wrap with decorators for policy (invert,53 cooldown, repeat, force-success).545. **For Utility:** enumerate considerations, map each raw fact through a **normalized 0..1 curve**,55 combine (weighted product with compensation, or weighted sum), then select the max — add56 hysteresis so agents don't flip-flop on ties.576. **Tick deliberately.** Tick the tree/evaluator once per *decision step* (often slower than58 render). Preserve `Running` state between ticks; verify by drawing the active path and the59 per-action scores on screen while tuning.6061## Architecture at a glance6263A behavior tree evaluates top-down, left-to-right; each node returns a status up to its parent:6465```mermaid66flowchart TD67 Root["Selector (root)"] --> Combat["Sequence: Combat"]68 Root --> Patrol["Action: Patrol"]69 Combat --> See["Condition: CanSeePlayer?"]70 Combat --> InRange{"Selector: Reach"}71 Combat --> Attack["Action: Attack (Running)"]72 InRange --> Close["Condition: InAttackRange?"]73 InRange --> MoveTo["Action: MoveToPlayer (Running)"]74```7576Utility AI is a scoring pipeline — every candidate action is scored, then one is selected:7778```text79facts (distance, health, ammo…)80 │ each fact → a normalized 0..1 response curve (consideration)81 ▼82score(action) = weight · combine(consideration_1 … consideration_n) # product+compensation or sum83 ▼84select: argmax · or softmax / weighted-random for variety · + hysteresis to avoid jitter85```8687**Status is a three-value enum** shared by every node — this is the contract that makes the tree88composable:8990```csharp91public enum Status { Success, Failure, Running }9293public abstract class Node94{95 public abstract Status Tick(Blackboard bb, float dt);96 public virtual void Reset() { } // called when a parent abandons this subtree97}98```99100```csharp101// Selector = fallback/OR: return the first child that is not Failure.102// `Current` (from Composite) remembers a Running child so the next tick resumes there.103public sealed class Selector : Composite104{105 public override Status Tick(Blackboard bb, float dt)106 {107 for (; Current < Children.Count; Current++)108 {109 var s = Children[Current].Tick(bb, dt);110 if (s == Status.Running) return Status.Running; // resume here next tick111 if (s == Status.Success) { Current = 0; return Status.Success; }112 }113 Current = 0;114 return Status.Failure; // every child failed115 }116}117```118119The reciprocal `Sequence` (AND — stop at first non-`Success`), the reactive variants that let a120higher-priority branch interrupt a running one, `Parallel`, the `Blackboard`, the leaf base121classes, and every decorator are in `references/behavior-tree-core.md`. The leaves use Unity's122`Vector2` member names (`magnitude`, `normalized`, `sqrMagnitude`); in Godot C# use `Length()`,123`Normalized()` and `LengthSquared()`.124125## Utility scoring in one snippet126127```csharp128// A consideration maps one raw fact to 0..1 through a response curve.129float Score(Blackboard bb)130{131 float distance01 = Curves.InverseLerp01(bb.Get<float>("distToPlayer"), 20f, 2f); // near = 1132 float health01 = Curves.Sigmoid(bb.Get<float>("health01"), k: 8f, mid: 0.4f); // hurt = low133 // A 0 in any factor still vetoes the action; compensation stops each extra134 // consideration from dragging every score toward 0. No allocation per call.135 return Curves.Compensate(distance01 * health01, count: 2);136}137```138139The full curve library (linear, quadratic, exponential, logistic/sigmoid, smoothstep), the140`Consideration`/`UtilityAction` types, and the `UtilityEvaluator` selection strategies are in141`references/utility-ai-system.md`.142143## Pitfalls144145- **Re-ticking a `Running` action from the root every frame restarts it.** Return `Running` and146 resume where you left off; only `Reset()` a subtree when a parent actually abandons it.147- **Deep trees re-evaluated wholesale each tick** waste time and cause thrash. Prefer shallow148 trees and *conditional aborts* (a higher-priority condition can interrupt a lower branch).149- **A guard condition stops being checked once the action after it is `Running`.** A memory150 `Sequence` resumes at the running child, so `[CanSeePlayer?, Chase]` keeps chasing after sight151 is lost. Use a `ReactiveSequence` (re-checks from the first child each tick) or have the action152 itself fail when its blackboard input disappears.153- **A cooldown that clears on `Reset()`** lets an agent bypass it by flickering between branches.154 Keep the ready-time when the branch is aborted.155- **Un-normalized considerations.** If one curve outputs 0..100 and another 0..1, the big one156 dominates. Every consideration must return 0..1.157- **Utility jitter on near-ties.** Add hysteresis: give the currently-running action a small bonus158 so the agent commits instead of oscillating.159- **Allocating nodes, closures, or arrays every tick** creates GC spikes. Build the tree once at160 spawn; keep per-tick work allocation-free.161162## References163164- `references/behavior-tree-core.md` — Blackboard, `Node`/leaf base classes, action & condition165 leaves, `Sequence`/`Selector`/`Parallel`, and the decorator library (full C#).166- `references/utility-ai-system.md` — response-curve library, `Consideration`, `UtilityAction`,167 and the `UtilityEvaluator` (argmax, softmax, weighted-random, hysteresis).168- `references/practical-examples.md` — a guard Patrol→Combat BT, a villager needs-based Utility169 AI, and a hybrid agent, as drop-in templates.170- `references/best-practices-and-pitfalls.md` — memory management, profiling, avoiding deep trees,171 event-driven aborts, and combining Utility AI with BTs (hybrid architecture).172173## Related skills174175- `game-ai` — choose between FSM / BT / steering; A* and navmesh pathfinding.176- `unreal-behavior-trees` — Unreal's asset-based BT/Blackboard, tasks, decorators, services.177- `unity-navmesh` — the `NavMeshAgent` that carries out "move to" intents.178- `physics-tuning` — agent radius, movement, and collision response for the motion layer.179- `tower-defense`, `fps-shooter`, `rpg` — genres that compose this decision layer.