---
game: Cosmorig
document: Game Specification & Audit
status: active-development
updated: 2026-08-27
commit: 6bea132
---

# Cosmorig — Game Specification & Audit

> Canonical, live document. Code is the source of truth. Statuses:
> `IMPLEMENTED` · `PARTIAL` · `PLANNED` · `IDEA` · `REMOVED` · `UNKNOWN`.

## Executive Summary

Cosmorig is a modern web-first **incremental space-industry game** — a
TypeScript/Svelte/PixiJS reinterpretation of Space Company. The player is
a **director of an industrial civilization**: they start on Earth with
three gatherable resources (metal, wood, gems) and a handful of machines,
then grow through research, energy and rocket-fuel chains, a rocket
launch, colonizing all seven solar bodies, building three Wonders, a Sol
Center plasma economy, interstellar expansion across 27 stars, faction
reputation and military conquest, a Dyson swarm, and galaxy-reset
prestige. The core loop is **build → automate/earn → research →
expand → unlock → repeat**, with automation scaling as the empire grows.
Development is deep past a playable vertical slice: save schema is at
version 18 with safe migrations, 136 unit tests pass, the UI follows a
Dark Space + Industrial Sci-Fi design system with isometric 2.5D assets,
and a Playwright Visual Audit captures the whole UI for desktop and
mobile. The main pillars already implemented are the Earth/solar economy,
interstellar+factions+military layer, and strategic events; still partial
are a visual galaxy map and full i18n; still planned are deeper 3D→2.5D
rendered assets and rounding (balance, native builds).

## Player Fantasy

- **Who:** a director commanding an industrial civilization.
- **What the player manages:** machines and buildings on Earth and
  colonies, energy, research, a rocket program, star expedition and
  fleets, faction relations, megastructures.
- **The world:** a stylized isometric 2.5D sci-fi solar system and galaxy.
- **Goal:** grow from a single mine on Earth to a multi-system industrial
  empire (outpost → colony → Dyson civilization → galactic industry).
- **Emotions targeted:** satisfying idle growth, visible world
  progression, aspirational scale. The world dominates panels — not a
  financial dashboard.
- **Distinguishing goals (from design docs):** "World first, UI second";
  capability-based tech over +5% stats; automation reduces clicking as
  scale grows.

## Core Gameplay Loop

```text
Explore & Build
 → Resources accumulate (idle)
 → Storage caps (upgrade or lose)
 → Research unlocks capabilities
 → Build up the rocketeering chain (fuel → rocket → launch)
 → Expand solar system (colonize, produce)
 → Wonders / Sol Center / interstellar (antimatter → stars)
 → Factions / fleet (conquest), events, Dyson
 → Prestige reset (dark matter) → start loop stronger
```

### First 5 Minutes
A contextual onboarding card walks a new player through: Earth location
→ first gather → build a Miner → open Research → unlock energy → plan the
launch. State-driven: already-done steps auto-skip; the mission "Reach
Orbit" stays visible as the goal.

### First 30 Minutes
Produce science via labs; research storage/basic energy/oil/solar/
machines/space; buy oil pumps and chemical plants; refit rocket fuel;
launch into orbit (animated); exploration appears; decide between
mining vs production vs research (Colony Policy available later).

### Normal Session
Keep buildings producing, buy upgrades, research the next capability,
explore bodies/stars, answer strategic events, spend faction
reputation, upgrade ships, connect logistics.

### Long-Term Loop
Over days: prestige resets bank dark matter (+50% prod each), drive
techs expand the star map, conquest extends control, Dyson swarms, and
the Galactic Overview shows empire scale.

## Player Journey

1. **First launch** — COSMORIG boots the Svelte shell; fresh save or
   legacy import; a fresh save auto-starts the guided onboarding
   (step 1: Welcome to Earth).
2. **Starting state** — metal/wood/gem, miner/woodcutter/gemMiner/lab
   unlocked; storage 50.
3. **First decision** — manual gathering vs upgrading; which building.
4. **First resource acquisition** — gather + build order.
5. **First upgrade** — building count scaling (×1.1 cost), storage
   upgrades after `unlockStorage`.
