2026-03-25 22:48:51 -07:00
# Magic Civilization — Development Roadmap
> Fresh build starting from M0. Reference implementation: `@magic-civilization.messy/`
## Early Access Scope ("Age of Dwarves")
2026-03-26 11:38:24 -07:00
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.
2026-03-25 22:48:51 -07:00
### 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) |
| 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 |
2026-03-26 11:38:24 -07:00
### Track 2b: Age of Dwarves (expansion)
2026-03-25 22:48:51 -07:00
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
2026-03-26 11:38:24 -07:00
- [ ] Game pack: age-of-dwarves → age-of-dwarves
2026-03-25 22:48:51 -07:00
**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 × ×
- [ ] 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 |
2026-03-26 11:38:24 -07:00
### Track 2b: Age of Dwarves (expansion, deferred)
2026-03-25 22:48:51 -07:00
| 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**
