# apps/game — Playable Game Client

Package: `@void-nav/game`
Port: `http://localhost:5175`

The **standalone playable game** connected to a SpacetimeDB backend. This is the production game client — all other apps are documentation or marketing.

## Current State (Phase 0-2)

The game implements the basic loop: **undock → select target → approach asteroid → mine ore → dock → sell ore**. Keyboard shortcuts (U/D/A/M/1-9) and 3D click selection work. SVG mini-map and 3D scene stay synchronized through SpacetimeDB subscriptions.

## Structure

```
src/
  main.tsx                   Entry point, renders GameShell into #root
  GameShell.tsx              Root layout: 3-column grid (left sidebar, center 3D scene, right sidebar, bottom command rail)
  module_bindings/           Auto-generated SpacetimeDB TypeScript bindings (24 files)
    types.ts                 All table row types and reducer call types
    ...                      One file per table + connection builder
  scene/                     3D rendering (React Three Fiber)
    SpaceCanvas.tsx          R3F Canvas wrapper (camera at [8,9,44], FOV 48)
    SpaceEnvironment.tsx     Background, fog, lights, star field
    GameSpaceScene.tsx       Main orchestrator: places stations/asteroids/ship, manages operations, interpolates movement
    StationMesh.tsx          Torus + cylinder station, clickable, selection ring
    AsteroidMesh.tsx         Icosahedron asteroid, tumble animation, clickable
    ShipMesh.tsx             Cone + box + sphere ship, engine glow by mode, bob animation
  spacetime/                 SpacetimeDB connection layer
    client.ts                Connection factory, table subscriptions, auth token storage
    useSpacetimeConnection.ts React hook: connection state, identity, revision polling
    useGameSession.ts        React hook: reads all tables into GameSession object, exposes action callbacks for all reducers
  ui/                        UI panels
    CommandRail.tsx          Bottom-fixed contextual action bar with progress bars
    ConnectionPanel.tsx      Dev diagnostic: connection status, identity, rename/ping
    CargoPanel.tsx           Cargo hold items with quantity and price
    NpcMarketPanel.tsx       Sell ore at fixed NPC price (docked only)
    WalletPanel.tsx          ISK balance display
    ShipStatusPanel.tsx      Hull/shield/speed bars, position, operation timer
    TargetPanel.tsx          Selected target info, clickable POI list
    MiniStarMap.tsx          SVG 2D system map with ship position and operation lines
    EventFeed.tsx            Server event log (last 12 events)
    useKeyboardShortcuts.ts  U=undock, D=dock, A=approach, M=mine, 1-9=select target
  styles/
    tailwind.css             Tailwind v4 entry point
```

## SpacetimeDB Tables (9) and Reducers (12)

See `services/spacetimedb/AGENTS.md` for full backend details.

## Known Hardcoded Values

- `client.ts:77-78` — subscriptions hardcoded to `solace` system and `solace-prime` station
- `useGameSession.ts:129-130` — system/station lookup hardcoded to specific IDs
- `ShipStatusPanel.tsx:44` — hullPct always 100 (no damage model)
- `ShipStatusPanel.tsx:45` — shieldPct uses Math.random() (not server data)
- `NpcMarketPanel.tsx:5-7` — NPC_PRICES hardcoded client-side (only Veldspar at 12 ISK)
- `GameSpaceScene.tsx:120-124` — asteroid cluster offsets hardcoded (3 rocks per belt)