6. **First expansion** — energy (charcoal/solar), oil, chemical plant.
7. **First strategic choice** — rocket launch (fuel bank vs launch), then
   which solar body to explore, which wonder/policy to prioritize.
8. **Mid-game** — interstellar: antimatter economy, Impulse/Warp drives,
   faction contracts, fleet conquest, Dyson.
9. **Long-term** — prestige loops, full galaxy, Galactic Overview.
_Missing beyond this: galaxy-wide settlement management and endgame
content beyond the Overview (see Missing Gameplay)._

## Game Systems Overview

| System | Status | Purpose | Player Interaction |
| --- | --- | --- | --- |
| Guided Onboarding | IMPLEMENTED | First-run micro-tutorial | context card, skip/later |
| Earth Economy (resources/buildings) | IMPLEMENTED | Core idle production | build, upgrade, toggle |
| Research / Tech | IMPLEMENTED | Capability unlocks (incl. range) | buy research |
| Storage | IMPLEMENTED | Capacity scaling | buy upgrades |
| Automation Toggles | IMPLEMENTED | Charcoal/fuel/energy control | toggle |
| Rocket / Launch | IMPLEMENTED | Gate to space, animated | launch |
| Solar System / Colonies | IMPLEMENTED | 7 bodies, planet production | explore + build |
| Wonders (x3) | IMPLEMENTED | Production multipliers | tier build + activate |
| Sol Center / Plasma | IMPLEMENTED | Advanced energy → antimatter | build generators |
| Interstellar / Stars | IMPLEMENTED | 27-star map, range-gated | explore |
| Factions | IMPLEMENTED | Reputation + efficiency contracts | contract purchase |
| Military / Conquest | PARTIAL | Star conquest (stat combat) | build ships, attack |
| Strategic Events | IMPLEMENTED | Expansion decisions | choose outcome |
| Dyson Swarm | IMPLEMENTED | Energy multiplier | build segments |
| Prestige / Galaxy Reset | IMPLEMENTED | Dark matter meta-progression | reset |
| Achievements | IMPLEMENTED | Milestones (monotonic) | passive |
| Missions / Objectives | IMPLEMENTED | Early guidance chain | passive/active |
| Colony Policy | IMPLEMENTED | Production bias | choose policy |
| Logistics Routes | PARTIAL | Read-only route listing | view |
| Diplomacy ladder | IMPLEMENTED | Reputation tiers | passive/visible |
| Director Command | IMPLEMENTED | Derived +10% production layer | passive + status/help |
| Visual Galaxy (map render) | PARTIAL | Overview + star lists | navigate panels |
| Fleet ship visuals | PARTIAL | Sprites shown; no combat anim | view |
| Economy balancing | PARTIAL | Values scaled from legacy | passive |
| i18n | PARTIAL | `t()` scaffold; partial keys | passive |
| Multiplayer/social | IDEA | Not present | — |
| Backend/API/multiplayer | REMOVED/absent | No server gameplay | — |

## Major Mechanics (detail)

### Earth Economy
**Status:** IMPLEMENTED
- **Purpose:** primary idle production loop.
- **Player actions:** gather (metal/wood/gem/charcoal), buy buildings,
  buy storage upgrades, toggle automation.
- **Inputs/Costs:** building costs scale `base × 1.1^owned`; gathered
  resources capped by storage.
- **Time:** accumulation every simulated second (rAF clock, silent ticks,
  12s autosave flush + tab-hide).
- **Outputs:** resources; buildings convert to /s production.
- **Progression:** research unlocks oil/energy/rocket fuel; wonders and
  Dyson multiply output.
- **Current limitations:** no per-building consumption beyond
  chemical/plasma chains; oil pump has no energy cost (legacy-faithful).

### Research
**Status:** IMPLEMENTED
- Purpose/Range: gated capability unlocks; includes **Exploration Range**
  techs (Impulse 12 LY, Warp 30 LY) that literally open the star map.
- 8 researches: storage, basic energy, oil, solar, machines,
  solar system, impulse drive, warp drive.
- Limitations: linear chain; no parallel branches yet.

