gamedev-skills/awesome-gamedev-agent-skills

ai-behavior-trees-utility-ai

Engine-neutral behavior tree and utility AI code for NPCs in any language: Blackboard, reactive composites, decorators and response-curve scoring.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill ai-behavior-trees-utility-ai

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Behavior trees and Utility AI

A behavior tree (BT) gives an agent ordered, interruptible priorities; Utility AI scores every option and picks the most wanted one. The code is plain C# so it ports to any engine; the non-obvious part is the lifecycle contract (who resets what, and when), which is where almost every BT bug lives.

When to use

  • Build or fix a reusable BT runtime: Blackboard, leaves, composites, decorators.
  • Build a utility decider: curves, considerations, a selector with hysteresis.
  • Combine them: a BT branch that hands a graded choice (which attack, which target) to utility.

Not this skill: choosing FSM vs BT, steering, A*, flow fields and perception belong to game-ai. Unreal's BehaviorTree/Blackboard assets, BTTask/BTService, EQS and StateTree belong to unreal-behavior-trees. The agent that physically moves (NavMeshAgent, NavigationAgent3D) belongs to the engine navigation skill.

Workflow

  1. Read what exists. Find the current AI code, its tick site and how it reads the world. If

the project already ships a BT plugin (Godot LimboAI or Beehave, Unity Behavior, NodeCanvas), extend it instead of adding a second runtime.

  1. Pick the default shape: BT outside, utility inside. The BT decides engage, flee or patrol;

a utility node inside the engage branch picks how. Use utility at the top only when every top-level behavior is a graded trade-off (needs-driven villagers), because it is harder to debug and prone to thrashing.

  1. Design the Blackboard first. Perception writes facts (targetPos, health01,

distToPlayer); leaves read them. Nodes never hold references to each other.

  1. Choose memory or reactive per composite. Priority selectors at the top are reactive so

a higher branch can preempt; a Sequence whose first child is a guard condition must be a ReactiveSequence, or the guard stops being checked once the action runs.

  1. Normalize every utility input to 0..1 through a curve before combining; multiply with

compensation so a 0 still vetoes.

  1. Tick on a decision cadence (5-15 Hz for most NPCs) from an accumulator, staggered across

agents. Movement and animation still run every frame.

  1. Prove it with a headless tick test (below): script the Blackboard, tick N times and

assert the status sequence and reset counts. Then draw the running leaf and per-action scores on screen while tuning.

The lifecycle contract

Every node returns Success, Failure or Running. Parents reset a child as soon as it returns a terminal status and when they abandon it while Running; the tree resets a terminal root. Reset() must be idempotent and must clear only execution-local state (timers, reservations), never persistent state such as a cooldown deadline.

csharp
// 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
            Children[Current].Reset();                                // terminal child can re-enter cleanly
            if (s == Status.Success) { Current = 0; return Status.Success; }
        }
        Current = 0;
        return Status.Failure;                                         // every child failed
    }
}

This is the memory variant: it cannot be preempted. Sequence, ReactiveSelector, ReactiveSequence, Parallel, the decorators and BehaviorTree follow the same contract in references/behavior-tree-core.md.

Utility scoring in one snippet

csharp
// 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);
}

Selection: argmax with an inertia bonus of about 0.05 for the running action is the default; softmax (temperature about 0.2) when designers want variety without silly picks.

Headless tick test

Run this shape in the project's test runner (Unity Test Framework, GdUnit4, xUnit) before tuning by eye; Assert stands for the framework's assertion. A probe leaf counts ticks and resets, so lifecycle bugs show up as numbers.

csharp
sealed class Probe : Leaf
{
    public int Ticks, Resets; readonly int _after; readonly Status _end;
    public Probe(int after, Status end = Status.Success) { _after = after; _end = end; }
    public override Status Tick(Blackboard bb, float dt) => ++Ticks >= _after ? _end : Status.Running;
    public override void Reset() { Ticks = 0; Resets++; }
}
// Guard lost mid-action: the running action must be aborted, not resumed.
var bb = new Blackboard(); var chase = new Probe(after: 3);
var seq = new ReactiveSequence().Add(new Condition(b => b.Get<bool>("sees"))).Add(chase);
bb.Set("sees", true);  Assert(seq.Tick(bb, 0.1f) == Status.Running);
bb.Set("sees", false); Assert(seq.Tick(bb, 0.1f) == Status.Failure && chase.Ticks == 0);

