gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/ai-behavior-trees-utility-ai
ai-behavior-trees-utility-ai
VerifiedEngine-neutral behavior tree and utility AI code for NPCs in any language: Blackboard, reactive composites, decorators and response-curve scoring. Use when an enemy keeps chasing after losing sight, restarts its action every frame or flip-flops between choices. Not for FSMs, steering or pathfinding (`game-ai`) or Unreal BT, EQS and StateTree (`unreal-behavior-trees`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.1 KB |
| references/behavior-tree-core.md | markdown | 18.2 KB |
| references/best-practices-and-pitfalls.md | markdown | 5.1 KB |
| references/practical-examples.md | markdown | 8.1 KB |
| references/utility-ai-system.md | markdown | 9.3 KB |
references/behavior-tree-core.md
View on GitHub# Behavior Tree core: Blackboard, nodes, leaves, composites, decorators
Contents:
1. Blackboard (dictionary and fields variants)
2. Node base and the `Reset()` contract
3. Base classes: leaf, composite, decorator
4. Condition leaves
5. Action leaves (`MoveToTarget`, `Wait`)
6. Composites: `Sequence`, `Selector`, `ReactiveSelector`, `ReactiveSequence`, `Parallel`
7. Decorators: `Inverter`, `ForceSuccess`, `Repeat`, `Cooldown`
8. Running the tree (`BehaviorTree`, fluent assembly)
A complete, allocation-conscious C# behavior-tree
runtime. The tree logic is plain C# with no engine types; the example leaves use a `Vector2` with
Unity's member names (`magnitude`, `normalized`, `sqrMagnitude`), so they compile as-is in
Unity 6. In Godot 4 C# the same leaves need `Length()`, `Normalized()` and `LengthSquared()`;
outside an engine, `System.Numerics.Vector2` has `Length()`, `LengthSquared()` and
`Vector2.Normalize(v)`. Bind the leaves to your engine's transform/navigation in the concrete
actions.
Contract in one line: every node's `Tick` returns `Success`, `Failure`, or `Running`, and a
parent decides what that means. Build the tree once at spawn; keep per-tick work allocation-free.
## Blackboard — the shared state system
The **Blackboard** is the agent's working memory. Leaves read and write it; no node holds a
reference to another. That indirection is what lets the same `MoveTo` action serve chase, patrol,
and flee subtrees, and what makes subtrees reusable across enemy types.
```csharp
using System.Collections.Generic;
// A typed key/value store. Keys are strings (or use enum/int keys to avoid hashing cost).
public sealed class Blackboard
{
private readonly Dictionary<string, object> _values = new();
public void Set<T>(string key, T value) => _values[key] = value!;
public T Get<T>(string key, T fallback = default!)
=> _values.TryGetValue(key, out var v) && v is T t ? t : fallback;
public bool TryGet<T>(string key, out T value)
{
if (_values.TryGetValue(key, out var v) && v is T t) { value = t; return true; }
value = default!;
return false;
}
public bool Has(string key) => _values.ContainsKey(key);
public void Remove(string key) => _values.Remove(key);
}
```
For hot agents, prefer a **struct-of-fields blackboard** (public fields on a class) over a string
dictionary — it removes hashing and boxing entirely. Use the dictionary form when designers add
keys at runtime or you serialize the board.
```csharp
// Zero-allocation alternative: a plain data object shared by every node on this agent.
public sealed class AgentContext
{
public Vector2 Position;
public Transform Target; // null when no target
public Vector2 Home;
public float LastSeenTime;
public readonly List<Vector2> Path = new();
}
```
## The node base and status
```csharp
public enum Status { Success, Failure, Running }
// Every node in the tree derives from Node. dt is the decision-step delta (may differ from frame dt).
public abstract class Node
{
public abstract Status Tick(Blackboard bb, float dt);
// Parents reset terminal children and aborted branches; BehaviorTree does so for the root.
// Clear execution-local state and release reservations. Repeated resets must be harmless.
public virtual void Reset() { }
}
```
Parents call `Reset()` immediately after a child returns `Success` or `Failure`, and when they
abandon a `Running` branch. The root follows the same rule in `BehaviorTree`. Reset must be
idempotent: an ancestor may reset an already-clean child again. Clear execution-local state
(timers, animations, reservations), while retaining persistent state such as a cooldown deadline.
Code that ticks a node directly takes on this parent responsibility.
## Base classes: leaf, composite, decorator
Three structural node kinds cover every tree:
```csharp
// A leaf does the actual work; it has no children.
public abstract class Leaf : Node { }
// A composite has many children and defines how their statuses combine (see Composites below).
public abstract class Composite : Node
{
protected readonly List<Node> Children = new();
protected int Current; // resume index for Running composites
public Composite Add(Node child) { Children.Add(child); return this; }
public override void Reset()
{
Current = 0;
foreach (var c in Children) c.Reset();
}
}
// A decorator wraps exactly one child and transforms its status or gates it (see Decorators below).
public abstract class Decorator : Node
{
protected Node Child = default!;
public Decorator Wrap(Node child) { Child = child; return this; }
public override void Reset() => Child.Reset();
}
```
## Condition leaves — instantaneous predicates
A **condition** reads the blackboard and returns `Success` or `Failure` in the same tick. It never
returns `Running` and never mutates game state. Express reusable predicates as one small class with
an injected test, or subclass for named conditions.
```csharp
// Generic condition: succeed when a predicate over the blackboard holds.
public sealed class Condition : Leaf
{
private readonly System.Func<Blackboard, bool> _predicate;
public Condition(System.Func<Blackboard, bool> predicate) => _predicate = predicate;
public override Status Tick(Blackboard bb, float dt)
=> _predicate(bb) ? Status.Success : Status.Failure;
}
// Named condition when the check is non-trivial or reused across trees.
public sealed class CanSeeTarget : Leaf
{
private readonly float _sightRange;
public CanSeeTarget(float sightRange) => _sightRange = sightRange;
public override Status Tick(Blackboard bb, float dt)
{
if (!bb.TryGet<Vector2>("targetPos", out var target)) return Status.Failure;
var self = bb.Get<Vector2>("position");
// Real games also raycast for line of sight; keep the check cheap and cache the result.
return (target - self).sqrMagnitude <= _sightRange * _sightRange
? Status.Success : Status.Failure;
}
}
```
Note the pre-allocated `System.Func` delegate: create conditions **once** when the tree is built,
not per tick, so no closure is allocated during evaluation.
## Action leaves — multi-frame work that returns Running
An **action** performs work and returns `Running` until it completes, then `Success` (or `Failure`
if it can't). Returning `Running` is what lets a walk, an animation, or a timed wait span many
ticks without the parent restarting it.
```csharp
// Move toward a blackboard target; Running until within arrive radius, then Success.
public sealed class MoveToTarget : Leaf
{
private readonly float _speed, _arriveRadius;
public MoveToTarget(float speed, float arriveRadius)
{ _speed = speed; _arriveRadius = arriveRadius; }
public override Status Tick(Blackboard bb, float dt)
{
if (!bb.TryGet<Vector2>("targetPos", out var target)) return Status.Failure;
var pos = bb.Get<Vector2>("position");
var offset = target - pos;
if (offset.magnitude <= _arriveRadius) return Status.Success; // arrived
pos += offset.normalized * _speed * dt;
bb.Set("position", pos); // in an engine, drive the NavMeshAgent / CharacterBody here
return Status.Running; // keep going next tick
}
}
// A timed wait — the canonical Running action, useful for patrol pauses and cooldown holds.
public sealed class Wait : Leaf
{
private readonly float _duration;
private float _elapsed;
public Wait(float duration) => _duration = duration;
public override Status Tick(Blackboard bb, float dt)
{
_elapsed += dt;
if (_elapsed < _duration) return Status.Running;
return Status.Success;
}
public override void Reset() => _elapsed = 0f; // restart cleanly if the branch is re-entered
}
```
`Wait` shows why `Reset()` matters: its `_elapsed` accumulator must be cleared on completion or
abort, or the second execution finishes instantly.
The `Sequence`/`Selector`/`Parallel` execution logic and the decorator library build directly on
these base classes — see the composites and decorators sections below.
## Composites — how child statuses combine
Composites are the control flow of a tree. The two you use constantly are `Sequence` (AND) and
`Selector` (OR/fallback); `Parallel` covers concurrent branches.
```csharp
// Sequence = AND: tick children in order; stop at the first that is not Success.
// Resumes at the Running child next tick ("memory" variant).
public sealed class Sequence : 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
Children[Current].Reset(); // ready for its next execution
if (s == Status.Failure) { Current = 0; return Status.Failure; }
}
Current = 0;
return Status.Success; // every child succeeded
}
}
// Selector = OR / fallback: return the first child that is not Failure.
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
Children[Current].Reset();
if (s == Status.Success) { Current = 0; return Status.Success; }
}
Current = 0;
return Status.Failure; // every child failed
}
}
```
**Memory vs reactive.** The versions above *remember* the `Running` child and resume there. That is
efficient but does not let a higher-priority sibling interrupt. For a **reactive** selector — the
common case for combat AI — re-check children from index 0 every tick and abort the running branch
when an earlier child changes its mind:
```csharp
// Reactive selector: earlier (higher-priority) children can preempt a lower running branch.
public sealed class ReactiveSelector : Composite
{
private int _running = -1;
public override Status Tick(Blackboard bb, float dt)
{
for (int i = 0; i < Children.Count; i++)
{
var s = Children[i].Tick(bb, dt);
if (s != Status.Running) Children[i].Reset();
if (s == Status.Failure) continue;
if (_running != -1 && _running != i) Children[_running].Reset(); // abort old branch
_running = s == Status.Running ? i : -1;
return s; // Success or Running
}
_running = -1;
return Status.Failure;
}
public override void Reset() { base.Reset(); _running = -1; }
}
```
The reactive selector re-ticks its *children* from index 0, but a memory `Sequence` child still
resumes at its own running action, so the condition at the front of that sequence is not
re-checked while the action runs. When a condition must keep guarding a running action ("chase
only while I can see the player"), use a **reactive sequence**:
```csharp
// Reactive sequence: re-checks every child from index 0 each tick. If an earlier child stops
// succeeding, the later Running child is aborted with Reset(). Put only conditions (or cheap,
// repeatable actions) in front of the long-running child.
public sealed class ReactiveSequence : Composite
{
private int _running = -1;
public override Status Tick(Blackboard bb, float dt)
{
for (int i = 0; i < Children.Count; i++)
{
var s = Children[i].Tick(bb, dt);
if (s != Status.Running) Children[i].Reset();
if (s == Status.Success) continue;
if (_running > i) Children[_running].Reset(); // an earlier child stopped us
_running = s == Status.Running ? i : -1;
return s; // Failure or Running
}
_running = -1;
return Status.Success;
}
public override void Reset() { base.Reset(); _running = -1; }
}
```
`Parallel` ticks every unfinished child each step and resolves with a policy — succeed when *any*
(or *all*) succeed, fail when *any* (or *all*) fail. Use it for "attack while strafing" or "play
VFX while moving". It must remember which children already finished: re-ticking a child that
succeeded restarts it, and `RequireAll` would then never see every child succeed on the same tick.
```csharp
public enum ParallelPolicy { RequireOne, RequireAll }
public sealed class Parallel : Composite
{
private readonly ParallelPolicy _success, _failure;
private Status[] _results = System.Array.Empty<Status>(); // per-child result; Running = unfinished
public Parallel(ParallelPolicy success, ParallelPolicy failure)
{ _success = success; _failure = failure; }
public override Status Tick(Blackboard bb, float dt)
{
int n = Children.Count;
if (_results.Length != n) // first tick (or children changed)
{
_results = new Status[n];
System.Array.Fill(_results, Status.Running);
}
int successes = 0, failures = 0;
for (int i = 0; i < n; i++)
{
if (_results[i] == Status.Running)
{
_results[i] = Children[i].Tick(bb, dt);
if (_results[i] != Status.Running) Children[i].Reset();
}
if (_results[i] == Status.Success) successes++;
else if (_results[i] == Status.Failure) failures++;
}
var outcome = Status.Running;
if ((_failure == ParallelPolicy.RequireOne && failures > 0) ||
(_failure == ParallelPolicy.RequireAll && failures == n)) outcome = Status.Failure;
else if ((_success == ParallelPolicy.RequireOne && successes > 0) ||
(_success == ParallelPolicy.RequireAll && successes == n)) outcome = Status.Success;
else if (successes + failures == n) outcome = Status.Failure; // all done, no policy met
if (outcome != Status.Running) Reset(); // stop children still running, clear the record
return outcome;
}
public override void Reset()
{
base.Reset(); // resets every child
System.Array.Fill(_results, Status.Running);
}
}
```
## Decorators — wrap one child to change its meaning
Decorators add policy without new leaves: invert a result, force a status, gate on a cooldown, or
repeat. Each wraps exactly one child.
```csharp
// Inverter: Success <-> Failure (Running passes through). "NOT".
public sealed class Inverter : Decorator
{
public override Status Tick(Blackboard bb, float dt)
{
var s = Child.Tick(bb, dt);
if (s != Status.Running) Child.Reset();
return s switch
{
Status.Success => Status.Failure,
Status.Failure => Status.Success,
_ => Status.Running,
};
}
}
// ForceSuccess: swallow a child's failure so a Sequence keeps going (optional steps).
public sealed class ForceSuccess : Decorator
{
public override Status Tick(Blackboard bb, float dt)
{
var s = Child.Tick(bb, dt);
if (s != Status.Running) Child.Reset();
return s == Status.Running ? Status.Running : Status.Success;
}
}
// Repeat: run the child up to n times (n <= 0 = forever), restarting on each Success.
public sealed class Repeat : Decorator
{
private readonly int _count;
private int _done;
public Repeat(int count) => _count = count;
public override Status Tick(Blackboard bb, float dt)
{
var s = Child.Tick(bb, dt);
if (s == Status.Running) return Status.Running;
Child.Reset(); // includes failure and the final repetition
if (s == Status.Failure) { _done = 0; return Status.Failure; }
_done++;
if (_count > 0 && _done >= _count) { _done = 0; return Status.Success; }
return Status.Running;
}
public override void Reset() { base.Reset(); _done = 0; }
}
// Cooldown: gate the child so it can only run once per interval (attack/ability rate-limiting).
// No Reset() override on purpose: aborting the branch must not clear the cooldown, or an agent
// that flickers between branches attacks every time it re-enters.
public sealed class Cooldown : Decorator
{
private readonly float _seconds;
private float _readyAt;
public Cooldown(float seconds) => _seconds = seconds;
public override Status Tick(Blackboard bb, float dt)
{
float now = bb.Get<float>("time");
if (now < _readyAt) return Status.Failure; // still cooling down
var s = Child.Tick(bb, dt);
if (s != Status.Running) Child.Reset();
if (s == Status.Success) _readyAt = now + _seconds;
return s;
}
}
```
## Running the tree
Wrap the root and tick it on your decision cadence. A behavior tree does **not** need to tick every
render frame — 5–15 Hz is plenty for most NPCs and slashes CPU cost.
```csharp
public sealed class BehaviorTree
{
private readonly Node _root;
private readonly Blackboard _bb;
public BehaviorTree(Node root, Blackboard bb) { _root = root; _bb = bb; }
public Status Tick(float dt)
{
_bb.Set("time", _bb.Get<float>("time") + dt); // keep a clock for Cooldown/Wait
var s = _root.Tick(_bb, dt);
if (s != Status.Running) _root.Reset();
return s;
}
}
// Fluent assembly — build once at spawn, then tick.
var tree = new BehaviorTree(
new ReactiveSelector()
.Add(new ReactiveSequence() // combat branch (highest priority)
.Add(new CanSeeTarget(sightRange: 12f)) // re-checked every tick
.Add(new MoveToTarget(speed: 6f, arriveRadius: 1.5f))
// ForceSuccess: while the cooldown blocks the swing, the guard holds position
// instead of failing the branch and stepping back into Patrol for a tick.
.Add(new ForceSuccess().Wrap(new Cooldown(0.8f).Wrap(new AttackTarget()))))
.Add(new Patrol(waypoints)), // fallback
blackboard);
```
`Patrol` and `AttackTarget` are game-specific leaves; the skill's guard example defines both.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |