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/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.
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 |