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/best-practices-and-pitfalls.md

View on GitHub
# Scaling and debugging: performance, memory, hybrid AI

How to keep a BT/Utility runtime fast, debuggable, and
maintainable at scale (dozens–hundreds of agents), and how to combine the two models well.

## Memory management

- **Build the tree once, at spawn — never per tick.** Node objects, delegates, and consideration
  lists are created during assembly and reused every tick. A tree rebuilt each frame is both a GC
  storm and a correctness bug (it discards `Running` state).
- **Keep `Tick` allocation-free.** No `new`, no LINQ (`Where`/`Select` allocate iterators), no
  closures capturing locals, no boxing. Pre-allocate scratch buffers; iterate with indexed `for`.
- **Prefer a struct-of-fields blackboard** (or `int`/enum keys) over a `Dictionary<string,object>`
  on hot agents — it removes hashing and value-type boxing. Keep the dictionary form for
  designer-authored or serialized boards.
- **Pool agents and their trees.** Reuse a despawned enemy's tree instance on respawn; call
  `Reset()` instead of reallocating.
- **Share immutable data.** Curves and static config are stateless — one instance serves every
  agent. Only per-agent mutable state (the blackboard, `Running` indices) is unique.

## Performance & profiling

- **Profile before optimizing.** Measure AI time in the engine profiler (Unity Profiler, Godot
  Monitors, Unreal `stat game`). The usual cost is not the tree walk — it is what the *leaves* do
  (raycasts, pathfinding, `FindObjectsByType`). Cache perception; pathfind on a timer, not per tick.
- **Tick on a decision cadence, not per frame.** 5–15 Hz is imperceptible for most NPCs and cuts
  cost 4–10×. Drive the tree from an accumulator that adds frame `dt` and ticks once it passes
  the decision interval, passing the accumulated time as the tree's `dt`.
- **Time-slice across frames.** Don't tick every agent on the same frame. Stagger by bucketing
  agents and ticking one bucket per frame, so the cost spreads instead of spiking.

```csharp
// Round-robin: only ~1/N of agents think each frame; the herd cost is flat, not a spike.
_bucket = (_bucket + 1) % Buckets;
for (int i = _bucket; i < agents.Count; i += Buckets)
    agents[i].Think(dt * Buckets);      // scale dt so per-agent cadence is unchanged
```

- **LOD your AI.** Distant or off-screen agents tick slower (or freeze). Tie the cadence to
  distance-from-camera; a guard 200 m away does not need 10 Hz decisions.
- **Utility cost scales with actions × considerations.** Don't score 40 actions × 8 considerations
  every tick. Prune obviously-irrelevant actions first (a cheap gate consideration that early-outs
  at 0), and re-score only when a relevant fact changed.

## Avoiding deep, brittle trees

- **Keep trees shallow and wide.** Deep nesting is hard to read and forces full re-evaluation.
  Factor repeated subtrees into named builder methods and reuse them.
- **Use conditional aborts / a reactive selector** so a high-priority condition (took damage, lost
  the player) interrupts a lower branch, instead of polling a deep tree for the change.
- **Prefer event-driven perception over polling.** Let sensors push `targetPos` onto the blackboard
  when they fire; the tree reads a cached fact instead of raycasting inside a condition every tick.
- **Cache condition results within a tick** if the same expensive check appears in multiple places.

## Combining Utility AI with behavior trees (hybrid)

The two models answer different questions — use each where it is strong:

| Use a **behavior tree** for… | Use **Utility AI** for… |
|---|---|
| Top-level structure & priorities (patrol / engage / flee) | "How much do I want each option right now?" |
| Ordered, interruptible sequences | Target selection, item/ability choice, needs |
| Clear, debuggable, designer-readable flow | Smooth trade-offs with many inputs |

Recommended default: **BT on the outside, Utility on the inside.** The BT decides *engage vs
disengage vs patrol*; a `UtilitySelectorNode` inside the engage branch decides *which target / which
attack*. Keep the utility set small and local to the branch so
scoring stays cheap, and give the running action hysteresis so the sub-choice doesn't flicker.

Avoid the inverse (utility choosing between whole behavior trees) unless you truly need graded
top-level behavior — it is harder to debug and easy to make thrash.

## Debugging

- **Draw the decision.** Overlay the active BT path (highlight the running leaf) and, for utility,
  a live bar per action score. Most "bad AI" bugs are visible instantly: a stuck `Running` leaf, an
  un-normalized consideration pinning one action to 1.0, or a mis-shaped curve.
- **Log transitions, not ticks.** Print only when the chosen action or active branch *changes*;
  per-tick logs bury the signal.
- **Make randomness reproducible.** Seed the `System.Random` used by softmax/weighted-random per
  agent so a misbehaving agent can be replayed. Never use a shared global RNG across agents.
- **Assert the `Reset()` contract.** A common bug is a `Running` action (`Wait`, `Repeat`, cover
  reservation) that isn't reset on completion or when its branch is abandoned. If timed actions
  "finish instantly" after re-entry, a missing `Reset()` is the cause.
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