Architecture

The constraints

Three rules shaped everything else.

• No build step for the game. index.html loads eighteen plain <script> tags in order. Everything hangs off a single window.BW namespace. You can open the file from disk and it runs; you can edit a file and hit reload. The bundler exists only to produce the single-file distribution.
• No external assets. Every mesh, texture, sound and icon is generated at runtime from code. The application icon is drawn by a hand-written PNG encoder using nothing but zlib. That keeps the repository small and means nothing can rot or go missing.
• No runtime dependencies. Three.js is vendored (594 KB, MIT). Electron, electron-builder and Playwright are development-only — they package and test, and none of them ships inside the game.

Module map

Load order matters, because it is plain classic scripts: utilities first, data second, then the systems that need them.

Entities and state

There are no classes for game objects. Every entity — villager, building, tree, rock, creature, platoon, town — is a plain object with a numeric id, held in a Map and in a per-type array. Systems are free functions over that state.

The one rule that makes this work: anything prefixed with an underscore is transient. A building's Three.js mesh lives at _mesh, a cached adjacency result at _adj, a dirty flag at _dirty. Serialisation strips every key beginning with _, so the save format is whatever the simulation actually needs and nothing else — no manual list of fields to keep in sync.

// world.js — the entire save filter
const strip = (k, v) => (k.startsWith('_') ? undefined : v);
return JSON.stringify(data, strip);

Rendering and crowds

A town at full tilt has dozens of villagers and tens of thousands of trees. Drawing each as its own mesh would be hopeless, so almost everything goes through InstancedMesh crowds that are rebuilt per frame from state:

Buildings are the exception: each is a small Group of boxes, cones and cylinders assembled by a buildingMesh function. Upgrading rebuilds the group with extra storeys and ornaments, which is why a level-three building visibly fills more of its hex.

Simulation has its own level of detail. Villagers far from the camera tick every third frame with a tripled delta, which keeps a large town cheap without changing its behaviour.

World generation

Every island comes from one integer seed, through a mulberry32 PRNG and value-noise fbm. Nothing is stored; the same seed rebuilds the same world exactly, which is also what makes save files small.

• Coastline. A radial mask whose radius is domain-warped by noise, so the shore has bays and peninsulas instead of being a circle. Four seeded islets sit offshore.
• Relief. Ridged noise raises mountain spines, and a second low-frequency field carves inland lakes with smoothed shores.
• Biomes. Moisture, temperature and slope fields are blended into nine weighted biomes. Each contributes to ground colour, tree density, tree species, crop growth and which ores appear.
• Town sites are flattened to gentle plateaus, and each one is guaranteed stone, iron and gold within reach so no start is unplayable.

Simulation and pathfinding

Two spatial structures carry the load. A uniform grid hash (cell size 8) answers "what is near this point" for the thousands of nearest-neighbour queries each second. A separate navigation grid (cell size 3) holds walkability and movement cost.

Villagers try a straight line first and only run A* when it is blocked. Roads cost less, so people prefer them and visibly move 40% faster. Buildings stamp themselves into the grid by cell centre, gates are passable to their owner only, and anyone who somehow ends up inside a blocked cell is allowed to walk out — without that escape rule a single mis-stamped cell can strand a villager forever, which is exactly the bug it was written to fix.

The grid is rebuilt lazily: a navDirty flag plus a version counter, so paths recompute only when the world actually changed under them.

Save format

A save is JSON in local storage: the god, the towns, the people, the buildings, the creatures, the effects, the camera, the PRNG cursor and the weather. Trees are the one hand-packed structure — tens of thousands of them become compact arrays rather than objects.

Loading tolerates older saves through a chain of migrations: a resource that was renamed, a field that did not exist, levels added to buildings. Each is a couple of lines in loadState, which is cheap insurance against a format that is still moving.

Build and packaging

build.js inlines the stylesheet and all eighteen scripts into dist/index.html — about 1 MB, completely self-contained, works from file:// with no network. That single file is the browser build, the download on the releases page, and the page this site serves at /play/.

The desktop app is an Electron shell around exactly that file. The renderer is sandboxed: no Node integration, context isolation on, external links handed to the real browser, and one instance at a time so two copies cannot fight over the same saves. The packaged archive contains three files — the main process, the bundled game, and a manifest.

electron-builder produces an NSIS installer and a portable executable for Windows, dmg and zip for both Mac architectures, and an AppImage and deb for Linux.

Testing and releases

Three suites run on every pull request.

Releases need no approval and no release pull request. Every pull request carries one label — release:patch, release:minor, release:major or release:none — and merging a versioned one bumps the version, dates the changelog, commits and tags on main, builds all three platforms, and publishes the release with those changelog entries as its notes. The labels create themselves on first run, so the repository needs no setup.