### Rocket & Launch
**Status:** IMPLEMENTED
- Cost: 20 rocket fuel + a built rocket pad. On launch: pad consumed,
  fuel spent, `rocketLaunchedAt` recorded, orbit reached (unlocks
  `solar`), Pixi launch animation plays (~2.6 s), event toasts +
  achievements. Waystation markers appear in the Earth scene.

### Solar System & Colonies
**Status:** IMPLEMENTED
- 7 bodies (Moon, Venus, Mars, Asteroid Belt — inner; Jupiter, Saturn,
  Pluto — outer) with fuel costs (20…5000) and resource unlocks
  (lunarite, methane, titanium+silicon, gold+silver, hydrogen, helium,
  ice). Explored bodies unlock planet production buildings
  (lunariteMine…silverMine) shown in the Map panel.
- Limitations: no per-planet management beyond those buildings; colony
  specialization is global (Colony Policy), not per body.

### Wonders
**Status:** IMPLEMENTED
- Three wonders, each 5 tiers + activation: Precious (gem → ×2 gems),
  Energetic (wood/charcoal → ×2 energy), Tech (silicon/gold/gem → ×2
  science). Tiers cost within storage reach; activations spend
  resources and set permanent modifiers.

### Sol Center / Plasma
**Status:** IMPLEMENTED
- Super-Heater spends 20 energy + 2 hydrogen/s → +1 plasma/s.
  Unlocked after exploring all solar bodies. Feeds antimatter.

### Interstellar
**Status:** IMPLEMENTED
- Antimatter Condenser (100 energy + 10 plasma/s → 1 antimatter/s).
  27 stars from legacy `starData.js` with distance → antimatter cost
  (≈ ×116) and defense; travel gated by Exploration Range
  (base 5 → Impulse 12 → Warp 30). Explored stars grant faction
  reputation and resources.

### Factions
**Status:** IMPLEMENTED
- 5 factions (Hyacinite, Carnelian, Prasnian, Kitrinos, Moviton).
  Exploring/conquering stars raises reputation; **efficiency contracts**
  spend reputation per level to raise global resource efficiency 1%/lvl.
  Reputation ladder: Hostile ←10→ Unfriendly ←25→ Neutral ←50→ Friendly
  ←100→ Allied. Trade colony policy amplifies reputation gains (+50%).

### Military / Conquest
**Status:** PARTIAL
- Ships: **Scout** (power 3), **Frigate** (power 5) as buildings.
  Conquer an explored star when fleet power ≥ star defense (legacy
  values up to ~956); grants reputation ×15. No animated combat or ship
  HP — resolution is stat-based. Ship SVG sprites exist and show in a
  Fleet panel block; cruiser/cargo sprites are decorative previews.

### Strategic Events
**Status:** IMPLEMENTED
- 4 deterministic events (Unknown Colony, Rich Asteroid, Refugee Fleet,
  Trader Cartel) spawn after star exploration/conquest once no event is
  active. Choices apply resource gains or faction reputation
  (effects applied against capacities); seen events never repeat.

### Dyson
**Status:** IMPLEMENTED
- Up to 10 segments; each +8% energy production (modifier `dysonBoost`);
  costs metals (metal/titanium/gold/lunarite) scaling ×1.15.

### Prestige
**Status:** IMPLEMENTED
- Galaxy Reset: requires orbit; banks +1 dark matter per reset and sets
  `darkMatterBoost = 0.5 × darkMatter` (permanent production bonus).
  Resets Earth/research/solar/wonders; **keeps** achievements (now
  monotonic), interstellar exploration/conquest, faction state.

### Achievements & Objectives
**Status:** IMPLEMENTED
- 13 achievements evaluated from live state and persisted monotonically.
- Launch mission chain: Miner → Energy → Rocket Fuel → Rocket → Moon.

### Colony Policy
**Status:** IMPLEMENTED
- Global policy: balanced, industry (+15% resources), extraction
  (+10%), science (+25%), energy (+25%), trade (+50% rep).

## Player Actions

