Planetary Production¶
How a colony turns colonists into resources. Mostly applies to Phase 1+ (Outpost and beyond); Sector 1 / Terra worlds don't produce.
Formula¶
resource += colonists_in_role × planet_type_efficiency × hours_elapsed × (1 + upgrade_bonus)
- colonists_in_role — current allocation for that role (
Planet.fuel_allocation/organics_allocation/equipment_allocation). - planet_type_efficiency — multiplier from the planet's type (see colonization.md).
- hours_elapsed — production calculated hourly.
- upgrade_bonus — +10% per upgrade level, max level 10 per resource.
Production halts when storage hits capacity for that resource.
Three production roles¶
Colonists can be assigned to:
- Fuel production → produces
ore/fuel(the codebase usesfuel_oreandfuel_allocationas a unified field for the historical "ore" + propulsion resource). - Organics production → produces
organics. - Equipment production → produces
equipment.
Reallocation is instant, 0 turns, no cost. Total assigned must equal Planet.colonists.
Storage capacity¶
Storage caps scale with citadel level:
| Citadel level | Cap per resource |
|---|---|
| 1 (Outpost) | 1,000 |
| 2 (Settlement) | 5,000 |
| 3 (Colony) | 15,000 |
| 4 (Major Colony) | 50,000 |
| 5 (Planetary Capital) | 150,000 |
Planet type also caps maximum storage further (e.g. a Volcanic planet has 0 organics cap because it can't store food).
Production upgrades¶
- Three independent upgrade tracks: ore, organics, equipment.
- Each level: +10% multiplicative bonus.
- Max level: 10 per resource (so up to +100%).
- Purchased with credits and resources (specific costs not codified — design-stage tuning).
Planet-type efficiency table¶
(Repeated from colonization.md for convenience.)
| Type | Fuel mult | Organics mult | Equipment mult |
|---|---|---|---|
| TERRA | 0 | 0 | 0 |
| M_CLASS | 1.0 | 1.0 | 1.0 |
| L_CLASS | 0.6 | 0.4 | 1.5 |
| O_CLASS | 1.5 | 0.4 | 0.6 |
| K_CLASS | 0.4 | 1.5 | 0.6 |
| H_CLASS | 1.0 | 0.0 | 2.0 |
| D_CLASS | 0.0 | 0.0 | 1.5 |
| C_CLASS | 0.8 | 1.2 | 0.5 |
Optimal allocation example (Oceanic, 1.5× fuel): assign ~70% to fuel for max throughput.
Genesis Device starting state¶
| Genesis tier | Initial production state |
|---|---|
| Basic (1 device) | Outpost-level production, 100–1,000 colonists, no bonuses |
| Enhanced (3 devices) | Outpost-level, but planet type biased toward better roll |
| Advanced (Colony Ship sacrifice) | Settlement-level, 5,000 colonists, +10% bonus, basic facility pre-built — ~5× higher than standard |
Edge cases¶
- Hostile worlds (D_CLASS / C_CLASS) have negative population growth, so production declines over time without immigration.
- Volcanic worlds (H_CLASS) cannot produce organics at all (0× multiplier).
- Storage full → production stops; player must collect or storage upgrades.
Player-facing affordances¶
- Allocation sliders with live preview of hourly output per resource.
- Storage bars per resource with "days until full" estimate.
- Production upgrade UI showing current level, next level cost, expected throughput delta.
- Empire-wide production dashboard for multi-colony players.
Source map¶
| Topic | Path |
|---|---|
| Planetary service | services/gameserver/src/services/planetary_service.py |
| Planet model + production fields | services/gameserver/src/models/planet.py |
| Production tick | services/gameserver/src/services/planetary_service.py (hourly producer) |
| Citadel storage caps | services/gameserver/src/services/citadel_service.py:CITADEL_LEVELS |
| Planet API | services/gameserver/src/api/routes/planets.py |