Blame for README.md

# Stellar Frontier: RTS

A browser-based real-time strategy game set in the same universe as
[Stellar Frontier](https://github.com/alma92350/SpaceExploration) (the turn-based space
trading/exploration game) — a separate, standalone game, not a mode bolted onto the original.
Vanilla JavaScript, ES modules, **no build step, no dependencies**. Play a 1v1 skirmish against a
scripted AI, or an open-ended **Odyssey** that strings worlds together into a galaxy you settle,
trade across, and conquer.

## Running it

The game has no build step, but it loads as ES modules, which browsers refuse to import over
`file://` — so it needs to be served over HTTP. A zero-dependency dev server ships with the repo:

```
npm start          # serves at http://localhost:8080
```

Nothing to install first — no `npm install`. (Any static server works too: `npx serve .` or
`python3 -m http.server`.) Then open the printed URL. Requires Node ≥ 20.

## Tests

```
npm test
```

Runs the full suite (`node --test`): the engine's unit and integration tests — including a full
simulated skirmish played out to a winner and a galaxy played across multiple worlds — plus the
determinism, purity, and static-integrity guards. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
invariants those guard.

```
npm run typecheck
```

Type-checks the JSDoc-annotated files against the shared shapes in `engine/types.js`
(`tsc -p jsconfig.json`; needs a TypeScript compiler on the path, or `npx -y typescript`). CI runs
it as a required step alongside the suite, so it is worth running before you push.

## The skirmish

A 1v1 real-time match against a scripted AI on one of nine charted worlds, picked at the start.
Gather ore/crystals/radioactives with Workers, build a Barracks, produce a mixed army, expand and
fortify, fight under fog of war, and win by destroying the enemy's last Command Center (or lose
yours). A defensive stall can't run forever: if neither side is finished off, a match time limit
settles it on score (banked resources plus the built value of everything you own), so there's
always a terminal state.

The splash screen configures the skirmish before you pick a world. **AI speed** is a 1–150
actions-per-minute cap on the opponent — every command it takes (produce, build, expand, research,
scout) spends one action, so a low setting is a sluggish, forgiving foe and a high one relentless
(its attack commit is exempt, so it always resolves the game). **Map size** scales the field from
Small (1600×1000) up to Gigantic (4×) with more caches in the bigger space, **Resources**
(Rare / Normal / Abundant) scales every deposit's yield, and **Match length** picks Quick (20 min),
Standard (40 min), or Marathon (60 min) instead of always the same fixed clock — the final 5
minutes flip the readout to a countdown next to a live score bar either way. Whatever the world,
every map guarantees a near-base surface source of ore, crystals, and radioactives so all builds
are possible — the planet's own deposit table just shapes how much of each there is. Oort's and
Nimbus's asymmetric matchups also offer a side-swap toggle, so either half is playable from either
seat.

**Units.** Four combat units. Three form a genuine rock-paper-scissors triangle, not just a single
hard counter: Skiff (fast, cheap) beats Lancer, Bastion (slow, short-ranged, tanky) beats Skiff,
and Lancer (long-ranged, armor-piercing) beats Bastion — each unit's bonus damage targets exactly
the matchup that would otherwise be its worst, and nothing beats all three at once. The fourth, the
Breacher, sits deliberately *outside* the triangle: a slow siege platform that outranges static
defenses and tears through buildings, but has the worst anti-unit damage in the game and folds to
massed Skiffs for a fraction of its cost — a turtle-breaker that's helpless without an escort.
Scouting what the enemy is building, and countering it, matters.

**Veterancy.** Every confirmed kill counts toward a unit's own record — three permanent ranks
(earned at 3, 8, and 18 kills) each layer roughly the same compounding bonus, stacking to about
+19% damage dealt and −17% taken at max rank, visible as small chevrons over the health bar.
Turrets and buildings never rank up; only units that can actually fight do, and the bonus survives
repair, so a bloodied army is worth pulling back to heal rather than replacing.

