magicciv/public/games/age-of-dwarves/docs/GLOSSARY.md

# Glossary — Science & Systems Terminology

> **Status:** Living document · Last updated 2026-03-25
>
> Every physics, ecology, economics, and political term used in the codebase or design docs. If a term appears in code or design, it belongs here.

---

## Atmospheric Physics

**Albedo** — Surface reflectivity (0.0–1.0). Ice=high, ocean=low. Per-terrain property in `climate.gd`. Ground-level, NOT atmospheric. Terrain changes (forest→desert) change albedo.

**Sulfate Aerosol** — Stratospheric particles from volcanic/impact events. Scatters sunlight → cooling + drying. Transient (decays 5%/turn, wind-transported). `tile.sulfate_aerosol`. Distinct from pollution — aerosol blocks light, pollution poisons. NOT from civic choices.

**Optical Depth** — Light attenuation through atmosphere. Higher = less sunlight. `sulfate_aerosol` serves as proxy.

**Ley Pollution** (planned) — Atmospheric contamination from magical labor/economic exploitation. WARMING (not cooling), TOXIC (health effects), CATALYTIC (accelerates corruption). Persistent (0.5%/turn decay). Pools locally. `tile.ley_pollution`. Mitigated by Nature magic.

**Industrial Pollution** (planned) — Physical contamination from mundane industrial labor. Does NOT warm atmosphere. Poisons water/soil (pandemic freq), degrades terrain. Mitigated by engineering tech, not nature magic. `tile.industrial_pollution`.

**The Masking Trap** — Volcanic cooling (aerosol) can temporarily cancel industrial warming (ley pollution). Aerosol decays 10× faster. When aerosol clears, accumulated warming snaps into effect.

## Heat & Energy

**Solar Forcing** — Latitude-dependent sun energy. `net_solar = solar × (1 - albedo) × energy_scale`.

**Thermal Conductivity** — Heat transfer rate between tiles via wind. `wind_conductivity`.

**Equilibrium Relaxation** — Temperature drifts toward solar baseline. Prevents runaway.

**Lake Thermal Moderation** — Lakes buffer adjacent temperatures. `lake_thermal_conductivity`.

**Deep Earth Water** — Geothermal moisture from volcanoes/hot springs, independent of precipitation.

## Water Cycle

**Evaporation** — Ocean/coast/lake tiles convert heat to moisture. Multi-hop inland. `ocean_dead_fraction` reduces.

**Evapotranspiration** — Moisture released by vegetation. Per-terrain. More forest = more moisture. Positive feedback loop.

**Moisture Transport** — Wind carries moisture tile-to-tile. Double-buffered.

**Precipitation** — Excess moisture above threshold → terrain quality improvement.

**Atmospheric Loss** — Slow constant moisture drain. Prevents infinite accumulation.

**Hadley Cell** — Equatorial circulation creating subtropical dry zones. `precipitation_latitude` config.

**Ocean Dead Fraction** — Fraction of biologically dead ocean. Reduces evaporation → inland drought cascade. Increased by economic `ocean_harvest_mult`.

## Ecology & Terrain

**Terrain Quality** — Fertility score per tile (1–5). Determines terrain type and yields.

**Quality Ladder** — Terrain transitions as quality changes: desert ↔ plains ↔ grassland ↔ forest ↔ jungle.

**Corruption Pressure** — Per-tile magical degradation (0.0–1.0). Spreads via ley lines (Death 3×, Nature/Life 0.5×). At 0.5: terrain flips to corrupted_land (zero yields).

**Reef Health** — Coastal ecosystem viability. Bleaches above 0.75 temperature. Dies below 0.3.

**Anoxia** — Marine oxygen depletion. T5 event: permanent fish/reef death.

**Exploitation Damage** (planned) — Per-tile soil exhaustion from labor + economy interaction. `labor.exploitation_rate × economy.exploitation_mult`. Thresholds: 0.3=quality drop, 0.5=terrain downgrade, 0.7=generates corruption, 0.9=exhausted. Heals 0.01/turn.