| Action | Screen | Cost | Time | Result | Unlocks | Status |
| --- | --- | --- | --- | --- | --- | --- |
| Gather resource | Base | none | instant | +1 capped | — | IMPLEMENTED |
| Buy building | Base/Map | scaled resources | instant | +production | more | IMPLEMENTED |
| Storage upgrade | Base | resource+metal | instant | cap ×2 | — | IMPLEMENTED |
| Buy research | Research | science | instant | capability | next research | IMPLEMENTED |
| Set automations | Base | none | instant | toggles | — | IMPLEMENTED |
| Launch rocket | Base/context | 20 fuel + pad | instant | orbit, animation | solar | IMPLEMENTED |
| Explore body | Map | rocket fuel | instant | resource unlocks | colony buildings | IMPLEMENTED |
| Buy planet building | Map | resources | instant | colony production | — | IMPLEMENTED |
| Build/activate wonder | Wonders | resources | instant | modifier ×2 | — | IMPLEMENTED |
| Explore star | Map | antimatter (range-gated) | instant | star, reputation | stars | IMPLEMENTED |
| Attack star | Map | fleet power ≥ defense | instant | conquest, +rep | — | IMPLEMENTED |
| Faction contract | Map | reputation | instant | +1% efficiency | — | IMPLEMENTED |
| Choose event | Home alert | choice | instant | resources/rep | — | IMPLEMENTED |
| Select scene object | World canvas | none | instant | contextual panel | — | IMPLEMENTED |
| Dyson segment | More | metals | instant | +8% energy | — | IMPLEMENTED |
| Reset galaxy | More | orbit req. | instant | dark matter, wipe | stronger loop | IMPLEMENTED |
| Set colony policy | More | none | instant | production bias | — | IMPLEMENTED |

## Resources & Economy

| Resource | Source | Usage | Storage | Status |
| --- | --- | --- | --- | --- |
| Metal | miner | buildings, everything | 50+ | IMPLEMENTED |
| Wood | woodcutter | buildings, charcoal | 50+ | IMPLEMENTED |
| Gems | gemMiner | buildings, wonders | 50+ | IMPLEMENTED |
| Charcoal | manual/gather | energy, rocket fuel | 50+ | IMPLEMENTED |
| Energy | solar/charcoal | plasma, antimatter | 100k | IMPLEMENTED |
| Science | lab | research | ∞ | IMPLEMENTED |
| Oil | oilPump | rocket fuel | 50+ | IMPLEMENTED |
| Rocket fuel | chemical plant | launches | ∞ | IMPLEMENTED |
| Lunarite/Methane/Titanium/Silicon/Gold/Silver | planet buildings | buildings, wonders, stars | 50+ | IMPLEMENTED |
| Hydrogen/Helium/Ice | outer bodies | plasma, stars | 50+ | IMPLEMENTED |
| Plasma | Super-Heater | antimatter | 50k | IMPLEMENTED |
| Antimatter | Condenser | star travel | 50k | IMPLEMENTED |

**Flow:** SOURCE → RESOURCE → PLAYER DECISION → SINK → PROGRESSION.
**Noted issues to document (not fixing):** several late resources lack
deep sinks beyond a single cascade (silver/gold mostly power wonders and
star counts); energy has a very large cap (100k) vs. modest sinks;
colony “industry/extraction” partially duplicate each other. Balance is
intentionally unchanged.

## Progression

- Early: manual→automatic Earth production, storage, science, oil,
  rocket fuel. Mid: solar colonization, wonders, plasma/antimatter,
  interstellar, factions, military, events, Dyson. Late: prestige loops
  (dark matter), full 27-star map, Galactic Overview.
- Strength drivers: building counts, modifiers (efficiency, wonders,
  Dyson), dark matter boost, efficiency contracts.
- No levels/XP; progression is capability- and multi–plier-based.
- **Late game beyond prestige/overview is thin** — flagged below.

## Timers & Time-Based Mechanics

| Action | Duration | Accelerable | Impact | Status |
| --- | --- | --- | --- | --- |
| Offline gains on load | <=8 h cap | no | idle reward | IMPLEMENTED |
| Autosave tick | ~1 s simulation, 12 s flush | no | durability | IMPLEMENTED |
| Rocket launch animation | ~2.6 s | no | spectacle | IMPLEMENTED |
| Production accrual | continuous | buildings/boost | core | IMPLEMENTED |
| Event/alert | instant | no | decisions | IMPLEMENTED |
| Conquest/exploration | instant | no | expansion | IMPLEMENTED |

## Universe & Map

- Earth scene (Pixi world): planet, industrial clusters, rocket, orbit
  traffic, per-body waystations; camera pan/zoom/reset; click-select
  clusters → contextual side panel.
- Solar System: 7 bodies (Map panel list + scene waystations).
- Interstellar: 27 stars (distance, faction, resources, defense) in a
  list within the Map; exploration gated by range; no rendered starfield
  map yet (PARTIAL → Planned).
- Galaxy Overview aggregates empire stats (discovered/controlled
  systems, colonies, industry, energy, science, fleet, Dyson, range,
  top faction) and cargo-route listing (surveyed/active).

## AI / NPC / Simulated Companies

- **No AI players / NPC economy / market simulation.**
- Strategic events are deterministic scripted decision points (not
  simulator-driven NPCs).

## Multiplayer & Social

- **None.** No accounts, ranks, PvP, alliances, trading between players,
  or leaderboards. Status: IDEA (not built).

## UI / Screens

| Screen/Panel | How opened | Purpose | Actions | Status |
| --- | --- | --- | --- | --- |
| Home / Base | nav Base / default | build, gather, storage, automation, contextual selection | buy/upgrade | IMPLEMENTED |
| Research | nav Research | tech tree | buy tech | IMPLEMENTED |
| Map | nav Map | solar + interstellar + fleet + factions + logistics | explore/build/attack | IMPLEMENTED |
| Wonders | nav Wonders | 3 wonders | tier build/activate | IMPLEMENTED |
| More | nav More | progress, galactic overview, sectors(Sol Center), achievements, settings(Low FX), colony policy, prestige, Dyson | misc | IMPLEMENTED |
| Sol Center | More→Open Sol Center | plasma production | build generators | IMPLEMENTED |
| Event alert card | left panel | strategic choice | choose | IMPLEMENTED |
| Context selection | click scene cluster | object panel (upgrade/launch) | upgrade | IMPLEMENTED |
| Tutorial card | floating (first-run / restart) | step guidance + highlight | Continue / Skip | IMPLEMENTED |
| Loading / Recovery | boot / error | states | — | IMPLEMENTED |

Nav is bottom-pill (5 slots) on desktop and mobile; right panel swaps by
active state. No separate company/fleet/ships/ranking/market screens
exist (fleet is a block in Map; ships are sprites + power).

## Visual Audit

- Local Playwright runner: `npm run visual:audit` (desktop 1440×900,
  mobile 390×844; optional tablet off). Runs against `/?seed=full` (a
  dev-only full-empire state), waits for the Svelte shell + nav, clicks
  panels, screenshots into `public/visual-audit/`.
- Cloudflare Browser Rendering worker variant available
  (`visual:audit:cf`) for remote capture.
- Gallery and manifest are generated into `public/visual-audit/` and
  ship with the site:
  - Gallery: `https://cosmorig.pages.dev/visual-audit/` (adjust to the
    real production host)
  - Manifest: `https://cosmorig.pages.dev/visual-audit/manifest.json`

## Screenshot Index

