magicciv/.project/TERMINOLOGY.md

# Developer Terminology Reference

Canonical terms for code, content, and guide authoring. Deviations cause inconsistency across three guide apps, JSON data, GDScript, and Rust.

---

## World vs Planet

| Term | Meaning | Use when |
|------|---------|----------|
| **world** | The in-game fictional entity | All game prose, UI labels, routes, variable names |
| **planet** | Real-world scientific concept | Archetype qualifiers only ("Mars-type world", "Mars-analog") |

The three worlds are **based on** real planets — that is the only role "planet" plays in user-facing text.

**Route prefix:** `/worlds/` (not `/planets/`)  
**Variable names:** `WORLD_ROUTES` (not `PLANET_ROUTES`)  
**Prose:** "multi-world maps", "dual-world", "cross-world", "world-scoped"

### Canonical world names

| World | Archetype | Homeworld for | ID |
|-------|-----------|---------------|----|
| **Khazad Prime** | Earth-archetype | Dwarves | `khazad_prime` |
| **The Hive** | Mars-archetype | Kzzkyt | `the_hive` |
| **Silvandel** | Venus-archetype | Elves | `silvandel` |
| **Terra** | Earth-archetype | Terrans (Game 4, planned) | `terra` |

Use world names as primary. Archetype is scientific context only — acceptable in parentheses or technical descriptions ("a Mars-type world with 0.38g gravity").

---

## Species vs Race

| Term | Meaning | Examples |
|------|---------|---------|
| **species** | Biological lineage | Elf, Dwarf, Kzzkyt, Terran, Orc |
| **race** | Playable subdivision within a species | High Elf, Dark Elf, Forest Elf, Water Elf |

Most species have one race. Elf is the exception: four races (High, Dark, Forest, Water).  
Dwarf has one race. Kzzkyt has one race. Terran has one race.

Code IDs use the race, not the species: `high_elf`, `dwarf`, `kzzkyt`.

---

## Episode vs Game

Both terms exist but have different emphasis:

| Term | Use |
|------|-----|
| **Game N** | Engineering and design docs (Game 1, Game 2, Game 3) |
| **Episode N** | Marketing, guide UI, player-facing copy |
| **Age of X** | The release name (Age of Dwarves, Age of Kzzkyt, Age of Elves) |

These are interchangeable but prefer "Episode N" in guide prose and "Game N" in design/code docs.

---

## Kzzkyt Terminology

| Term | Meaning | Not |
|------|---------|-----|
| **Queen** | Pioneer + Regent-Archon combined unit. Mobile until it converts. Builds the hive with herself at the center. | "settler", "founder" |
| **Hive** | Kzzkyt city equivalent. Immobile once established. | "city", "base" |
| **Drone** | Basic Kzzkyt worker/combat unit | "soldier", "worker" |
| **Deep Hive** | Underground infrastructure tiers (production, ancestral chambers) | "underground city" |
| **Broodmother** | Orbital bombardment platform. Sterile — no queens, upgradeable drone deployment. | "Hive Mother", "space station" |
| **Launch-beasts** | Giant insectoid creatures that hurl queens and Broodmothers into space. Biological, not mechanical. | "rockets", "ships", "resonance launch" |
| **Resonance** | Kzzkyt biological field interaction with ley anchors. A geological property they cultivate, not a power they project. | "instinct magic", "pheromone magic" |
| **Pheromone zone** | Kzzkyt zone of control (ZOC equivalent). Range-limited biological signal. | "telepathy", "hive mind radius" |
| **Resonance Lattice** | Inter-world communication system. Weak signal via ley anchors, unknowingly routing through the Ethereal Plane. | "hive mind", "telepathy network" |
| **Anchor cultivation** | Queens awakening dormant ley anchors through presence. The primary reason Kzzkyt invade Khazad Prime. | "anchor building", "ley construction" |
| **Ravager Drop** | Kzzkyt WMD. T10 Broodmother upgrade launches apex organisms. Go feral after ~4 turns (MAD). | "bioweapon", "Hive Mother attack" |
| **Assassin** | Kzzkyt specialist unit for queen persuasion. Convinces rogue queens to rejoin the hive. | "assassin caste" is fine, but note: it convinces, not kills |

