# Orbit

> A procedurally generated space RPG in the spirit of *Privateer*, in
> top-down 2D. Built with **Phaser 4** as plain **ES6 modules** — no build
> step, no package managers required to run.

## Run it

Any static file server works (Python, Node, Caddy, nginx, …):

```sh
cd orbit
python3 -m http.server 8080
# → http://localhost:8080
```

> Must be served over **http(s)** — opening `index.html` via `file://` won't
> work, because the game uses ES modules and `fetch`es its JSON config.

## Current state — v0.2: a seedable galaxy

- Main menu with **Continue** (resumes the newest save — grayed out while
  the save bank is empty), **New Game**, **Load Game** (the full slot
  bank), and a **Galaxy Seed** panel: the seed is displayed, editable
  (click it and type), and rerollable — and the menu shows what that seed
  builds (the galaxy's name, system count, archetype count) **before** you
  commit. Same seed ⇒ same galaxy.
- **Procedural galaxy**: 40,000 star systems in a seeded disk + core +
  spiral arms (`data/galaxy.json`), typed into six themed archetypes
  (`data/systems.json`) with per-type distribution weights and radial
  bands — the first "how does the galaxy lay itself out" rules.
- **Two-level generation**: the whole galaxy roster is generated at New
  Game (~70 ms); each system's planets/moons/belts/settlements are
  generated lazily on arrival, deterministically (seed + system id), so
  lazy and eager give identical results.
- **A lived-in galaxy**: the galaxy was settled long before you arrive.
  Systems host colonies on habitable worlds, mining stations over resource
  worlds, cloud bases riding gas giants, stations adrift in open space, and
  beacons — or report *charted · unclaimed* when nobody's there. Rates are
  per-archetype (`data/systems.json`) and thin out from the settled core to
  the wilder rim (`data/galaxy.json`). Each settlement has a name,
  population, and an `owner` seam reserved for the factions/pirates to come.
  The current system's dossier (name, identity, what's there) shows
  top-left in the game scene.
- **Names with a point of view** (`data/naming.json`): planets draw from a
  deep curated bank — colonial "New Denver" worlds beside alien "Klaxoria"
  worlds — and stations from a bank of official designations ("Deep Space
  SC-145") and smuggler hangouts ("Hell's Hideout"). Names are dealt out
  randomly per system **without repeats until the bank is exhausted** (a
  seeded shuffle, so the first N draws are N distinct names). Stars and the
  galaxy itself are still synthesised from syllable pools, so you never run
  out of those. Within a system a planet never shares a name with another
  planet and a station never with another station.
- Game screen with a top-down ship (real spritesheet art — frame 0 of
  `assets/images/ships-player.png`, see `data/ship.json`): **click anywhere to fly there**
  in the current system's open space (system boundaries/jumps come next).
  Discovered worlds get a screen-edge arrow + a name tag showing the
  world's **name** (e.g. `HOME WORLD · ESHKAELURA`); **clicking the
  name tag autopilots the ship there** (it arrives on the keep-out rim,
  facing the world)
- **The home planet** — the player's world — in the system you start in:
  a 1024 px disc rendered 1:1 from the `assets/images/planets.png`
  spritesheet, with a **proper name drawn from the planet name bank** (the
  first name off the starting system's deck, so it never clashes with one
  of the other worlds). Which Terran face it shows (frames 0–2) is a
  seed-deterministic pick, so the same galaxy always yields the same home
  world. The ship spawns ~150 px (edge-to-edge) off its rim in a
  seed-derived direction, may fly in as close as 50 px from the rim, and
  can never cross it — a planet is solid (tuning in `data/planets.json`)
- **The tether — your range.** You start with a level-1 tether anchored
  on the home world: a circular zone, **5120 px from the planet's center**
  (`data/tether.json`). The ship cannot leave it — anywhere in the union
  of its tethers' zones is open space (where zones overlap there is no
  line and no wall), and the rim is a hard barrier rendered as a thick,
  glitchy, marching dotted line (neon core + RGB fringe + ambient glitch
  bursts, contact shudder where the ship bumps it). Click-to-fly and
  autopilot targets are clamped to the union boundary, so a world outside
  your range is where the ship parks — on the line — until a tether grows.
  Upgrades and extra anchors (planets/stations) plug into
  `TetherField.add/setLevel` (tuning in `data/tether.json`)
