Planetary Defense

A multi-layered system protecting colonies. Five engagement layers, each with its own buildings, costs, and effective targets.

Engagement order

When a hostile fleet attacks a planet:

1. Long-range scanner detects approach (1–2 sectors out).
2. Orbital defense platforms open fire from 2 sectors away.
3. Fixed rail gun batteries engage in planetary orbit (1 sector).
4. Defense drones swarm.
5. Shield generators absorb damage to citadel.
6. Citadel structure — final layer; if destroyed the planet is permanently lost (population dies, production gone, safe contents preserved for the owner).

Defense drones

Citadel level	Max drones
1	10
2	25
3	50
4	100
5	200

• Cost: 1,000 cr each at military stations.
• Planet-deployed drones get +5% effectiveness vs ship-mounted.
• Drone health 0–100; 100 cr to repair, 1,000 cr to replace.
• Drones engage all ship sizes equally.

Shield generators

10 levels, each with strength and regen.

Level	Shield strength
0	0
1	1,000
2	2,500
3	5,000
4	10,000
5	15,000
6	20,000
7	30,000
8	40,000
9	50,000
10	75,000

• Regen: 10%/hour at peace, 5%/hour during combat.
• Upgrade costs scale steeply (10k cr → 1.5M cr); total to Level 10 ≈ 4.5M cr + 450k equipment.

Orbital defense platforms

• Citadel level 4+ required.
• Capacity: 1 platform at L4, 3 platforms at L5 (max).
• Cost: 500,000 cr + 50,000 ore + 25,000 equipment per platform.
• Build time: 168 hours (7 days).
• Range: 2 sectors out — engages before attackers reach the planet.
• Targeting priority: largest ships first (Carriers, Colony Ships).
• Fire rate: 1 burst / 30s; damage 500–1,500.
• Platform health: 5,000 hull + 2,500 shields (regen 10%/hr).

Upgrades: - Enhanced Targeting (+25% accuracy) — 200,000 cr. - Increased Power (+50% damage) — 300,000 cr. - Advanced Shields (+2,500 shields) — 250,000 cr. - Rapid Fire (30s → 20s) — 400,000 cr.

Fixed rail gun batteries

• Citadel level 4+ required.
• Capacity: 4 batteries at L4, 10 at L5 (max).
• Cost: 150,000 cr + 20,000 ore + 10,000 equipment per battery.
• Build time: 72 hours (3 days) per battery.
• Range: planetary orbit only (1 sector).
• Fire rate: 1 shot / 60s; damage 1,000–3,000 before size multipliers.

Damage by ship size:

Ship class	Damage %
Carrier	200%
Colony Ship	200%
Cargo Hauler	150%
Defender	120%
Light Freighter	50%
Warp Jumper	25%
Fast Courier	15%
Scout Ship	10%

This makes rail guns a specialized anti-capital weapon. Small/fast ships shrug them off; large ships take heavy damage.

Upgrades: - Predictive Targeting (+20% vs large) — 100k cr per battery. - Armor-Piercing Rounds (ignore 50% shields) — 150k cr per battery. - Rapid Reload (60s → 45s) — 200k cr per battery.

Auxiliary defensive buildings

Defense grid

• Citadel level 3+, 200,000 cr + 15,000 equipment, 96h.
• +15% drone damage and accuracy. Upgradable to L2 (+25% total) for 300k cr.

Scanner array

• Citadel level 2+, 75,000 cr + 10,000 equipment, 48h.
• Capacity: 1 at L2, 1 at L3, 2 at L4–L5.
• Effect: 1-sector early warning; advanced upgrade extends to 2 sectors.
• Upgrade: Advanced Scanner — 200,000 cr.

Automated turret network ✅ Shipped

• Citadel level 3+.
• Cost: 150,000 cr + 8,000 equipment; 72h build.
• Capacity: 2 at L3, 4 at L4, 6 at L5.
• Each turret destroys 1–3 attacking drones per round.

