Ant Colony
A live 3D ant colony as a Wallpaper Engine
web wallpaper, and as a page you can just open in a browser:
Live demo: https://thom-ernst.github.io/Ants-Wallpaper/
No video, no downloaded assets: the ground, the nest craters, the plants and
the ants themselves are generated when the page loads and simulated while
you watch. Ants loiter, patrol and groom around the nest entrances, foraging
trails run off-screen and come back with food, diggers dump spoil on the
mound, and every so often a nuptial flight boils out of a hole.
What you get
- Three species, switchable in the settings:
- Messor barbarus (harvester ants): dry sandy ground, three castes, seeds
carried home, cooperative transport of dead beetles and seed heads, husk
middens beside the entrances.
- Atta cephalotes (leafcutters): dark forest floor with leaf litter, four
castes from tiny minims to huge-headed soldiers, a seedling whose leaves
the workers climb and cut from the edges (it regrows once stripped), leaf
fragments held up over the head, minims hitchhiking on the leaves.
- Lasius niger (black garden ants): a garden path with gravel and moss,
an aphid colony on a plant stem that foragers climb to and come home from
with honeydew-swollen gasters, crumbs carried in the jaws.
- A new map every time. Nest entrances, trails and the places the ants
collect food from are generated from a seed and laid out inside the ground
your camera actually sees, so an ultrawide screen gets a wider colony. Pick
a new map each start, each day, keep a seed you like, or use the classic
hand-placed one. No two nest holes are the same.
- Bustle. Walkers hesitate and dart rather than glide, ants that meet
stop nose to nose and drum antennae, foragers pause to check the ground,
and the whole colony has moods: lulls and rushes, a food find or a flight
rousing everyone.
- Nuptial flights. On warm afternoons winged queens and males climb out,
shiver their wings and take off; later, mated queens land, shed their wings
and wander off to found a colony.
- Day and night follow your clock (or a short cycle), with a full moon
keeping the trails readable at night.
- Runs all day on a desktop: about 60 draw calls, instanced ants with a
procedural gait, honours Wallpaper Engine's FPS limit and pause.
Install in Wallpaper Engine
The folder is loaded as-is; nothing needs building on the Windows side.
- Download the latest
we-ant-colony.zip from
Releases (or
clone this repository; only index.html, project.json, preview.jpg
and dist/bundle.js are needed at runtime) and unpack it into
...\Steam\steamapps\common\wallpaper_engine\projects\myprojects\ant-colony.
- In Wallpaper Engine open Wallpaper Editor → Open wallpaper and pick
the folder's
project.json, or restart WE and find it under
Installed → My projects.
- Apply it. Ant species, Colony activity, Speed, Time of
day, Camera, Quality, Map and Map seed are in the
wallpaper's properties panel.
In a browser
The live demo is the same
scene with a gear button (top right, fades when the mouse is still) that
opens the same settings. Settings persist in the browser; Copy link makes
a URL that opens with them, and query parameters override stored values:
?species=atta-cephalotes&seed=42&hour=23 for instance.
It is published by the GitHub Actions workflow in .github/workflows/
on every push to main. To host it yourself, npm run pack writes
we-ant-colony-web.zip; unpack it into any static web root
(deploy/compose.yaml is an nginx example).
Development
Needs Node 18+. See CLAUDE.md for the tooling and DESIGN.md for the
concept and architecture.
npm ci
npm run build # -> dist/bundle.js (committed: the WE machine has no toolchain)
npm run pack # build + we-ant-colony.zip (WE) + we-ant-colony-web.zip / site/ (browser)
npm run watch # rebuild on change
npm run serve # http://localhost:8000/web.html
npm test # sim / gait / layout / colony tests, no browser needed
npm run shot -- --out shots/x.png --sim 30 # headless render (software WebGL)
Query parameters for inspection: ?seed=3 (map seed; 0 = classic),
?map=daily, ?species=lasius-niger, ?activity=2, ?quality=low,
?hour=23 (pin the time of day), ?bonanza=1 (drop food at once, optionally
&bonanzaTrail=1), ?groom=1 (every idle ant grooms), ?camera=focus
(shots default to a static camera and 13:00), ?focus=165,-200 (lean in on a
point), ?vantage=2 (start at a vantage point), ?lookant=major,loiter
(frame one ant of that caste and state, with &camh=6&campitch=20&camfov=26),
?debugbite=1 (bite every source blade at once), ?flight=1 (start a nuptial
flight, &flightEntrance=0 to choose the hole), and camera overrides
?camh=45&campitch=24&camfov=30&lookx=-70&lookz=0.
Ideas for later
1.0 is feature-complete. None of these are needed:
- More species packs (Formica rufa wood ants with a needle mound,
Camponotus carpenter ants at night).
- Weather: a rain shower that empties the surface, wind bending the grass.
- Visitors: a beetle blundering through a trail, a spider at the edge, a
bird's shadow that makes everyone freeze.
- A brood chamber cutaway as an optional camera vantage.
- A glTF ant model in place of the procedural parts (the rig's pivot
convention in
src/render/antRig.js is designed for it).
