Feature Library

Ambient GPU swarms

0.21 GPU · 0.27 CPU ms
A still of the Ambient GPU swarms demo
Still
The live demo starts when it’s in view.Move the cursor to repel flyers · drag to orbit · scroll to zoom · Scatter is the keyboard equivalent

Flies over a pond, fireflies at dusk, a starling murmuration and long-gliding gulls: nine kinds of small flyers with their own shapes and flight patterns.

Stochastic flocking samples six or twelve neighbours per flyer, so work grows linearly with the population. One compute dispatch and one instanced draw per moving swarm; homes, threats, wind and an optional coast stencil are the only inputs from the host.

What it costs a frame

0.21 ms
0.27 ms
GPU
0.21 ms
CPU, median
0.27 ms
CPU, 95th pct
0.43 ms
Draw calls
8
Compute passes
4
Weight
Light

Measured 19 November 2026 on RTX 4060 Laptop, 13th Gen Intel(R) Core(TM) i9-13900H, Chrome 157, 1920×1080 at 1×. 600 frames × 3 rounds, median kept (rounds ranged GPU 0.21–0.22, CPU 0.27–0.28 ms). What ran: Four active kinds: 9,000 starlings, 400 flies, 300 fireflies and 12 gulls at high tier. One compute and one swarm draw per active kind, plus a static pond and reeds. The pointer is idle. No readback. The demo rests after 30 seconds; benchmark mode keeps it moving. Phones: tiers are being measured next.

How steadily it runs on RTX 4060 Laptop · 13th Gen Intel(R) Core(TM) i9-13900H · reference

Typical frame ?
3.52 ms
1% low ?
152 fps
Varies by ?
±0.88 ms
All metricsRTX 4060 Laptop · 13th Gen Intel(R) Core(TM) i9-13900H · reference
p50p95p990.14 ms6.57 ms +
How long each frame took. Most frames sit in the tall bars; a long tail to the right is hitching.

Frames run back to back, each starting once the GPU has finished the last, so frame times show the work itself. They have a floor of about 4–5 ms from the browser’s own scheduling: GPU and CPU ms stay the measure of cost.

Frames

Median (p50) ?
3.52 ms
p95 ?
5.39 ms
p99 ?
6.17 ms
Slowest ?
7.05 ms
Mean ?
3.77 ms
Standard deviation ?
0.88 ms
1% low ?
152 fps
0.1% low ?
142 fps
Hitches ?
1 of 600
Over budget ?
0 of 600

Main thread

Long tasks ?
0
Long frames ?
0
Event-loop delay ?
0.0 / 0.7 / 0.7 ms

Input

No input during this run.

Memory

JavaScript heap ?
59.1 → 53.3 MB
Growth ?
-5.80 MB

Browser

JavaScript a frame ?
0.01 ms
All tasks a frame ?
0.48 ms
Layout / style ?
0.00 / 0.00 ms
Main thread busy ?
13%

Garbage collection

Collections ?
1 (1 minor, 0 major)
Pauses ?
1.0 ms in all, longest 1.0

What it needs

Renders with
WebGPUNeeds WebGPU: current Chrome and Edge, Safari 26+, Firefox 141+ on Windows.
Your browser
Checking…Looking for WebGPU
Depends on
three.js 0.187.0No other packages
With an agent
install("ambient-swarms")Your coding agent reads its pitfalls and installs it through the library’s MCP server. Set it up

What it’s for

  1. Ambient birds and insects in a landscape
  2. A murmuration responding to a cursor
  3. Fireflies around a moving focus
  4. Several patches of flies in one draw
  5. Gulls constrained to a supplied shoreline

Pitfalls, in brief

  1. The demo needs WebGPU for compute and storage buffers.
  2. Add the mesh without transforming it: positions, homes, targets and threats are already world-space, Y-up, metres.
  3. Each active swarm submits one compute dispatch and one instanced draw, not constant total cost: six (game) or twelve (stage) sampled neighbours per flyer make generic flocking O(count).
  4. The two banks prevent neighbours from reading partially updated positions.
  5. Kind, count, homes, quality and target allocation are construction choices. setKnobs changes only live numeric/colour controls; rebuild to change count or species.
5 more in brief
  1. Call update before drawing, once per moving frame. dt is seconds, capped at 1/30 to keep the simulation stable after a stall.
  2. Gulls stay hidden until setCoast supplies a valid 64×64 RGBA float stencil and homes. buildCoastPatch samples the host only when called; CoastPatchBuild accepts an optional host deadline for incremental rebuilding.
  3. Coast heights are constant cell floors, not collision geometry.
  4. A threat is xyz plus a radius multiplier in w (zero disables it).
  5. Visibility help caps enlargement at twice the authored wingspan.
10 pitfalls in full, the hook-up guide, the module source and its tests come with the part.

Where it comes from

From HaTac. Adapted from published work, named below.

Hannes Andersson: The source flocking, species shapes, flight patterns and coast residency stencil.

Craig Reynolds, Flocks, Herds, and Schools (1987): Separation, alignment and cohesion; the source approximates neighbours with a fixed number of random samples.

Jarzynski and Olano, Hash Functions for GPU Rendering (2020): PCG hash supplied by three TSL; used for placement and neighbour selection.

swarmflockingbirdsinsectsfirefliesgullsstarlingsambientcomputeinstancingtslreduced motionno readback

Near it in the frame