Citadels¶
The fortified structure that is a colony — population, storage, defenses, and a secure vault. Citadel level drives the colony's phase, capacity, and what defensive buildings unlock.
Levels and capacities¶
Authoritative source: services/gameserver/src/services/citadel_service.py:CITADEL_LEVELS.
| Level | Name | Max population | Safe storage (cr) | Drone capacity | Upgrade cost (cr) | Upgrade hours | Resources required |
|---|---|---|---|---|---|---|---|
| 0 | No Citadel | 0 | 0 | 0 | — | — | — |
| 1 | Outpost | 1,000 | 100,000 | 10 | 0 (free establish) | 0 | — |
| 2 | Settlement | 5,000 | 500,000 | 25 | 50,000 | 48 | 500 fuel_ore + 200 equipment |
| 3 | Colony | 15,000 | 2,000,000 | 50 | 150,000 | 72 | 1,500 fuel_ore + 500 organics + 800 equipment |
| 4 | Major Colony | 50,000 | 10,000,000 | 100 | 500,000 | 120 | 5,000 fuel_ore + 2,000 organics + 3,000 equipment |
| 5 | Planetary Capital | 200,000 | 50,000,000 | 200 | 2,000,000 | 240 | 15,000 fuel_ore + 8,000 organics + 10,000 equipment |
Per-level upgrade costs, durations, and resource requirements are defined in the CITADEL_LEVELS constant in citadel_service.py. The constant is the source of truth — this table mirrors it for reference.
🐛 Bug — level naming. Target spec is the lifecycle progression above (Outpost / Settlement / Colony / Major Colony / Planetary Capital).
citadel_service.CITADEL_LEVELSships with military-fortress names (Outpost / Garrison / Fortress / Stronghold / Citadel). UpdateCITADEL_LEVELS[*]["name"]incitadel_service.pyand any UI strings that surface those names to match the lifecycle table.
Per-level passive bonuses¶
| Level | Production bonus | Notes |
|---|---|---|
| 1 | +5% all production | Establishes basic colony multiplier. |
| 2 | +10% | |
| 3 | +15% | |
| 4 | +20% | |
| 5 | +25% | Capped here; matches the cap in ../../SYSTEMS/planetary-production-tick.md. |
📐 Design-only — citadel production bonus. The +5%/level multiplier is specified in the production-tick math but is not yet applied in
planetary_service._calculate_production_rates. Target: include(1 + 0.05 * citadel_level)in the production formula.
Defensive buildings unlocked by citadel level¶
citadel_service.DEFENSE_BUILDINGS:
| Building | Min citadel | Max count by level | Cost (cr) | Build hours | Effect |
|---|---|---|---|---|---|
| Orbital Defense Platform | 4 | L4: 1, L5: 3 | 500,000 | 168 | 2-sector range, 500 dmg/round |
| Long-Range Scanner Array | 2 | L2: 1, L3: 1, L4: 2, L5: 2 | 75,000 | 48 | 2-sector detection |
| Automated Turret Network | 3 | L3: 2, L4: 4, L5: 6 | 150,000 | 72 | 3 anti-drone kills/round |
Plus shields, drones, rail guns, and the defense grid documented in defense.md.
Upgrade workflow¶
- Meet population requirement — current pop must hit max for current level.
- Stockpile resources — credits + commodities on the planet (or in the safe).
- Meet defense prerequisite —
Planet.defense_levelthresholds enforced incitadel_service.start_upgrade: - L3 requires defense level 2+ (basic defenses).
- L4 requires defense level 5+ (advanced defenses).
- L5 requires defense level 8+ (fortified defenses).
- Initiate upgrade — credits and resources consumed immediately, construction timer starts.
- Wait — citadel remains functional during build; population cap stays at current level until done; partial defensive bonus (+50% of next-level effects) during construction.
- Complete —
check_upgrade_completionapplies the new level when the timer elapses; new capacity unlocked instantly.
🐛 Bug — prerequisite framing. Design intent maps the prerequisite to a specific structure (shield generator → L3, defense grid → L4, orbital platform → L5) rather than the flat
defense_levelinteger scale. The shipped check uses defense level only. Target: gate L3/L4/L5 upgrades on the actual prerequisite buildings being present.
The safe vault¶
Every citadel has a secure storage area that survives even if the citadel is destroyed.
| Citadel level | Safe capacity (cr-equivalent) |
|---|---|
| 1 | 100,000 |
| 2 | 500,000 |
| 3 | 2,000,000 |
| 4 | 10,000,000 |
| 5 | 50,000,000 |
Safe contents: - Credits (direct). - Any commodity that fits in cargo (ore, organics, equipment, etc.). - Special resources (Quantum Shards, Photonic Crystals, Prismatic Ore). - Genesis Devices. - Ship upgrades / equipment.
Properties: - ✅ NOT lost on citadel destruction. - ✅ Attackers cannot steal from the safe. - ✅ Transfers with planet ownership. - ✅ Only the planet owner can deposit/withdraw.
Usage: - Deposit/withdraw when docked at the planet. - Optional auto-transfer of planetary production into the safe. - Emergency evacuation: pull all safe contents to ship cargo (subject to cargo capacity).
Citadel destruction consequences¶
When citadel hull hits 0 in combat: - Population dies. - Production facilities destroyed. - Planet reverts to uncolonized — anyone can re-colonize it. - All defensive structures (drones, shields, platforms, rail guns) lost. - Safe contents preserved — recoverable by the previous owner.
Strategic patterns¶
- Multiple Level 2–3 citadels > single Level 5 for most players: distributed risk, distributed production, multiple safe storage locations.
- Level 5 is for prestige and fortresses — 50M-credit safe, near-impregnable defense, team headquarters potential.
- Resource pre-stockpiling is critical — long upgrade timers mean the resources sit unused for days during construction.
Player-facing affordances¶
- Citadel panel shows current level, next level requirements, progress bars on each requirement.
- Safe vault UI with deposit/withdraw, auto-deposit toggle, content list.
- Upgrade timer with cancel option (refund schedule TBD; most upgrades are non-refundable mid-build).
- Defense building queue.
Source map¶
| Topic | Path |
|---|---|
| Citadel service & level table | services/gameserver/src/services/citadel_service.py |
| Planet citadel fields | services/gameserver/src/models/planet.py |
| Defense building constants | services/gameserver/src/services/citadel_service.py:DEFENSE_BUILDINGS |
| Combat consequences | services/gameserver/src/services/combat_service.py:_resolve_planet_combat |
| Genesis-derived starting citadel | services/gameserver/src/services/genesis_service.py |
Status: 🚧 Partial —
Planet.citadel_*columns,citadel_service.py(level table, upgrade workflow, safe deposit/withdraw, defense-building construction), and the player-clientplanetary/CitadelManager.tsxUI are in place. Outstanding gaps: the citadel-driven production bonus (📐 Design-only), prerequisite checks tied to specific buildings (🐛 Bug), level naming (🐛 Bug), and refunds-on-cancel for in-progress upgrades.