Colonization & Colony Management¶
Covers the lifecycle from buying colonists at Sector 1 through running a Planetary Capital.
Two paths to a colony¶
1. Traditional colonization¶
Requires: - 10,000 colonists in cargo (1 cargo space each). - 10,000 credits investment. - An uncolonized planet you can land on.
Result: Outpost (Phase 1, citadel level 1) with 100–1,000 starting population.
2. Genesis Device terraforming¶
See galaxy/genesis-devices.md.
- Basic Genesis (1 device) → Outpost.
- Enhanced Genesis (3 devices) → Outpost (better planet-type roll).
- Advanced Genesis (Colony Ship sacrifice) → instant Settlement (Phase 2, citadel level 2) with 5,000 colonists, +10% production, 4 turrets, basic shields.
Population (colonist) flow¶
Population is treated as a commodity (colonists) that becomes colonists on planet arrival.
Acquiring population¶
- Sold only at Sector 1 of every region (Earth in Terran Space, regional hubs elsewhere).
- Class-0 station, special inventory.
- Unlimited supply.
Pricing (✅ Shipped)¶
colonists is a dynamic-priced commodity, not a fixed sticker. Source: services/gameserver/src/services/trading_service.py — COMMODITY_PRICE_RANGES["colonists"] = {min: 30, max: 80}, calculate_dynamic_price().
Per-unit price is computed at the population hub station as:
supply_ratio = station.commodity.quantity / capacity # 0.0 – 1.0
midpoint = base_price × (1.5 - supply_ratio)
sell_price = midpoint × 1.15 (SELL_SPREAD)
final = clamp(sell_price, 30, 80)
Drivers:
- Supply at the hub is the only live signal — heavy buying drains stock, raising the price toward 80; periodic restocks pull it back toward 30.
- The 15% sell spread is the same one used for every commodity (SELL_SPREAD = 1.15).
- Federation tax / region control do not currently feed into the formula.
Effective range a player will see: ~30–80 cr/unit, dependent on hub stock at purchase time. Bulk colonization runs (10,000 units) deplete the hub enough to noticeably push the price up mid-buy.
Transport¶
- 1 cargo space per unit.
- For 10,000 colonists you need 10,000 cargo space — multiple trips for any non-Cargo Hauler ship.
- Standard cargo loss rules apply (lose all on ship destruction).
Becoming colonists¶
When you colonize:
- Cargo colonists decremented by 10,000.
- Credits decremented by 10,000.
- Planet.colonists += 10,000 (assigned with default allocation).
- Player added to player_planets association table.
Planet types¶
Eight types (models/planet.py:PlanetType).
| Type | Fuel mult | Organics mult | Equip mult | Fuel cap | Org cap | Equip cap | Growth/day | Habitability % | Native life chance |
|---|---|---|---|---|---|---|---|---|---|
| TERRA (sector 1) | 0 | 0 | 0 | ∞ | ∞ | ∞ | ∞ | 100 | — |
| M_CLASS (Earth-like) | 1.0 | 1.0 | 1.0 | 10,000 | 10,000 | 10,000 | +0.5% | 95–100 | 60% |
| L_CLASS (Mountainous) | 0.6 | 0.4 | 1.5 | 8,000 | 5,000 | 15,000 | +0.3% | 60–75 | 40% |
| O_CLASS (Oceanic) | 1.5 | 0.4 | 0.6 | 15,000 | 5,000 | 8,000 | +0.4% | 60–75 | 75% |
| K_CLASS (Desert) | 0.4 | 1.5 | 0.6 | 5,000 | 15,000 | 8,000 | +0.2% | 30–45 | 25% |
| H_CLASS (Volcanic) | 1.0 | 0.0 | 2.0 | 8,000 | 0 | 15,000 | +0.1% | 10–25 | 10% |
| D_CLASS (Barren) | 0.0 | 0.0 | 1.5 | 0 | 0 | 20,000 | −0.1% | 0 | 5% |
| C_CLASS (Ice) | 0.8 | 1.2 | 0.5 | 10,000 | 15,000 | 8,000 | −0.2% | 35–50 | 30% |
Barren and Ice planets have negative natural growth — without continuous immigration or terraforming, the colony shrinks.
Colony lifecycle phases¶
Colonies progress through five phases, each tied to a citadel level (see citadels.md for the structural side):
| Phase | Pop range | Citadel level | Notes |
|---|---|---|---|
| 1 — Outpost | 0–1,000 | 1 | Survival focus, minimal defense |
| 2 — Settlement | 1,001–5,000 | 2 | Basic shield, moderate production |
| 3 — Colony | 5,001–15,000 | 3 | Specialization, defense grid |
| 4 — Major Colony | 15,001–50,000 | 4 | Industrial scale, orbital platforms unlock |
| 5 — Planetary Capital | 50,001–200,000 | 5 | Fortress, max upgrades |
Promotion between phases requires meeting population, resource, and prerequisite thresholds — see citadels.md for the full upgrade matrix.
Production growth is multiplicative across phases: - Outpost → Settlement: ~5×. - Settlement → Colony: ~3×. - Colony → Major Colony: ~4×. - Major Colony → Planetary Capital: ~5×.
Population capacity¶
Two ceilings interact:
Planet.max_colonists— base workforce ceiling, default10,000(models/planet.py,services/planetary_service.py:308).Planet.max_population— habitability-derived total inhabitants ceiling.
Target formula (legacy intent):
max_population = habitability_score × 1,000
Examples: - Habitability 95 (M-class) → 95,000 max population. - Habitability 60 (L/O-class) → 60,000. - Habitability 25 (H-class) → 25,000. - Habitability 0 (D-class) → 0 — orbital habitats only.
🐛 Bug — max_population is currently set ad-hoc by world generation (services/genesis_service.py:247 uses planet_size × 100,000; services/nexus_generation_service.py:464 uses (size × habitability × 100,000) / 10). The habitability_score × 1,000 rule is the target; align world-gen and any in-game habitability mutation paths to recompute max_population from this formula.
The runtime habitability-effects helper (services/planetary_service.py:946 get_habitability_effects) reports effectiveMaxColonists = max_colonists × (habitability/100) — keep this view; it's the workforce-side limiter that pairs with max_population as the inhabitants-side limiter.
Population growth¶
Source: services/gameserver/src/services/planetary_service.py:914 (_calculate_production_rates).
Daily formula:
colonist_rate = colonists × 0.01 × (habitability_score / 100)
i.e. base growth = 1% per day, scaled linearly by habitability. With a specialization bonus applied:
colonist_rate ×= specialization.production.colonists # e.g. agricultural
Per-planet-type effective rates (base 1% × habitability midpoint):
| Type | Habitability | Effective daily growth |
|---|---|---|
| M_CLASS | 97 | ~0.97% |
| L_CLASS | 67 | ~0.67% |
| O_CLASS | 67 | ~0.67% |
| K_CLASS | 37 | ~0.37% |
| C_CLASS | 42 | ~0.42% |
| H_CLASS | 17 | ~0.17% |
| D_CLASS | 0 | 0% |
The per-planet-type "growth rate" column in the planet-type table is a presentation summary; the load-bearing formula is the one above.
Other growth modifiers¶
- Siege:
colonist_rate = 0whilePlanet.under_siegeis true (planetary_service.py:937). ✅ Shipped. - Specialization: agricultural / balanced configurations multiply colonist growth via
_calculate_specialization_bonuses. ✅ Shipped. - Terraforming: raises
habitability_score, which directly raisescolonist_rate; see terraforming.md. Terraforming completion also floorspopulation_growthto 1.0 / 1.5 / 2.0 depending on tier (services/terraforming_service.py:481). - Negative natural growth for D_CLASS / C_CLASS in the planet-type table: 📐 Design-only — current code clamps
habitabilityto a minimum of 1 before the multiplier and never produces a negative rate. To match the table, the production tick needs an explicit decline branch whenhabitability_score < threshold(e.g.,< 20).
Overcrowding¶
📐 Design-only. Neither max_population nor max_colonists is enforced as a cap on colonist_rate in planetary_service._calculate_production_rates. Target rule (legacy intent):
- At
population ≥ max_population: growth halts (colonist_rate = 0). - Above
0.9 × max_population: linear taper ofcolonist_ratefrom 100% → 0%. - No decay below the cap — overcrowding stops growth, it does not shrink the colony.
Implement in the production-tick path; cite services/gameserver/src/services/planetary_service.py:_calculate_production_rates.
Low-habitability resource cost penalty¶
📐 Design-only. Legacy spec calls for +20% resource costs (life support / environmental control) when habitability_score is below a threshold (target: < 30). No code path applies this penalty today — production output is multiplied by habitability, but no resource-consumption multiplier exists. If kept, document the threshold and apply the multiplier in the production tick alongside the existing siege multiplier.
Colonist allocation¶
Planet.fuel_allocation, organics_allocation, equipment_allocation — three buckets (sum = total population). Adjustable any time, instantly, no cost.
Production: see production.md.
Optimal allocation depends on planet type. Example: - Oceanic (1.5× fuel): 70% fuel / 15% organics / 15% equipment. - Mountainous (1.5× equipment): 15% / 15% / 70%. - M-Class (balanced 1.0×): allocate based on empire needs.
Colony management actions¶
Daily¶
- Withdraw produced resources (production stops at storage cap).
- Adjust allocation as market prices shift.
- Monitor drone count and shield strength.
Strategic¶
- Citadel upgrades (resources + time + prerequisites; see citadels.md).
- Production upgrades (+10% per level, max level 10 per resource).
- Defensive investments (drones, shields, orbital platforms, rail guns; see defense.md).
- Terraforming (see terraforming.md).
Ownership controls¶
- Transfer ownership to another player (5% transfer fee, recipient must accept).
- Abandoned planets (owner inactive 90+ days) become claimable for 50,000 cr + 5,000 each of ore/organics/equipment — design.
- Landing rights: Public / Team Only / Private / Custom whitelist / Deny list.
🚧 Partial — abandonment, transfer fees, and granular landing-rights ACLs are documented in design; the code has owner-only access and basic transfer.
Player-facing affordances¶
- Planet management UI: phase, population, growth rate, allocation sliders, storage levels, defense rating.
- Resource collection panel (transfer to docked ship's cargo).
- Citadel upgrade timer with prerequisite tracker.
- Map overlay showing all your owned planets across regions.
- Income feed showing passive credit/resource gains.
- Population graphs and "days until citadel cap" projections.
Colonist profession system¶
📐 Design-only. A profession layer sits over the three-bucket allocation model: generic colonists are trained (irreversibly) into twelve specialized roles (Engineering, Scientific, Military, Economic) that stack percentage bonuses on top of base production, defense, research, and terraforming. Specialization cap scales with citadel phase from 0% at Outpost to 75% at Planetary Capital, and training requires citadel L3+. No code path exists today — Planet has no profession column and there is no colonist_professions table.
Full mechanics, the per-profession bonus table, training and retraining flow, cross-system effects, and target source-file map live in professions.md.
Source map¶
| Topic | Path |
|---|---|
| Planetary service | services/gameserver/src/services/planetary_service.py |
| Growth + production tick | services/gameserver/src/services/planetary_service.py:_calculate_production_rates |
| Habitability effects helper | services/gameserver/src/services/planetary_service.py:get_habitability_effects |
| Planet model | services/gameserver/src/models/planet.py |
| Player ↔ planet association | services/gameserver/src/models/planet.py:player_planets |
| Planet API routes | services/gameserver/src/api/routes/planets.py |
| Admin colonization tools | services/gameserver/src/api/routes/admin_colonization.py |
| Genesis-based creation | services/gameserver/src/services/genesis_service.py |
| Citadel upgrades | services/gameserver/src/services/citadel_service.py |
| Terraforming | services/gameserver/src/services/terraforming_service.py |
| Population commodity pricing | services/gameserver/src/services/trading_service.py (COMMODITY_PRICE_RANGES["colonists"], calculate_dynamic_price) |