space-game/SESSION.md

Session Summary

Current State

The project is a Three.js/Vite space simulation with:

• autonomous ships
• orbital travel
• docking and undocking
• mining and refinery delivery
• refining / fabrication
• faction growth through ship and outpost production
• observer-focused debugging tools

The active runtime model now follows the intended layered architecture more closely:

• order
• defaultBehavior
• assignment
• controllerTask
• state

The previous captainGoal layer has been removed.

Ship Runtime Model

Ships now carry:

• 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

Current precedence is:

1. order
2. defaultBehavior
3. assignment-derived fallback behavior
4. idle fallback

The main loop in src/game/GameApp.ts is now:

• refreshControlLayers()
• planControllerTask()
• updateControllerTask()
• advanceControlState()

Travel Model

Travel is destination-driven and orbital-centric.

• same-system travel:
  • spooling-warp -> warping -> arriving
• inter-system travel:
  • spooling-ftl -> ftl -> arriving
• arrival anchors the ship to the destination orbital when appropriate

Destination ownership lives in the controllerTask.

Examples:

• travel(destination)
• dock(host, bay)
• extract(node)
• unload(station)
• undock(host)

Mining / Delivery / Refining

Current industrial loop:

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

Important details:

• 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
• unload state is now transferring
• unload completion emits <unloaded>

Refineries and fabricators feed faction production.

The faction economy now uses fabricated goods to:

• build new ships
• build defense outposts in valuable systems

Current production behavior lives in:

• src/game/GameApp.ts
  • tryBuildShipForFaction()
  • tryBuildOutpostForFaction()

Faction Growth Loop

The active empire growth loop is:

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

This means the simulation is no longer missing a use for refined goods.

What is still missing is stronger strategic prioritization, for example:

• when to build more miners vs escorts vs warships
• how to react to throughput shortages
• how to react to pirate pressure

Pirates / Threats

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 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
  • main simulation loop
  • layered planning
  • travel, docking, mining, unloading, faction growth, combat, debug history
• src/game/types.ts
  • order / defaultBehavior / assignment / controllerTask / state model
• src/game/world/worldFactory.ts
  • ship and station instancing
• src/game/ui/presenters.ts
  • selection cards
  • station cards
  • debug history markup
• 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