Implementation Progress

Last updated: 2026-02-23

Priority Order

✅ Done

1 & 2 — Planet Economy Engine + Population/Food

Backend

• PlanetEntity — coordinates, planet size (Small/Medium/Large), housing capacity, population, stability (0–100), 5 resource stockpiles (metal/crystal/gas/rare/food), specialization type, last_tick_at
• EconomicTickService — applies one or more economic ticks to a planet; called lazily on planet access
• Pure static calculators: FoodCalculator, PopulationCalculator, ProductionCalculator, StabilityCalculator, BuildingCalculator
• Population growth (+2%/tick) and starvation (−0.5× food deficit) based on net food
• Housing efficiency modifier with five interpolated zones (optimal at ratio 0.75–0.90)
• Stability delta: −2/tick starvation, −1/tick overcrowding, +1/tick recovery
• Resource production from buildings, modified by efficiency × stability × specialization × energy ratio
• API: POST /api/v1/game/tick, GET /api/v1/planets/{id}/economy, GET /api/v1/game/config

Frontend

• PlanetsPage — list all planets, owned planets sorted first
• PlanetDetailPage — stockpiles, stability bar, population bar, coordinates, specialization badge
• EconomyPanel — production rates, food outlook, per-resource rates, energy section, collapsible

3 — Blueprint System (Hangar)

Backend

• FrameEntity — 8 hull classes (5 ships + 3 stations), slot layout, power budget, resource costs, build ticks; seeded as static reference data
• ModuleEntity — 16 modules across 4 types (Weapon / Defense / Engine / Utility), stats, counter tags, resource costs; seeded as static reference data
• BlueprintEntity + BlueprintModuleEntity — player designs with versioning and role assignment
• Full CRUD for blueprints; frames and modules are read-only

Frontend

• HangarPage — blueprint list with edit/delete
• BlueprintDesigner modal — frame picker, slot assignment, module picker with power budget display
• BlueprintCard — summary view with role, hull class, version

Visualizer (ships/, port 5174)

• Three.js standalone app — renders ship blueprints in a blueprint-aesthetic 3D viewport
• Real-time preview as modules are assigned to slots

4 — Fleet System

Phase 1: Ship Production

• FleetEntity + FleetShipEntity — docked/moving fleet with ship stacks (blueprint → count)
• ProductionOrderEntity — tick-based build queue; resources deducted upfront
• ShipProductionService: QueueOrderAsync, AdvanceProductionAsync, CancelOrderAsync
• Endpoints: POST/GET /api/v1/planets/{id}/production, DELETE .../production/{orderId}, GET .../production/cost/{blueprintId}
• Fleet endpoints: GET /api/v1/fleets, GET /api/v1/fleets/{id}
• Frontend: ProductionQueue on planet detail, BuildShipsModal, FleetsPage

Phase 2: Fleet Movement

• FleetMovementService: DispatchAsync, GetEtaAsync, AdvanceMovementAsync
• Fleet speed = sum of Engine module speed values for the slowest ship; default 1.0 if no engines
• Euclidean distance; ticks_remaining stored for smooth interpolation on the galaxy map
• Endpoints: POST /api/v1/fleets/{id}/dispatch, GET /api/v1/fleets/{id}/eta/{destinationId}
• Frontend: DispatchModal with live ETA preview, Galaxy Map (/map) with SVG planet circles, fleet route lines, real-time fleet tween

5 — Deterministic Combat

• Pure combat simulation: same fleet compositions always produce the same outcome (no RNG)
• Initiative from weighted-average fleet speed; higher speed attacks first each round
• Round loop: attacker selects targets, damage applied (shield → armor → hull), defender retaliates
• Damage formula: effective_damage = base_damage × targeting_modifier × counter_modifier
• Counter tags: armor_piercing / shield_breaker weapon tags vs piercing_resistance / breaker_resistance defense tags (1.25× modifier)
• CombatEvent log per round; human-readable battle report generated post-combat
• Hash verification: sha256(fleetA_state + fleetB_state + engine_version)
• Endpoint: POST /api/v1/combat/simulate