**Tech: doctrines and structures.** A Refinery (built by a Worker, like the Barracks) researches
army-wide upgrades — timed rather than instant now (scaled by the world's own tech rating, so a
Refinery mid-research is a real, raidable window), applied live the moment each finishes, not just
to future production — but they're three **mutually-exclusive doctrines**, so this is a real
commitment, not a buy-both. **Assault** (Overcharged Weapons → Overcharged Core → Overdrive
Actuators) stacks more damage dealt and eventually faster attacks; **Bulwark** (Reinforced Plating →
Reinforced Bulwark → Self-Sealing Plating) stacks less damage taken and adds out-of-combat regen —
by every unit AND every structure, turrets and the Command Center and Habitats included, so it's the
turtle doctrine for your base as much as your army. **Logistics** trades combat power for economy
and tempo instead. Researching one locks out the other two, and each now runs a full three tiers
deep, the last gated behind an Arsenal. Assault costs radioactives and Bulwark crystals, so a
world's deposit specialty (Korrath has no crystals, Vesper no radioactives) tilts which doctrine
comes easier. Beyond the Refinery, a Foundry and a Datacenter open further research — crystals and
radioactives fund all of it, so those deposits never dead-end.

**Expanding and fortifying.** The Command Center is buildable (steep — 400 ore, slow to raise), so
taking a second base is a real mid-game decision: nodes deplete, and a fresh field plus a fresh
drop-off point is how you outlast a drained home economy. Static defense now runs three tiers: the
Sentinel Turret (crystal-funded), the Foundry-gated Bastille (tankier and harder-hitting but
shorter-ranged), and the Arsenal-gated Aegis Bastion (fires nothing — it just shields everything
friendly nearby, units and structures alike, by 20%) — all of it makes raids cost something and
base layout matter, and the Breacher remains the answer to a wall of any of them, since every siege
unit still strictly outranges every static-defense structure.

**Supply.** Army size is capped by supply, not just ore: every unit costs some, Command Centers
grant a baseline, and a cheap Habitat raises the ceiling. It's a genuine macro choice (army now vs.
infrastructure now), a raidable weak point (burn a Habitat and push someone over their cap), and it
keeps late-game battles bounded. Losing a Habitat can leave you legally over cap — nothing dies,
but production blocks until you rebuild.

**The AI.** Each world gives the AI a different temperament — Rusher (small economy, commits
early), Economist (out-scales before attacking, expands and turtles behind turrets), Balanced, or
the Kybernet-only Technologist (small and teched-up — the only archetype that ever fields a
Colossus) — and it plays the whole toolkit: it attacks in repeated waves, not just once; it scouts
and reacts to whatever combat type you field most, a hard counter inside the Skiff/Bastion/Lancer
triangle and a documented cost-efficient answer (usually massed Skiffs) for anything outside it,
including a wall of your own turrets — more often the higher the difficulty, never on Easy; and it
expands when its home ore runs thin, fortifies the approach lane with turrets (and Bastilles, once
it has a Foundry), runs multiple Barracks, and raises Habitats to stay under supply. It plays under
its own fog too — not omniscient — reacting only to what it has actually seen.

