Colonist Professions¶
Status: 🚧 Partial — gameserver profession kernel + training queue + assign API + numeric bonus wiring shipped on tip
459c83155; player-client owner training + active-assignment UI ✅ tip-PRESENT (ProfessionsPanel.tsxviaCitadelPanel.tsx:56, LEG-2583/#847; assign wire LEG-3719). Training charges ✅ provisional-on-queue —queue_trainingcalls_apply_training_charge(profession_service.py:511-512); response includescost_charged: truewithcost_basis: provisional_per_100(:463-466). Magnitudes provisional pending balance pass (ADR-0093 item 35). Phase specialization caps ✅ —_assert_specialization_caponqueue_training(profession_service.py:369-374,:560); fractions fromSPECIALIZATION_CAP_BY_CITADEL_LEVEL(:41-48). (re-verified 2026-09-02 vs Sectorwars2102459c83155— LEG-3972 honesty pass.)
🚧 Partial — kernel + UI shipped; canon residuals remain. Shipped on tip: colonist_profession + profession_training_queue models, profession_service.py, GET /planets/{id}/professions + POST …/professions/train + POST …/professions/assign (planets.py:2675, assign at :2751), and wired numeric bonuses in mining/trade/repair/combat/terraforming/movement paths. Player-client: ProfessionsPanel.tsx + Vitest ProfessionsPanel.test.tsx (train + active-assign paths — handleAssign at :268-474 → planetaryAPI.assignPlanetProfession in api.ts:547-552). ✅ Training charges on queue: PROFESSION_TRAINING_COST_PER_100 defines provisional per-100 recipes for all 12 professions (colonist_profession.py:61-76); _apply_training_charge debits credits + planet stockpile on queue (profession_service.py:384-401, :511-512). GET payload exposes training_costs_per_100, cost_blocked: false, cost_basis: provisional_per_100 (:463-466). ✅ Phase specialization caps: SPECIALIZATION_CAP_BY_CITADEL_LEVEL + max_specialized_for_planet enforce citadel-phase fractions; _assert_specialization_cap rejects overflow on queue (profession_service.py:41-80, :369-374, :560). API maps specialization_cap_exceeded → 400 (planets.py:2743). 📐 Still design-only / TBD: retraining flow, per-profession soft caps, acceleration/rush. Per-profession cost magnitudes remain implementer-proposed provisional pending balance tuning (ADR-0093 item 35). Assume 📐 on subsections below unless marked ✅.
Overview¶
A profession layer sits on top of the three-bucket allocation model documented in colonization.md. Generic colonists are trained (irreversibly) into specialized roles that stack percentage bonuses on top of base production, defense, research, and terraforming. Professions exist to:
- Give planets distinct strategic identities (industrial hub, military bastion, research world, terraforming engine).
- Create credit and resource sinks for late-game wealth.
- Gate certain capabilities (e.g. raising
max_populationceilings) behind a long-lead investment. - Reward forward planning — training is real-time days, not turns.
Generic colonists continue to drive the fuel/organics/equipment allocations. Specialized colonists either replace generics in those roles (with a multiplier) or unlock entirely new roles (terraforming, research, planetary defense bonuses) that allocation buckets cannot express.
The 12 professions¶
Twelve professions, four categories. Per-1,000 / per-colonist multipliers and base costs are sourced from the legacy spec; values flagged TBD were never specified there and need to be set when the system is scheduled.
Engineering¶
| Profession | Bonus / effect | Training time | Training cost | Prerequisite |
|---|---|---|---|---|
| Space Engineers | +25% ship repair speed at this planet; unlocks advanced ship-upgrade facilities | 30 days | 50,000 cr + 1,000 equipment per 100 trainees | Citadel L3 + Orbital Shipyard L2 |
| Structural Engineers | −20% building upgrade costs on this planet; unlocks unique defensive structures | 25 days | TBD cr + TBD equipment | Citadel L3 |
| Mining Engineers | +30% fuel/ore production efficiency; unlocks deep-core mining facilities | 20 days | TBD cr + TBD equipment | Citadel L3 |
Scientific¶
| Profession | Bonus / effect | Training time | Training cost | Prerequisite |
|---|---|---|---|---|
| Research Scientists | +40% research speed; unlocks breakthrough techs (quantum drives, advanced sensors) | 40 days | TBD cr + TBD tech | Citadel L3 + Research Lab L3 |
| Agricultural Scientists | +35% organics production, +15% population growth; unlocks GM crops + hydroponics | 30 days | TBD cr + TBD organics | Citadel L3 |
| Medical Professionals | +20% population growth, disease prevention; unlocks advanced medical facilities | 35 days | TBD cr + TBD equipment | Citadel L3 |
| Terraform Engineers | +0.5 habitability per 1,000 engineers per month (cap +5/month at 10k engineers); unlocks atmospheric processors, ecosystem seeding, climate control | 35 days | TBD cr + TBD organics + TBD equipment | Citadel L3 + Terraforming Lab L3 |
Military¶
| Profession | Bonus / effect | Training time | Training cost | Prerequisite |
|---|---|---|---|---|
| Combat Pilots | +50% planetary defense drone effectiveness; unlocks elite drone squadrons | 25 days | TBD cr + TBD equipment | Citadel L3 + Military Academy L2 |
| Defense Coordinators | +30% turret/shield effectiveness; unlocks integrated defense networks | 30 days | TBD cr + TBD equipment | Citadel L3 |
| Strategic Analysts | Early-warning detection for incoming attacks; unlocks sector-scanning capabilities | 35 days | TBD cr | Citadel L3 |
Economic¶
| Profession | Bonus / effect | Training time | Training cost | Prerequisite |
|---|---|---|---|---|
| Trade Specialists | +25% credit generation from trade routes through this planet; unlocks private NPC-faction trade agreements | 20 days | TBD cr | Citadel L3 |
| Industrial Managers | +35% equipment production; unlocks automated factory systems | 25 days | TBD cr + TBD equipment | Citadel L3 |
Per-100 anchor¶
The legacy training example pegs Space Engineers at 50,000 cr + 1,000 equipment per 100 trainees, completing in 30 real-time days. This is the only fully-specified recipe. Other professions should be priced by analogy when the system is scheduled — military and economic professions roughly equal Space Engineers; scientific (especially Research Scientists, Terraform Engineers) trend ~1.5× more expensive due to longer training.
Training mechanism¶
Where training happens¶
- Training is planet-local. A planet trains its own generic colonists into specialists; trainees do not transit between planets.
- A planet must be citadel level 3+ (Colony phase or higher) to operate a training pipeline at all. Outposts and Settlements cannot run profession training, regardless of population.
- Some professions require an additional building at a minimum level (Orbital Shipyard, Research Lab, Military Academy, Terraforming Lab — see prerequisite column above). Without the building, that profession's training option is hidden.
Time and cost¶
- Training time: the integer real-time days listed per profession (20–40 days). The clock runs whether the player is online or not.
- Training cost: deducted from the player's credits and from the planet's stockpile (equipment / organics / tech as specified) when training is queued, not when it completes. Cancelling a training run before completion refunds zero — costs are sunk on queue.
- Acceleration: an optional
accelerateflag pays additional credits to compress training. Multiplier and per-day premium TBD.
Throughput¶
- Max trainees per cycle: TBD. The legacy spec implies a queue (the UI shows multiple in flight) but does not pin a numeric cap. Target rule: cap concurrent trainees at a fraction of the planet's generic colonist pool — e.g. 5% of
Planet.colonistsmay be in training at any time. - Queue depth: TBD. Suggest at least 5 simultaneous orders so a player can stack a long-running run (Research Scientists, 40 days) behind shorter ones.
- A rush option pays extra credits to skip remaining training time. Cost factor TBD.
Conversion¶
Training converts generic colonists into specialists permanently:
- Generic colonist count drops by the trainee count when the queue completes.
- Specialist count for that profession increases by the same number.
- The conversion is irreversible — there is no de-training back into generic colonists. Switching a colonist's profession requires a separate retraining flow (see below) and pays full cost again.
Profession assignment¶
Who can assign¶
- Only the planet's owner. Co-owners and team-mates with landing rights cannot queue training or reassign specialists.
What "assignment" means¶
Two distinct concepts:
- Profession — what the colonist is. Set at training-completion and persistent until retrained.
- Active assignment — what the profession is doing right now. For example, a population of 2,000 Terraform Engineers can be assigned to
ACTIVE_TERRAFORMINGon this planet, or held in reserve. Combat Pilots can be tied to specific drone squadrons.
A profession's bonuses (production multipliers, drone effectiveness) typically apply passively as long as the colonists exist on-planet. Active-assignment toggles matter for professions that consume resources (Terraform Engineers burn organics + equipment while assigned to active terraforming).
Switching jobs (retraining)¶
- Retraining cost: full training cost of the new profession (no discount for already-specialized colonists).
- Retraining time: same as the new profession's training time.
- During retraining the colonist is not productive in either profession — bonuses lapse for the duration.
Off-planet movement¶
Specialists are still colonists. They occupy 1 cargo space per unit if loaded onto a ship and are subject to the standard cargo-loss rule on ship destruction. Whether transferred specialists retain their profession at the destination planet is TBD — design intent leans toward yes, with a re-acclimation period of TBD days during which bonuses are halved.
Multi-role professions (Phase 3 extension)¶
A late-tier extension introduces hybrid professions that fill two roles at reduced effectiveness instead of one role at full effectiveness:
- Versatile Engineers — partial Space Engineer + partial Industrial Manager (ship repair and equipment production).
- Agri-Scientists — partial Agricultural Scientist + partial Research Scientist (organics yield and tech research).
- Combat-Engineers — partial Defense Coordinator + partial Industrial Manager (defenses and equipment).
Stacking percentages, training cost, and unlock requirements are TBD. Multi-role professions are scheduled for Phase 3 of the rollout (see Status summary).
Caps and limits¶
Specialization cap by phase¶
The fraction of a planet's population that can be specialized scales with the colony lifecycle phase from colonization.md:
| Phase | Citadel level | Max specialized | Training available |
|---|---|---|---|
| 1 — Outpost | 1 | 0% | No |
| 2 — Settlement | 2 | 10% | No (training needs L3) |
| 3 — Colony | 3 | 25% | Yes |
| 4 — Major Colony | 4 | 50% | Yes |
| 5 — Planetary Capital | 5 | 75% | Yes |
A Settlement (Phase 2) can hold up to 10% specialists if they were transferred in from another planet, but cannot train new ones locally. Outposts cannot host any specialists at all — incoming specialists revert to generic colonists or are refused.
Per-profession soft caps¶
Soft caps per profession (preventing a planet from trivially stacking 100% Mining Engineers) are TBD. Legacy spec does not pin numbers. Target rule: each profession is capped at a fraction of the global specialization cap, e.g. no single profession may exceed 40% of the planet's specialized headcount.
Active-assignment caps for resource-consuming professions¶
- Terraform Engineers: meaningful impact requires at least 500 engineers; rate caps at +5 habitability/month at 10,000 engineers. Above 10k, additional engineers add no terraforming speed (they can still passively boost research / morale via secondary roles, TBD).
- Other professions: no upper cap on bonus stacking specified. Diminishing returns beyond the planet's specialization cap is TBD.
Worked example — terraforming a volcanic world¶
Illustrative end-state scenario, mirroring the legacy reference project:
Planet: VOLCANIC
Starting habitability: 15
Target habitability: 75
Engineers trained: 3,000 (from generic colonists, 35d each)
Terraform rate: +1.5 habitability/month (3000 / 1000 × 0.5)
Project duration: ~40 months
Organics consumed: ~200,000 units (drawn from planet stockpile)
Equipment consumed: ~120,000 units
Total credits spent: ~500,000 (training + ongoing)
Population cap change: 15,000 → 75,000 (+60,000)
Growth multiplier: 0.15× → 0.75× of base
The terraforming-rate scaling (0.5 habitability/month per 1,000 engineers) and the per-habitability-point cost ramp (+25% at 41–70, +50% at 71–90, +100% at 91–100) live in terraforming.md once that doc absorbs the Terraform-Engineer integration; this profession spec sets the engineer-side numbers only.
Cross-system effects¶
| Profession | Touches | Mechanism |
|---|---|---|
| Mining Engineers | production.md | +30% multiplier on fuel/ore production for colonists allocated to fuel role |
| Industrial Managers | production.md | +35% multiplier on equipment production |
| Agricultural Scientists | production.md, colonization.md | +35% organics production, +15% colonist growth rate |
| Medical Professionals | colonization.md | +20% colonist growth rate, suppresses disease events |
| Terraform Engineers | terraforming.md | Drives the long-running habitability-raise project; consumes organics + equipment from planet stockpile while active |
| Combat Pilots | defense.md, galaxy/sectors.md | +50% planetary defense drone effectiveness in sector engagements |
| Defense Coordinators | defense.md | +30% turret + shield effectiveness |
| Strategic Analysts | galaxy/sectors.md | Early-warning detection of hostile fleets approaching the sector |
| Space Engineers | defense.md, ships | +25% ship-repair throughput at the planet's shipyard |
| Structural Engineers | citadels.md | −20% citadel and building upgrade costs |
| Research Scientists | Citadel Research (research_cockpit.py, RP ledger + tech-tree unlock — already live and shipped, distinct from this row's gap) |
+40% research speed; unlocks tier-3 techs — 📐 the profession's bonus hook into that ledger is not yet specced: no rule ties a colony's Research Scientist headcount to the empire RP faucet rate or to which tech_tree nodes are unlockable |
| Trade Specialists | trading subsystem | +25% credit generation on trade routes that originate or terminate at this planet |
Bonuses stack multiplicatively with citadel-level passive bonuses and production-upgrade bonuses unless a specific subsystem doc specifies additive stacking.
Source map¶
| Concern | Path | Tip status |
|---|---|---|
| Profession service (training queue, counts, bonus multipliers) | services/gameserver/src/services/profession_service.py |
✅ Shipped |
| Profession data model | services/gameserver/src/models/colonist_profession.py |
✅ Shipped |
| Training queue model | services/gameserver/src/models/profession_training_queue.py |
✅ Shipped |
| Profession enum | services/gameserver/src/models/colonist_profession.py:ProfessionType |
✅ Shipped |
| Production-tick integration (Mining / Industrial / Agricultural / Medical) | services/gameserver/src/services/planetary_service.py via production_multipliers |
✅ Shipped |
| Terraforming integration (Terraform Engineer rate boost) | services/gameserver/src/services/terraforming_service.py |
✅ Shipped |
| Defense integration (Combat Pilots / Defense Coordinators) | services/gameserver/src/services/combat_service.py |
✅ Shipped |
| Trade / repair bonuses (Trade Specialists / Space Engineers) | trading.py, player.py, ship_upgrades.py |
✅ Shipped |
| Strategic Analyst early warning | services/gameserver/src/services/movement_service.py:_sweep_strategic_analyst_detection |
✅ Shipped |
| API — list + train | GET/POST …/planets/{id}/professions (+ /train) in planets.py:2675 |
✅ Shipped |
| API — assign / reassign active jobs | POST …/professions/assign in planets.py:2751 (owner-only ProfessionService.assign_active) |
✅ Shipped |
| Player UI — profession panel + training queue | ProfessionsPanel.tsx via CitadelPanel.tsx:56 |
✅ tip-PRESENT |
| Player UI — active assignment (set active headcount) | ProfessionsPanel.tsx:268-474 handleAssign → api.ts:547-552 POST …/professions/assign |
✅ tip-PRESENT |
Cross-references:
- colonization.md — population flow, allocation buckets, lifecycle phases.
- terraforming.md — habitability-raise project that Terraform Engineers accelerate.
- production.md — base production formula that Mining / Industrial / Agricultural professions multiply.
- citadels.md — citadel level gates training and the per-phase specialization cap.
- defense.md — drone, turret, and shield effects boosted by Combat Pilots and Defense Coordinators.
- galaxy/sectors.md — sector-scale combat where planetary professions amplify defenders.
- DATA_MODELS/planets.md —
Planetmodel that grows new relationships to profession aggregates. - DATA_MODELS/player.md — player-side credit and resource deductions for training costs.
Status summary¶
✅ Shipped on tip (459c83155):
colonist_professions+profession_training_queuetables and Alembic migration chain.ProfessionTypeenum (all 12 types trainable); owner-onlyGET/POST /planets/{id}/professions(+/train+/assignatplanets.py:2751).- Numeric bonus wiring for Mining / Industrial / Agricultural / Medical / Research / Structural / Combat / Defense / Terraform / Space Engineer repair / Trade Specialist credit paths (see Cross-system effects).
- Strategic Analyst same-sector early-warning sweep in movement.
- Player-client
ProfessionsPanel— counts, queue display, owner train enqueue, active-assignment UI (handleAssign→assignPlanetProfession; no invented prices). - Phase specialization caps — citadel-phase fractions via
SPECIALIZATION_CAP_BY_CITADEL_LEVEL/max_specialized_for_planet(profession_service.py:41-80);_assert_specialization_caponqueue_training(:369-374,:560); API mapsspecialization_cap_exceeded→ 400 (planets.py:2743).
📐 Residuals (honest design-only):
- Training cost magnitudes — per-100 recipes are provisional (
colonist_profession.py:61-76); balance pass pending (ADR-0093 item 35). Charges do debit on queue (profession_service.py:511-512). - Retraining flow, off-planet profession retention, per-profession soft caps, acceleration/rush.
- Multi-role / hybrid professions (Phase 3).
Implementation order for remaining canon (when scheduled) follows the legacy phase plan:
- Phase 1 — Space Engineers, Mining Engineers, Trade Specialists, Terraform Engineers (high priority due to habitability-driven population caps).
- Phase 2 — Combat Pilots, Research Scientists, Defense Coordinators, Agricultural Scientists.
- Phase 3 — Medical Professionals, Structural Engineers, Strategic Analysts, Industrial Managers, plus multi-role / hybrid professions.
If this system is indefinitely deferred, file an ADR in ADR/ capturing the deferral rationale and the conditions under which it would be picked up.