magicciv/.project/AGE-OF-DWARVES-FEATURES.md

Age of Dwarves — Feature Inventory

Source-grounded inventory pulled from public/games/age-of-dwarves/data/*, src/simulator/crates/*, src/game/engine/scenes/*, and .project/objectives/* on 2026-04-25. Excludes anything tagged Game 2/3/4/5 (magic schools, leylines, additional races, etc. — see "Out of Scope" at the end).

---

Part 1 — Flat list

Each line is a discrete shipped feature. ~120 items across simulation, presentation, infra, content, and meta.

Simulation core

1. Hex-grid world map with axial/cube coordinate system
2. Procedural map generation (5 topologies: continents, pangaea, team_continents, ffa_cross, ffa_plus)
3. Balanced fair-start placement
4. Iron-ore strategic-resource density guarantee near starts
5. Fog of war + per-player exploration
6. Per-tile terrain typing
7. Ten biome families (aquatic, arctic, arid_world, elevated, geological, substrates, temperate, tropical, volcanic_world, wetland)
8. Climate model — temperature, moisture, wind/pressure, ocean currents, climate cycles
9. Weather events — atmospheric, drought, ecological, glacial, impact, magical, marine, pandemic, plague, seismic, solar, volcanic, wildfire (12 categories)
10. Ecology tick — flora canopy / undergrowth, fauna populations
11. Wild creature populations + lairs
12. Per-turn determinism end-to-end (same seed → byte-identical run)
13. Score-victory fallback at turn limit
14. Ten eras (era_1 … era_10)

Empire & economy

15. City founding with founder unit
16. City growth, citizen assignment, food/production/science yields
17. Tile improvements — farm, mine, quarry, lumber_mill, plantation, pasture, trading_post, road, fort, mana_well, irrigation, drainage, windbreak, terrace_farming, deforestation, reforestation, hunting_grounds (17 total)
18. Worker unit + tile-improvement build loop
19. Building production queue
20. 13 building types — ale_hall, barracks, bathhouse, colosseum, forge, library, marketplace, monument, mundane_wonders, temple, walls (+ stub & manifest)
21. Building rally points (auto-deploy produced units to a hex via PatrolOrder)
22. Gold + upkeep + trade routes (marketplace)
23. Treasury items — 29 craftable/found items in 8 categories
24. Strategic-resource ledger (e.g. iron_ore gates cavalry/ironwarden production)
25. Strategic-resource yield bonuses → production
26. Happiness pool with global modifiers
27. Per-tier dwarven happiness (racial happiness curve)
28. Golden ages (trigger + duration)
29. Culture generation per turn
30. Border expansion via culture
31. Tech web — 25 techs across 9 pillars (military, metallurgy, agriculture, civics, masonry, natural_philosophy, naval, scholarship, aviation), 9 tier levels
32. Tech research costs + science pool pacing
33. Five government types (chieftainship → monarchy → republic → theocracy → military_state)

Combat & units

34. Twenty-eight unit types — civilian (founder, dwarf_tribe, dwarf_wanderer), military (archer/pikeman/cavalry/berserker/runesmith/ironwarden/forge_titan/mithril_vanguard, tier 1-6), and wild creatures (feral_spider, fire_imp, dire_wolf, dire_bear, frostfang_alpha, basilisk_wild, drake_wild, ancient_hydra, elder_wyrm, lava_elemental, etc.)
35. Hex-based tactical combat
36. PvP combat resolved inside the authoritative turn processor
37. Combat keywords (elite, formation, mithril_armor, etc.)
38. Combat preview UI (pre-attack predictions)
39. Promotions — 3 trees (melee, ranged, siege) with rank progression at 4 XP thresholds
40. Wild creature combat (lair clearing loop)
41. Formation aggregation — adjacent same-owner units link into a Formation
42. Formation shapes (Line, Column, Wedge, Diamond)
43. Formation reflow solver (auto-compress shape when terrain blocks preferred layout)
44. Formation-level command actions (Defend, Patrol, Advance)
45. Formation-aware combat scaling (dmg × count^0.75, HP × count)
46. Patrol orders — standing waypoint loop for individual units
47. Per-unit auto-join toggle (some unit types never auto-join formations)

AI

48. MCTS-driven strategic decisions (mc-ai crate, GDExtension GdMcTreeController)
49. MCTS per-decision wall-clock budget (env-tunable, p1-22)
50. PUCT priors infrastructure (in progress for biased tree search)
51. Five distinct AI clan personalities — ironhold, goldvein, blackhammer, deepforge, runesmith
52. Six strategic personality axes — aggression, expansion, production, wealth, trade_willingness, grudge_persistence
53. Personality-emergent tactical thresholds (lifted from hardcoded constants)
54. Formation-level MCTS planning (vs per-unit)
55. Tactical AI (movement / combat / city-action) — currently in GDScript, porting to mc-ai crate
56. Difficulty-calibrated AI progression (tier-peak distributions per Easy/Normal/Hard/Insane)
57. Four difficulty levels — Easy, Normal, Hard, Insane (with per-level production/research/gold modifiers + extra starting units)

Diplomacy

58. Peace/war toggle between players

59. Trade action (luxury ↔ gold: sell luxury for gold, buy luxury with gold) 59a. (planned) Trade luxury or gold for open borders agreement (timed, N turns) 59b. (planned) Trade luxury or gold for shared map for N turns — gated on a physical link: a built Courier unit carries the map data between capitals. Knowledge propagates at the courier's movement speed; the courier is killable mid-route (intercept = no map delivered, gold/luxury already paid). Courier has tech-gated upgrade tiers mapped one-per-era from era_2 onward; each tier raises movement speed / range and shrinks the knowledge-delay window. Tiers 1–5 are roaming units; tiers 6–9 shift to fixed infrastructure (operator + severable line/tower); tier 10 is wonder-tier and uninterceptable.

    Era	Courier tier	Built by (city building)	Route infrastructure	Delay
    era_2 Founding	Foot Runner	Messenger Hut	none	very high
    era_3 Exploration	Mounted Courier	Stables	benefits from road	high
    era_4 Craft	Carrier Bird	Rookery	none (flies)	medium-high
    era_5 Kingdoms	Dispatch Rider	Post House (← Messenger Hut)	Post Road tile	medium
    era_6 Conquest	Semaphore Operator	Semaphore Tower (hilltop, killable)	LOS tower chain	low (LOS = turn-of)
    era_7 Industry	Telegraph Operator	Telegraph Office	Telegraph Line tile (severable)	~1 turn
    era_8 Cataclysm	Radio Operator	Wireless Station (← Telegraph Office)	none on map (jammable)	~1 turn
    era_9 Restoration	Network Engineer	Telecom Exchange (← Wireless Station)	mesh, auto-reroutes	~instant
    era_10 Ascension	Aether Conduit (no unit)	Ascension Spire (wonder)	none	instant

    Pattern: linear city-side upgrade chain Messenger Hut → Post House → Telegraph Office → Wireless Station → Telecom Exchange. Side branches (Stables, Rookery) also serve other units. Severable infrastructure (lines, towers) replaces "kill the courier" as the intercept surface from era_6 on. None of these buildings or units exist in the data packs yet.

Discovery & exploration

60. Village discovery (world-map feedback: notification, reward popup, minimap ping)
61. Freepeople tribe-founding cinematic (turn -1 / 0 / 1 start sequence)
62. Movement mode UX (Move button, path preview, right-click confirm, fog-aware pathing)
63. Lens system (22 lenses including atmospheric_chemistry, tectonic_activity, weather_prediction, biosphere_health, etc. — game1 ships the ones not gated to magic schools)

Victory

64. Four victory conditions — Domination, Score, World Peace, World Domination
65. Score formula (population × 3 + techs × 5 + great_works + …)
66. Victory/defeat screen with recap + replay seed

UI — main menus

67. Main menu
68. Game setup (new-game dialog with difficulty / clan preview)
69. Loading screen
70. Options menu
71. Settings menu
72. About screen + version string
73. Credits screen
74. Load game (slot picker)
75. How-to-play (basic player guide screen)
76. Throne Room (post-victory spoils + banner)

UI — in-game HUD (17 scenes)

77. Top bar
78. End-turn button
79. Minimap (with fog reflection + unit markers)
80. Unit panel (single + double-click formation/unit selection)
81. Action button (move/attack/fortify/etc.)
82. Chronicle panel (notification log)
83. Tutorial overlay (opt-in HUD button, disappears after turn 5)
84. Hotkey cheat sheet (F1)
85. Diplomacy panel
86. Happiness breakdown panel
87. Climate indicator
88. AI turn overlay (waiting indicator)
89. Crafting complete modal
90. Turn notification
91. Debug menu
92. Tooltips on every HUD element

UI — overviews

93. City screen (citizen assign, queue controls, promotion picker)
94. Tech tree screen
95. Encyclopedia (in-game lore browser)
96. Demographics overview (Civ5-style rankings + history graphs over score / population / military / cities / techs / wonders — backed by StatsTracker autoload)
97. End-game stats screen
98. Combat result screen
99. Promotion picker

Visual / audio polish

100. TileMap-based hex rendering
101. Per-tile terrain sprites
102. Unit sprites — Dwarf-racial roster (m/f variants per unit type)
103. Wild creature & fauna sprites (generic)
104. Building sprites
105. Mundane wonder sprites (24 distinct)
106. City population-tier sprites (q1 … q5)
107. Sprite generation pipeline (procedural + AI-assisted)
108. Sprite manifest + ThemeAssets autoload
109. Player color system
110. Camera (pan/zoom)
111. Selection highlights + movement/attack range overlays
112. Animated unit movement
113. City borders rendering
114. Resource/village/lair overlays
115. Improvement overlays
116. River/road rendering
117. Audio system — manifest + autoload + EventBus wiring
118. 10 SFX cues
119. 3 music tracks

Save / load

120. Slot-based JSON saves (integer slots + named: quicksave, autosave, timestamped manual)
121. Autosave on quit
122. Schema-versioned save envelope

Achievements

123. 10 achievements (first_blood, founder, empire_builder, scholar, archmage, …)

Telemetry / observability

124. Per-game turn_stats.jsonl (per-player tier_peak, peak_unit_tier, wonder_count, combat counts, ecology fields)
125. Per-game events.jsonl (combat events, city captures, weather events, strategic-gate rejections)
126. Per-game meta.json (seed, player_clans, version, etc.)
127. Sub-second median single-player turn latency
128. Game-quality metrics instrumentation (tier_peak, peak_unit_tier, wonder_count)

Localization & accessibility

129. vocabulary.json centralizes every UI string (no hardcoded strings audit ✓)
130. Colorblind palette
131. Keyboard-navigable UI

Build / ship pipeline

132. Three-platform export: macOS .app, Linux native binary, Windows .exe
133. Per-platform GDExtension shipping (no cross-shipping of .dylib/.so/.dll)
134. Cross-compile Windows MSVC-ABI binaries from Linux via cargo-xwin (no Windows host needed)
135. Auto-pull fresh Linux .so from apricot before macOS exporter bundles it
136. Auto-relocate .so / .dll into engine/addons/magic_civ_physics/ post-export
137. Forgejo CI workflow — regression on every push to main
138. Forgejo release workflow — bundles Linux + macOS + Windows + WASM-guide on tag push, generates release notes from CHANGELOG diff
139. Headless GUT test stage in CI

Companion guide web app

140. React + Vite + pnpm dev/build pipeline
141. Routes mirror in-game encyclopedia content (techs / units / buildings / lore)
142. WASM-loaded simulation cache for live previews
143. Pre-warmed sim frames baked into the static build
144. Auto-deploy to dev URL on push to main
145. Race/gender-aware welcome modal + theming
146. Climate simulation worker + display
147. Guide progress dashboard

Meta / dev infra

148. ScreenCapture autoload + screenshot tools (proof scenes for phase gates)
149. AutoPlay autoload (deterministic batch test harness)
150. Environment-config autoload (EnvConfig) for per-host tuning
151. Bootc image (~/Code/bootc-bluefin/) baking dev toolchain incl. wine for cross-platform smoke

---

Part 2 — Categorization rationale

Picking categories that correspond to ownership / mental model / where you'd add new features, not just code structure. Five top-level domains — three are game-content-facing (Players Experience), one is engineering, one is meta/lifecycle. This map is the basis for the categorized inventory in Part 3.

Category	What goes here	Why this cut
A. World & Procedural Generation	Hex grid, terrain, biomes, climate, weather, ecology, map generation, fog of war	Things the engine makes; the playing field.
B. Empire & Economy	Cities, buildings, tech, units (creation/upgrade), economy, happiness, culture, government, items, resources, eras, rally points	Things the player builds and stats they manage.
C. Combat & Units	Tactical combat, unit types/tiers, formations, promotions, patrol orders, wild creatures, lairs, combat AI behavior	A separate category from "empire" because combat has its own rule surface (resolver, formation math, keywords).
D. AI Opponents	MCTS strategic, tactical AI, personality system, difficulty modifiers	The minds the player faces. Decoupled from "C" because AI is the driver, combat/units/empire are what it manipulates.
E. Player Experience	Menus, HUD, overviews, tutorial, encyclopedia, save/load, achievements, audio, localization, accessibility	Everything the player directly touches; closest to design/UX work.
F. Engineering & Lifecycle	Build/export pipeline, telemetry, determinism, latency, CI/CD, companion guide web app, dev infra	Owned by infra/build folks.

Justifications for the splits:

• C separated from B: combat changes require mc-combat + tactical AI changes; building/economy changes don't. Different code-area, different specialist (combat-dev vs game-systems agents).
• D separated from C: AI work is its own crate (mc-ai) and its own personality / MCTS infrastructure. Combat/units exist whether AI plays or not.
• F is "engineering": anything that doesn't change what the player does in-game but is required for the game to ship/run/be maintained.

---

Part 3 — Categorized inventory

A. World & Procedural Generation (12)

• Hex-grid world map (axial/cube coord system)
• Procedural map generation — 5 topologies (continents, pangaea, team_continents, ffa_cross, ffa_plus)
• Balanced fair starts
• Iron-ore strategic-resource density guarantee
• Fog of war + per-player exploration
• Per-tile terrain typing
• 10 biome families
• Climate model (temperature, moisture, wind, currents, cycles)
• 12 weather event categories (volcanic, seismic, drought, plague, etc.)
• Ecology tick (flora canopy/undergrowth + fauna)
• Wild creature populations + lairs
• 10 eras

B. Empire & Economy (19)

• City founding (via founder unit)
• City growth + citizen assignment
• 17 tile improvements (farm, mine, road, mana_well, hunting_grounds, …)
• Worker / improvement build loop
• Building production queue
• 13 building types
• Building rally points (auto-deploy via PatrolOrder)
• Gold + upkeep + trade routes
• 29 treasury items in 8 categories
• Strategic-resource ledger (gates unit production)
• Strategic-resource production bonuses
• Happiness pool with global modifiers
• Per-tier dwarven happiness curve
• Golden ages
• Culture generation
• Border expansion via culture
• Tech web — 25 techs / 9 pillars / 9 tier levels
• Science pool + research pacing
• 5 governments (chieftainship → military_state)

C. Combat & Units (14)

• 28 unit types (military / civilian / wild)
• Tier-1 to tier-6 unit progression
• Hex-based tactical combat
• PvP combat resolved in authoritative turn processor
• Combat keywords (elite, formation, mithril_armor, …)
• Combat preview UI
• Promotions — 3 trees (melee/ranged/siege), 4 rank thresholds
• Wild creature combat + lair clearing loop
• Formation aggregation (adjacent units link)
• 4 formation shapes (Line, Column, Wedge, Diamond)
• Formation reflow solver (terrain-aware compression)
• Formation command actions (Defend, Patrol, Advance)
• Formation combat scaling (dmg × count^0.75, HP × count)
• Patrol orders + per-unit auto-join toggle

D. AI Opponents (10)

• MCTS strategic decision-making (mc-ai + GdMcTreeController)
• MCTS per-decision wall-clock budget (env-tunable)
• PUCT priors infrastructure (in progress)
• 5 AI clan personalities — Ironhold, Goldvein, Blackhammer, Deepforge, Runesmith
• 6 strategic personality axes
• Personality-emergent tactical thresholds
• Formation-level MCTS planning (not per-unit)
• Tactical AI (currently GDScript, porting to mc-ai)
• Difficulty-calibrated AI progression
• 4 difficulty levels (Easy / Normal / Hard / Insane)

E. Player Experience (44)

Menus & flow (10)

• Main menu, Game Setup, Loading Screen, Options, Settings, About, Credits, Load Game, How-to-Play, Throne Room

HUD (17)

• Top bar, End-turn button, Minimap (fog + units), Unit panel (single/double-click), Action button, Chronicle, Tutorial overlay, Hotkey cheat sheet, Diplomacy panel, Happiness breakdown, Climate indicator, AI turn overlay, Crafting modal, Turn notification, Debug menu, Tooltips everywhere, Movement mode UX

Overviews (7)

• City screen, Tech tree, Encyclopedia, Demographics (Civ5-style), End-game stats, Combat result, Promotion picker

Diplomacy (2)

• Peace/war toggle, trade action (luxury ↔ gold: sell luxury for gold, buy luxury with gold); (planned) trade luxury/gold for open borders or shared maps (N turns) — shared-map gated on built Courier unit (killable, knowledge propagates at courier movement speed) with tech-gated upgrade tiers (Foot Runner → Mounted → Carrier Bird → Semaphore → Telegraph → Telecom; later tiers shrink the delay toward instant)

Save / load + meta (4)

• Slot-based JSON saves, autosave on quit, schema-versioned envelope, Throne Room post-victory spoils

Discovery (3)

• Village discovery (notification + reward + minimap ping), Freepeople tribe-founding cinematic, Lens system (22 lenses)

Victory (3)

• 4 victory conditions (Domination, Score, World Peace, World Domination), Score formula, Victory/defeat screen with replay seed

Achievements (1)

• 10 achievements (first_blood, founder, empire_builder, scholar, archmage, …)

Audio (1)

• Audio system + 10 SFX + 3 music tracks (ogg)

Localization & accessibility (3)

• Centralized vocabulary.json, colorblind palette, keyboard navigation

Visual / rendering (10)

• TileMap hex rendering, per-tile terrain sprites, unit sprites (Dwarf m/f variants), wild creature sprites, building sprites, 24 mundane-wonder sprites, city population-tier sprites (q1-q5), sprite generation pipeline, ThemeAssets autoload + manifest, player color system, camera (pan/zoom), selection highlights + range overlays, animated unit movement, city borders, resource/village/lair overlays, improvement overlays, river/road rendering

F. Engineering & Lifecycle (15)

• Per-turn determinism gate (same seed → byte-identical)
• Sub-second median single-player turn latency
• Game-quality metrics instrumentation (tier_peak, peak_unit_tier, wonder_count)
• Per-game telemetry: turn_stats.jsonl + events.jsonl + meta.json
• Three-platform export: macOS .app / Linux binary / Windows .exe
• Per-platform GDExtension binaries (no cross-shipping)
• Cross-compile Windows MSVC-ABI from Linux via cargo-xwin
• Auto-pull fresh Linux .so from apricot before bundling
• Post-export .so/.dll relocation into addon dir
• Forgejo CI — regression on push, release on tag
• Headless GUT test stage in CI
• Companion guide web app (React + Vite + WASM sim cache, race/gender themed)
• Pre-warmed sim frames baked into static guide build
• Bootc image with cross-platform smoke toolchain (incl. wine)
• AutoPlay + ScreenCapture autoloads for deterministic test runs

---

Known gaps in Game 1 (in scope, not yet shipped)

These are missing pieces that BELONG in Game 1 but aren't built yet — distinct from the deferred-to-G2+ list below.

• Tile-placement UX with effect preview — Civ7-style "pick a tile for this building, see the yield-delta + adjacency bonuses live before committing". Today every building has placement: "city" (no tile choice) and worker improvements drop with no yield preview. Tracked in p1-26-tile-placement-preview-ux.md.

---

Out of scope for Game 1 (deferred to Game 2-5)

These exist in the codebase as design or stubs but do not ship in Game 1 — listed for completeness so the inventory above is unambiguous about what Game 1 actually is.

• Magic system entirely — five schools (Life/Death/Chaos/Aether/Green), spells, mana economy, mana wells producing mana, Archons (High Archon + school Minor Archons), enchantments, summoning, casting skill, Arcane Ascension victory, school world wonders → Games 2 (Green only) and 3 (full)
• Ley line system — Voronoi network, school-aligned segments, nexus capture metagame → Game 2
• Additional playable races — beastmen, dark_elves, draconians, fae, forest_elves, giants, gnolls, gnomes, halflings, high_elves, humans, klackons, kzzkyt, lizardmen, orcs, trolls, undead, water_elves (16 race files exist as design docs, only dwarves ships) → Games 2-5
• Multiplayer netcode — hot-seat hooks present, real netcode → v2.0
• Naval combat — post-v10
• Caravan trade routes — post-v10
• Map editor / mod support — post-v10
• Religious victory — Game 4
• Psionics — Game 4
• Phantasma / Flügel / Gith / Demonia species — Game 5
• Production sprite art / sound / music polish — v1.5 post-EA
• Full balance pass — v1.5 post-EA