### What "instinct" means for Kzzkyt

Kzzkyt do NOT have uncontrollable threshold-triggered magic. That would make the race unplayable. Resonance is:
- A biological field they interact with **deliberately**
- Something queens can **amplify** at anchor points
- NOT something that fires automatically when conditions are met

The in-game magic section is called "Resonance" or "Resonance biology" — not "Instinct magic".

---

## Ley System Terminology

| Term | Meaning |
|------|---------|
| **Ley anchor** | Physical point where ley energy concentrates. Tiers 1-10. |
| **Ley line** | Connection between two ley anchors. Strength = product of anchor tiers. |
| **Dormant anchor** | Ley anchor with no active catalyst. Kzzkyt queens awaken them on Khazad Prime. |
| **Anchor cultivation** | Process of queen-presence raising anchor tier over time. |
| **Ethereal Plane** | Intermediate reality where inter-world ley distances are shorter. Routes the Resonance Lattice without any faction knowing. Not visitable until Episode 5 (tentative). |
| **Resonance Lattice** | Kzzkyt inter-world weak signal. Communication only, not control. |

---

## Magic System Terminology

| Term | Meaning |
|------|---------|
| **Schools** | Life, Death, Chaos, Nature, Aether — the five magical disciplines |
| **Archon** | Magical champion unit. High Archon casts world-map spells; school Minor Archons specialize. |
| **Ascension** | Victory condition. Research and ritual, not a conventional military win. |
| **Arcane Ascension** | The specific ritual that unlocks the Ascension victory. |
| **Mana pool** | Per-faction magical resource. Regenerates via ley anchor proximity. |
| **Instinct** | Kzzkyt-specific "magic" — resonance biology, not school-based. Separate system. |

---

## Tier and Era System

All use a **1–10 scale**:

| Concept | Scale | Notes |
|---------|-------|-------|
| **Era** | 1–10 | Game-pack-driven. Names in `eras.json`. |
| **Content tier** | 1–10 | Units, spells, buildings. Defined per game pack. |
| **Event tier** | 1–10 | Environmental event severity. |
| **Ley anchor tier** | 1–10 | Anchor strength. `ley_anchor_strength` field. T10 = ley nexus. |
| **Ecosystem tier** | 1–10 | Emerges from simulation, never assigned directly. |

`anchor_tier` in event JSON equals event tier. Tiers are classified from observed state, not set.

---

## Code Conventions

### IDs (snake_case)
```
high_elf, dark_elf, forest_elf, water_elf
dwarf
kzzkyt
khazad_prime, the_hive, silvandel
life, death, chaos, nature, aether
```

### Routes
```
/worlds/khazad-prime
/worlds/the-hive
/worlds/silvandel
/episodes/age-of-dwarves
/episodes/age-of-kzzkyt
/episodes/age-of-elves
```

### Vocabulary keys (ThemeVocabulary)
Always resolve display strings through `ThemeVocabulary.lookup(engine_key)`. Never hardcode theme-specific names (a T9 forest is "haunted" to Dwarves, "enchanted" to Elves).

---

## Common Mistakes

| Wrong | Correct | Why |
|-------|---------|-----|
| "Mars" as world name | "The Hive" | Mars is the real planet; The Hive is the world |
| "Earth" as world name | "Khazad Prime" | Same reason |
| "Venus" as world name | "Silvandel" | Same reason |
| "Martian" as adjective | "Hive" | Derives from the wrong name |
| "multi-planet" | "multi-world" | Game entities are worlds |
| "planet roster" | "world roster" | Same |
| "instinct magic" | "resonance", "resonance biology" | Instinct = uncontrollable threshold → unplayable |
| "Hive Mother" | "Broodmother" | Canonical unit name |
| "Queen lands" | "Queen converts" | Queens don't land — they convert a location into a hive |
| "resonance field projected by queen" | "geological resonance that queens cultivate" | Resonance is terrain property, not queen emission |
| `PLANET_ROUTES` | `WORLD_ROUTES` | Variable naming alignment |
| `/planets/` routes | `/worlds/` routes | Route prefix alignment |