<!-- GAME-SPEC:SCREENSHOTS -->
| UI State | Desktop | Mobile |
  | --- | --- | --- |
  | Earth Industrial Zone | [desktop](/visual-audit/screenshots/earth-industrial-zone-desktop.png) | [mobile](/visual-audit/screenshots/earth-industrial-zone-mobile.png) |
  | Event | [desktop](/visual-audit/screenshots/event-desktop.png) | [mobile](/visual-audit/screenshots/event-mobile.png) |
  | Fleet | [desktop](/visual-audit/screenshots/fleet-desktop.png) | [mobile](/visual-audit/screenshots/fleet-mobile.png) |
  | Home | [desktop](/visual-audit/screenshots/home-desktop.png) | [mobile](/visual-audit/screenshots/home-mobile.png) |
  | Map | [desktop](/visual-audit/screenshots/map-desktop.png) | [mobile](/visual-audit/screenshots/map-mobile.png) |
  | Research | [desktop](/visual-audit/screenshots/research-desktop.png) | [mobile](/visual-audit/screenshots/research-mobile.png) |
  | Settings | [desktop](/visual-audit/screenshots/settings-desktop.png) | [mobile](/visual-audit/screenshots/settings-mobile.png) |
  | Solcenter | [desktop](/visual-audit/screenshots/solcenter-desktop.png) | [mobile](/visual-audit/screenshots/solcenter-mobile.png) |
  | Tutorial Director Command | [desktop](/visual-audit/screenshots/tutorial-director-command-desktop.png) | [mobile](/visual-audit/screenshots/tutorial-director-command-mobile.png) |
  | Tutorial First Step | [desktop](/visual-audit/screenshots/tutorial-first-step-desktop.png) | [mobile](/visual-audit/screenshots/tutorial-first-step-mobile.png) |
  | Tutorial Industrial Zone | [desktop](/visual-audit/screenshots/tutorial-industrial-zone-desktop.png) | [mobile](/visual-audit/screenshots/tutorial-industrial-zone-mobile.png) |
  | Wonders | [desktop](/visual-audit/screenshots/wonders-desktop.png) | [mobile](/visual-audit/screenshots/wonders-mobile.png) |
  
  Regenerated: 2026-08-27T09:27:46.295Z (24 screenshots)
<!-- /GAME-SPEC:SCREENSHOTS -->

# Game Design Audit

## Core Loop Audit
**Strong.** The loop (build→earn→research→expand→repeat) is visible,
linked, and each action feeds the next; idle feedback is constant (HUD
rates, toasts, achievements). The early mission gives a clear direction.

## Onboarding Audit
**Acceptable→needs polish.** First objective is explicit ("Reach Orbit"
chain) and the world draws attention, but resource discovery (space
resources) only appears after exploration and there is little in-game
explanation of chains (storage caps, energy). UI shows the next
mission step; option count is manageable.

## Progression Audit
**Strong early/mid, weak endgame framing.** Clear short-term (next
building/tech) and mid-term goals (rocket→solar→interstellar). Long-term
aspiration exists (Galactic Overview, prestige) but the galaxy map is a
list, not a visual territory — expansion feels abstract late.

## Economy Audit
**Acceptable.** Sources/sinks mostly connect; prestige and wonders give
meaningful multipliers. Weakness: several resources (silver, gold,
silicon…) have thin late sinks; energy cap is large vs. sinks; wild
contracts/efficiency can inflate numbers; a few curves (star costs,
defense) are straight legacy scalings.

## Strategic Decisions
**Partial.** Real decisions exist (research vs. production, which body/
star, wonder vs. conquest, policy, prestige timing). However most
repeated actions are "buy upgrade" — middle-long game needs more
A-vs-B and risk choices (fleet losses, expedition commitment, event
trade-offs already hint at it).

## Session Structure
- 1–5 min: meaningful (gather, buy, research, toasts) ✓
- 10–20 min: good (rocket, solar, events) ✓
- Returning player: offline report + mission/next step ✓
- Daily return: weak pull — no daily contracts/objectives; prestige is
  the main long pull.

## UX Audit
**Good overall.** Clear hierarchy (world dominant), readable tokens,
consistent panels, bottom-pill nav; contextual selection and Low FX +
reduced-motion. Mobile is functional but dense in More (long vertical
panel); some microtext sizes hover near the 12 px floor; loading/
recovery states are plain. Consistency is high; feedback (toasts,
"HUD full", focus rings) is present.

## Missing Gameplay / Gaps

**Critical**
- Rich visual galaxy map with territory/routes/zoom (currently a list).
- Mid/late goals beyond prestige (colony specialization per body,
  logistics that matter, meaningful fleet ops).

**Important**
- Per-planet colony management & selection.
- Daily/weekly goals + notifications (return-pull).
- Economy depth: real energy costs, resource sinks, balance pass.

**Optional**
- Full i18n, animated combat, leaderboards/intro-social, deeper event
  pool, onboarding tutorial.

## Current Strengths
- Coherent, extensible architecture: data-driven systems + versioned
  validated saves (V18) + migrations + 136 green tests.
- Clean presentation layer: Svelte + Pixi, design system, isometric
  SVG/procedural assets, procedural policy (no external graphics).
- Visible world progression (waystations, launch animation, clusters,
  camera) and automation as you scale.
