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:
67
services/spacetimedb/AGENTS.md
Normal file
67
services/spacetimedb/AGENTS.md
Normal 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
|
||||
Reference in New Issue
Block a user