axiom-ai

Boids

Flocking birds from three simple rules, with predators and obstacles.

Build log

Status

Not started. This log is written by Claude Code during the cloud session that builds the demo, then lightly edited.

The brief

The prompt the session received, verbatim, and a link to the cloud session and PR.

Approach

What was chosen and why. Alternatives considered. Anything reused from open source, with license and link.

Timeline

Short dated entries as the work progressed: what was tried, what broke, what fixed it.

Numbers

Rough wall-clock time, number of turns, tokens or cost if known, bundle size, frames per second on a laptop and a phone.

What I would do next

Known gaps, stretch goals, ideas.

Original spec

Boids

Build a flocking simulation in projects/boids/demo/index.ts following the demo contract in CLAUDE.md.

Goal

A visually striking, smooth flocking demo that lets a visitor feel how three local rules produce global behaviour, and that scales far enough to be impressive on a laptop.

Must have

  • Canvas 2D rendering, full-size inside the container, HiDPI aware, ResizeObserver for resizes.
  • Boids implemented with Reynolds’ three rules: separation, alignment, cohesion. Each has a slider for weight and perception radius.
  • A spatial hash (uniform grid) for neighbour lookup so 5,000 boids run at 60 fps on a mid-range laptop. Default count 1,500 on desktop, 400 on phones (detect by matchMedia('(pointer: coarse)') or width).
  • Boid count slider (100 to 20,000). Show live fps and count in the controls bar.
  • Predators: a toggle adds 1 to 5 predators that chase the nearest boid; boids flee predators within a radius.
  • Obstacles: click or tap to place circular obstacles; boids steer around them. A “clear” button.
  • Mouse or touch attract/repel: hold pointer to attract, hold with shift (or a toggle) to repel.
  • Wrap-around world edges, with an option to switch to bounded (soft wall avoidance).
  • Pause, reset, and a “randomise rules” button that picks a plausible preset (tight flock, loose swarm, schooling).
  • Rendering: boids drawn as small triangles oriented to velocity; colour by heading or by local density (toggle). Predators drawn distinctly.

Should have

  • Trails option (fade the canvas each frame instead of clearing).
  • Three or four named presets selectable from a dropdown.

Stretch

  • WebGPU compute path for 100k boids, selected automatically when navigator.gpu exists, with the Canvas 2D path as fallback. Only attempt after everything above is done and committed.

Reference material

  • Daniel Shiffman, The Nature of Code, chapter on autonomous agents and flocking (MIT licensed examples at github.com/nature-of-code). Reuse ideas, write your own code.
  • Craig Reynolds’ original boids page for the rule definitions.

Acceptance

  • npm run check and npm run build pass.
  • 5,000 boids with predators and obstacles at 60 fps on a laptop (log measured numbers in BUILD-LOG.md).
  • Works on a phone in portrait with touch controls.
  • project.json status set to live, BUILD-LOG.md complete per CLAUDE.md.