7.7 KiB
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 |