- **The Research console** — the **RESEARCH** deck button opens a full-screen
  window: the left pane loops the muted `assets/videos/research-computer.mp4`
  archive feed (scanlines, sweep band, REC pulse, glitch bursts), the right
  pane holds the category tabs and the **branching tech tree** for the
  selected category — it starts at the top and unlocks downward, one branch
  at a time. Selecting a tech shows its dossier (icon + description +
  duration) and a **RESEARCH** button, which appears only when the tech is
  researchable and nothing else is in progress (one project at a time,
  `maxConcurrent: 1`). A deck progress bar tracks the run; completion fires
  the tech's `effects` (e.g. `tether: {level: N}` grows the home tether's
  range) and a toast. Each category's tree is its own JSON file under
  `data/research/` (the first is **Exploration**: Tether Level 1–4,
  Tether Anchoring, Signal Amplification). Unlocks and in-progress work
  persist in the save bank — and resume correctly on load
- Camera gently trails the ship; the **parallax starfield** streams past
  while it flies and the view slowly recenters (≈1.5 s) once the ship
  comes to rest
- Config-driven setup: every tunable value lives in `data/*.json`

## Project layout

```
orbit/
├── index.html              # boots the game
├── data/                   # ← ALL tunable config (edit these freely)
│   ├── manifest.json       #   which config files exist
│   ├── game.json           #   dimensions, colors, starfield, …
│   ├── menu.json           #   menu text, colors, button layout, seed panel
│   ├── theme.json          #   shared UI theme: fonts, palette, CRT/glitch tuning
│   ├── ship.json           #   the ship: art, feel (thrust, drag, maxSpeed…), base stats (hull, shields, cargo, minerals)
│   ├── planets.json        #   home world + system layout + solid-disc rules
│   ├── tether.json         #   the tether (your range): level radii, barrier line, glitch, contact
│   ├── galaxy.json         #   galaxy scale & shape (count, radius, spiral…)
│   ├── systems.json        #   system archetypes: theme, attributes, distribution
│   ├── settlements.json    #   the lived-in layer: settlement kinds & populations
│   ├── research.json       #   RESEARCH: global rules (time unit, one at a time) + category registry
│   │                       #   trees live one-per-file below (section name = file basename)
│   ├── research/
│   │   └── exploration.json#   the Exploration tree: tether levels, anchoring, signal amp
│   ├── builds.json         #   BUILDING: credits + minerals, ship/planet/station upgrades
│   ├── actionbar.json      #   the command deck: 6 slots (Research, Scan, Ship, ·, ·, Menu)
│   └── naming.json         #   names: star/galaxy syllable pools + the curated PLANET & STATION name banks
├── assets/images/          # art: planets.png (1024×1024 frames), ships-player.png (256×256 frames)
├── assets/fonts/           # UI typefaces: Ethnocentric (headers), Centauri (body)
├── lib/                    # vendored third-party libs (Phaser 4.2.1)
├── js/
│   ├── main.js             # entry point: load config → boot Phaser
│   ├── config/             # Config singleton, ConfigLoader, game config
│   ├── scenes/             # MenuScene, GameScene (thin, orchestration)
│   ├── entities/           # Ship (own behavior), Planet (home world, solid)
│   ├── galaxy/             # Galaxy (seeded world model), SystemGenerator, SystemReport
│   ├── tether/             # Tether (pure range math) + TetherField (constraint + barrier line)
│   ├── research/           # ResearchModel (pure tree rules/layout), ResearchState (unlocks + active run), ResearchIcons
│   ├── ui/                 # MenuButton, GlitchText, CyberShape, ActionBar, DiscoveryCompass (reusable), ResearchWindow
│   ├── visuals/            # Starfield, CyberOverlay (CRT/glitch, shared)
│   ├── utils/              # small pure helpers (Color, Rng, NameGenerator)
│   └── vendor/             # shim to the vendored Phaser
└── docs/PROJECT_NOTES.md   # ← project conventions: read this
```

