Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/ai-behavior-trees-utility-ai

ai-behavior-trees-utility-ai

Verified

Engine-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`).

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.
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 implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall