jbourdon/space-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor ship control layers and update docs

Browse Source
This commit is contained in:
Jonathan Bourdon
2026-03-12 16:44:00 -04:00
parent 7e41274620
commit 0a76c60ab1
12 changed files with 2580 additions and 565 deletions
Download Patch File Download Diff File Expand all files Collapse all files

359
SESSION.md
View File

@@ -1,196 +1,239 @@
# Session Summary
## Project State
## Current State
This repository now contains a playable Three.js/Vite autonomous space-sim prototype that has moved away from a player-command RTS testbed and toward a game-master / observer simulation.
The project is a Three.js/Vite space simulation with:
The codebase is still TypeScript + Three.js on Vite, with authored catalogs under `src/game/data/`, but the runtime now centers on:
- autonomous ships
- orbital travel
- docking and undocking
- mining and refinery delivery
- refining / fabrication
- faction growth through ship and outpost production
- observer-focused debugging tools
- procedural universe generation
- autonomous faction behavior
- direct per-ship faction control
- economic production loops
- pirate harassment
- strategic system control
- observer-oriented HUD and camera controls
The active runtime model now follows the intended layered architecture more closely:
## Current Prototype
- `order`
- `defaultBehavior`
- `assignment`
- `controllerTask`
- `state`
The current build includes:
The previous `captainGoal` layer has been removed.
- a generated universe with a few dozen systems
- 4 empire factions inspired by EVE-style sovereign powers
- multiple pirate factions that raid empire space
- rich central systems that factions contest for control
- faction-owned stations, ships, inventories, and combat stats
- autonomous shipbuilding and limited outpost growth
- observer controls for camera orbit, pan, focus, and inspection
## Ship Runtime Model
## Major Gameplay / Sim Systems
Ships now carry:
### Universe Generation
- `order`
- direct one-shot instruction such as `move-to`, `mine-this`, `dock-at`
- `defaultBehavior`
- standing automation such as `auto-mine`, `patrol`, `escort-assigned`, `idle`
- `assignment`
- contextual ownership / doctrine such as `unassigned`, `commander-subordinate`, `station-based`, `mining-group`
- `controllerTask`
- immediate executable task such as `travel`, `dock`, `extract`, `unload`, `follow`, `undock`
- `state`
- physical ship state such as `spooling-warp`, `warping`, `arriving`, `docking`, `docked`, `undocking`, `transferring`
- Startup no longer uses the fixed two-system authored sandbox.
- `src/game/world/universeGenerator.ts` now generates:
- empire capitals
- empire mining systems
- pirate base systems
- central high-value systems
- frontier filler systems
- The generated scenario also assigns:
- faction definitions
- initial faction-owned stations
- initial ship formations
- central system IDs
Current precedence is:
### Factions
1. `order`
2. `defaultBehavior`
3. assignment-derived fallback behavior
4. idle fallback
- Runtime faction state now exists in `src/game/types.ts`.
- Factions track:
- credits
- ore mined
- goods produced
- ships built
- stations built
- ships lost
- enemy ships destroyed
- raids completed
- stolen cargo
- owned systems
- Empire factions and pirate factions are distinct runtime kinds.
The main loop in [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts) is now:
### High-Level AI / Delegation
- `refreshControlLayers()`
- `planControllerTask()`
- `updateControllerTask()`
- `advanceControlState()`
- Faction AI now acts at a strategic level and issues direct orders to ships.
- Empire AI chooses high-level goals such as:
- secure home and mining space
- contest central systems
- send miners to resource systems
- send military ships to rally and patrol targets
- Pirate AI chooses raid targets and moves military ships into hostile space.
- The fleet / wing layer has been removed from both simulation and UI.
## Travel Model
### Economy / Production
Travel is destination-driven and orbital-centric.
- Mining, refining, and fabrication still run through recipe-driven station logic.
- Faction-owned inventories are effectively pooled across faction stations for recipe consumption.
- Factions can build new ships when enough goods exist.
- Empires can build limited defense outposts in central systems they control.
- same-system travel:
- `spooling-warp -> warping -> arriving`
- inter-system travel:
- `spooling-ftl -> ftl -> arriving`
- arrival anchors the ship to the destination orbital when appropriate
### Combat / Control
Destination ownership lives in the `controllerTask`.
- Ships and relevant stations now have combat stats:
- health
- damage
- range
- cooldown
- Combat is lightweight and proximity-based.
- Central systems track control progress and controlling faction.
- Pirate ships can steal cargo from vulnerable civilian ships.
Examples:
## Starting State
- `travel(destination)`
- `dock(host, bay)`
- `extract(node)`
- `unload(station)`
- `undock(host)`
- Empires now start very small for easier debugging and growth observation.
- Each empire currently starts with:
- 1 miner
- 1 manufactory
- 1 refinery
- Each pirate faction currently starts with:
- 1 frigate
- 1 trade hub
- This is a bootstrap-oriented setup: factions mine first, then try to grow from minimal infrastructure.
## Mining / Delivery / Refining
## UI / UX State
Current industrial loop:
### Observer HUD
1. miner travels to node
2. miner extracts ore
3. miner travels to refinery
4. miner docks
5. miner unloads over time
6. miner undocks
7. loop repeats
- The old summary panel is gone.
- The old bottom RTS command bar has been removed.
- The bottom HUD is now a selection dock that shows:
- selection title
- status line
- horizontally scrolling cards for selected entities
- fallback observer details when nothing specific is selected
- A dedicated `Debug` window now contains the `New Universe` button.
Important details:
### Selection / Inspection
- `mine-this` is a one-shot order and currently completes when cargo is full
- `auto-mine` is persistent behavior and includes its own internal phase state
- unloading is time-based through `transferRate` in [src/game/data/balance.json](/home/jbourdon/repos/space-game/src/game/data/balance.json)
- unload state is now `transferring`
- unload completion emits `<unloaded>`
- Selection is no longer limited to ships and stations.
- It is now possible to select:
- systems
- planets
- ships
- stations
- Double-click centers / focuses the clicked target.
- Multiple ship selections render as horizontal cards in the bottom dock.
Refineries and fabricators feed faction production.
### Windows
The faction economy now uses fabricated goods to:
- Generic draggable / resizable app windows still exist.
- Main windows currently in use:
- `Ships`
- `Debug`
- The `Ships` window:
- lists ships grouped by faction
- selects a ship on click
- focuses a ship on double click
- focuses a faction home system when clicking that faction header
- build new ships
- build defense outposts in valuable systems
### Strategic Rendering
Current production behavior lives in:
- Strategic overlay and minimap infrastructure still exist.
- The minimap canvas is still created for renderer use, but it is no longer shown in the visible HUD.
- Fleet link overlays and fleet counters were removed along with the fleet system.
- [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts)
- `tryBuildShipForFaction()`
- `tryBuildOutpostForFaction()`
## Controls
## Faction Growth Loop
- `Left Click`: inspect / select systems, planets, ships, or stations
- `Shift + Left Click`: add ships to multi-selection
- `Ctrl/Cmd + Left Click`: toggle ships in multi-selection
- `Left Drag`: marquee-select multiple visible ships
- `Double Click`: center / focus the clicked target
- `Middle Drag`: orbit camera
- `Shift + Middle Drag`: pan camera
- `Mouse Wheel` or `-` / `=`: zoom
- `W A S D`: pan camera using the same motion as `Shift + Middle Drag`
- `Q / E`: rotate camera
- `F`: focus current selection
- `G`: toggle ships window
- `Tab`: jump camera between systems
The active empire growth loop is:
## Technical Notes
1. mine ore
2. refine / fabricate goods
3. spend goods on ships
4. spend goods on military outposts
5. project power into central / contested systems
- Main runtime remains concentrated in `src/game/GameApp.ts`
- World construction and entity instancing:
- `src/game/world/worldFactory.ts`
- Procedural universe generation:
- `src/game/world/universeGenerator.ts`
- Selection state:
- `src/game/state/selectionManager.ts`
- HUD / presentation:
- `src/game/ui/hud.ts`
- `src/game/ui/presenters.ts`
- `src/game/ui/strategicRenderer.ts`
- Production build is currently passing with `npm run build`
This means the simulation is no longer missing a use for refined goods.
## Known Limitations / Caveats
What is still missing is stronger strategic prioritization, for example:
- `GameApp.ts` is still carrying too much simulation responsibility.
- Faction AI is improved, but still fairly heuristic and not yet a deep planning system.
- Combat is lightweight and does not yet model formations, threat evaluation, or target priorities in a sophisticated way.
- Economic logistics are still abstracted heavily.
- Ship construction is recipe-gated but still simplified.
- Stations consume pooled faction stock rather than explicit transport delivery chains.
- Bootstrap progression is still constrained by the current station recipe / stock model.
- The ships window is useful for inspection, but the overall UI is still only partially refit for observer mode.
- There is still no persistence layer for window layouts, saves, or generated universe seeds.
- when to build more miners vs escorts vs warships
- how to react to throughput shortages
- how to react to pirate pressure
## Suggested Next Steps
## Pirates / Threats
- Extract faction strategy into a dedicated AI / planning module
- Separate economic simulation from UI and rendering concerns
- Improve transport logistics so goods physically move through faction supply chains
- Add explicit shipyard construction queues and faction production priorities
- Rework bootstrap progression so factions can genuinely grow from near-zero infrastructure
- Add system-level threat, ownership, and economy views for game-master inspection
- Add save/load support for generated universes and long-running simulations
Pirates already exist as an active faction and can raid / fight.
Current pirate support includes:
- pirate faction command logic
- hostile target selection
- ship combat and destruction
What is still underdeveloped:
- explicit preference for miners, haulers, and refinery traffic
- clearer harassment behavior around resource chains
## Debug History
The debug window is focused on the selected ship and includes:
- `order`
- `defaultBehavior`
- `assignment`
- `controllerTask`
- `state`
- task target
- anchor
History is event-oriented plus explicit state lines.
Current notation includes:
- controller commands:
- `[travel]`, `[dock]`, `[unload]`, `[undock]`
- state snapshots:
- `state=move-to:.../travel-to-node [travel]/(warping)`
- events:
- `<arrived ...>`
- `<docked>`
- `<unloaded>`
- `<undocked>`
- `<cargo-full>`
- `<cargo-empty>`
- `<order ...>`
- `<default-behavior ...>`
- `<assignment ...>`
- `<docking-clearance ...>`
- `<docking-bay ...>`
- `<anchor ...>`
History remains HTML-escaped before rendering and same-tick changes are still batched.
Copy-to-clipboard includes:
- current live summary block
- event history
## Selection / HUD
The HUD currently supports selecting:
- ships
- stations
- systems
- planets
- asteroid field nodes
Notable UI status:
- ship cards show cargo and current layered control summary
- station cards show ore stored and refined stock
- Fleet and Debug window toggle buttons exist
- debug history is scrollable and copyable
## Important Recent Changes
- removed the old `captainGoal` layer
- planner now derives `controllerTask` directly from `order` and `defaultBehavior`
- moved mining / patrol progress state into `order` and `defaultBehavior`
- updated debug / selection UI to show the active layered model
- removed confirmed dead code found by strict TypeScript unused checks
## Current Known Limitations
- [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts) is still too large and owns too much simulation responsibility
- order types are still narrow
- currently focused on `move-to`, `mine-this`, `dock-at`
- default behavior set is still narrow
- currently focused on `idle`, `auto-mine`, `patrol`, `escort-assigned`
- pirate harassment exists but is not yet economically targeted enough
- faction production logic is timer-driven and only lightly reactive
- no persistence for saves, seeds, or layouts
## Important Files
- [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts)
- main simulation loop
- layered planning
- travel, docking, mining, unloading, faction growth, combat, debug history
- [src/game/types.ts](/home/jbourdon/repos/space-game/src/game/types.ts)
- `order` / `defaultBehavior` / `assignment` / `controllerTask` / `state` model
- [src/game/world/worldFactory.ts](/home/jbourdon/repos/space-game/src/game/world/worldFactory.ts)
- ship and station instancing
- [src/game/ui/presenters.ts](/home/jbourdon/repos/space-game/src/game/ui/presenters.ts)
- selection cards
- station cards
- debug history markup
- [src/game/data/balance.json](/home/jbourdon/repos/space-game/src/game/data/balance.json)
- travel, docking, transfer rates
## Validation
Validation passing at the end of this session:
- `npx tsc --noEmit --noUnusedLocals --noUnusedParameters`
- `npm run build`