## Conventions (short version)

- **Config in JSON.** If a value might change, it goes in `data/`, not code.
  Add a file = one line in `data/manifest.json`.
- **One class per file**, ES modules, scenes stay thin, entities own their
  behavior. Details in [`docs/PROJECT_NOTES.md`](docs/PROJECT_NOTES.md).
- Phaser is imported only via `js/vendor/phaser.js` (one-file version swap).

## The player's loop: research + building

Beyond flying, Orbit is built around two progression verbs:

- **Research** (`data/research.json` + `data/research/<category>.json`) —
  *time-based*. A project takes a fixed `duration` (`timeUnit: seconds`);
  the player researches **one thing at a time** (`maxConcurrent: 1`).
  Research is the gate: it unlocks **builds** and **further research**
  (each category tree is a DAG — a node's `requires` must be unlocked
  first). The RESEARCH deck button opens the console window
  (`js/ui/ResearchWindow.js`): looping archive feed, category tabs, the
  branching tree, per-tech dossier + RESEARCH button, and a deck progress
  bar. The rules are pure (`js/research/ResearchModel.js`,
  `ResearchState.js` — Node-testable); the window is a passive view that
  asks `GameScene` to start a run. `effects` on a finished node carry the
  payload (e.g. `{ tether: { level: 2 } }` → `TetherField.setLevel`), so new
  effect kinds plug in without touching the tree data.
- **Building** (`data/builds.json`) — *cost-based*, paid in **credits and
  minerals** (`resources`). A build improves the **ship**, a **planet**, or a
  **space station** (`category`). `builds` is an empty map; the `_template`
  entry documents the shape (including `repeatable`, for things like extra
  mining rigs). The build UI is next — the research side is live now.
- **The command deck** (`data/actionbar.json`, rendered by
  `js/ui/ActionBar.js`) — the cyberpunk bar across the bottom of the screen.
  Six evenly spaced slots: **Research, Scan, Ship, ·, ·, Menu**. The slots
  fire `onAction` and are otherwise inert; two slots are reserved. Dressed
  with the menu's CRT language — scanlines over the strip and the GlitchText
  RGB pull-apart on labels and the panel outline during bursts. All
  layout, palette, and motion (boot flicker, rail comet, glitch bursts, RGB
  split, scanlines) live in the config.

`_`-prefixed keys (`_comment`, `_template`, …) are documentation, not
runtime data — loaders and tests ignore them.

## Dev tools

```sh
node dev/ship-behavior.test.mjs   # runs the real Ship.update() loop in Node
node dev/starfield.test.mjs       # runs the real Starfield.create() in Node
node dev/galaxy.test.mjs          # galaxy determinism, distribution, lazy vs eager
node dev/discovery.test.mjs       # discovery rules + compass geometry + chip hit test
node dev/tether.test.mjs          # tether range math: union, clamp, visible arcs (no line in overlaps)
node dev/research-builds.test.mjs # data contract: research/builds/actionbar shapes + manifest
node dev/decode.test.mjs          # the shared decode scramble (menu seed + system dossier)
node dev/system-hud.test.mjs      # real GameScene dossier: layout + staggered decode to final report
node dev/sfx.test.mjs             # the shared SFX voice: guards + sfx.json keys/files
node dev/music.test.mjs           # the shared music voice: guards + music.json contract
```

`dev/test-game.html` boots straight into the GameScene (no menu click),
handy for manual testing of the flight feel. `dev/research-shot.html`
does the same but opens the Research console and starts a run, and
`dev/cdp-shot.mjs` waits for a readiness expression before screenshotting
through CDP (any Chromium-CDP browser on `127.0.0.1:9333`):

```sh
node dev/cdp-shot.mjs "http://127.0.0.1:8081/dev/research-shot.html" shot.png \
  "window.__RESEARCH_SHOT && window.__RESEARCH_SHOT.ready" 90000
```

## Phaser

Phaser 4.2.1 is vendored at `lib/phaser.min.js` (UMD build, MIT license —
see `lib/PHASER_LICENSE.md`). No internet or npm needed at runtime.