README.md

Stellar Frontier: RTS

A browser-based real-time strategy game set in the same universe as Stellar Frontier (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 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 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 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 and 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.