6 — Trade Routes

• TradeRouteEntity with source planet, destination planet, resource type, min/max stockpile thresholds, fleet assignment, shipment size
• Tick trigger: dispatch shipment if source > max_threshold AND dest < min_threshold AND fleet idle
• Resources deducted from source on dispatch; added to destination on fleet arrival
• TradeRouteService: CreateAsync, AdvanceTradeAsync (called each tick)
• Endpoints: GET/POST/DELETE /api/v1/planets/{id}/trade-routes
• Frontend: TradeRoutesPanel on planet detail, AddTradeRouteModal

7 — Espionage

• Three intel levels: ship counts → module types → full blueprint layout
• Deterministic resolution: success_score = attacker_espionage − defender_counterintelligence; success if score ≥ level threshold
• EspionageMissionEntity with attacker, target, intel level, ticks remaining, outcome
• EspionageService: LaunchMissionAsync, AdvanceMissionsAsync (called each tick), GetIntelReportAsync
• Endpoints: POST /api/v1/espionage/missions, GET /api/v1/espionage/reports/{id}
• Frontend: IntelReportModal

8 — Buildings System

• PlanetBuildingEntity — completed buildings: type, level (1–5), slot index
• BuildingConstructionOrderEntity — one active order per planet; resources deducted upfront; ticks_remaining decremented each tick
• BuildingDefinitions — static catalog of 8 building types with per-level stats (no DB table)
• BuildingCalculator — pure static: energy ratio, per-building output, housing, specialization modifier
• Energy system: Solar Arrays and Nuclear Reactors produce energy; extraction and farming buildings consume it; energy_ratio ∈ [0.5, 1.0] scales all outputs
• Hydroponic Farm stability floor (min 0.5 stability modifier) prevents unrecoverable death spirals
• IBuildingService / BuildingService: ConstructAsync, UpgradeAsync, DemolishAsync, CancelConstructionAsync, AdvanceConstructionAsync
• Buildings are wired into EconomicTickService tick loop; construction advances each tick
• API: GET/POST /api/v1/planets/{id}/buildings, POST .../buildings/{id}/upgrade, DELETE .../buildings/{id}, DELETE .../buildings/construction, GET /api/v1/buildings/definitions
• Frontend: BuildingsPanel, BuildingCard, ConstructBuildingModal on planet detail page; energy bar in panel header

9 — Lazy Tick System

• TICK_INTERVAL_SECONDS env var (default 300 = 5 minutes) → GameConfiguration.TickIntervalSeconds
• ITickClock / TickClock singleton — ElapsedTicks(last, now), Advance(last, n)
• GameStateEntity — singleton row tracking last_global_tick_at for global events (movement, trade, espionage)
• PlanetEntity.last_tick_at (nullable timestamptz) — per-planet tick timestamp
• IEconomicTickService.TickPlanetIfDueAsync(id) — applies all overdue planet ticks at once; construction and production advance by the same number of ticks; called automatically at the start of GET /planets/{id}
• GET /api/v1/game/config — returns { tickIntervalSeconds, lastGlobalTickAt, nextTickAt }
• POST /api/v1/game/tick — forced full tick of all planets (admin/testing)

Planets Pipeline (planets/)

• Node.js + Puppeteer pipeline generating WebM planet videos from GLSL shaders
• CLI supporting single-file and batch modes
• Output to planets/output/

⬜ Not Started

10 — Tech Tree

• Industrial, Fleet Engineering, Administration branches
• Persistent unlock state per player
• Modifiers fed into existing calculator services (efficiency bonuses, new module unlocks, stability buffers)

11 — Rebellion System

• Trigger at stability < 20 sustained for multiple ticks
• Production halted entirely; planet neutralized
• Fleet intervention required to restore order