# Session Summary

## Project State

This repository now contains a playable Three.js/Vite prototype for a space RTS / economy sim testbed inspired by EVE Online and X4.

The codebase has been refactored away from a single monolithic `GameApp.ts` toward a more maintainable, data-driven structure. Authored game content now lives in JSON catalogs, while runtime code is split into domain types, world-building helpers, UI presenters, and rendering helpers.

The current prototype includes:

- Two solar systems: `Helios Reach` and `Perseus Gate`
- A large space environment with stars, planets, orbit lines, nebulae, asteroid/resource fields, and starfield
- RTS-style ship selection, command issuance, camera movement, zoom levels, and follow-camera support
- Three view levels based on zoom: `local`, `solar`, and `universe`
- A bottom command bar with selection info, order buttons, and a minimap
- A strategic HUD overlay that switches to NATO / military-style symbols at higher zoom levels

## Major Gameplay Systems Added

### World / Navigation

- Ships can travel between the two systems using staged FTL travel
- Travel flow includes:
  - leaving gravity well
  - FTL spool
  - warp
  - arrival
- FTL speed was increased and a basic warp streak / tunnel effect was added
- Local ship movement is no longer purely straight-line:
  - ships bias toward curved orbital-style transfers around the system center
  - idle ships hold a passive orbit instead of freezing in place

### Orbital Model

- Stations are no longer static arbitrary points
- Stations in `Helios` are placed on Lagrange-style offsets relative to planets
- Stations update position over time with the planetary orbital motion
- Ships and stations are beginning to behave like orbitals rather than free-floating markers

### Units / AI / Orders

- Ship roles currently in the prototype:
  - military
  - transport
  - mining
- Unit state machine now includes states for:
  - idle / moving
  - FTL travel
  - mining and delivery
  - docking approach / docking / docked / undocking
  - patrol / escort
- Orders currently supported:
  - move
  - transfer
  - mine
  - patrol
  - escort

### Docking / Logistics

- Docking was added as a required step for transfer to stations
- Stations have limited docking capacity and explicit docking ports
- Mining ships now:
  - mine ore in `Perseus`
  - return to `Helios`
  - dock at a refinery
  - transfer ore
  - undock and repeat

### Economy / Inventory Foundations

- Added item storage classes:
  - `bulk-solid`
  - `bulk-liquid`
  - `bulk-gas`
  - `container`
  - `manufactured`
- Added module categories and starter module definitions for ships/stations
- Added explicit recipe data for refinery processing
- Ships and stations now expose compatible cargo/storage/module metadata
- Refineries track:
  - ore stored
  - active refining batch
  - refining timer
  - refined output stock
- Refinery processing now consumes ore inventory and produces manufactured output through a recipe-driven flow

### Energy / Fuel

- Ships now track:
  - fuel
  - energy
- Stations now track:
  - fuel
  - energy
- Ships consume energy/fuel depending on activity
- Docked ships recharge energy
- Stations recharge energy passively

## Testbed Layout

- `Helios Reach` is now the industrial / infrastructure system
  - stations are concentrated there
  - refinery loop terminates there
- `Perseus Gate` is now the extraction / resource system
  - resource asteroid nodes are concentrated there
  - miners operate there before hauling back

## UI / UX State

- Ship and station selection is supported
- Ship multi-selection is supported via click modifiers and marquee drag selection
- `Solar` and `universe` views now overlay high-level tactical symbology instead of relying only on 3D meshes
- Ships use role-specific long-range symbols:
  - military: hostile/combat-style diamond iconography
  - transport: boxed logistics symbol
  - mining: angular resource / industrial symbol
- Stations and constructibles use square strategic markers with category-specific internal glyphs
- `Universe` view groups ships into fleet counts per system and role for cleaner strategic readability
- Focusing works for:
  - single ships: follow camera
  - stations: focus camera on the station
- Selection panels show:
  - ship state, order, cargo, hold type, fuel, energy, modules
  - station role, docking occupancy, stored resources, refinery timing, fuel, energy, modules

## Controls

- `Left Click`: select ships or stations
- `Shift + Left Click`: add ships to ship selection
- `Ctrl/Cmd + Left Click`: toggle ships in selection
- `Left Drag`: marquee-select multiple ships
- `Right Click`: issue move/transfer orders
- `Mouse Wheel` or `-` / `=`: zoom
- `W A S D`: pan camera
- `Q / E`: rotate camera
- `F`: focus selection, and follow a single selected ship
- `Tab`: jump camera between systems
- `B`: toggle build mode
- `1-5`: choose constructible
- `M`: assign mining
- `P`: assign patrol
- `E`: assign escort

## Technical Notes

- The prototype is built with:
  - Vite
  - TypeScript
  - Three.js
- Authored data now lives in JSON files under `src/game/data/`, including:
  - `items.json`
  - `recipes.json`
  - `systems.json`
  - `modules.json`
  - `ships.json`
  - `constructibles.json`
  - `scenario.json`
  - `balance.json`
- Shared domain and runtime types now live in `src/game/types.ts`
- World construction is extracted into `src/game/world/worldFactory.ts`
- HUD creation and presentation logic are extracted into:
  - `src/game/ui/hud.ts`
  - `src/game/ui/presenters.ts`
  - `src/game/ui/strategicRenderer.ts`
- Inventory helpers now live in `src/game/state/inventory.ts`
- High-level symbology is rendered through a dedicated 2D HUD overlay canvas layered above the 3D scene
- Production build is currently passing with `npm run build`

## Known Limitations / Caveats

- Orbital behavior is still an approximation for gameplay, not a full orbital mechanics simulation
- Stations are on Lagrange-style offsets, but not using a physically rigorous orbital solver
- Ship transfer paths are curved and orbit-biased, but still use authored steering rather than patched conics or n-body integration
- Fuel / energy exist but station refueling, resupply, and depletion failure states are still minimal
- Module definitions exist, but there is no actual ship/station designer yet
- Inventory classes exist, but only a subset of economic flows are implemented
- Docking works for logistics, but there is not yet a richer docking queue / reservation UI
- NATO-style symbology is gameplay-oriented inspiration, not a strict APP-6 / MIL-STD implementation

## Suggested Next Steps

- Continue shrinking `GameApp.ts` by extracting simulation/order logic into dedicated gameplay systems once the current rules stabilize
- Add JSON schema validation or runtime validation for the authored data catalogs to catch content errors earlier
- Move constructible placement and future unit spawning onto a shared scenario/entity factory pipeline
- Introduce explicit orbital anchors for:
  - stars
  - planets
  - stations
  - asteroid belts / resource fields
- Replace the current movement approximation with a more formal orbital transfer model
- Add refueling and power management gameplay
- Add ship/station fitting data structures that can later drive a designer UI
- Expand the economy beyond ore/refining into manufactured goods and trade lanes
- Improve FTL visuals with a fullscreen post-process distortion or tunnel effect
- Expand the strategic overlay with threat rings, route arrows, and fleet stance/status markers