**Cross-Trigger** — One ecological event category boosts another's frequency. Drought T4 → wildfire ×2.0. Pandemic T4+ → plague ×1.5.

**Severity Weights** — Event tier probability distribution `[50,30,12,5,3]`. High inequality shifts weights toward T4/T5.

## Ley System

**Ley Density** — Magical field strength per tile (0.0–1.0). Powers mana nodes, sustains summons, resists corruption.

**Ley Channeling** — Corruption spreads faster along ley lines. Off-ley 1.0×, generic 2.0×, Death 3.0×, Nature/Life 0.5×.

**Ley Anchor** — Persistent ley modification from major events. Decays slowly.

**Ley Dead Zone** (planned) — `ley_density < 0.1`. Summons die, enchantments decay, mana nodes dead. Created by Ley Conscription labor + Ley Extraction economy.

**Iron Pylon** — Mundane anti-magic infrastructure. Freezes ley lines in radius (cannot grow, drain, or heal).

## Stochastic Systems

**Hash Noise** — Deterministic pseudo-random: `sin(x×127.1 + y×311.7 + seed×74.3) × 43758.5453`, frac only. Reproducible across engines.

**Double Buffering** — Read from snapshot, write to new buffer, swap. Prevents order-dependent artifacts.

## Civic System

**4-Axis Model** — Government (ruler selection) × Authority (power justification) × Labor (work organization) × Economy (wealth production/distribution). Religion reserved for expansion. See [civics/OVERVIEW.md](civics/OVERVIEW.md).

**Anarchy Period** — 5-turn penalty when switching any civic axis. Production halved, no gold income. Anarchy government exempts from this.

**Pressured Transition** — Nothing is forced. At inequality ≥50, Gilded Tyranny has no instability cost (others do). At inequality ≥70, Plutocracy has no crisis cost (others do). Player always chooses.

**Economic Instability** — At inequality ≥50, non-Gilded-Tyranny economies cost -5 gold/city/turn.

**Institutional Crisis** — At inequality ≥70, non-Plutocracy governments cost -3 gold/city/turn + -10% production.

**Exploitation Rate** — Per-tile damage from labor, amplified by economy. `labor.rate × economy.mult`. Labor axis sets the base rate, economy axis multiplies it.

**Capital Siphon** — Percentage of peripheral city surplus flowing to capital. Set by economy axis.

**Savings Rate** — Compound interest on treasury per turn. Set by economy axis (+1% from Oligarchic authority). The rich-get-richer incentive.

## Social Dynamics

**Inequality** — Per-player metric (0–100). Emerges from coefficient of variation of city wealth levels. Risk multiplier, not direct happiness drain. Threshold effects at 10/25/40/50/60/70/80.

**Relative Deprivation** — Per-city happiness based on wealth gap vs capital. `(capital.wealth - city.wealth) / capital.wealth`. Poor city in poor empire = fine. Poor city next to rich capital = fury.

**Education Level** — Per-city (0.0–1.0). Modifies inequality response: low=halved (ignorance), medium=full, high=×1.5 (awareness). Also determines revolt quality (bandits/rebels/revolutionaries).

**Civic Unrest** — Per-city integration of deprivation × education + inequality + ecological stress - happiness buildings.

**Suppression** (Nationalism authority) — Halves education awareness effect. Degrades 0.01/turn. After 50 turns at 50% — then accumulated inequality hits.

**Scapegoating** (Nationalism authority) — +3 happiness while at war or with declared enemy. -5 at peace with no enemy. Fascism requires a permanent enemy.

## Victory Wonders

**Doomsday Device** — Mundane evil victory. Destroys global ley network: all ley density → 0, all summons die, all enchantments break, all mana nodes dark. Builder wins because they rejected magic (mundane path). "I don't have to succeed, I just have to be more successful than everyone else."

