Planetary Production¶
How a colony turns colonists into resources. Mostly applies to Phase 1+ (Outpost and beyond); a region's Capital-Sector Terra hub planet doesn't produce.
Formula¶
resource += colonists_in_role × base_rate × planet_type_efficiency × hours_elapsed × (1 + upgrade_bonus)
- colonists_in_role — current allocation for that role (
Planet.fuel_allocation/organics_allocation/equipment_allocation). Each is a head-count of colonists assigned to that bucket, not a percentage. Sum may be ≤Planet.colonists; unallocated colonists are idle. - base_rate — 10 units / colonist / day baseline (see
../../SYSTEMS/planetary-production-tick.mdfor the per-tick implementation). - 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.
✅ Shipped — a scheduled production tick advances commodity accrual for every owned, colonized planet on the periodic planetary sweep (npc_scheduler_service._run_planetary_advance_sync calls PlanetaryService.realize_production per planet under a row lock), so a colony banks fuel / organics / equipment even when its owner never opens the screen. The accrual is durable-anchored (Planet.last_production + a production_carry sub-unit bank) and idempotent, so the sweep, the existing lazy advance-on-read, and the admin trigger never double-count. An operator can force one planet forward via POST /api/v1/admin/planets/{id}/tick, which returns the before/after/delta. The planet-type efficiency multiplier is folded into _calculate_production_rates (type_efficiency_for / TYPE_EFFICIENCY), applied to the three commodity rates exactly as the formula specifies.
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 be ≤ Planet.colonists — any unassigned head-count is idle (no production, no consumption penalty).
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 |
| MOUNTAINOUS | 0.6 | 0.4 | 1.5 |
| OCEANIC | 1.5 | 0.4 | 0.6 |
| DESERT | 0.4 | 1.5 | 0.6 |
| VOLCANIC | 1.0 | 0.0 | 2.0 |
| BARREN | 0.0 | 0.0 | 1.5 |
| ICE | 0.8 | 1.2 | 0.5 |
Optimal allocation example (Oceanic, 1.5× fuel) with 10,000 colonists: assign 7,000 to fuel for max throughput, 1,500 each to organics and equipment.
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 (BARREN / ICE) have negative population growth, so production declines over time without immigration.
- Volcanic worlds (VOLCANIC) 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 (scheduled + lazy + admin) | services/gameserver/src/services/planetary_service.py:realize_production; sweep services/gameserver/src/services/npc_scheduler_service.py:_run_planetary_advance_sync; admin trigger services/gameserver/src/api/routes/admin_colonization.py (POST /admin/planets/{id}/tick) |
| Citadel storage caps | services/gameserver/src/services/citadel_service.py:CITADEL_LEVELS |
| Planet API | services/gameserver/src/api/routes/planets.py |