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.

1. 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.
2. 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.
3. 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).