# Swarm Brain benchmark

Measured 2026-09-22 on Apple M5 Max (arm64), Zig 0.16.0, `ReleaseFast`.

From `src/hikari`:

```sh
zig build ai-population-bench -Dgame-src=<absolute example/src> -Doptimize=fast --summary all
```

One run, 600 simulated 60 Hz frames per case, no warm-up exclusion. Compilation
is outside the timed interval. These are CPU microbenchmark results, not a game
frame-rate guarantee. Re-run locally when comparing changes.

| Members | Mean µs | p95 µs | Worst admitted decision lateness, ms | Last member to hear noise, ms | Oldest observation, ms |
|---:|---:|---:|---:|---:|---:|
| 100 | 7.52 | 7.71 | 16.67 | 83.33 | 83.33 |
| 1,000 | 62.10 | 75.13 | 83.33 | 133.33 | 516.67 |

Each case shares one code-authored Brain and admits at most 128 decisions,
128 perception steps and 32 rays per frame. All members must receive service and
the noise. Compact execution is 48 bytes per member, versus 560 bytes for the
full instance with local overrides and 16 history records. The complete benchmark
fixture reserves 889,992 bytes at capacity 1,000 in either case, including sensing,
positions, goals, bookkeeping and selected-member history.

The benchmark moves positions at decision admission, applies duration overrides,
and evaluates a noise transition. Visibility uses an always-clear analytic query
against an actor target. It excludes physics, event dispatch, scene gathering,
route planning, the sample's per-frame motor, rendering and GPU work.

The 1,000-member case deliberately puts every member in sight range. Its ray
budget cannot sustain a 10 Hz cycle for every member; observation age rises to
about half a second. A fixed budget bounds work by allowing latency to increase.
The runnable scene reports actual adapter costs and observation age separately.

A separate game-package test drives 1,000 actual swarm rows through the sample's
Brain and route/movement loop, checks the eight-route-plan budget, delivers noise,
and retires/reuses a slot without inheriting execution, route or selected history.
See [Swarm AI](/docs/guides/swarm-ai.md) for the playable acceptance test.