- Offline progress, PWA, throttled autosave — good idle hygiene.

## Current Weaknesses
- Late-game abstraction (galaxy is a panel list, not a map).
- Economy pacing/late sinks & large energy cap; wild balance scaling.
- More panel is dense on mobile.
- Limited strategic depth beyond buying upgrades in the middle loop.
- No return-pull (daily/weekly), no social layer, partial i18n.

## Open Design Questions
- Should Exploration Range scale travel *time* or just accessibility?
- Is Conquest a real soft-4X layer or only a stat gate?
- Where do logistics/cargo matter economically (routes are read-only)?
- Should colony policy be per-body rather than global?
- How do events scale with empire size without feeling random?
- Is prestige interesting before a visual galaxy map exists?

## Recommended Development Priorities

**P0 — Critical**
- Problem: galaxy map is a list → expansion feels abstract.
  Why: long-term engagement depends on seeing territory grow.
  Direction: render explored stars/conquered systems on a procedural
  Pixi galaxy view with faction tints and routes (reuse existing data).
  Impact: dramatic late-game clarity and motivation.

**P1 — High**
- Problem: economy late sinks/thin choices.
  Why: mid-late loop devolves into buying upgrades.
  Direction: energy cost model for planet/ship upkeep, per-body colony
  specialization, a lightweight logistics economy (cargo capacity/time).
  Impact: real A-vs-B decisions and number-driven growth.

**P1 — High**
- Problem: return-pull missing.
  Why: idle retention.
  Direction: daily/weekly objectives + notifications module.
  Impact: stronger daily loop.

**P2 — Medium**
- Problem: onboarding explanation thin (chains, caps).
  Why: early churn.
  Direction: contextual tips tied to the mission panel.
  Impact: better first-30-minutes.

**P3 — Later**
- Military animation, i18n completion, social/leaderboards, balance
  script pass.

## Implementation Status

| Feature | Status | Evidence |
| --- | --- | --- |
| Earth economy | IMPLEMENTED | `src/core/economy/*`, `buildings/*` |
| Research | IMPLEMENTED | `src/core/research/earthResearch.ts` |
| Storage | IMPLEMENTED | `src/core/economy/storage.ts` |
| Rocket launch | IMPLEMENTED | `src/core/state/actions.ts` (launch) + renderer |
| Solar / colonies | IMPLEMENTED | `src/core/solar/solarSystem.ts` |
| Wonders | IMPLEMENTED | `src/core/wonders/*` |
| Sol Center | IMPLEMENTED | `earthSimulation` plasma block |
| Interstellar | IMPLEMENTED | `src/core/interstellar/*` |
| Range techs | IMPLEMENTED | `src/core/interstellar/range.ts` |
| Factions | IMPLEMENTED | `src/core/factions/factions.ts` |
| Military | PARTIAL | `src/core/interstellar/military.ts` (stat combat) |
| Events | IMPLEMENTED | `src/core/events/strategicEvents.ts` |
| Dyson | IMPLEMENTED | `src/core/dyson/dyson.ts` |
| Prestige | IMPLEMENTED | `actions.ts` resetGalaxy |
| Achievements | IMPLEMENTED | `src/core/achievements/achievements.ts` |
| Colony policy | IMPLEMENTED | `src/core/colonies/policies.ts` |
| Director Command | IMPLEMENTED | `src/core/director/directorCommand.ts` + sim boost |
| Guided Onboarding | IMPLEMENTED | `src/core/tutorial/tutorial.ts`, save V19 |
| Logistics (routes) | PARTIAL | `src/core/logistics/routes.ts` (read-only) |
| Save (V18) | IMPLEMENTED | `src/core/save/*`, migrations V1→V18 |
| Offline progress | IMPLEMENTED | `offlineProgress.ts` |
| UI panels/nav | IMPLEMENTED | `apps/web/App.svelte`, `EarthViewport.svelte` |
| PWA / Capacitor config | IMPLEMENTED | `public/*`, `capacitor.config.json` |
| i18n | PARTIAL | `src/i18n/strings.ts` |
| Visual audit | IMPLEMENTED | `scripts/visual-audit/*` + worker variant |

