# Magic Civilization — Development Roadmap

> Fresh build starting from M0. Reference implementation: `@magic-civilization.messy/`

## Early Access Scope ("Age of Dwarves")

Single playable race (Dwarf), no magic, mundane tech paths only. Same complete 4X game built end-to-end — roughly half the work of Age of Dwarves.

### Track 2a: Age of Dwarves (EA release)

| System | Scope |
|--------|-------|
| Hex map | Full — 20 terrain types, natural wonders, resources, fog of war |
| Map generation | 5 presets (Duel, Team Duel, FFA, FFA-Cross, FFA-Plus) |
| World simulation | Full — climate, flora/fauna, natural events (mundane fauna only). **Runtime worldsim is the game's USP**: a living, continuously-simulating world (per-turn flora succession + fauna population/migration + terraforming→environmental cascade), not a static map. Engines already exist + tested (`mc-ecology`/`mc-flora`/`mc-climate`); the work is wiring them into the playable turn via the new `mc-worldsim` crate (`p2-80`). Objectives `g2-05`–`g2-10` + `p2-75`–`p2-80` (promoted from Game 2, owner decision 2026-06-06). |
| Units | Full — movement, pathfinding, stacking, vision |
| Cities | Full — founding, growth, tile working, production queue, buildings, Deep Forge |
| Tech web | 6 mundane pillars + intersections (no school branches, no fusions) |
| Combat | Full — 1UPT, flanking, ZOC, ranged, terrain, fortification, promotions, siege |
| Happiness | Full — global pool, modifiers, Golden Ages |
| Victory | Domination, Score |
| AI | Basic — 1-3 Dwarf opponents |
| Save/Load | Basic — single slot + auto-save |

### Track 2b: Age of Dwarves (expansion)

Adds on top of 2a: 3 additional races (High Elf, Human, Orc), M4 (ley lines, mana, corruption), Phase 9 (spells, Archons, summoning, Ascension), magic school tech branches, fusion techs, 2-school lock, Arcane Ascension victory.

### Excluded (post-expansion)

12 additional races, 7 additional fusions, diplomacy, social policies, naval combat, Freepeople havens, trade routes, government types, strategic resources, game speed options, Ethereal Plane.

---

## M0: Foundation
**Goal:** Godot project opens, loads theme pack, shows something on screen. Transpiler pipeline verified.

- [ ] `project.godot` with autoloads registered
- [ ] `.gitignore`, `export_presets.cfg`, `gdlintrc`
- [ ] All 9 autoloads: EnvConfig, EventBus, GameLogger, DataLoader, GameState, TurnManager, ThemeVocabulary, ThemeAssets, SettingsManager
- [ ] Minimal data: `game.json`, `vocabulary.json`, `climate_spec.json`
- [ ] Main menu scene with "New Game" button
- [ ] pnpm workspace + guide shell
- [ ] Transpiler pipeline: climate GDScript -> TypeScript verified

**Done when:** `godot --headless --quit` exits 0. Main menu visible. `pnpm dev` serves guide. `transpile.py --check` exits 0.

---

## M1: Climate & Geology
**Goal:** The inorganic physical world. Temperature, pressure, wind, water, biomes.

- [ ] All terrain/climate/hydrology JSON data (FEATURE_GAP 3.1 additions)
- [ ] Map core: `hex_utils.gd`, `tile.gd`, `game_map.gd`
- [ ] Map generation pipeline (9-stage): landmass, elevation, sea level, relief, temperature, moisture, terrain patches, wind, hydrology
- [ ] Climate physics: temperature, moisture advection, pressure, wind, precipitation
- [ ] Atmosphere: pressure bands, Coriolis, dynamic anomalies
- [ ] Hydrology: Planchon-Darboux depression fill, D8 flow routing, rivers, lakes
- [ ] Biome assignment from climate gradients
- [ ] GDScript<->TypeScript golden vectors (seed 42)
- [ ] Guide climate visualizer (all lenses)

