space-game/SESSION.md

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