# services/spacetimedb — Authoritative Game Backend

Package: `@void-nav/spacetimedb`
Single file: `src/index.ts` (~595 lines)

This is the **entire server-side game logic** — all tables, all reducers, all validation. SpacetimeDB runs this as a hosted module; clients subscribe to tables and call reducers.

## Tables (9)

| Table | PK | Purpose |
|-------|-----|---------|
| `player` | identity | Player identity, connection state, display name |
| `ship` | ship_id (u64) | Ship position, flight mode, docking state, cargo capacity |
| `system` | system_id | Star system (currently only "solace") |
| `station` | station_id | Station within a system |
| `point_of_interest` | poi_id | Navigable locations: stations, asteroid belts |
| `cargo_item` | cargo_item_id (u64) | Ship cargo: item type, category, quantity, unit price |
| `wallet` | owner_identity | ISK balance |
| `ship_operation` | ship_id | Active timed operation (approach/mining) with start time and duration |
| `server_event` | event_id (u64) | Server-side event log |

## Reducers (12)

| Reducer | Purpose |
|---------|---------|
| `seedWorld` | Creates starter system, station, POIs |
| `connectPlayer` | Player onboarding: creates player + ship + wallet |
| `renamePlayer` | Updates display name |
| `ping` | Connection test |
| `undock` | Transitions ship from docked to flight |
| `selectTarget` | Sets ship's selected POI target |
| `startApproach` | Begins 5s approach operation to selected target |
| `completeApproach` | Finalizes approach, updates ship position |
| `dock` | Transitions ship to docked at current station |
| `startMining` | Begins 6s mining cycle at asteroid belt |
| `completeMiningCycle` | Finalizes mining, adds 1000 Veldspar to cargo |
| `sellOreToNpcMarket` | Sells ore from cargo, credits ISK wallet |

## Constants (all hardcoded, top of file)

| Constant | Value | Should become |
|----------|-------|---------------|
| `STARTER_SYSTEM_ID` | `"solace"` | Procedurally generated |
| `APPROACH_DURATION_MS` | `5000n` | Ship-class dependent |
| `MINING_DURATION_MS` | `6000n` | Module + skill dependent |
| `STARTER_WALLET_ISK` | `25000n` | Tunable |
| `STARTER_CARGO_CAPACITY` | `2500n` | Ship-class dependent |
| `MINING_YIELD_QUANTITY` | `1000n` | Module + skill dependent |
| Veldspar price | `12n` ISK | Dynamic NPC pricing |

## Validation

Every reducer has guard clauses that throw on invalid state (wrong flight mode, missing target, already operating, etc.). Timing is server-authoritative — `completeApproach` and `completeMiningCycle` check `ctx.timestamp` against `completes_at_ms`.

## What's Not Here Yet

The design docs describe 56+ tables. This module implements 9. Missing systems:
- Combat (NPC entities, damage, power allocation, bounties, loot)
- Ship fitting (module catalog, CPU/PG, slot types)
- Multiple ship classes
- Refining and manufacturing
- Missions / NPC agents / faction standing
- Dynamic NPC pricing (EMA, demand pressure)
- Multi-system travel (stargates, warp)
- Skills / XP progression
- Insurance, CONCORD, world events
- Zora ship AI