initial commit

SESSION.md

@@ -0,0 +1,173 @@
+# 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 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
+- Ships and stations now expose compatible cargo/storage/module metadata
+- Refineries track:
+  - ore stored
+  - active refining batch
+  - refining timer
+  - refined output stock
+
+### 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
+- 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
+
+- 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