Spaces:
Paused
Paused
| # 03 — Client coupling: what must change to become a networked client | |
| **Status:** analysis, input to ADRs and `TASKS.md`. Not a specification. | |
| **Source audited:** `/home/user/alma92350/spaceexploration-rts` @ working tree (read-only clone). | |
| **Assumed decision (upstream):** server-authoritative headless Node sim; the browser renders a | |
| state it is given and sends commands instead of mutating locally. | |
| All `file.js:line` citations are against the SOURCE tree. Line numbers are exact at the time of | |
| writing; they are cited so a reader can confirm each claim, not as a patch plan. | |
| --- | |
| ## 0. Headline findings | |
| Five facts shape everything below. They are the reason this port is a re-seaming job and not a | |
| rewrite. | |
| 1. **The client barely mutates the sim.** Outside `engine/`, sim mutation happens at exactly | |
| **56 call sites** across **6 files** — and *all but 10 of them* go through named engine | |
| functions (`issue*`, `queueProduction`, `sell`/`buy`, …) that already take an explicit | |
| `(state, entityId, args)` shape. Those 46 sites are already command envelopes; they just | |
| aren't serialized. The other 10 are `state.selection = …`, which isn't sim state at all | |
| (`engine/persist.js:777` resets it to `[]` on load). | |
| 2. **No client file writes `resources` or `credits` directly.** Verified by grep — zero hits. | |
| Every economic mutation is an engine call. The trust boundary is therefore already drawn in | |
| the right place; it is simply not enforced. | |
| 3. **The engine is already owner-generic in its bones.** `state.owners` is the canonical side | |
| list, `state.players` and `state.fogs` are keyed by owner id, and `state.fog`/`state.fogAI` | |
| are documented *aliases* into `state.fogs` (`engine/state.js:167-189, 227-234`), pinned by | |
| `test/ownerScaffold.test.js`. Victory already iterates `state.owners` | |
| (`engine/victory.js:11, 30, 165`). "Seat 3 of 5" is a change to `ownerDefs` | |
| (`engine/state.js:174-181`), not a sweep. | |
| 4. **The renderers are already owner-generic for colour and already fog-gate every entity.** | |
| Team colour is read as `state.players[owner].color` at all four draw sites | |
| (`renderUnits.js:66`, `renderBuildings.js:75`, `minimap.js:95`, `minimap.js:100`); the | |
| fog rule is factored into one named predicate, `renderShared.js:253 hiddenByFog`. Nothing | |
| hardcodes `#4fd1ff`/`#f87171` for entities — those literals live in `engine/state.js:179-180` | |
| as *data*. | |
| 5. **The sim is cheap.** Measured on this machine: a full skirmish with **both** seats | |
| AI-driven costs **0.096–0.142 ms/tick** (27,000 ticks, 15 sim-minutes, small and 2× maps). | |
| At 20 Hz that is ~0.2–0.3 % of one core per match. A single Node process can host dozens of | |
| concurrent matches without breaking a sweat. Headless authority is not a performance risk. | |
| The real work is concentrated in three places: `boot.js` (the lifecycle), `input.js` + | |
| `inputCommands.js` + `hudSelection.js` (the ~46 synchronous engine calls), and the ~110 | |
| hardcoded `"player"`/`"ai"` owner literals scattered across the HUD and renderers. | |
| --- | |
| ## 1. The local-authority inventory | |
| ### 1.1 `engine/commands.js` `issue*` — direct order issuance | |
| `engine/commands.js` exports 22 `issue*` functions (lines 231–531). Four client files import | |
| them. **Every one of these becomes `submitCommand(envelope)`.** | |
| | Site | Call | Notes | | |
| |---|---|---| | |
| | `main.js:21` | *import* `issueMove, issueAttackMove` | minimap right-click | | |
| | `main.js:149` | `issueAttackMove(combatants, world.x, world.y)` | minimap command | | |
| | `main.js:150` | `issueMove(others, world.x, world.y)` | minimap command | | |
| | `input.js:12` | *import* `issueBuild, issueStop, issueScout, issueHold, issueHoldFormation, issuePatrol` | | | |
| | `input.js:346` | `issueStop(selectedUnits())` | S key | | |
| | `input.js:351` | `issueScout(selectedUnits())` | scout toggle | | |
| | `input.js:355` | `issueHold(selectedUnits())` | H key | | |
| | `input.js:372` | `issuePatrol([u], points)` | per-unit patrol loop | | |
| | `input.js:379` | `issueHoldFormation(selectedUnits(), game.formation.shape, game.formation.leaderPos)` | reads client-only `game.formation` (`session.js:75`) | | |
| | `input.js:521` | `issueBuild(state, worker.id, buildingType, p.x, p.y)` | **returns a value the client uses** — see §1.6 | | |
| | `inputCommands.js:27` | *import* 11 `issue*` | the right-click router | | |
| | `inputCommands.js:94` | `issueAttackMove(combatants, x, y, queue, formation)` | | | |
| | `inputCommands.js:95` | `issueMove(others, x, y, queue, formation)` | | | |
| | `inputCommands.js:199` | `issueSetRally(building, p.x, p.y, node?.id)` | passes a **live building object**, not an id | | |
| | `inputCommands.js:212` | `issueAssistBuild(workers, target.id, target.type, queue)` | | | |
| | `inputCommands.js:226` | `issueServiceBuilding(workers, target.id, queue)` | | | |
| | `inputCommands.js:235` | `issueRepair(workers, target.id, queue)` | | | |
| | `inputCommands.js:245` | `issueSetHomeBase(eligible, target.id)` | | | |
| | `inputCommands.js:249` | `issueAttack(attackers, target.id, queue)` | | | |
| | `inputCommands.js:259` | `issueFerryFreighter(workers, target.id, queue)` | | | |
| | `inputCommands.js:266` | `issueRepair(workers, target.id, queue)` | | | |
| | `inputCommands.js:273` | `issueEscort(escorts, target.id, queue)` | | | |
| | `inputCommands.js:278` | `issueGather(workers, node.id, queue)` | | | |
| | `inputCommands.js:282` | `issueMove(selected, p.x, p.y, false, currentFormation(heading))` | | | |
| | `hudSelection.js:21` | *import* `issueSetAILogistics, issueSetCollectPoint, issueSetLogiPriority, issueRecycle, issueCancelRecycle` | | | |
| | `hudSelection.js:518` | `issueSetAILogistics([f], !on, state)` | | | |
| | `hudSelection.js:542` | `issueSetCollectPoint([f], !on)` | | | |
| | `hudSelection.js:600` | `issueSetLogiPriority(state, b.id, LOGI_PRIORITY_NEXT[cur])` | | | |
| | `hudSelection.js:1821` | `issueCancelRecycle(recyclingNow)` | passes **live entity objects** | | |
| | `hudSelection.js:1835` | `issueRecycle(recyclable)` | passes **live entity objects** | | |
| | `tools/ailab.js:78,82,168-320` | `issueAttackMove`, `issueBuild` | headless bench, not shipped client | | |
| **Shape problem to fix once:** most `issue*` take **arrays of live unit objects**, and three take | |
| live building/entity objects (`inputCommands.js:199`, `hudSelection.js:1821`, `:1835`). A wire | |
| envelope must carry **ids**. Recommended: add one dispatcher, | |
| `applyCommand(state, seat, {verb, ids, args})`, in `engine/commands.js` that resolves ids → | |
| entities, **filters to entities owned by `seat`** (this is the anti-cheat gate, and it does not | |
| exist anywhere today), then calls the existing `issue*` unchanged. Every existing | |
| `test/commands.test.js` assertion (503 LOC) keeps passing against the raw `issue*`. | |
| ### 1.2 Non-`issue*` engine mutators called from the client | |
| These are just as authoritative and are easy to miss because they don't share a prefix. | |
| | Site | Call | Subsystem | | |
| |---|---|---| | |
| | `hudSelection.js:1098, 1104, 1198, 1629` | `queueProduction(state, b.id, t[, true])` | production | | |
| | `hudSelection.js:197` | `cancelProduction(state, building.id, i)` | production | | |
| | `hudSelection.js:1149` | `researchUpgrade(state, refinery.id, u.id)` | tech | | |
| | `hudSelection.js:1179` | `researchTech(state, datacenter.id, t.id)` | tech (Odyssey) | | |
| | `hudSelection.js:235` | `cancelResearch(state, building.id, i)` | tech | | |
| | `hudSelection.js:381, 395, 405` | `sell(game.galaxy, state, com, qty)` | market (Odyssey) | | |
| | `hudSelection.js:414` | `buy(game.galaxy, state, com, TRADE_LOT)` | market (Odyssey) | | |
| | `hudSelection.js:449, 485` | `loadFreighter(state, f.id, com, qty)` | freight (Odyssey) | | |
| | `hudSelection.js:459, 494` | `unloadFreighter(state, f.id, com, qty)` | freight (Odyssey) | | |
| | `hudSelection.js:630` | `offerTribute(game.galaxy, state)` | diplomacy (Odyssey) | | |
| | `hudSelection.js:661` | `fulfillRequest(game.galaxy, state)` | diplomacy (Odyssey) | | |
| | `hudSelection.js:705` | `offerGift(state, com, TRADE_LOT)` | diplomacy (Odyssey) | | |
| | `hudSelection.js:766, 777, 781, 793` | `unassignShipFromLane / assignShipToLane / deleteLane / createLane` | lanes (Odyssey) | | |
| | `hudSelection.js:831, 837, 850, 870, 876` | `setColonyPolicy(g, planetId, …)` | colony policy (Odyssey) | | |
| | `hudSelection.js:900` | `upgradeToCapital(state, cc)` | Odyssey | | |
| | `hudSelection.js:905` | `packCommandCenter(state, cc.id)` | Odyssey | | |
| | `hudSelection.js:1386` | `upgradeSpaceport(state, spaceport)` | Odyssey | | |
| | `hudSelection.js:1455` | `lightFuse(state, bomb)` | bombs — **skirmish, must be a command** | | |
| | `hudSelection.js:1750` | `deployColonyShip(state, colonyShip.id)` | Odyssey | | |
| | `hud.js:37` | `repairConvoy(game.state)` | scenario | | |
| | `hud.js:38` | `departNow(game.state)` | scenario | | |
| | `starmap.js:229, 239, 244` | `setColonyPolicy(g, w.id, …)` | Odyssey | | |
| For **v1 skirmish MP**, the mandatory set is small: `queueProduction`, `cancelProduction`, | |
| `researchUpgrade`, `cancelResearch`, `lightFuse`, plus the `issue*` family. Everything marked | |
| Odyssey is out of scope (§7) and stays reachable only on the offline path (§8). | |
| ### 1.3 Direct `state.*` writes | |
| Only two kinds exist in the whole non-engine tree. | |
| | Site | Write | Verdict | | |
| |---|---|---| | |
| | `input.js:318, 337, 382, 395, 411, 543` | `state.selection = …` | **Not sim state.** Move to the client session. | | |
| | `inputCommands.js:147, 152, 154, 157, 177` | `state.selection = …` | same | | |
| | `boot.js:766` | `state.events.length = 0` | The client *drains* the sim's event queue. On the server path, events arrive per-snapshot and are consumed the same way. | | |
| `state.selection` also has **2 engine references** (`engine/state.js:346` prunes dead ids; | |
| `engine/galaxy.js:1422` clears both sides on a jump), **32 client references** and **124 test | |
| references**. It is single-seat by construction and *must* move out of the shared sim state — it | |
| is the single largest mechanical edit in the port. `engine/persist.js:777` already proves it is | |
| disposable (it saves as `[]`). | |
| ### 1.4 `state.players.player.resources` and friends — direct owner-keyed reads | |
| There are **no writes**. Reads (all of which become "read *my* seat"): | |
| | Site | Read | | |
| |---|---| | |
| | `hud.js:99` | `{ ...state.players.player.resources }` (flow history sample) | | |
| | `hud.js:174` | `state.players.player.resources` (topbar readout) | | |
| | `hudSelection.js:272, 363, 432, 522, 680` | `state.players.player.resources` | | |
| | `hudSelection.js:651` | `state.players.player.resources[req.com]` | | |
| | `hudSelection.js:508, 1122, 1157` | `state.players.player.upgrades` | | |
| | `hudSelection.js:1941` | `state.players.player.color` (button sprite tint) | | |
| | `hudSelection.js:1955` | `canAfford(state.players.player.resources, cost)` | | |
| | `hudPanelSignature.js:146, 264, 344` | `state.players.player.resources` | | |
| | `hudPanelSignature.js:180` | `state.players.player.upgrades` | | |
| | `hudPanelSignature.js:227, 228` | `state.players.player.resources[…]` | | |
| | `overlays.js:34` | `st.players.player.faction` **and `st.players.ai.faction`** | | |
| | `observer.js:276` | `state.players.ai` (spectator stats) | | |
| | `techChart.js:36` | `const OWNER = "player"` — the whole module's owner, used at `:138, :153, :196` | | |
| **Fix:** one accessor. `me(state)` → `state.players[session.seat]`. 20 sites, purely mechanical. | |
| `overlays.js:34` and `observer.js:276` are the two that read *someone else's* player record and | |
| therefore need a public-facts channel under filtering (§4). | |
| ### 1.5 `createGameState` / `tick()` / `createLoop` — the sim ownership itself | |
| All in `boot.js`. This is the file that becomes the transport. | |
| | Site | Call | | |
| |---|---| | |
| | `boot.js:14` | *import* `createGameState` | | |
| | `boot.js:16` | *import* `createLoop` | | |
| | `boot.js:17` | *import* `tick` | | |
| | `boot.js:22` | *import* `createSelfPlayState, tickSelfPlay, SELFPLAY_HZ` | | |
| | `boot.js:119` | `createGameState({ planetId, seed, rng: mulberry32(seed), … })` — skirmish | | |
| | `boot.js:169` | `createGameState({ … })` — competition fixture | | |
| | `boot.js:207` | `createSelfPlayState({ … })` — watched AI-vs-AI | | |
| | `boot.js:236, 244, 252` | `setupEscort / setupRaider / setupBounty` — scenarios | | |
| | `boot.js:262` | `createGalaxy({ … })` — Odyssey | | |
| | `boot.js:287` | `jumpCapital(game.galaxy, destId, …)` | | |
| | `boot.js:344` | `surrenderGalaxy(game.galaxy)` | | |
| | `boot.js:485` | `loop = createLoop({ hz, speed, update, render })` | | |
| | `boot.js:503` | `stepGalaxy(game.galaxy, dt)` | | |
| | `boot.js:504` | `sweepColonies(game.galaxy, dt)` | | |
| | `boot.js:530` | `tickSelfPlay(game.state, dt)` | | |
| | `boot.js:531` | `tick(game.state, dt)` — **the single skirmish tick** | | |
| Note `engine/loop.js:34` `createLoop` is a *render* loop with an embedded fixed-step accumulator. | |
| On the server, the accumulator half is reusable verbatim; the `requestAnimationFrame` half | |
| (`engine/loop.js:69, 77, 81`, each marked `browser-exempt`) needs a `setInterval`/timer driver. | |
| Recommendation: extract the accumulator into a `stepper` and give it two drivers, rather than | |
| forking the file — the fixed-step semantics documented at `engine/loop.js:18-26` are what make | |
| replay determinism hold, and they must not diverge. | |
| ### 1.6 Return values the client consumes — the "optimistic" hazards | |
| Three call sites use the *return value* of a mutation, which a fire-and-forget command envelope | |
| cannot provide: | |
| - `input.js:521` — `issueBuild(...)` returns the new building id or `null`; the client uses the | |
| falsy result to keep build mode armed and play a rejection sound. Under server authority this | |
| becomes a *rejection message* or an optimistic ghost that clears on the next snapshot. | |
| - `hudSelection.js:449, 459, 485, 494` — `loadFreighter`/`unloadFreighter` return the quantity | |
| actually moved and drive the UI feedback (`sound.playProductionBlocked()` on 0). Odyssey-only. | |
| - `boot.js:287` — `jumpCapital` returns a result object or `null`. Odyssey-only. | |
| Only the first matters for v1. | |
| --- | |
| ## 2. `session.js` / `boot.js` — the lifecycle, and how it re-shapes | |
| ### 2.1 `session.js` today (120 LOC) | |
| A single exported mutable object, `game`, that every UI module reads **at call time** (never | |
| destructured at module scope) so a restart is picked up automatically. Its 17 fields are exactly | |
| three kinds of thing: | |
| | Kind | Fields | MP fate | | |
| |---|---|---| | |
| | **The sim handles** | `state` (`session.js:16`), `galaxy` (`:22`) | Become *received* state; `galaxy` out of v1 | | |
| | **The input controller** | `input` (`:17`) | Stays; becomes command-emitting rather than state-mutating | | |
| | **Per-viewer UI state** | `supplyBlockedUntil` (`:34`), `lastAttackAt` (`:40`), `lastGateCharge` (`:52`), `colonyAlerts` (`:64`), `groups` (`:69`), `formation` (`:75`), `collapsedSections` (`:84`), `observerMode` (`:89`), `spectateId` (`:92`), `spectatePreview` (`:99`), `observerCamera` (`:103`), `spectateSpeed` (`:119`) | **Stays exactly as-is.** None of it is sim state; all of it is per-client. | | |
| | **Match-provenance flags** | `competition` (`:30`), `spectateMatch` (`:114`) | Replaced by `match` (server-issued match descriptor) | | |
| **This object is the right shape already.** The port adds fields, it does not restructure: | |
| `seat` (my owner id), `seats` (public roster: id, name, colour, faction, isAI/isAgent), | |
| `transport`, `connection` (connecting/live/desynced/dropped), `serverTick`, `selection` | |
| (moved off `state`), and `role` (`"player" | "spectator"`). | |
| ### 2.2 `boot.js` today — the lifecycle in one line each | |
| ``` | |
| main.js:165 renderMapSelect() splash / map-select screen (setup.js:306) | |
| └ user picks world + dials → setup (setup.js:104, the shared config object) | |
| boot.js:109 startGame(planetId) resolveSeed → difficultyDials → createGameState | |
| boot.js:443 bootState(newState, {intro}) THE single boot path — 5 other entry points funnel here | |
| :444-446 stop old loop, destroy old input, exitObserverMode | |
| :447-451 hide mapSelect / gameOver / underAttack overlays | |
| :453-457 clear galaxy / competition / spectateMatch / groups / colonyAlerts | |
| :458 game.state = newState | |
| :463-465 seed chip, faction chip, objectives strip | |
| :466 game.input = attachInput(canvas, state, () => renderHUD()) | |
| :471-475 open camera on state.map.bases.player, clamp | |
| :476-482 resetEffects / resetFacing / resetPanelSignature / resetWorldUiBookkeeping / clearPause | |
| :485 loop = createLoop({ hz: PLAY_HZ(20) | SELFPLAY_HZ, speed, update, render }) | |
| :499-532 update(dt): pause gate → snapshotPositions → (stepGalaxy | tickSelfPlay | tick) | |
| :533-579 render(alpha): tickCamera → drawFrame → drawMinimap → processFrameEvents | |
| → throttled renderHUD/renderObserverPanel (150 ms) | |
| → **over-poll**: if (state.over && !announced) → showGameOver | |
| :581 loop.start(); :582 renderHUD() | |
| boot.js:400 restartToMapSelect() loop.stop, input.destroy, null state/galaxy, | |
| clearPause, renderMapSelect, unhide mapSelect | |
| ``` | |
| Five other entry points reuse `bootState` verbatim: `startCompetitionMatch` (`:159`), | |
| `startSpectatedMatch` (`:204`), `startScenario`/`startRaider`/`startBounty` (`:234/:242/:250`), | |
| `startOdyssey`→`bootGalaxy` (`:259`/`:273`), and `saveload.js`'s load path. | |
| Three structural properties matter for the port: | |
| - **End of match is a *poll*, not an event** (`boot.js:551`: `if (game.state.over && !announced)`). | |
| There is no callback, no state machine. The client discovers the match ended by looking. | |
| - **`bootState` is idempotent teardown-then-setup.** Every "leaving" concern is already | |
| centralised — the comment block at `boot.js:390-399` documents exactly why nulling the session | |
| matters (stale hotkeys, the autosave timer writing after "Exit without Saving"). | |
| - **The loop reads `game.state` live** (`boot.js:501, 503, 530, 531, 545`), never a captured | |
| binding. Swapping the state under it is already a supported operation (that is how the Odyssey | |
| jump works, `boot.js:365 focusActivePlanet`). | |
| ### 2.3 The multiplayer re-shape | |
| The lifecycle gains one screen and loses ownership of two transitions. Concretely: | |
| ``` | |
| SPLASH → LOBBY → (host: configure | join: wait) → server: MATCH_START | |
| → bootState(receivedSnapshot, {seat}) → loop(render-only) + command submit | |
| → server: MATCH_END → post-match screen → LOBBY | |
| ``` | |
| **`setup.js` splits in two.** `setup.js:104`'s `setup` object is *match configuration* — world, | |
| seed, difficulty, sizeMult, resourceMult, matchTimeLimit, popCap, faction. In MP that object is | |
| the **host's lobby form**, sent to the server once, and echoed back to every client as part of | |
| the match descriptor. The battlefield cards (`setup.js:306 renderMapSelect`) stay verbatim for | |
| the host; joiners see the same cards read-only. `setup.js` keeps its exported option tables | |
| (`MAP_CHOICES:29`, `MATCH_LENGTH_OPTIONS:59`, `POP_CAP_OPTIONS:77`, `STRATEGY_OPTIONS:98`, | |
| `DIFFICULTY_OPTIONS` re-export at `:18`) unchanged — they are pure data and the server needs | |
| the same lists to validate a lobby form. | |
| **`startGame` inverts.** `boot.js:109-125` currently *constructs* the state. It becomes: | |
| ``` | |
| startGame(planetId) → transport.requestMatch(setup) // returns nothing; server decides | |
| server MATCH_START → onMatchStart({ config, seat, seats, snapshot }) | |
| → bootState(hydrate(config, snapshot), { intro: true, seat }) | |
| ``` | |
| `hydrate` is cheap because the save format already does it: `engine/persist.js:496 serPlanet` | |
| persists only `(seed, planetId, sizeMult, resourceMult, swapAsym)` plus dynamic entities, and | |
| `rehydratePlanet` regenerates the whole map deterministically. **The client can regenerate | |
| terrain and node geometry itself from the config**; only `node.amount` and the entity tables | |
| need to arrive (`engine/persist.js:549-551` already ships exactly `{id, amount}` per node). | |
| **`bootState` keeps its body almost exactly.** Changes: | |
| - `:485` `createLoop` keeps `render` and *drops* the sim from `update`. The `update` callback | |
| becomes `applySnapshot`/`interpolate`. `snapshotPositions(game.state)` at `:501` must still run | |
| immediately **before** each applied snapshot (it is the interpolation baseline, | |
| `renderShared.js:45`); this is the one ordering constraint that must not be lost. | |
| - `:471` `state.map.bases.player` → `state.map.bases[seat]`. | |
| - `:466` `attachInput(canvas, state, onChange)` gains a `seat` and a `submit` collaborator. | |
| - `:551` the over-poll is replaced by an explicit `MATCH_END` message from the server carrying | |
| `winner`, `winReason`, and per-seat scores (§4 explains why scores must be server-computed). | |
| Keep the poll as the loopback path's implementation of the same callback (§8). | |
| **`restartToMapSelect` (`boot.js:400`) becomes `leaveMatch`.** Its existing teardown is exactly | |
| right and should be preserved verbatim (it is the file's most carefully-reasoned function). It | |
| gains: close/park the transport, clear `seat`/`seats`, and — the new hazard — handle *the server | |
| ending the match while the client is mid-teardown*. | |
| **New states with no analogue today:** `LOBBY` (roster, ready-up, seat/faction/colour pick), | |
| `CONNECTING`, `RECONNECTING`, `DESYNCED`, and `OPPONENT_DROPPED`. `pauseReasons` | |
| (`boot.js:94-106`) is a refcounted set and is the right primitive for "the server paused us" — | |
| but note that **`pauseLoop` currently gates only the local `update`** (`boot.js:500`). In MP, | |
| pause must come *from* the server; a client-side pause becomes a render-freeze only, and | |
| `togglePause` (`boot.js:103`) must be disabled or converted to a vote. `landingPicker`, | |
| `starmap`, and `techchart` all currently call `pauseLoop` to freeze the world behind a modal | |
| (`boot.js:332`, `starmap.js` tail, `techChart.js` tail) — **all three must stop pausing in MP**; | |
| they become non-blocking overlays. | |
| --- | |
| ## 3. Hardcoded "you are the player" assumptions | |
| ~110 literal `"player"`/`"ai"` occurrences outside `engine/`. They fall into five classes. | |
| ### 3.1 "Is this entity mine?" — the largest class, and the easiest | |
| Every one of these is `owner === "player"` / `owner !== "player"` and becomes | |
| `owner === session.seat`. | |
| | File | Lines | | |
| |---|---| | |
| | `input.js` | `317` (click-select own), `383` (select-all-army), `391` (idle worker), `407` (idle producer), `423` (CC cycle) | | |
| | `inputCommands.js` | `58`, `62` (fog gate on hit-test), `99` (`alivePlayerUnitIds`), `131`, `136`, `170`, `178`, `197`, `210`, `223`, `232`, `242`, `247`, `257`, `264`, `271` — the entire right-click router | | |
| | `hud.js` | `47` (gate chip), `137`, `194`, `336` (idle workers), `352` (idle production), `429` (freighter count) | | |
| | `hudPanelSignature.js` | `149`, `234`, `290`, `312` | | |
| | `renderBuildings.js` | `84` (enemy pip), `120`, `147`, `165`, `181`, `233` | | |
| | `renderEffects.js` | `413`, `563` (rally point), `600` (waypoints), `637` (escort links) | | |
| | `renderUnits.js` | `91` (enemy pip) | | |
| | `renderShared.js` | `254` — `hiddenByFog`, the one fog predicate; **fix here fixes four draw passes at once** | | |
| | `minimap.js` | `94`, `99` | | |
| | `boot.js` | `370` (`focusActivePlanet` finds own CC), `675` (event fog gate), `684`, `704`, `712` (under-attack trigger), `737` (own supply block) | | |
| | `starmap.js` | `56`, `58` | | |
| | `landingPicker.js` | `60`, `61`, `151`, `160` | | |
| | `techChart.js` | `36` — `const OWNER = "player"`, then used at `138`, `153`, `196` | | |
| | `overlays.js` | `68-81` (the eight opening-objective predicates, each `countUnits(state,"player",…)` / `hasCompletedBuilding(state,"player",…)`) | | |
| **Recommendation:** introduce `isMine(e)` in `session.js` and a `SEAT` accessor, then sweep. | |
| This is ~70 one-line edits with excellent test coverage already in place | |
| (`test/input.test.js` 57 tests, `test/renderShared.test.js` 34 tests, `test/hud.test.js` 33). | |
| ### 3.2 "The enemy is `"ai"`" — the class that genuinely breaks at N seats | |
| These assume **exactly one opponent**, not merely that it is named `"ai"`: | |
| | Site | Assumption | | |
| |---|---| | |
| | `boot.js:684, 704, 712` | `if (ev.owner === "ai") triggerUnderAttack(...)` — the comment at `boot.js:669-671` states it outright: *"an attackHit whose attacker is the AI necessarily means the target is the player's (only two sides exist)"*. At 5 seats this fires the under-attack alarm for every fight on the map. **Must become `ev.targetOwner === seat`, which means `engine/combat.js` must start emitting the target owner on `attackHit`.** This is the one place a *sim* change is forced by multiplayer. | | |
| | `hud.js:314` | `playerScore(state, "ai")` — the topbar score bar shows "you vs them" | | |
| | `overlays.js:407` | `playerScore(opts.state, "ai")` — the game-over breakdown | | |
| | `overlays.js:34` | `FACTIONS[st.players.ai.faction]` — the faction chip is a two-sided "you vs them" | | |
| | `overlays.js:376, 392` | `winner === "player" ? victory : defeat` | | |
| | `overlays.js:393-394` | *"Victory — the enemy's last Command Center is destroyed"* / *"Defeat — your last Command Center was destroyed."* — singular "the enemy" | | |
| | `observer.js:290, 291` | `supplyUsed(state,"ai")` / `supplyCap(state,"ai")` | | |
| | `observerPanel.js:89` | `owner => (owner === "player" ? watch.aName : watch.bName)` — hard two-entrant | | |
| | `observer.js:116` | `state.map.bases.player \|\| state.map.bases.ai` | | |
| | `hudPanelSignature.js:225-228` | diplomacy signature reads `state.diplomacy` as a single relationship | | |
| The score bar, the faction chip and the game-over copy are all **"two columns" UI**. At N seats | |
| they need to become a small roster table. That is a real (if modest) UI design job, not a rename. | |
| ### 3.3 Colours | |
| **Not a problem.** `#4fd1ff` / `#f87171` appear as *entity* colours only in | |
| `engine/state.js:179-180`, as `ownerDefs[].color`. Every renderer reads | |
| `state.players[owner].color` (`renderUnits.js:66`, `renderBuildings.js:75`, `minimap.js:95, 100`), | |
| and `hudSelection.js:1941` / `techChart.js:196` / `landingPicker.js:149` do the same for icons. | |
| The remaining literals in `renderEffects.js:111-113, 315, 326, 447, 511, 542, 584, 616, 680`, | |
| `minimap.js:114`, `renderUnits.js:126`, `renderShared.js:195`, `renderBuildings.js:109, 154, 197` | |
| are **semantic** colours (valid/invalid placement, health tiers, power tiers, tracer types) that | |
| happen to reuse the same hexes. Leave them. | |
| **Action:** extend `ownerDefs` to N entries with a colour ramp; add colours to `style.css` | |
| (3 hits) for the HUD chrome. Nothing else. | |
| ### 3.4 `state.fog` vs `state.fogAI` | |
| Already an alias pair over `state.fogs` (`engine/state.js:232-234`, pinned by | |
| `test/ownerScaffold.test.js`). Client reads: | |
| | Site | Read | | |
| |---|---| | |
| | `render.js:202` | `drawFogBase` — the charted-space wash | | |
| | `minimap.js:36, 83` | minimap fog underlay + entity gate | | |
| | `renderShared.js:254` | `hiddenByFog` | | |
| | `renderNodes.js:26` | `isNodeDiscovered(state.fog, n)` | | |
| | `renderEffects.js:466` | node picking overlay | | |
| | `inputCommands.js:58, 62, 69` | hit-test + node-pick gating | | |
| | `boot.js:675` | event audibility | | |
| **All nine become `state.fogs[seat]`.** The remaining hazard is *inside the engine*: | |
| `engine/sim.js:70-71` hardcodes `updateFog(state, state.fog, "player")` and | |
| `updateFog(state, state.fogAI, "ai")` even though `state.fogs` exists. That must become | |
| `for (const id of state.owners) updateFog(state, state.fogs[id], id)` — which is exactly what | |
| `engine/state.js:270` already does at construction time. | |
| ### 3.5 `state.map.bases.player` | |
| `boot.js:371`, `boot.js:471`, `input.js:430`, `observer.js:116`, and inside the engine | |
| `engine/galaxy.js:421, 1365`, `engine/map.js:177, 179, 207`. `engine/aiMilitary.js:554, 574, 589, | |
| 694` already indexes generically (`state.map.bases[owner]`). Map generation must produce N start | |
| positions — this is a **map-generation change** (`engine/map.js`) and is the single largest | |
| *engine* task implied by N-seat multiplayer. It is out of the client's scope but gates it. | |
| --- | |
| ## 4. Rendering under authoritative fog | |
| ### 4.1 How hard is per-client filtering? | |
| **Much easier than it looks, because the client already renders as if it were filtered.** | |
| `engine/fog.js` is 144 LOC, pure, and already per-owner: `createFog(map)` (`:34`), | |
| `isVisibleAt(fog,x,y)` (`:49`), `isExploredAt` (`:55`), `isNodeDiscovered` (`:66`), | |
| `updateFog(state, fog, owner)` (`:124`). `state.fogs[owner]` exists. There is **no remembered | |
| snapshot of enemy positions** (`engine/fog.js:14-15` says so explicitly) — an out-of-vision enemy | |
| simply stops rendering. That is precisely the semantics a filtered projection provides. | |
| So `projectFor(state, seat)` is a ~60-line pure function: | |
| ``` | |
| units → own ∪ { u : isVisibleAt(fogs[seat], u.x, u.y) }, enemy entries stripped | |
| of order/orderQueue/homeCC/target internals (intel leak) | |
| buildings → same rule | |
| nodes → { id, amount } for every charted node; hidden nodes only where | |
| isNodeDiscovered(fogs[seat], n) (engine/fog.js:66) | |
| players → { [seat]: full record } + public facts for the rest | |
| (id, name, colour, faction, score, supply, isAI) | |
| fogs → { [seat]: fogs[seat] }, with `fog` aliased for the legacy readers | |
| owners → unchanged (public) | |
| selection → this seat's own (once it moves off state) | |
| events → the rule already at boot.js:675: own events, plus any event | |
| at a currently-visible point | |
| map → NOT sent; client regenerates from (planetId, seed, sizeMult, | |
| resourceMult, swapAsym) — engine/map.js generateMap is deterministic | |
| ``` | |
| The renderer **needs no changes to consume this**, because every per-entity fog gate | |
| (`renderShared.js:254`, `minimap.js:94, 99`, `renderNodes.js:26`, `inputCommands.js:58, 62`) | |
| simply becomes tautologically true rather than wrong. | |
| ### 4.2 What filtering would strip that the client currently needs | |
| Six real dependencies. Five are trivially fixable; one is a genuine visual regression. | |
| 1. **`playerScore(state, "ai")`** — `hud.js:314` (score bar), `overlays.js:407` (game-over | |
| breakdown). Reads *all* of the enemy's bank/army/structures. → Server computes per-seat scores | |
| and ships them as public facts. `engine/victory.js:158-165` already iterates `ownersOf(state)`. | |
| 2. **Enemy faction** — `overlays.js:34` reads `st.players.ai.faction` for the "you vs them" chip. | |
| → Public lobby fact; ship in the match descriptor. | |
| 3. **Enemy supply** — `observer.js:290-291`. Spectator-only; the spectator seat receives an | |
| unfiltered projection. | |
| 4. **Enemy CC existence for victory** — client never checks this; `engine/victory.js` does, on the | |
| server. No client change. | |
| 5. **Hidden-node discovery** — `isNodeDiscovered` gates *right-click targetability* | |
| (`inputCommands.js:69`), not just drawing. If the client recomputes fog locally (see below), a | |
| snapshot-rate mismatch could make client and server disagree about whether a cache is | |
| targetable. → Ship an authoritative `discoveredNodeIds` set per seat. It is tiny (caches are | |
| a handful per map, `engine/map.js:266-267`). | |
| 6. **Interpolation continuity — the real regression.** `renderShared.js:39 prevPos` keys | |
| interpolation baselines by unit id; `renderShared.js:69 pruneFacing` deletes the baseline the | |
| moment a unit is absent from `state.units`. Today an enemy unit that ducks behind fog stays in | |
| the Map (only its *draw* is gated), so it keeps a continuous baseline. Under filtering it | |
| *leaves the map*, loses its baseline and its `facing` entry, and on re-entry snaps rather than | |
| slides. → Give `pruneFacing` a grace window (drop after N frames absent, not immediately). | |
| ~5 lines in a file with 34 existing tests. | |
| Everything else the renderer touches is either the client's own entities, immutable map data it | |
| can regenerate, or already fog-gated. | |
| ### 4.3 Measured payload (this machine, `engine/persist.js` format) | |
| Full `serializeGameString` snapshot, 15 sim-minutes, both seats AI-driven: | |
| | Map | units / bldgs | full | fog (both) | units | buildings | nodes | | |
| |---|---|---|---|---|---|---| | |
| | Small (1600×1000) | 16 / 16 | 18.9 KB | 3.9 KB | 4.5 KB | 3.7 KB | 4.4 KB | | |
| | Standard 2× (3200×2000) | 27 / 16 | 30.1 KB | 15.6 KB | 6.7 KB | 3.7 KB | 2.4 KB | | |
| | Gigantic 4× (6400×4000) | — | 69.6 KB | **62.5 KB** | 3.5 KB | 1.1 KB | 1.3 KB | | |
| **Fog dominates on large maps and entities are tiny.** That single fact drives the recommendation. | |
| ### 4.4 Recommendation | |
| > **Ship fog-filtered-per-client, and ship *no fog grid at all*.** | |
| Three parts: | |
| 1. **Filter entities server-side** with `projectFor(state, seat)`. This is the anti-cheat | |
| boundary and it must exist before any public or agent-played match. It is ~60 LOC of pure | |
| engine code, directly unit-testable against the existing `test/fog.test.js` fixtures. | |
| 2. **Do not transmit the fog grid.** The client already has everything needed to recompute it: | |
| its own units and buildings, and a deterministically regenerated map. | |
| `updateFog(state, myFog, seat)` (`engine/fog.js:124`) is pure, allocation-free, and is exactly | |
| what `engine/sim.js:70` already calls each tick. `explored` accumulates client-side across | |
| snapshots (it is monotonic). This deletes 3.9–62.5 KB from every snapshot and makes payload | |
| scale with *army size* rather than *map size*. The only thing that must remain | |
| server-authoritative is hidden-node discovery (see §4.2 item 5), which is a tiny id set. | |
| 3. **Keep full-state broadcast as a named, flagged mode** — `spectator` and `replay` — not as | |
| the default. `observer.js` (§7) is already exactly this client, and | |
| `saveShape.js:28 resumableMode` already encodes "a spectated match is not the player's game". | |
| **Trade-off, stated plainly.** Full-state broadcast is ~2 days of work and lets every existing | |
| client module run untouched; it is also trivially cheatable by anyone who opens devtools, and it | |
| is *especially* wrong for this project because MCP agents receive state programmatically — an | |
| agent handed the full state is not playing the same game as a human. Filtering costs perhaps a | |
| week (the projection function, per-seat score/faction public facts, the `pruneFacing` grace | |
| window, and the discovered-node channel) and is the only version that survives contact with | |
| public play. | |
| **Migration path.** These are additive and independently shippable: | |
| - **M0** — `projectFor(state, seat)` written and tested, but the server still broadcasts full | |
| state. Test: `projectFor(s,"player")` renders pixel-identically to `s` under the existing | |
| render tests. This proves the renderer tolerates a filtered state before anything depends on it. | |
| - **M1** — server switches to `projectFor`; fog grid still shipped. Add per-seat public scores | |
| (`hud.js:314`, `overlays.js:407`) and the faction roster (`overlays.js:34`). | |
| - **M2** — stop shipping fog; client calls `updateFog` locally on each snapshot. Add the | |
| `discoveredNodeIds` channel. Add the `pruneFacing` grace window. | |
| - **M3** — delta-encode entities against the previous acknowledged snapshot. At 16–27 entities, | |
| this is optional until army sizes grow. | |
| --- | |
| ## 5. What is reusable VERBATIM | |
| The tree is 90,762 LOC total (`.js/.css/.html/.json/.md`); 81,257 LOC of `.js/.css/.html`, of | |
| which **43,101 is tests**. Shipped application code is ~35,400 LOC (`engine` 15,659 + top-level | |
| client 17,903 + css/html 1,815). | |
| ### 5.1 Zero change — pure, import-free or engine-data-only leaves | |
| | Module | LOC | Why it is untouched | | |
| |---|---|---| | |
| | `sound.js` | 181 | **No imports at all.** Pure WebAudio. Nothing about it is single-player. | | |
| | `effects.js` | 183 | **No imports at all.** Tracers, death flashes, pings, fireworks — pure render-side particle bookkeeping. | | |
| | `camera.js` | 105 | **No imports at all.** `createCamera/zoomAt/panCamera/pinchZoomPan/screenToWorld/clampCamera`. | | |
| | `data.js` | 242 | Static tables (planets, commodities, recipes). Pure data. | | |
| | `dom.js` | 68 | Element handles + `MINIMAP_W/H` + `isTouchMode()`. Already Node-import-safe by design (`dom.js:11-18`). | | |
| | `style.css` | 1,732 | 3 hits on the team hexes; add N-seat colour variables. Otherwise verbatim. | | |
| | `saveShape.js` | 31 | Two pure predicates. Gains one term (§6). | | |
| | `renderShared.js` | 255 | One line (`:254`). Geometry/colour helpers, interpolation, health bars — all generic. | | |
| | `renderNodes.js` | 171 | One line (`:26`). | | |
| | `renderUnits.js` | 699 | Two lines (`:91` enemy pip, `:126` a semantic red). Colour already comes from `players[owner].color` (`:66`). | | |
| | `minimap.js` | 138 | Two lines (`:94, :99`). | | |
| | `render.js` | 277 | `drawFrame` orchestration + `spriteIcon` cache + `drawFogBase`. Only `state.fog` → `state.fogs[seat]` at `:202`. | | |
| | `renderBuildings.js` | 807 | Six `owner !== "player"` lines. Everything else — hull art, power tiers, storage bars, jump staging — is generic. | | |
| | `renderEffects.js` | 683 | Five `owner !== "player"` lines. | | |
| | `techChart.js` | 366 | One line: `const OWNER = "player"` (`:36`). Plus: stop calling `pauseLoop` in MP. | | |
| | `landingPicker.js` | 211 | Four owner lines. Odyssey-only anyway (§7). | | |
| | `elo.js` | 147 | Pure rating math, zero engine/DOM. **Lift to the server verbatim** when MP ranking lands. | | |
| | `pairing.js` | 518 | Pure Swiss/round-robin scheduling; its own header (`pairing.js:15`) notes the single import is `hashStr`. **Lift to the server verbatim.** | | |
| | `version.js` | 60 | Version/save-impact reporting. | | |
| | **Subtotal** | **~6,874** | | | |
| ### 5.2 Near-zero change — a rename sweep, no restructuring | |
| | Module | LOC | Change | | |
| |---|---|---| | |
| | `overlays.js` | 585 | Owner literals at `:34, :68-81, :376, :392-394, :406-407`; game-over copy becomes N-seat. Toasts/hints/help/objectives verbatim. | | |
| | `hud.js` | 452 | 9 owner literals; score bar becomes a roster; two scenario buttons (`:37, :38`) become commands. | | |
| | `hudPanelSignature.js` | 380 | 4 owner literals + the `players.player` reads. It is a pure signature/diff function — the mechanism is untouched. | | |
| | `session.js` | 120 | Additive fields only. | | |
| | `observer.js` + `observerPanel.js` | 550 | Repurposed as the spectator client (§7). `enterObserverMode` (`observer.js:128`) gains a third permitted condition. | | |
| | `main.js` | 168 | `:145-151` (minimap right-click) becomes a command submit. Everything else is canvas/DPR/toggles. | | |
| | `starmap.js` | 318 | Odyssey-only; unchanged on the offline path. | | |
| | `update.js` | 108 | Version chip / auto-update. Verbatim. | | |
| | **Subtotal** | **~2,681** | | | |
| ### 5.3 Real work | |
| | Module | LOC | Nature | | |
| |---|---|---| | |
| | `boot.js` | 788 | Lifecycle inversion (§2). The single heaviest file. | | |
| | `input.js` | 588 | 6 `state.selection` writes, 6 `issue*` calls, 5 owner literals; becomes command-emitting. Gesture/camera/touch code untouched. | | |
| | `inputCommands.js` | 288 | 5 selection writes, 13 `issue*` calls, 16 owner literals. Its own header (`inputCommands.js:15-17`) notes `commandAt` is *already* the "what does this click mean" decision, callable directly — **this file is the natural home of client-side command construction.** | | |
| | `hudSelection.js` | 1,998 | ~30 mutator calls + `players.player` reads. But ~900–1,000 LOC of it is Odyssey panels (`renderMarket:346`, `renderFreight:430`, `renderDiplomacy:612`, `renderLanes:717`, `renderColonyPolicy:809`, `renderCapital:890`, `renderSpaceport:1328`, `renderDatacenter:1156`) that are **out of v1 scope and need no change at all**. | | |
| | `setup.js` | 462 | Splits into lobby form + option tables (§2.3). | | |
| | `saveload.js` | 371 | §6. | | |
| | **Subtotal** | **~4,495** | | | |
| ### 5.4 Quantified | |
| Of the **~17,900 LOC of shipped client JS**: | |
| - **~6,900 LOC (≈39 %) verbatim or one-line-per-file** (§5.1) | |
| - **~2,700 LOC (≈15 %) a mechanical owner-literal sweep** (§5.2) | |
| - **~4,500 LOC (≈25 %) genuine rework** (§5.3), of which roughly a fifth is Odyssey panels that | |
| are simply not touched in v1 | |
| - **~3,800 LOC (≈21 %) out of v1 scope entirely** — the competition cluster (§7) | |
| Plus **1,732 LOC of CSS effectively verbatim** and **15,659 LOC of engine** that keeps running | |
| unchanged — on the server instead of in the tab. The 5 renderer files alone | |
| (`render` + `renderBuildings` + `renderEffects` + `renderNodes` + `renderUnits` + | |
| `renderShared` = **2,892 LOC**) survive with **17 changed lines between them**. That is the | |
| single strongest argument for server-authoritative-with-thin-client over any rewrite. | |
| --- | |
| ## 6. `saveload.js` / autosave / `localStorage` in multiplayer | |
| ### 6.1 What exists | |
| - Two channels (`saveload.js:1-18`): **file** (topbar Save/Load, an explicit `.json`) and | |
| **localStorage autosave** every 12 s (`saveload.js:39`) plus on tab-hide/unload, feeding the | |
| map-select "Continue" buttons. | |
| - Two generations per key (`saveload.js:33-38, 84-98`) so one corrupt write cannot lose a run. | |
| - Keys: `stellarfrontier.save.v1` (`:31`), `stellarfrontier.odyssey.v1` (`:32`). | |
| - The decision of *what is resumable* is a 3-line pure function, | |
| `saveShape.js:28 resumableMode({state, galaxy, spectateMatch})` — already unit-tested | |
| (`test/save-shape.test.js`) and already refuses to checkpoint a scenario, a finished match, or | |
| **a spectated match whose player seat isn't really the player's**. | |
| - Other `localStorage` users: `overlays.js:104-108` (objectives-strip dismissed, per mode), | |
| `update.js:23-24` (version-banner dismissed), `competitionLedger.js:1238-1286` (the Elo ledger, | |
| two generations, sanitized on read). | |
| ### 6.2 Recommendation | |
| > **Drop client saves for multiplayer entirely. Persist matches server-side using the existing | |
| > format. Record replays as command logs, not snapshots.** | |
| 1. **Client autosave off in MP — a one-term change.** `saveShape.js:28` already reads | |
| `{ state, galaxy, spectateMatch }`. Add `netMatch`: | |
| `if (!state || state.over || state.scenario || spectateMatch || netMatch) return null;` | |
| That single edit disables autosave, "Save & Exit", and the "Continue" buttons for a networked | |
| match, in a pure function with existing tests. Resuming a *shared* match from one participant's | |
| private browser copy is incoherent, and the localStorage payload is attacker-editable — the | |
| file's own header (`competitionLedger.js:11`) already says so. | |
| 2. **Server-side match persistence reuses `engine/persist.js` unchanged.** `serializeGameString` | |
| (`:808`) / `deserializeGame` (`:811`) already produce and consume the exact snapshot the server | |
| needs, and `deserializeGame` already treats its input as hostile | |
| (`sanitizeSave`, `engine/persist.js:48-49`, plus `test/save-hardening.test.js` at 836 LOC). | |
| The server checkpoints on the same 12 s cadence; a crash resumes the match. **Zero new format.** | |
| 3. **Replays are command logs, not snapshot streams.** The sim is deterministic from | |
| `(config, seed)` and the loop is fixed-step (`engine/loop.js:18-26` explains why the timestep | |
| is the simulation and not a tuning knob). There is already determinism coverage | |
| (`test/determinism.test.js`, `test/determinism-roster.test.js`) and a replay concept | |
| (`boot.js:215-219`'s `recorded`, which lets the game-over screen state honestly whether the | |
| determinism claim held). A `(config, [{tick, seat, envelope}])` log is orders of magnitude | |
| smaller than snapshots, doubles as the anti-cheat audit trail, and is the natural artefact for | |
| an MCP agent to review its own play. **Recording the command log should be built in from day | |
| one** — it is nearly free once commands are envelopes, and retrofitting it is not. | |
| 4. **Keep client `localStorage` for per-viewer preferences only** — `overlays.js:104-108`, | |
| `update.js:23-24`, volume/mute. These are correct as-is. | |
| 5. **File Save/Load stays, single-player only.** Hide `saveBtn`/`loadBtn` (`dom.js:42-43`) in a | |
| networked match, exactly as `starmapBtn` is already conditionally hidden. | |
| 6. **`competitionLedger.js`'s localStorage Elo ledger is single-player only** and stays that way. | |
| Any MP ladder must be server-side or it is forged by editing a string. | |
| --- | |
| ## 7. Odyssey / galaxy / competition / observer — in or out for v1 | |
| | Subsystem | LOC (client + engine) | v1 verdict | | |
| |---|---|---| | |
| | **Skirmish** (the base game) | — | **IN** — this *is* v1 | | |
| | **Odyssey / galaxy** | `engine/galaxy.js` 1,431 + `colony` 93 + `colonyPolicy` 160 + `diplomacy` 501 + `market` 309 + `wonder` 93 + `starmap.js` 318 + `landingPicker.js` 211 + ~950 of `hudSelection.js` = **≈4,066** | **OUT** | | |
| | **Competition / Elo / ladder** | `competition.js` 3,773 + `competitionLedger.js` 1,290 + `competitionWorker.js` 355 + `pairing.js` 518 + `elo.js` 147 + `playerFingerprint.js` 167 + `tools/duelCore.js` 119 + `tools/genome.js` 680 = **7,049** | **OUT as shipped; mine it** | | |
| | **Observer / spectator** | `observer.js` 304 + `observerPanel.js` 246 = **550** | **IN — repurposed** | | |
| | **Scenarios** (Escort / Raider / Bounty) | `engine/scenarios.js` 720 | **OUT** (offline path only) | | |
| ### Odyssey — OUT | |
| Three independent reasons, any one sufficient: | |
| - **It is not a match; it is a save file.** The Odyssey is an open-world sandbox that ticks | |
| *every world in the galaxy each tick* (`boot.js:503 stepGalaxy`), with a single per-player | |
| credit pool, background colonies raising notifications (`boot.js:504 sweepColonies` → | |
| `boot.js:605 notifyColony`), and interplanetary relocation that swaps which state is rendered | |
| (`boot.js:365 focusActivePlanet`). "Two players share a galaxy" is an unanswered **game-design** | |
| question, not a porting question. | |
| - **It pauses the world for modals.** `boot.js:332` (landing picker), `starmap.js` (M key), and | |
| `techChart.js` (T key) all call `pauseLoop`. In MP nothing may pause the shared world for one | |
| participant. Every Odyssey overlay would need reworking. | |
| - **It carries most of the client's remaining complexity.** Roughly half of `hudSelection.js` | |
| (the 1,998-LOC file) is Odyssey panels. Excluding Odyssey removes ~950 LOC of panel work from | |
| v1 at zero cost, because those panels never render when `game.galaxy` is null. | |
| **Keep the code in-tree and reachable on the offline path (§8). Do not delete it.** Its tests | |
| (`test/odyssey.test.js` 809 LOC, `test/starmap.test.js` 482, `test/landing.test.js` 439, | |
| `test/lanes.test.js`, `test/colonyPolicy.test.js`, `test/livingGalaxy.test.js`, | |
| `test/domination.test.js`, `test/rivalgate.test.js`) keep passing and keep protecting the shared | |
| engine code that skirmish also uses. | |
| ### Competition / Elo — OUT as shipped, but read it first | |
| `competition.js` (3,773 LOC) is a single-player *ladder screen*: it schedules AI-vs-AI duels, | |
| runs them in a Web Worker (`competitionWorker.js`), and writes ratings into a localStorage ledger. | |
| None of that is multiplayer. But three things in this cluster are the prior art for the port and | |
| should be **read before writing the server**: | |
| - `competitionWorker.js` (355) + `tools/duelCore.js` (119) + `tools/selfplay.js` (169) — | |
| **this is already a headless, off-main-thread, deterministic match runner.** It is the server | |
| sim in miniature. `engine/state.js:250-254` documents `state.playerAi`, the second controller | |
| slot that makes owner `"player"` AI-driven — the exact hook an MCP agent occupies. | |
| - `pairing.js` (518) and `elo.js` (147) are **pure, engine-free, and directly liftable** to the | |
| server when MP ranking lands. `pairing.js:15` states it holds no engine state at all. | |
| - `playerFingerprint.js` (167) — `fingerprintPlayer(state, owner = "player")` (`:53`) and | |
| `mirrorOfPlayer(state, {owner})` (`:162`) are already owner-parameterised. Useful for | |
| agent-vs-human matchmaking later. | |
| Also note the guard at `test/engine-purity.test.js:20-41`: it already extends the determinism scan | |
| to *browser-reachable* `tools/` files precisely because "bench" code started deciding persisted | |
| ratings. **The same guard should be extended to the server's sim entry point on day one.** | |
| ### Observer — IN, repurposed as the spectator client | |
| This is the highest-leverage "already written" asset in the tree. `observer.js`'s header states | |
| its contract exactly: it *"reveals fog on whichever world you're looking at"*, gives a free camera, | |
| *"deliberately does not touch `game.state`, `game.galaxy.activeId`, or the real input camera"*, | |
| and makes `input.js` refuse to issue a single order — every mouse/wheel/key path already | |
| early-returns into `observer.js` while `game.observerMode` is on. **That is a spectator client, | |
| already built and already tested** (`test/observer.test.js`, 23 tests). | |
| The change is one condition. `observer.js:128 enterObserverMode()` currently permits exactly two | |
| cases (an Odyssey, or a watched AI-vs-AI match) and refuses an ordinary skirmish because that | |
| would be a fog cheat. Add a third: *the server assigned this connection the spectator role*. The | |
| server then hands that connection an unfiltered projection, which is legitimate precisely because | |
| a spectator has no seat to cheat with. | |
| Justification for including it in v1: multiplayer needs spectating on day one, and **AI-agent | |
| matches make it a requirement, not a nicety** — an MCP agent playing a match is only interesting | |
| if a human can watch it. `observerPanel.js:89`'s two-entrant naming | |
| (`owner === "player" ? watch.aName : watch.bName`) is the only piece needing real work. | |
| --- | |
| ## 8. Offline / single-player preservation | |
| > **Yes — and it should be the primary design constraint, not an afterthought.** | |
| Two reasons. First, the game *is* the single-player game; shipping a port that can only run | |
| against a server throws away a working product. Second and more practically: of ~2,466 tests, | |
| roughly **1,735 are engine/tools tests** that drive `tick()` and `createGameState` directly, and | |
| roughly **731 are client tests** that drive the current client against a locally-constructed | |
| state (`test/input.test.js` 57, `test/hudSelection.test.js` 50, `test/boot.test.js` 29, | |
| `test/hud.test.js` 33, `test/renderShared.test.js` 34, `test/overlays.test.js` 26, | |
| `test/saveload.test.js` 24, `test/observer.test.js` 23 …). **If the client can no longer run its | |
| own sim, every one of those 731 tests needs a mock.** That is the single biggest risk in the port. | |
| ### 8.1 Recommendation — a loopback transport | |
| Define one interface and give it two implementations: | |
| ``` | |
| Transport { | |
| submit(envelope) // a command from this client's seat | |
| onSnapshot(fn) // state deliveries | |
| onMatchStart(fn) / onMatchEnd(fn) | |
| seat, seats, role | |
| } | |
| ``` | |
| - **`LoopbackTransport`** — constructs the state in-process with `createGameState`, runs | |
| `createLoop`/`tick` exactly as `boot.js:485-531` does today, and `submit` **applies the command | |
| synchronously, in the caller's stack frame**, by calling the same `issue*` the client calls | |
| today. Behaviourally byte-identical to the current game. | |
| - **`SocketTransport`** — serializes envelopes, applies snapshots. | |
| ### 8.2 Why this keeps the tests meaningful | |
| The seam is placed at exactly two points, and both preserve today's *observable* semantics: | |
| 1. **Command submission.** Because `LoopbackTransport.submit` mutates before returning, every | |
| existing client test that asserts "after this click, the unit has this order" **still passes | |
| unchanged**. This is the whole trick: keep the loopback synchronous. | |
| 2. **State delivery.** `boot.js`'s `update` callback (`:499-532`) becomes transport-driven. | |
| `snapshotPositions(game.state)` (`:501`) must run before either a local tick or an applied | |
| snapshot — one ordering rule, easy to pin with a test. | |
| Add one new engine function, `applyCommand(state, seat, envelope)`, that resolves ids → entities, | |
| **filters to `seat`-owned entities**, and calls the unchanged `issue*`. Then: | |
| - `test/commands.test.js` (503 LOC) keeps testing `issue*` directly — untouched. | |
| - One new test file pins envelope → `issue*` and the ownership filter (which is *new* safety | |
| the game has never had: today nothing stops a client from ordering enemy units, because there | |
| is no adversary). | |
| - `test/input.test.js`, `test/hudSelection.test.js`, `test/boot.test.js` keep working against the | |
| loopback. | |
| **The one unavoidable test churn is `state.selection`** (§1.3): 124 test references. Moving it to | |
| the client session is mechanical but wide. Budget for it explicitly; do it as its own change, | |
| before the transport work, so the diff is reviewable. | |
| ### 8.3 What single-player retains | |
| With a loopback transport, **the full offline game keeps working**: skirmish, all three scenarios | |
| (`boot.js:234, 242, 250`), the whole Odyssey (`boot.js:259`), the competition ladder and its Web | |
| Worker duels, file save/load, and localStorage Continue. `saveShape.js:28`'s `netMatch` term | |
| (§6.2) is exactly what keeps the two worlds from contaminating each other. The Hugging Face Space | |
| can therefore serve one bundle that plays offline *and* connects — and the offline path is also | |
| the fastest development loop for anyone working on the renderers or the HUD. | |
| --- | |
| ## 9. Summary table | |
| Verdicts: **verbatim** (0–2 changed lines) · **light** (a rename sweep, no restructuring) · | |
| **heavy** (real rework) · **server-side** (moves out of the browser) · | |
| **out-v1** (untouched, offline-only) | |
| | Module | LOC | Verdict | Why | | |
| |---|---|---|---| | |
| | `engine/` (all 49 files) | 15,659 | **server-side** | Runs headless. Needs: `applyCommand` dispatcher, `projectFor(state, seat)`, N-entry `ownerDefs` (`state.js:174`), owner-generic `updateFog` loop (`sim.js:70`), N start bases (`map.js`), `attackHit` target owner (`combat.js`) | | |
| | `style.css` | 1,732 | **verbatim** | 3 team-colour hits; add N-seat variables | | |
| | `index.html` | 83 | **light** | Add a lobby container; hide save/load in MP | | |
| | `sound.js` | 181 | **verbatim** | Zero imports | | |
| | `effects.js` | 183 | **verbatim** | Zero imports | | |
| | `camera.js` | 105 | **verbatim** | Zero imports | | |
| | `data.js` | 242 | **verbatim** | Static tables | | |
| | `dom.js` | 68 | **verbatim** | Already Node-safe (`dom.js:11-18`) | | |
| | `version.js` | 60 | **verbatim** | | | |
| | `update.js` | 108 | **verbatim** | Self-wired version chip | | |
| | `saveShape.js` | 31 | **verbatim** | +1 term: `netMatch` (`:28`) | | |
| | `renderShared.js` | 255 | **verbatim** | `:254` only; + `pruneFacing` grace window (§4.2) | | |
| | `renderNodes.js` | 171 | **verbatim** | `:26` only | | |
| | `minimap.js` | 138 | **verbatim** | `:94, :99` | | |
| | `render.js` | 277 | **verbatim** | `:202` (`state.fog` → `fogs[seat]`) | | |
| | `renderUnits.js` | 699 | **verbatim** | `:91`; colour already generic at `:66` | | |
| | `renderBuildings.js` | 807 | **verbatim** | 6 owner lines; colour generic at `:75` | | |
| | `renderEffects.js` | 683 | **verbatim** | 5 owner lines | | |
| | `techChart.js` | 366 | **verbatim** | `:36` `OWNER`; stop pausing in MP | | |
| | `elo.js` | 147 | **server-side** | Pure; lift verbatim when ranking lands | | |
| | `pairing.js` | 518 | **server-side** | Pure; lift verbatim when ranking lands | | |
| | `playerFingerprint.js` | 167 | **out-v1** | Already owner-parameterised (`:53, :162`); useful later | | |
| | `session.js` | 120 | **light** | Additive: `seat`, `seats`, `role`, `transport`, `selection` | | |
| | `main.js` | 168 | **light** | `:145-151` minimap command → submit | | |
| | `hud.js` | 452 | **light** | 9 owner literals; score bar → roster; `:37, :38` → commands | | |
| | `hudPanelSignature.js` | 380 | **light** | 4 owner literals + `players.player` reads | | |
| | `overlays.js` | 585 | **light** | `:34, :68-81, :376, :392-394, :406-407`; N-seat game-over copy | | |
| | `observer.js` | 304 | **light** | `:128` gains a third permitted case → the spectator client | | |
| | `observerPanel.js` | 246 | **light** | `:89` two-entrant naming → N-seat | | |
| | `inputCommands.js` | 288 | **heavy** | 13 `issue*` + 5 selection writes + 16 owner literals; becomes the command constructor | | |
| | `input.js` | 588 | **heavy** | 6 `issue*` + 6 selection writes + 5 owner literals; gesture/camera/touch untouched | | |
| | `setup.js` | 462 | **heavy** | Splits: lobby form + (verbatim) option tables | | |
| | `saveload.js` | 371 | **heavy** | MP: off. SP: unchanged. Server reuses `engine/persist.js` | | |
| | `boot.js` | 788 | **heavy** | Lifecycle inversion; the single biggest file of real work | | |
| | `hudSelection.js` | 1,998 | **heavy** (~1,050) / **out-v1** (~950) | ~30 mutator calls in the skirmish half; the Odyssey panels are untouched | | |
| | `starmap.js` | 318 | **out-v1** | Odyssey | | |
| | `landingPicker.js` | 211 | **out-v1** | Odyssey | | |
| | `competition.js` | 3,773 | **out-v1** | Single-player ladder screen | | |
| | `competitionLedger.js` | 1,290 | **out-v1** | localStorage Elo ledger — forgeable, SP-only | | |
| | `competitionWorker.js` | 355 | **out-v1** | Read as prior art for the headless server sim | | |
| | `tools/` (`selfplay`, `duelCore`, `genome`, `ailab`, `serve`, `smoke`) | 3,593 | **out-v1** | `selfplay.js`/`duelCore.js` are the closest existing thing to the server runner | | |
| | `test/` | 43,101 | **preserve** | ~1,735 engine tests unaffected; ~731 client tests preserved by the synchronous loopback (§8) | | |
| **Totals:** verbatim/near-verbatim ≈ **6,900 LOC (39 % of shipped client JS)** · | |
| light sweep ≈ **2,700 (15 %)** · heavy ≈ **4,500 (25 %)** · out-v1 ≈ **3,800 (21 %)** · | |
| plus 15,659 LOC of engine relocated intact and 1,732 LOC of CSS untouched. | |
| --- | |
| ## 10. Ordered recommendations | |
| 1. **Move `state.selection` off the sim state first.** 10 write sites, 32 client reads, 2 engine | |
| reads, 124 test references. It is the widest mechanical change and it is independent of | |
| everything else — do it as its own reviewable diff, before the transport. | |
| 2. **Add `applyCommand(state, seat, envelope)` to `engine/commands.js`**, with the | |
| **seat-ownership filter** that does not exist today. Keep every `issue*` unchanged so | |
| `test/commands.test.js` is untouched. | |
| 3. **Introduce `Transport` with `LoopbackTransport` first.** Land the whole port against | |
| loopback before a socket exists. The client tests are the regression suite. | |
| 4. **Sweep the owner literals** behind `session.seat` / `isMine(e)` (§3.1). ~70 one-liners with | |
| heavy existing coverage. | |
| 5. **Make the engine N-seat**: `ownerDefs` (`engine/state.js:174`), the `updateFog` loop | |
| (`engine/sim.js:70`), N start bases (`engine/map.js`), and `attackHit`'s target owner | |
| (`engine/combat.js`). `test/ownerScaffold.test.js` is the spec that already exists. | |
| 6. **Write `projectFor(state, seat)` and prove it renders identically to the full state** | |
| before anything depends on it (M0 in §4.4). | |
| 7. **Record the command log from day one.** It is nearly free once commands are envelopes, it | |
| is the replay format, the anti-cheat audit trail, and the MCP agent's trace. | |
| 8. **Extend `test/engine-purity.test.js`'s reachability walk to the server entry point** the | |
| moment it exists. The guard's own comment (`:20-41`) explains what happened last time a | |
| "bench" file started deciding real outcomes. | |
| 9. **Defer Odyssey and the competition ladder; keep both alive on the loopback path.** They cost | |
| nothing to keep and protect ~1,000 tests over shared engine code. | |
| 10. **Ship the spectator seat in v1** by widening `observer.js:128`. It is already written, | |
| already tested, and AI-agent matches make it a requirement rather than a nicety. | |