Add game UI panels, keyboard shortcuts, docs narrative overhaul, and unified dev script

- Add MiniStarMap, NpcMarketPanel, ShipStatusPanel, useKeyboardShortcuts
- Add progress bars for approach/mining operations and cargo fill indicator
- Rewrite docs from spreadsheet-first to exploration-first open-world RPG
- Replace dev:db + dev:standalone with unified dev script (scripts/dev.sh)
- Add Vite chunk splitting for three.js and spacetimedb
- Fix displayName dependency in useSpacetimeConnection
- Remove stale usePlayerSession.ts
- Add AGENTS.md files across all packages
This commit is contained in:
2026-06-02 17:32:15 -04:00
parent be8967d5fe
commit 7c93b8a1ae
40 changed files with 2263 additions and 266 deletions

12
services/AGENTS.md Normal file
View File

@@ -0,0 +1,12 @@
# services/ — Backend Services
Server-side modules that own authoritative game state.
| Service | Protocol | Description |
|---------|----------|-------------|
| `spacetimedb` | SpacetimeDB TS module | Authoritative game backend: all tables, reducers, validation |
## Key Files
- `spacetime.json` (repo root) — points `module-path` at `./services/spacetimedb`
- `spacetime.local.json` — local database name: `void-nav-dev`

View File

@@ -0,0 +1,67 @@
# 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