magicciv/.project/ROADMAP.md

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)
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