Cover at least: a Wait that runs twice in a row takes full time both runs; a lost guard aborts its action; a cooldown still blocks after its branch is aborted; utility returns null (and the caller copes) when every action scores 0.

Gotchas

  • Guard not re-checked. A memory Sequence resumes at its running child, so

[CanSeePlayer?, Chase] chases forever after sight is lost. Use ReactiveSequence, or make the action fail when its Blackboard input disappears.

  • Priority never preempts. A memory Selector at the root keeps resuming a running Patrol

and never re-asks Attack. Top-level priority selectors are reactive, and they must Reset() the branch they abandon or its move or animation keeps running.

  • Timed actions finish instantly the second time. Wait/Repeat accumulators were not

cleared because the parent skipped Reset() on a terminal child.

  • Cooldown bypass. A Cooldown that clears its ready-time in Reset() lets an agent attack

every time it flickers between branches. Keep the deadline across resets.

  • `Parallel` restarts finished children. Re-ticking a child that already succeeded restarts

it, and RequireAll then never sees all children succeed on one tick. Store per-child results.

  • Cooldown inside a `Sequence` makes the agent step back to patrol for a tick each time it is

blocked. Wrap it in ForceSuccess when "wait for the cooldown" should hold the branch.

  • Mixed ranges. One consideration in 0..100 next to others in 0..1 dominates and makes

weights meaningless. Clamp every curve output to 0..1.

  • Plain products sink with more considerations. Five factors of 0.8 give 0.33. Apply the

compensation factor (Curves.Compensate), which keeps an exact 0 as a veto.

  • Inertia revives a vetoed action. Add the hysteresis bonus only to positive raw scores.
  • Softmax overflows at small temperatures (exp(score / 0.01) is infinity in float). Subtract

the best score before exp.

  • GC spikes. Build the tree once at spawn; Tick allocates nothing (no LINQ, no closures

capturing locals, no boxing in hot Blackboards). Use a fields class instead of a Dictionary<string, object> for agents that tick often.

  • Cost lives in the leaves. Raycasts and path queries inside conditions dominate CPU; let

perception cache facts on the Blackboard and pathfind on a timer.

References

  • references/behavior-tree-core.md: read when writing or reviewing the runtime itself

(Blackboard, base classes, every composite including the reactive ones, Parallel, decorators, BehaviorTree).

  • references/utility-ai-system.md: read when building the scorer (curve library,

compensation, Consideration, UtilityAction, argmax and softmax selection).

  • references/practical-examples.md: read when you need a full agent to adapt (guard

Patrol/Combat BT, needs-driven villager, hybrid UtilitySelectorNode).

  • references/best-practices-and-pitfalls.md: read when scaling to many agents or debugging

(time-slicing, AI LOD, event-driven aborts, debug overlays, reproducible randomness).

Related skills

  • game-ai: decision-model choice, FSMs, steering, pathfinding, perception.
  • unreal-behavior-trees: Unreal's asset-based BT, Blackboard, EQS and StateTree.
  • unity-navmesh: the NavMeshAgent that carries out "move to" intents.

Version notes

Last verified: 2026-11-11.

  • The C# compiles with no engine types. Example leaves use Unity 6 Vector2 member names

(magnitude, normalized, sqrMagnitude); Godot 4 C# uses Length(), Normalized(), LengthSquared(); System.Numerics.Vector2 uses Length() and Vector2.Normalize(v).

  • The repository test tests/test_ai_examples.py compiles the published blocks with the .NET 10

SDK and runs the lifecycle scenarios.

  • BT plugins worth extending instead of replacing (latest releases at check): Unity Behavior

com.unity.behavior 1.0.17, LimboAI 1.8.1 and Beehave 2.9.3 for Godot.

  • Sources: compensation factor from Dave Mark and Mike Lewis, "Building a Better Centaur: AI at

Massive Scale", GDC 2015 AI Summit (https://www.gdcvault.com/play/1021848); Unity package registry (https://packages.unity.com/com.unity.behavior); GitHub releases of limbonaut/limboai and bitbrain/beehave.

from this repository

More skills

All skills
gamedev-skills
Community

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

24h installs
433
GitHub stars
10K
Updated
Nov 12
gamedev-skills
Community

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

24h installs
431
GitHub stars
10K
Updated
Nov 12
gamedev-skills
Community

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

24h installs
365
GitHub stars
10K
Updated
Nov 12
gamedev-skills
Community

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

24h installs
360
GitHub stars
10K
Updated
Nov 12