magicciv/public/games/age-of-dwarves/docs/cities/POPULATION.md

Population Management

Every citizen is assigned to one of three categories: building worker, tile worker, or construction worker. The player controls building assignments manually. Everything else is auto-optimized.

---

Three Worker Categories (assignment axis)

Category	Assignment	Expertise	Notes
Building workers	Manual (player sets count per building)	5 tiers, tech-gated	Produce units, research, culture, equipment
Tile workers	Auto-assigned from remaining population	3 tiers, no tech gate	Work terrain for food/production/gold
Construction workers	Manual (player sets count for build queue)	Masonry track	Build/upgrade buildings and wonders

Output-Domain Taxonomy (mc_core::WorkerCategory)

Orthogonal to the assignment axis above, every Specialist (and, downstream, every building-worker slot) is also tagged with one of three output domains. Per-category aggregation, expertise ladders (p2-56b), and aura propagation (p2-56c) all key off this taxonomy.

Domain	Yields	Examples
Sustenance	food, healing	(no Game-1 specialists yet — content gap)
Construction	production, engineering	Forge Engineer
Wealth	commerce, research, culture	Tradeswright, Runescribe, Saga Writer, Forge-Chanter, Rune Artisan, Stonewright

Canonical enum: mc_core::WorkerCategory { Sustenance, Construction, Wealth } serialized as snake_case. JSON values authored on every entry under public/resources/specialists/; missing or unknown variants fail tools/validate-game-data.py.

---

Building Worker Expertise

Workers assigned to a building gain experience over time. Experience is tracked per building category (military, production, research, etc.) — not per individual.

Tier	Efficiency	Tech unlock (culture tree)
Novice	60%	Default
Apprentice	80%	Default
Journeyman	100%	Apprenticeship
Master	120% + same-tile aura	Guilds
Grandmaster	140% + adjacent-tile aura	Academies

Without Apprenticeship, all buildings are capped at Apprentice (80%) no matter how long workers have been assigned.

Canonical enum: mc_core::ExpertiseTier { Novice, Apprentice, Journeyman, Master, Grandmaster } (snake_case serde, Ord-derived for ladder progression). Per-worker XP state lives in mc_city::expertise::WorkerExpertise; per-tier xp_to_next thresholds and idle_decay_per_turn are loaded from public/games/age-of-dwarves/data/balance/expertise.json. Per-turn XP earn / idle-decay tick wired into mc_turn::processor::process_city_production (p2-56b).

Aura Effects

Masters boost all same-category buildings on the same tile:

• Own building: 120%
• Other same-category buildings on same tile: +10%

Grandmasters boost same-category buildings on the same tile and all adjacent tiles:

• Own building: 140%
• Other buildings on same tile: +15%
• Buildings on adjacent tiles: +10%

Auras do not stack. If a building is in range of two Grandmasters, it receives +10% (best wins, not combined).

Decay Rates

Workers who are idle (building has no active queue) lose experience over time.

Tier	Base decay (per turn idle)	Turns to drop one tier
Novice	None (clamps at 0)	Never
Apprentice	2 XP/turn	~10 turns
Journeyman	2 XP/turn	~20 turns
Master	2 XP/turn	~40 turns
Grandmaster	2 XP/turn	~80 turns

The constant idle_decay_per_turn lives in data/balance/expertise.json (currently 2); per-tier overrides can be added there without code changes. Utilization-based scaling (next section) is layered on top.

Utilization-Based Decay

Decay is not binary. It scales with how much of a Master or Grandmaster's aura range is actively producing.

effective_decay = base_decay × (1 - utilization)
utilization = active same-category buildings in aura range / total same-category buildings in aura range

A Grandmaster covering 6 Barracks where 5 are producing has 83% utilization — decay is nearly zero. The same Grandmaster with all 6 idle decays at full rate.

Reassignment

Moving workers between buildings resets experience:

• Building worker moved to a different building: full reset to Novice

The auto-assignment system always removes the least experienced worker when a building needs to shed a slot.

---

Tile Worker Expertise

Tile workers learn the specific land they work. There are no tech gates — this expertise comes purely from time in place.

Tier	Yield bonus	Turns on same tile
Novice	0%	0–5
Experienced	+15%	6–12
Veteran	+30%	13+

Terrain Category Rules

Knowledge transfers within terrain categories, not across them.

Move	Result
Same tile	No loss
Different tile, same terrain category	Drop 1 tier
Different tile, different terrain category	Full reset to Novice

Terrain categories:

Category	Terrains
Farming	Grassland, Plains, Forest
Mining	Hills, Mountains, Volcano
Aquatic	Lake, Coastal Waters, Inland Sea
Specialist	Tundra, Desert, Swamp, Enchanted Forest

A Veteran miner moved to a different Hill tile drops to Experienced. The same miner moved to a farm resets to Novice.

Auto-Assignment Priority

When the system assigns tile workers, it:

1. Places the most experienced worker on the tile they have tenure on
2. Fills remaining tiles with best available workers
3. When pulling a tile worker to staff a building, removes the least experienced tile worker first

---

Construction Workers

Construction workers form a separate pool that builds the city's physical structures. They are manually assigned from the total population.

• More workers = faster construction (diminishing returns beyond 3)
• Expert construction workers build significantly faster than Novices
• Construction expertise decays when no build queue is active
• When a building is upgrading, construction workers do the physical work while the building's assigned workers stay in place (maintaining their experience but producing nothing)

---

Worker Capacity by Building Level

Building Level	Max workers
Lv1	1
Lv2	2
Lv3	3 (requires Guilds tech)
Lv4	4 (requires Academies tech)

---

Idle Population

Citizens without assignment auto-assign to the best available unworked tile. Unassigned citizens with no viable tiles incur a happiness penalty — idle Dwarves are unhappy Dwarves.

Growth that outpaces infrastructure results in wasted citizens. The player who upgrades buildings before population arrives never wastes a turn.

---

Population Summary UI

The city screen shows three sections:

1. Building workers — each building with [-][+] controls, current tier, efficiency bar, queue status
2. Tile workers — auto-assigned list showing terrain, tier, and yield
3. Available — unassigned citizens and where auto-assign would place them

Hovering [-] on a building shows an impact preview: which worker would leave, their category, where auto-assign would place them, what experience they'd lose, and how it affects aura utilization.