Add design spec for probability-based space trading sim

2026-06-12 13:26:23 +00:00
commit 7358ee322e
1 changed files with 161 additions and 0 deletions
@@ -0,0 +1,161 @@
+# Probability — design spec
+
+A single-player space trading simulation in the browser. Inspired by Space Rangers.
+The core conceit: NPC ships in systems the player cannot see exist as probability
+clouds, not concrete positions. Entering a system collapses the clouds in it.
+Probability is visible gameplay, not just an engine optimization: the player sees
+clouds, stale prices, and aging intel, and trades on imperfect information — exactly
+like every NPC does.
+
+## Goals
+
+- A complete, playable trading loop: fly, dock, buy low, sell high, reach a credit target.
+- The probability mechanic is visible and legible: clouds on the map, intel that ages.
+- A living galaxy of 100–200 NPC traders at near-zero simulation cost while unobserved.
+- Deterministic, headless-testable simulation core.
+
+## Non-goals (v1)
+
+- Combat, named pirate units, missions, factions, sound, save/load.
+  (Pirates exist only as hazard fields. localStorage save is a v1.5 candidate.)
+- Free 2D flight. All movement is graph-based, including inside systems.
+- Multiplayer, server, persistence beyond a session.
+
+## World model
+
+- **Galaxy**: an undirected graph of ~25 systems connected by jump lanes, generated
+  from a seed with a roughly planar layout.
+- **System contents**: one star, 1–3 planets, one jump gate per lane. Inside a system,
+  ships move along straight legs between gate(s) and planets — still a graph
+  (nodes: gates, planets; edges: legs).
+- **Commodities**: 6 goods. Each planet produces some and consumes others at fixed
+  rates. Price is a deterministic curve over current stock (low stock → high price).
+- **Hazard fields**: each lane has a pirate danger rating in [0, 1]. Danger feeds the
+  probabilities of bad branches for ships using that lane: delay, cargo loss, or
+  destruction. No individual pirate units exist in v1.
+
+## NPC model
+
+NPC traders (100–200) alternate between two states:
+
+- **Docked (concrete decision point)**: the NPC picks the best arbitrage opportunity
+  it knows about and plans a route. Decisions use *stale news*, not live state:
+  price snapshots propagate through the galaxy at a fixed speed (a few lanes per
+  game-day). This bounds decision cascades — an NPC's plan depends only on committed
+  history at planning time — and makes NPCs fallible the same way the player is.
+- **In transit (branch tree)**: the plan is a tree of possible histories. Branch
+  points: route choice (weighted by NPC caution vs. lane danger), hazard outcomes
+  per lane (safe / delayed / cargo lost / destroyed), and fuzzy arrival times
+  (a time distribution per leg whose spread grows with legs traveled since the NPC
+  was last observed).
+
+**Hidden-variable determinism**: every NPC has a seed. Every branch outcome is drawn
+deterministically from (seed, branch id). Outcomes are therefore fixed-but-unknown
+from the moment a plan is made; observation merely reveals them. This guarantees
+observation-order consistency (seeing a market first or the ship first always yields
+the same history) and makes the sim reproducible for tests.
+
+## Probability clouds
+
+Because movement is graph-based, a cloud is one-dimensional: a weighted set of
+lane/leg segments, derived analytically from the plan and elapsed time (no per-tick
+integration). Properties:
+
+- Total mass is 1 across all branches/segments (invariant, asserted).
+- Spread grows with time/legs since last observation.
+- Observation that excludes branches (e.g., "the ore never arrived at B, so the
+  safe-and-on-time branch is dead") renormalizes the remainder — observing a market
+  sharpens the cloud of every ship entangled with it.
+
+## Markets and probabilistic trades
+
+Markets in unobserved systems hold **pending probabilistic transactions**
+("+50 ore, 85% likely, arriving t=10–18") instead of applying trades on a schedule.
+Anything needing a price meanwhile (NPC planning, news snapshots) uses the
+expected (probability-weighted) market state. The concrete price exists only after
+resolution.
+
+## Observation and collapse
+
+The player's current system is a **classical bubble** — fully concrete and simulated
+in real time. All conversion happens at its boundary:
+
+- **Player enters a system**: every cloud with mass inside is sampled (from its seed):
+  the ship spawns concrete, or is excluded and its remaining cloud renormalized
+  outside.
+- **While the player stays**: an **arrival queue** holds potential arrival events for
+  this system — every branch in every NPC tree that routes through it, plus new
+  plans made elsewhere as they are created. When an event comes due, roll it: ship
+  materializes at the gate, or the branch silently didn't happen. Traffic volume
+  emerges from trade-route topology; nothing is scripted.
+- **Docking at a planet**: resolve that market's pending transactions in
+  chronological order → concrete stock and price.
+- **A concrete ship jumps out / the player leaves**: concrete state re-fuzzes into a
+  tight cloud anchored at the last known position and time, spreading thereafter.
+
+## Time
+
+Real-time with pause and ×1 / ×4 / ×16 speed. Internally: a global event queue
+(arrivals, plan completions, news propagation) plus a fixed sim tick (~10 Hz,
+scaled by game speed) for in-system ship motion. Clouds cost nothing between
+observations.
+
+## Player gameplay (v1)
+
+- Fly between systems via gates, dock at planets, buy/sell on a market screen,
+  manage credits and cargo capacity. Win: reach a credit target (e.g., 100,000 cr).
+- Player ship is subject to the same lane hazards (cargo loss / delay; destruction
+  = game over).
+- **Galaxy map intel layer**:
+  - Lanes tinted by hazard rating.
+  - Last-known prices per planet, displayed with their age ("ore 12 cr — 3 days old").
+    The player's price knowledge updates by visiting or as news reaches their location.
+  - Probability clouds rendered as glowing smears along lanes — only for ships the
+    player has personally observed at least once.
+
+## Rendering
+
+- **PixiJS v8** on a single canvas, WebGL backend.
+- **Two views**: galaxy map (systems = bright circles, lanes = dim lines, clouds =
+  bloomed smears) and system view (star = large bright circle, planets = circles,
+  ships = triangles sliding along legs, gates marked at the rim).
+- **Neon look**: `AdvancedBloomFilter` (pixi-filters) over the world container;
+  simple flat-color geometry underneath.
+- **UI as DOM overlay** (not canvas): market table, cargo panel, time controls,
+  hover tooltips.
+
+## Architecture
+
+```
+src/
+  sim/      pure JS, zero rendering imports; deterministic given a seed
+            galaxy generation, economy, news propagation, NPC planning,
+            branch trees, clouds, observation/collapse, event queue, seeded RNG
+  render/   Pixi scene graph, two views, bloom, motion interpolation
+  ui/       DOM panels and tooltips
+  main.js   game loop: advance sim, project state into render/ui
+```
+
+The sim exposes a small read API (system contents, cloud segments, market views,
+player state) and a small command API (depart, dock, buy, sell, set speed). The
+renderer and UI never mutate sim state directly.
+
+Plain JavaScript (ES modules), Vite for dev server and bundling, Vitest for tests.
+
+## Testing
+
+Headless tests against `sim/`:
+
+- Cloud invariants: mass sums to 1; renormalization after exclusion is correct.
+- **Observation-order independence**: observing market-then-ship produces the same
+  committed history as ship-then-market (the per-seed hidden-variable guarantee).
+- Economy sanity: prices respond to stock; NPC arbitrage narrows price gaps over time.
+- Event queue: chronological resolution; arrival events match branch probabilities
+  over many seeds (statistical test).
+- Determinism: same galaxy seed + same player inputs → identical end state.
+
+## Error handling
+
+Single-player browser game: invariant assertions in `sim/` (probability mass,
+non-negative stock, queue ordering) that throw in dev builds. No network, no I/O
+beyond the page.