**Done when:** Rivers flow downhill. Biomes form correctly. Climate deterministic. Golden vectors pass. Guide renders all lenses.

---

## M2a: Ecosystem Engine — Architecture + Proof
**Goal:** Decompose terrain into geological substrate + computed biomes. Build Lotka-Volterra population dynamics. Prove with 6 species across 5 biomes.

- [ ] Substrate refactor: terrain_id → biome_id, substrate fields, water body identification
- [ ] OOP models (BiomeModel, SpeciesModel, FloraProfile) + DataLoader typed returns
- [ ] SQLite for dynamic population state
- [ ] BiomeClassifier: substrate + climate + flora → biome_id (~5 proof biomes)
- [ ] Flora dynamics: canopy/undergrowth/fungi with cross-effects, succession, desertification
- [ ] Fauna dynamics: Lotka-Volterra, migration, carrying capacity (grass→deer→wolf, phytoplankton→fish→whale)
- [ ] Marine harvest port, NPC buildings (lairs/villages), ecosystem health metric
- [ ] Sprite-gen extended for species + substrate + biome categories
- [ ] Game pack: age-of-dwarves → age-of-dwarves

**Done when:** Wolf population tracks deer. Fish breed in lakes. Biomes shift with climate. SQLite stores populations. 6 species end-to-end.

---

## M2b: Full Planetary Mundane Ecosystem
**Goal:** Fill the planet with life. All 25 Earth biomes, all 39 species, full food webs.

- [ ] Remaining 20 biome definitions + complete BiomeClassifier
- [ ] Remaining 33 species authored (13 flora + 10 herbivores + 10 predators)
- [ ] Full food web tuned for population stability (200 turns, 5 seeds)
- [ ] Cross-biome species (bear fishes, eagle hunts across biomes)
- [ ] Full sprite generation: 39 species × 20 variants, 25 biomes × Q1-Q5
- [ ] Guide: all biomes, all species, food web visualization
- [ ] Golden vectors for all species + biomes

**Done when:** Every hex has appropriate biology. 15+ biomes on standard map. Predator-prey oscillations dampen. All 39 species stable.

---

## M3: Natural Events
**Goal:** Dynamic disruptions reshape geology and biology.

- [ ] Event dispatch engine: `hash_noise()` PRNG, frequency/severity rolls
- [ ] Geological events: volcanic eruption, earthquake, tsunami, impact
- [ ] Ecological events: wildfire, drought, plague, pandemic
- [ ] Global events: marine die-offs, solar events, glacial events
- [ ] Weather system
- [ ] Terrain evolution: quality ladder, climate-driven terrain flip
- [ ] Guide event timeline + impact visualization

**Done when:** Events fire deterministically. Volcanic eruption creates terrain. Wildfire burns forest (regrows via M2). Events match GDScript<->TypeScript.

---

## Phase 5: Map Rendering + Units
**Goal:** See the world. Move things on it.

- [ ] `TileMapLayer` renders terrain sprites
- [ ] Camera — pan (WASD/drag/edge scroll), zoom (scroll wheel)
- [ ] Fog of war — unexplored / fog / visible
- [ ] `Unit` class — type, stats, position, owner, movement
- [ ] Founder + Wanderer at game start
- [ ] Click-to-select, A* pathfinding, animated movement
- [ ] Vision radius, fog updates
- [ ] Turn system — movement refresh, "End Turn" button
- [ ] Village discovery — reward on entry

**Done when:** Map renders. Camera moves. Units move. Fog clears. Turns cycle.

---

## Phase 6: Cities
**Goal:** Found cities, grow them, produce things.

- [ ] Founder "Found City" action
- [ ] `City` class — position, owner, population, worked tiles
- [ ] Tile yield calculation — food/production/trade (modified by M2 ecology)
- [ ] Population growth from food surplus
- [ ] Production queue — units and buildings
- [ ] Building completion effects (including Deep Forge)
- [ ] Unit completion — spawns on map
- [ ] City screen UI
- [ ] Multiple cities per player
- [ ] Happiness system (global pool)
- [ ] Culture + border expansion