**Worlds.** Six of the nine worlds carry a single rule modifier that applies to both sides —
Glacius's ice slows everyone, Nimbus's storms shorten sight, Pyralis's open dunes lengthen it, Helix
packs an extra crystal field, Oort's deposits run rich, and Forge's industry speeds construction.
Six also carry **terrain**: rough ground you cross slower (never impassable — it slows and shapes,
it doesn't wall) and high ground that sees farther and hits harder — real objectives to seize.
Terrain is mirrored, so both sides face the same ground, and you can't build on rough ground, so
base layout has to work around it. Two worlds are **asymmetric matchups** where the modifier hits
the sides *differently* (Oort: you out-mine, they out-build; Nimbus: you out-scout, they
out-tempo), so which corner you start in defines your plan. The three original worlds (Ferros,
Korrath, Vesper) stay clean open plains.

**Fog & caches.** Fog of war hides enemy units and buildings outside your vision. The charted
surface deposits near each base are always shown — map knowledge, not battlefield intel — but the
map also hides resource **caches** in the contested middle and along the edges: extra deposits the
survey missed, invisible until one of your units scouts their location, then marked permanently.
They often hold the crystals or radioactives a world's surface lacks, so scouting can unlock a
resource — and the tech that needs it — you'd otherwise have no access to.

### Controls

Left-drag to select (Ctrl+drag adds to the selection, Alt+drag subtracts), right-click to move or
gather/assist-build/attack/set-rally depending on what's selected and under the cursor,
Ctrl+right-click to queue that order as a waypoint (chain several to lay down a path — combat units
attack-move along it), mouse wheel to zoom, WASD/arrow keys or the screen edge to pan. Control
groups bind with Shift+1–9 and recall with 1–9; double-click a unit to grab every on-screen unit of
that type (Ctrl+double-click extends the grab to the whole map, not just what's on screen); **Q**
selects your whole army, **X** halts the selection, **R** turns a selection's already-queued
waypoint path into a looping patrol, **`** cycles idle workers, **Space** centers on (and cycles
through) your bases, **Backspace** jumps to the most recent attack ping, **T** opens a full Tech &
Industry Chart overlay, and **P** pauses. Right-click the minimap to order the selection somewhere
off-screen. Click a Worker or a completed building for build/produce/research options in the side
panel (unaffordable options are greyed out); a full controls reference sits in the panel whenever
nothing is selected, and **F1** or **?** opens the help overlay.

## The Odyssey

The Odyssey is the open-world meta-layer: instead of a single match, you play a whole galaxy. Pick
your starting world from a card row of all 11 (or roll randomly), and every world is a full
skirmish map — but they never resolve by conquest or clock. Instead you hold **universal credits**
that travel with you, build a **Spaceport**, and **jump** to another world (jumps cost fuel, scaled
by distance and discounted up to 30% by your Spaceport's tier, funded by trading commodities at the
market). Settle a new world by carrying a **colony ship** on the jump and deploying it into a
Command Center; the world you leave becomes a **background colony** that keeps working, pays you
passive income while you're away, and can be handed standing orders (an auto-sell floor, a worker
headcount to sustain) so it keeps developing unattended.

The galaxy is alive before you visit it, but not all of it at once: alongside your seat, three
other worlds — a pseudo-random draw from the galaxy seed, so which three is part of what that seed
means — develop, trade and drift diplomatically in the background from turn one, and every world
you've been to keeps running after you leave. The rest of the roster stays dormant until you jump
there, then joins the living galaxy too.

Each world's neighbour has its own **diplomacy** — a grace period, grievances if you strip-mine or
attack, forgiveness that varies by personality, paid tribute truces, and now gifts plus occasional
favor requests as an actual road to Allied (which also trades at a tighter market spread) — so how
you treat a world shapes whether it turns hostile and sends waves after you. A developed neighbour
on Hard, or a patient one on any difficulty but Easy, can even race its own Antimatter Gate; if it
finishes, that faction claims the galaxy's unclaimed worlds in one burst and its stance toward you
locks cold for good. There's no hard win: the Odyssey is a **play-forever sandbox**, and progress is
marked by milestone fireworks — colonies founded, an **Antimatter Gate** coming online, and
**conquest domination** as you pacify neighbour after neighbour (a pacified world can never be
dragged back to war, quietly pays you a small annuity, and ripples its faction's standing toward
you) — that you keep playing past. Press **O** any time to flip into **Observer Mode**, a free-look
spectator camera over the whole galaxy with a live stats readout, if you'd rather watch the AI
factions develop than play a hand yourself. The world roster is the nine skirmish worlds plus two
Odyssey-only extras (a research capital and an agri world).

Aiming to pacify all 11? See
[docs/odyssey-conquest-strategy.md](docs/odyssey-conquest-strategy.md) for a full campaign playbook
against Hard difficulty, sourced from the engine and from real `tools/ailab.js` probes.

## Saves

Because the sim is deterministic and seed-driven, a save is just the serialized dynamic state — the
map regenerates from the seed on load, so saves stay small. Two channels:

- **Autosave** keeps the current game in browser `localStorage` on a timer (and on tab-hide /
  unload), so the map-select **Continue** buttons resume exactly where you left off — no manual
  save. Skirmish and Odyssey each have their own slot.
- **Save / Load** buttons move a save to and from a `.json` **file** — an explicit backup or
  transfer you keep on disk. A file import auto-detects whether it's a skirmish or a whole galaxy by
  its shape.

Saves are untrusted input: every load is sanitized and coerced (bad types dropped, numbers clamped)
before it touches the running game. Version checking is exact-match, not migration — a save whose
`v` doesn't equal the current `SAVE_VERSION`/`GALAXY_SAVE_VERSION` is rejected outright rather than
loaded into a broken state, with no attempt to translate it forward.

## Versioning

`version.js` holds `APP_VERSION` (the running build's semver) and is kept in sync with
`version.json`; an in-app update check compares the deployed `version.json` against the baked-in
value and tells you when a newer build is live — and whether it keeps your saves. Save-format
versions (`SAVE_VERSION` for skirmish, `GALAXY_SAVE_VERSION` for Odyssey) live in
`engine/persist.js` and are bumped independently whenever a save's shape changes in a way older
saves can't survive. Bumping either is a hard compatibility break: the loader requires an exact
version match and rejects anything else outright, with no migration and no partial tolerance —
which is what that "whether it keeps your saves" note above is warning you about. See
[CHANGELOG.md](CHANGELOG.md) for release history.

## Project layout

- `engine/` — the simulation: pure, deterministic, DOM-free logic. Fixed-timestep loop, movement +
  local avoidance, gather, combat, production, supply, placement validation, fog of war, AI, the
  market, diplomacy, colony/jump mechanics, and save serialization. Runs headless under
  `node --test`.
- `main.js` — **the page's only entry point** (`index.html` loads it and nothing else). Its
  side-effect-only imports (`starmap.js`, `techChart.js`, `update.js`) are load-bearing: those
  modules self-wire their buttons and hotkeys at module-load time, so dropping one silently
  disables a feature rather than raising an error.
- `render.js` / `renderUnits.js` / `renderBuildings.js` / `renderEffects.js` / `renderNodes.js` /
  `renderShared.js` / `minimap.js` / `camera.js` / `effects.js` — the canvas view. `render.js`
  orchestrates the frame; the `render*.js` family draws units, buildings, effects and nodes; there
  are no images, every silhouette is vector drawing code.
- `input.js` / `inputCommands.js` — mouse/keyboard/touch controls. `input.js` owns the stateful
  half (drag boxes, pinch gestures, held keys, control groups); `inputCommands.js` owns the
  stateless half — what is at a point, and what the right-click command ladder does about it.
- `hud.js` / `hudSelection.js` / `hudPanelSignature.js` / `overlays.js` / `setup.js` /
  `landingPicker.js` / `observerPanel.js` / `techChart.js` / `starmap.js` / `dom.js` — UI chrome.
  `hudSelection.js` owns the selection panel: one `render*` function per panel family, dispatched
  by `rebuildSelectionPanel`, with `hudPanelSignature.js` deciding when a rebuild is needed at all.
- `boot.js` / `session.js` / `saveload.js` / `update.js` / `version.js` / `saveShape.js` — wiring
  the sim to the page, session state, save/load, and the version/auto-update check.
- `sound.js` / `observer.js` — audio cues and Observer Mode.
- `data.js` — pure content (factions, the commodity catalog, production recipes, the charted
  worlds).
- `tools/serve.js` / `tools/ailab.js` / `tools/selfplay-cli.js` — Node CLI benches, never loaded by
  the browser: the zero-dependency dev server behind `npm start`, and a headless AI bench that runs
  the sim without a browser, scores the opponent over a long session, A/B-tests candidate AIs
  supplied as JSON, and evolves new ones. See [docs/odyssey-ai-review.md](docs/odyssey-ai-review.md)
  and [docs/ai-evolution-design.md](docs/ai-evolution-design.md).
- `tools/selfplay.js` / `tools/duelCore.js` / `tools/genome.js` — **shipped code that happens to live
  under `tools/`**, not benches. They run a match headlessly, which is what the CLI wants *and* what
  the in-browser competition Worker (`competitionWorker.js`) wants, so `boot.js`, `competition.js`
  and `playerFingerprint.js` import them too. Because a duel's outcome becomes a persisted Elo
  rating, they carry the same determinism and DOM-free requirements as `engine/`, and
  `test/engine-purity.test.js` scans them alongside it.

## Background: why a separate repo

The original game has no build step and no module system: ~30 script-tag files all read and mutate
one global state singleton, built entirely around discrete player-action "cycles." A real-time game
needs a wall-clock delta-time loop and a different state/update model, so retrofitting it would mean
a large, risky rewrite of a game that already works. This repo starts clean instead — same universe,
new engine.

What carried over: `data.js` (copied verbatim — genuinely pure data with zero dependency on the
original's turn/state engine) and the `style.css` `:root` colour palette (so the two games read as
the same universe). `catalogs.js` and `galaxygen.js` were **not** copied — they look like reusable
content tables but are logic-coupled to the original's global state and turn/political systems, so
copying them would just import dead or broken references. Anything worth reusing from them is design
inspiration to rebuild deliberately for a real-time model, not code to drag over.

## License

[MIT](LICENSE).