## Recent Changes
Notable gameplay/UI history (git, most recent first):
- Colony policy, strategic events, diplomacy/logistics/error monitoring.
- 2.5D procedural ship sprites + fleet panel; Playwright visual audit.
- Interstellar star roster (27), exploration-range drive techs, Galactic
  Overview, world camera, Dyson, prestige, factions/military, Sol Center,
  wonders, solar system/colonies, rocket launch, offline progress,
  PWA, save migration chain, Playwright layout fixes (mobile nav).

## Known Technical Limitations
- Late-game is list-driven (no rendered galaxy/territory).
- More panel density on mobile; tiny microtext in places.
- Energy economy underused (large cap, thin sinks).
- No server backend: saves live in browser IndexedDB/localStorage.
- Visual Audit requires a built/previewed app or deployed worker.

---

# LLM Quick Context

**What Cosmorig is:** a web incremental space-industry game (TS +
Svelte 5 + PixiJS 8), a ground-up rework of Space Company. Player is the
"director" of an industrial civilization. Save schema V18 (Zod-validated,
migrations V1→V18, legacy import, IndexedDB + localStorage backup).

**Current core loop:** build on Earth (metal/wood/gems) → energy &
rocket fuel → research (8 techs incl. drive-range techs) → rocket launch
(animated) → colonize 7 solar bodies (planet production buildings) →
3 wonders (gem/energy/science ×2) → Sol Center plasma → antimatter →
explore 27 stars (range-gated: 5 LY base, Impulse 12 LY, Warp 30 LY) →
factions (reputation + efficiency contracts; ladder Hostile..Allied) →
conquest (Scout 3 / Frigate 5 power vs star defense) → strategic events →
Dyson (+8% energy/segment) → galaxy reset prestige (dark matter +50%/reset).
Idle: rAF clock simulates each second silently, save flushes every 12 s
and on tab hide; offline gains capped at 8 h.

**Main resources (19):** metal, wood, gem, charcoal, energy, science,
oil, rocketFuel, lunarite, methane, titanium, silicon, gold, silver,
hydrogen, helium, ice, plasma, antimatter.

**Main progression:** buildings + storage caps → tech capabilities →
solar/interstellar expansion → multipliers (wonders, Dyson, efficiency
contracts, dark matter) → Galactic Overview (empire stats + routes).

**Main screens:** Base (build/manual/storage/automation/context-select),
Research, Map (solar + interstellar + fleet + factions + logistics),
Wonders, More (progress/overview/Sol Center launcher/achievements/
settings(Low FX)/colony policy/prestige/Dyson), plus event-alert card in
the left panel. Bottom pill nav (5 slots, desktop+mobile).

**Major implemented mechanics:** full Earth economy, research with
capability techs, storage upgrades, launch animation, solar colonies,
3 wonders, Sol Center, antimatter/interstellar, factions & contracts,
conquest, strategic events, Dyson, prestige, 13 achievements, Colony
Policy, Director Command (+10% production), guided onboarding (8 contextual
steps, save-persisted), offline + autosave, PWA, camera (pan/zoom/reset), context
selection, design system + isometric SVG assets + Playwright Visual
Audit (local Playwright, optional CF Browser worker).

**Major incomplete mechanics:** rendered galaxy map (currently lists),
fleet beyond stat conquest (no combat anim), logistics read-only,
i18n partial, per-body colony management, onboarding tips, balancing.

**Current biggest gameplay problems:** late-game expansion is abstract
(no visual territory); middle-loop decisions thin out to "buy upgrade";
economy has thin late sinks (silver/gold) and a large energy cap; weak
daily return-pull; mobile More panel is dense.

**Visual Audit:** local `npm run visual:audit` → `public/visual-audit/`
(gallery `index.html` + `manifest.json`); served after deploy at
`https://cosmorig.pages.dev/visual-audit/` (adjust host).

<!-- GAME-SPEC:QC-META -->
**Game spec commit:** `6bea132` · **Visual audit commit:** `6bea132` (generated 2026-08-27T09:27:05.772Z) · **Updated:** 2026-08-27
<!-- /GAME-SPEC:QC-META -->
**Last updated:** 2026-08-27 · commit `pending`.