🐛 Bug — Advanced Genesis turret start. The design intent has Advanced Genesis colonies start with 4 turrets pre-installed (matching the L2 capacity). genesis_service.py initializes citadel level 2 with population and safe storage but does not seed any turrets. Target: have the advanced-tier formation path also write the initial 4 turrets into Planet.active_events["defense_buildings"].

Siege

A siege is the persistent state imposed on an owned planet when hostile forces hold the surrounding sector for SIEGE_TURNS_THRESHOLD = 3 consecutive turns.

State on Planet: under_siege (bool), siege_started_at (datetime), siege_attacker_id (uuid), siege_turns (int).

While under_siege is true:

• Production penalty: all production rates ×0.75 (SIEGE_PRODUCTION_PENALTY = 0.25 in planetary_service.py). Applied inside _calculate_production_rates.
• Colonist growth halted: colonist rate forced to 0 each tick.
• Morale loss: SIEGE_MORALE_LOSS_PER_TURN = 5 percentage points per turn, mitigated by 0.05 × defense_level (each defense level reduces the per-turn morale loss).
• Defense damage reduction: each defense_level adds DEFENSE_DAMAGE_REDUCTION_PER_LEVEL = 0.10 (10%) damage reduction to citadel structure during siege resolution.
• Resource theft: a fraction of generated commodities should transfer to the besieger. 📐 Design-only — penalty is applied but no transfer.

A siege lifts when no hostile ships remain in the sector for the detection window (lift_siege in planetary_service.py).

Defensive strength examples

All examples assume the design naming progression (Outpost / Settlement / Colony / Major Colony / Planetary Capital).

L2 Settlement (traditional): 25 drones (25k cr) + Level 1 shields (10k cr) ≈ 35k investment → defense rating ~15/100.

L2 Settlement (Advanced Genesis start): 25 drones + L1 shields + 4 turrets included → ~25/100.

L4 Major Colony, fortified: 100 drones + L6 shields (~1.235M cr) + 1 orbital platform (500k) + 4 rail guns (600k) + L2 defense grid (500k) + advanced scanner (200k) + 4 turrets (150k) ≈ 3.5M cr → ~70/100.

L5 Planetary Capital, fortress: 200 drones + L10 shields (~4.485M) + 3 platforms (1.5M) + 10 rail guns (1.5M) + everything else ≈ 9.3M cr → ~95/100.

Citadel destruction

If the citadel falls: - Population dies. - Production facilities destroyed. - Planet reverts to uncolonized. - Safe contents are preserved — owner can recover what was in the safe vault. See citadels.md.

Player-facing affordances

• Defense overview panel: rating (0–100), drone count, shield strength, platform/rail-gun counts, recent attack log.
• Build queue UI showing upgrade timers.
• Real-time alerts when scanner detects incoming hostiles.
• Auto-repair toggle for drones (uses planet credits when below threshold).

Source map

Topic	Path
Citadel/defense service	services/gameserver/src/services/citadel_service.py
Siege detection, defense-level upgrades, shield mechanics	services/gameserver/src/services/planetary_service.py
Planet model defense fields	services/gameserver/src/models/planet.py
Combat resolution against planets	services/gameserver/src/services/combat_service.py:_resolve_planet_combat
Planet API routes	services/gameserver/src/api/routes/planets.py
Drone service	services/gameserver/src/services/drone_service.py

Status: 🚧 Partial — defense_level upgrades, shield mechanics, siege detection (SIEGE_TURNS_THRESHOLD, SIEGE_PRODUCTION_PENALTY, SIEGE_MORALE_LOSS_PER_TURN), and the citadel-bound defense-building queue (orbital platform, scanner array, turret network) are implemented. Outstanding gaps tracked inline above: Advanced Genesis turret pre-install (🐛 Bug), siege resource theft transfer (📐 Design-only), and rail gun + orbital platform combat resolution against the actual ship-size multiplier table (📐 Design-only).