**Done when:** Found a city, assign tiles, build a Spearman, see it appear on map.

---

## Phase 7: Tech Web
**Goal:** Research techs, unlock things.

- [ ] `TechWeb` — directed graph from techs.json
- [ ] Science accumulation -> current research
- [ ] Tech completion -> unlock signals
- [ ] Production gating by tech
- [ ] Tech tree UI — 6-pillar mundane web
- [ ] Click to research (if prereqs met)

**Done when:** Research Construction -> City Walls. Mundane tech progression through all 5 eras.

---

## Phase 8: Combat
**Goal:** Units fight.

- [ ] 1UPT enforcement + specialist stacking
- [ ] Click enemy to attack
- [ ] `CombatResolver` — damage formula, variance
- [ ] Flanking, Support, ZOC
- [ ] Ranged (no retaliation, LoS)
- [ ] Terrain defense bonuses
- [ ] Fortification
- [ ] Territory healing gradient
- [ ] Promotions — 4 levels, branching, heal 30% on level-up
- [ ] City siege — city HP, wall penalty, siege bonus
- [ ] Combat preview + result UI
- [ ] Wild creature spawning, combat, lair clearing (mundane fauna)

**Done when:** Flanking, ZOC, ranged, promotions, siege all work. Lairs can be cleared.

---

## Phase 10: AI & Difficulty
**Goal:** Play against someone.

- [ ] Hot-seat multiplayer
- [ ] All players are Dwarves with `dwarf_heritage` origin tech
- [ ] `ai_player.gd` — 7-phase turn processing
- [ ] `ai_city.gd` — site eval, build priority
- [ ] `ai_tactical.gd` — unit movement, attack targeting
- [ ] `ai_military.gd` — threat assessment, army composition
- [ ] AI difficulty modifiers
- [ ] AI personality system

**Done when:** Full game: explore -> build -> research -> fight -> win/lose vs AI.

---

## Phase 11: Polish
**Goal:** Production quality.

- [ ] Generated sprite art (tools/sprite-generation/ pipeline)
- [ ] Sound effects + music
- [ ] Save/load — GameState serialization
- [ ] Victory conditions (Domination, Score)
- [ ] Tile improvements (Farm, Mine, Road) + Engineer unit
- [ ] Gold economy — purchasing, rush-buying
- [ ] Game setup screen — map options, difficulty
- [ ] Minimap — SubViewport, terrain/unit dots, fog overlay
- [ ] Tutorial hints

---

## Milestone Summary

### Track 2a: Age of Dwarves (EA)

| Phase | Name | Core Deliverable |
|-------|------|-----------------|
| M0 | Foundation | Project opens, data loads, transpiler works |
| M1 | Climate & Geology | Temperature, wind, hydrology, biomes |
| M2a | Ecosystem Engine | Substrate refactor, trait-based species, Lotka-Volterra, ~10 proof species |
| M2b | Full Ecosystem | All 25 biomes, trait-tuned species per biome, population stability |
| M3 | Natural Events | Volcanic, weather, wildfire, plague, terrain evolution |
| 5 | Map + Units | Hex rendering, camera, fog, unit movement, turns |
| 6 | Cities | Found, grow, produce, Deep Forge |
| 7 | Tech Web | Research, unlock, 6-pillar mundane web |
| 8 | Combat | Fight, capture cities, lair clearing |
| 10 | AI & Difficulty | Play a full game vs Dwarf AI |
| 11 | Polish | Art, sound, save/load, victory, economy |

### Track 2b: Age of Dwarves (expansion, deferred)

| Phase | Name | Core Deliverable |
|-------|------|-----------------|
| M4 | Magic World | Ley lines, mana, corruption, magical ecology |
| 9 | Magic Gameplay | Spells, mana, summoning, Ascension |
| 10+ | Races | 3 additional races, heritage techs, race selection |
| 7+ | Magic Tech | School branches, fusion techs, 2-school lock |

**Track 2a = Complete Mundane 4X**
**Track 2b = Magic Expansion**