**Dark Ascension** — Magic evil victory. Sacrifice drained ley network for forced 5-turn Ascension.

**World Court** — Mundane good victory. Diplomatic/cultural through institution-building.

**Ascension Ritual** — Magic good victory. Standard 10 turns (7 with Arcane Dominion).

**World Restoration** — Ecological victory. Heal X% of global terrain quality via Harmony economy.

## Mundane vs Magic

**Mundane Rebirth** — One-way permanent decision when High Archon dies. Locks all magic, opens full mundane tech tree. Locks out: Ley Extraction, Mana Covenant, Arcane Rule, Arcane Dominion, Ley Conscription. Opens: Technocracy, Industrial Hegemony, Mundane Industry, Conservation.

**Deforestation** — Terrain quality degradation from mundane industrial labor. Forests cleared → less evapotranspiration → less rain → drought cascade.

---

## City & Production Systems

**Aura Range** — Zone of worker influence. Master workers affect their home tile only. Grandmaster workers affect their home tile (+15% efficiency) and all adjacent tiles (+10%). Auras do not stack — the highest-value aura applies. See [cities/POPULATION.md](cities/POPULATION.md).

**Hybrid Structure** — An irreversible merged building created when two compatible building pairs share a tile and the prerequisite tech (Advanced Synthesis) is researched. Examples: War Academy (Barracks+Rifle Range + Stable+Barding Hall), Assault Citadel (Barracks+Sword Hall + Siege Workshop+Siege Annex). Cannot be un-merged; must be demolished and rebuilt from scratch to undo. See [cities/BUILDINGS.md](cities/BUILDINGS.md).

**Utilization** — The fraction of same-category buildings in a worker's aura range that are actively staffed. Formula: `active buildings in aura range / total same-category buildings in aura range`. High utilization reduces expertise decay: `effective_decay = base_decay × (1 - utilization)`. See [cities/POPULATION.md](cities/POPULATION.md).

**Impact Winter** — Climate penalty following a medium or large asteroid impact. Reduces food yields across the affected biome region for 10–20 turns. See [terrain/VERTICAL_LAYERS.md](terrain/VERTICAL_LAYERS.md).

**Graviton Drive** — Tier-10 research technology. Enables asteroid redirection. Consumed on use (1-use per ship). See [terrain/VERTICAL_LAYERS.md](terrain/VERTICAL_LAYERS.md).

---

## Terrain & Engineering

**Tile HP** — Degradation state for surface and underground tiles. Surface states: Normal → Damaged → Cratered → Sunken → Ruins. Underground states: Solid → Stable → Developed → Hollowed → Cracked → Rubble → Sinkhole. See [terrain/TERRAIN_SYSTEM.md](terrain/TERRAIN_SYSTEM.md).

**Structural Integrity** — The tile HP system applied to underground layers. Collapse risk increases as tiles move from Solid to Hollowed. See [terrain/UNDERGROUND.md](terrain/UNDERGROUND.md).

**Excavation** — The process of creating underground space. Queued via Mason Lodge; costs production and stone; time scales with depth (L1=4–6 turns, L2=8–10, L3=12–15). Requires the previous layer to already be excavated. See [terrain/UNDERGROUND.md](terrain/UNDERGROUND.md).

**Raw Cavern** — First underground tile state after excavation completes. Usable but unfinished — can be upgraded to Finished Cavern (habitable) or Developed Chamber (full city functionality). See [terrain/UNDERGROUND.md](terrain/UNDERGROUND.md).

**Controlled Collapse** — Demolitions Expert ability to deliberately trigger underground collapse at a target tile. Used offensively (destroy enemy foundations), defensively (seal infiltration routes), or as a trap. See [units/SPECIALISTS.md](units/SPECIALISTS.md) and [terrain/UNDERGROUND.md](terrain/UNDERGROUND.md).