Formicary

A living ant world in the browser. Colonies forage by laying and reading pheromone trails, rear brood from the food they bring home, dig their nests out of the earth, fight neighbours over ground, and — left alone — send out queens that found daughter colonies, so the population of species drifts and competes over generations.

It is a simulation first and a toy second: the things that look designed mostly aren't. There is no script that says "build a trail" or "win the war" — those fall out of a few thousand ants each following local rules.

What's actually simulated

• Honest stigmergy. Ants don't know where home is. Outbound they lay a home trail and follow the food trail; returning they navigate by path integration (dead reckoning) plus the trail. Highways, shortcuts and detours emerge; none are hard-coded.
• Colony lifecycle. A queen lays eggs from surplus food; eggs become larvae, pupae, then adult workers/scouts/soldiers. Population is a consequence of the food balance, not a slider. Starve the larder and the colony dwindles.
• Terrain & digging. Elevation and moisture shape movement and the look of the ground. Colonies must excavate chambers to raise their brood capacity, so a colony literally digs its way to a larger population.
• Conflict. Enemy ants fight; the wounded raise an alarm pheromone that rallies soldiers; raiders plunder rival larders and can kill an enemy queen, ending a colony. Aggression and caste ratios are genetic, so outcomes vary.
• Evolution. Strong, wealthy colonies launch founding queens with mutated genomes. Selection (famine, war) culls the unfit; lineages drift apart into distinct species over time.

Architecture

• lib/engine/ — framework-agnostic, deterministic simulation. Structure-of- arrays agent store (agents.ts), a single ScalarField primitive behind all pheromone/terrain fields, a seedable RNG so a seed reproduces a whole run, and a fixed-timestep world.step().
• lib/render/ — a WebGL2 renderer: instanced ant sprites drawn by an SDF, pheromone/terrain/excavation fields as textures, and a pan/zoom camera.
• components/Formicary.tsx — the interactive shell (loop, god-tools, HUD).
• scripts/smoke.ts — a headless behavioural check (npm run smoke).

Run

npm install
npm run dev      # http://localhost:3000
npm run smoke    # headless: verify foraging + lifecycle still work

Drag to pan, scroll to zoom. Use the tools to drop food, seed colonies, smite ants, or inspect a nest's genome and nudge its evolution.