space-game/SESSION.md

# Session Summary

## Current State

The repository is now split into two apps that live side-by-side:

- [apps/backend](/home/jbourdon/repos/space-game/apps/backend)
  - authoritative ASP.NET Core simulation
- [apps/viewer](/home/jbourdon/repos/space-game/apps/viewer)
  - Three.js/Vite observer client
- [shared/data](/home/jbourdon/repos/space-game/shared/data)
  - shared scenario data

The complete simulation runs in the backend. The viewer fetches one world snapshot, then subscribes to an SSE delta stream and renders the world as an observer.

## Runtime / Networking

The backend currently provides:

- `GET /api/world`
  - initial authoritative snapshot
- `GET /api/world/stream`
  - incremental SSE deltas after a sequence number

The viewer currently does:

1. fetch the world once
2. connect to the stream
3. apply deltas into a local render model
4. interpolate and briefly extrapolate moving ships for presentation

This supports multiple simultaneous observers on the same world. Interest management is not implemented yet, so every observer still receives full-world deltas.

## Viewer Status

The viewer currently supports:

- single-click selection for ships, stations, nodes, planets, and stars
- rectangular marquee selection
  - constrained to one group at a time:
    - ships
    - structures
    - celestials
- `WASD` panning on the `XZ` plane
- middle-mouse orbit camera
- smooth wheel zoom across local, system, and universe scales
- presentation fades between zoom bands instead of hard switches
- procedurally animated planets and moons from orbital metadata
- ringed planets, binary star presentation, and richer resource visuals

Universe-level presentation is now star-centric:

- solar-system internals fade out as the camera pulls back
- star names remain readable
- system summary panels show icon-plus-count rollups only when entities are present

The viewer also includes plain-text HUD readouts for:

- game state
- network statistics

The viewer now consumes richer celestial metadata from the backend:

- star kind and star count
- planet type, shape, moon count, and orbital elements
- resource node source kind such as `asteroid-belt` and `gas-cloud`

Planets and moons are not simulated as networked entities. Their positions are reconstructed client-side from snapshot time plus orbital configuration.

## Simulation Status

The backend simulation already includes:

- autonomous ships
- orbital travel
- docking and undocking
- mining and refinery delivery
- refining / fabrication
- faction growth through ship and outpost production
- pirate pressure and combat
- procedural galaxy generation with deterministic expansion beyond the authored scenario
- handcrafted `Sol` system easter egg with Saturn and rings
- resource geography beyond simple ore nodes
  - asteroid belts for ore
  - gas clouds for gas

The runtime model still follows the intended layered control architecture:

1. `order`
2. `defaultBehavior`
3. `assignment`
4. `controllerTask`
5. `state`

## Important Recent Changes

- split the old monolith into `apps/backend` and `apps/viewer`
- moved simulation authority fully into .NET
- replaced frontend polling with snapshot-plus-delta SSE replication
- added viewer-side interpolation / short extrapolation for movement
- added a plain-text network statistics readout
- reworked the camera with smoother zoom, orbit, panning, and marquee selection
- cleaned up several viewer HUD elements and removed redundant panel content
- expanded the backend world into a large procedural galaxy with elevated vertical variance
- added deterministic orbital metadata for planets and client-side orbital animation in the viewer
- added moon rendering in the viewer
- added backend-generated asteroid belts and gas clouds as resource sources
- injected the `Sol` system into the generated galaxy

## Current Known Limitations

- replication is still world-wide
  - no observer-scoped interest management yet
- the viewer is still observer-focused
  - no command submission UI yet
- system/universe transitions are improved but still need tuning in feel and art direction
- the galaxy is much larger now, so viewer performance and visual density need active tuning
- moon rendering is procedural from counts, not authored moon-by-moon data
- resource extraction behavior still treats all resource nodes generically
- piracy and faction growth are still functional rather than strategically deep
- no persistence for saves, seeds, or reconnect state

## Important Files

- [apps/backend/Program.cs](/home/jbourdon/repos/space-game/apps/backend/Program.cs)
  - backend API endpoints
- [apps/backend/Simulation/WorldService.cs](/home/jbourdon/repos/space-game/apps/backend/Simulation/WorldService.cs)
  - authoritative world state and stream coordination
- [apps/backend/Simulation/SimulationEngine.cs](/home/jbourdon/repos/space-game/apps/backend/Simulation/SimulationEngine.cs)
  - simulation advancement
- [apps/backend/Simulation/ScenarioLoader.cs](/home/jbourdon/repos/space-game/apps/backend/Simulation/ScenarioLoader.cs)
  - faction bootstrap
  - galaxy generation
  - special systems
  - procedural celestial/resource content
- [apps/viewer/src/GameViewer.ts](/home/jbourdon/repos/space-game/apps/viewer/src/GameViewer.ts)
  - camera, selection, streaming integration, and presentation
  - orbital reconstruction and moon rendering
- [apps/viewer/src/api.ts](/home/jbourdon/repos/space-game/apps/viewer/src/api.ts)
  - snapshot fetch and SSE stream integration
- [apps/viewer/src/contracts.ts](/home/jbourdon/repos/space-game/apps/viewer/src/contracts.ts)
  - viewer-side snapshot contract for celestial metadata
- [shared/data](/home/jbourdon/repos/space-game/shared/data)
  - scenario and world data definitions

## Validation

Validation passing at the end of this session:

- `dotnet build apps/backend/SpaceGame.Simulation.Api.csproj`
- `cd apps/viewer && npm run build`