Architecture

The Arborwake alpha#

Layers#

Provenance files sit beside the code: game/INTEGRATION.json, game/UPDATED-PINS.json, game/art/SOURCES.json and game/RELEASE-FILES.json (1,149 inspected inputs with hashes).

Trust boundaries#

• The renderer never grants anything. beginRoom reserves endurance and fixes the launch facts. checkpointRoom checks the append-only command log with the pinned turn engine before saving it. finishRoom replays the log. A completion pays once, even after a reload.
• Shops recompute. A town menu sends only IDs; the host recomputes the transaction against the current ledger, commits it, and only then shows feedback.
• No farming. A trip that stays in town cannot advance a return cycle, refill deliveries or give recovery.
• Recruitment needs a quest receipt. The podium cannot recruit. Early story steps need physical observations and verified encounters. The story stops on purpose at the unwritten II2 scene.
• Threadway transport. Files over 20 MiB travel in exact-byte parts that are joined before decoding. Blender sources and review GLBs are not shipped.

Commands and tests#

These results are the lead’s own. On 3 November the wiki reran npm run test:systems (135/135) and npm test (11/11) on a clean extract of b89f778; it did not rerun the builds or browser suites.

The original opening on main (history)#

This is the engine of the three-minute Circuit Ranger opening. It still builds and runs on main, and parts of it (navigation, saves) were reused.

Stack#

JavaScript, HTML and CSS; Phaser 4.2.1 for drawing; Vite 8.3.5 for building; Playwright 1.64.1 with installed Edge for browser tests; Prettier 3.6.2; Node ≥ 22.12. Logical viewport 512×288, pixel-art scaling.

Principles#

• Plain-JavaScript state is the truth. Phaser only draws; renderers never complete work or grant anything.
• Deterministic fixed steps of 1/30 s. Paused or hidden time is discarded, so nothing changes while you are away.
• One world, one player, one home, one clock. Regions are data; there is one reusable scene.
• Every command goes through one dispatcher and returns {ok, reason?}. A rejected command changes nothing.

Modules#

One step#

step(state, dt) advances in this order:

time += dt → movePlayer → updateCells → updateHome → updateDiscovery → updateDirector

step throws if dt is not in (0, 0.05]. The director runs the opening phases: welcome → forecast → defence → recovery → ending → commons (after Continue), or practice in Gate A mode.

Commands#

pause, continue, move {x,y}, destination {x,y}, select {id}, cycle, cancel, call, build, assign {residentId, sectorId}, ready, tend. There are no skill or expedition commands; their future shapes are agreed in Integration.

Trace one action: select → tend → dispatcher checks pause, target, region and range → cells latch the action → each step advances material progress → completion writes cleared = true before one event → the renderer simply stops drawing it.

Saves#

IndexedDB database arborwake-save-v1, keys current and previous. A save writes both in one transaction (the old current becomes previous) with a revision check that rejects stale tabs. Schema version 1 validates the fixed regions, six sectors, 1–3 residents and Supply limits. Snapshots drop input, path and action, and load paused. Extra unknown data is not a supported extension mechanism.

Since the 31 October rename, the first run at a browser origin copies saves from the database used under the project's former name into the new one, keeping their revisions. It never overwrites an existing Arborwake record and never deletes the old database, which stays as a recovery source. Close tabs running an older build first: the old database is not kept in sync. Old identifiers are recognised only by src/persistence/legacy-brand.js.

Tests#

Browser suites refuse to reuse an existing server; set ARBORWAKE_TEST_PORT (or ARBORWAKE_SYSTEMS_TEST_PORT for the systems preview) for an isolated port. ?qa=1 exposes disclosed fixed-step acceleration for tests only; the browser QA hooks are window.arborwake and window.arborwakeSystems.

After the rename (main 54cc7cc), the lead reported on 31 October: npm test 101/101, npm run build and npm run build:systems passed, npm run test:browser 10/10 (including save migration), and npm run test:systems:browser 3/3. test:art and test:realtime were not rerun; the table above shows their last results.

Run it#

npm ci
npm run dev        # http://127.0.0.1:5173
npm test
npm run build
npm run test:browser

Or play the built snapshot without any setup.