# Mechanics (PRUNplanner-derived; source of truth)

Source files in `ref/frontend/src/features/planning/calculations/`. Everything here is read from their code, not verified in-game unless marked.

## Building efficiency = product of factors (`bonusCalculations.ts`)
| Factor | Value |
|---|---|
| Workforce | sum over tiers of (tier headcount / total headcount) x tier satisfaction-efficiency |
| COGC programme matching building expertise | x1.25 |
| COGC workforce programme (e.g. SETTLERS), building uses that tier | x1.10 |
| Corporation HQ | x1.10 |
| Expert count in that expertise (1..5) | x(1 + 0.0306, 0.0696, 0.1248, 0.1974, 0.284) |
| Fertility (FRM, ORC only) | x(1 + fertility x 10/33); fertility -1 gives 0 |
| Faction bonus | x(1 + bonus x m), m = 2 x (-2 x permits_used/permits_total + 3); needs building expertise |

Faction bonus table: ANTARES electronics 5%; BENTEN manufacturing 5%; HORTUS agriculture 3%, food industries 2%; MORIA metallurgy 2%, construction 3%; OUTSIDEREGION chemistry, fuel refining, resource extraction 2% each.

## Workforce satisfaction (`workforceCalculations.ts`)
- Satisfaction per tier = min(1, capacity/required) x base, base = 0.02 x (1+10/3) x 5 x (1+5/6) = 0.794.
- Luxury 1 met: x(1+1/11); luxury 2 met: x(1+2/13); both met gives 1.0. Consistent with handbook (PWO alone ~87%, COF alone ~91%).
- Consumption per worker per day = need/100 (table in the file). Consumption uses min(required, capacity) workers. Engineers and scientists needs (DW 10, MED 0.5, FIM/MEA 7, HSS/LC, PDA/WS, VG/NST lux1, GIN/WIN lux2) are in the source, absent from the old handoff.

## Extraction (`extractionCalculations.ts`)
- Cycle times: EXT (mineral) 12 h, COL (gas) 6 h, RIG (liquid) 4.8 h.
- Amount per cycle = ceil(daily_extraction x cycle/24h); time scaled so daily rate stays daily_extraction.
- Daily extraction = factor x 70 (MINERAL, LIQUID) or x 60 (GASEOUS), factor = concentration as a fraction (backend `gamedata/fio/importers.py`). VERIFIED live: an ALO factor of 0.4 -> 28/day per EXT (FIO order 14 ALO / 12.008 h), O 0.3 x 60 = 18, H2O 0.2 x 70 = 14: exactly the resource chips APEX and PRUNplanner show (the chip number IS daily extraction, not concentration). An old note 'FIO H2O 20 vs UI 14' was factor x 100 vs x 70. Efficiency then scales it. PRUNplanner quirk: ceil() on a float 28.0000004 shows 15 per 12h51m instead of 14 per 12h; the daily rate (28) is the same.

## Production time
- Recipe time in a building = time_ms x repeats / efficiency (efficiency shortens time). Batches/day = 24h x buildings / sum(times) (`usePlanCalculation.ts`, `buildingCalculations.ts`).

## Habitation (`habOptimization.ts`)
- Areas: HB1 10, HB2 12, HB3 14, HB4 16, HB5 18, HBB 14, HBC 17, HBM 20, HBL 22.
- Combined habs (75 + 75): HBB pioneer+settler, HBC settler+technician, HBM technician+engineer, HBL engineer+scientist.
- Optimizer is an LP (min cost, else min area if it does not fit). Reimplement in `puga/econ.py`.

## Conflicts with the old handoff (resolved in favour of PRUNplanner)
1. A common assumption is that the Antares faction gives a Metallurgy bonus. PRUNplanner: the Antares faction bonus is electronics only; metallurgy is Moria. A Metallurgy benefit on an Antares base comes from the COGC x1.25, not a faction bonus.
2. COGC ~25% was once treated as unverified; PRUNplanner models it as x1.25 efficiency for matching expertise (confirmed against live FIO efficiency, see below).
3. Consequence: HWP is a Metallurgy building, so on a base with an active Metallurgy COGC, with both luxuries supplied, HWP at 40/50 headcount runs at about 0.8 x 1.25 = 100% before expert and HQ bonuses; do not assume 80%.
4. Fertility slope is 10/33 (about 0.30 per fertility point), not 1.0.

## Base recipe times (FIO, confirmed in APEX)
- SME AL: non-flux 12h0m (6 ALO + C + O -> 3 AL), flux 14h24m (6 ALO + FLX + C + O -> 4 AL). Actual times = base / efficiency; use the efficiency model, not old hand measurements.

## Verified against live FIO (2026-09-18)
- FIO `/production/{user}` lines carry `Efficiency` (ground truth per building type) and `Condition`. a live smelter with 2 experts: 1.3361. Model: COGC 1.25 x expert(2) 1.0696 x condition 0.99936 = 1.33614, i.e. within 0.004%. So PRUNplanner's factor stack is right in-game; add a CONDITION factor (building wear) that PRUNplanner's list omits. Extractors: 0.9993 = condition only (no COGC on resource extraction).
- Company cash lives at `/company/code/{ticker}` Balances. Permits: `/sites` InvestedPermits and MaximumPermits (the game maximum can exceed what a planner empire setting says).
- Use `tools/state.py sync` to refresh `state/company.yaml`; it needs the FIO extension to have uploaded recently.

## PRUNplanner plans always include the core module (CM)
`usePlanCalculation.ts` (calculateConstructionMaterials) hard-codes CM x1 into every plan's construction list, so Plan Cost, Area (+25) and the payback ('ROI ... d') always include a core module (~202k at universe prices), even if the base already has one. Plan Construction Cart subtracts what is already built, but the Plan Cost overview does not. Degradation is production buildings only / 180 (CM and habs excluded). For an add-on buildout, judge payback on new capex only (buildings + habs you actually need to construct), not the simulator's ROI line. `tools/simulate.py` reproduces this and prints area, cost and degradation the same way.

## Workforce arrival (VERIFIED from official sources, 2026-09-19)
Sources: Prosperous Universe dev log #239 "Enlisting Labor" (https://prosperousuniverse.com/blog/2020/06/15/enlisting-labor-239) and the APEX handbook, Planetary Populations (https://handbook.apex.prosperousuniverse.com/tutorials/legacy-tutorials/planetary-population/index.html).
- Once a week, when the population report is generated, the planetary population is distributed among all bases of the planet (evenly, only as far as each base's production lines require workers).
- A base sends a workforce request whenever a production building is constructed or demolished, or its habitation capacity changes. The request is NOT filled immediately; it is filled at the weekly distribution.
- Reserve pool: each planet keeps a reserve of workers. When you build a NEW PRODUCTION BUILDING that requires them, workers from the reserve are assigned immediately. Each player can instantly recruit only a small percentage of the pool per week. The amount available is shown in brackets next to each building's workforce requirement in the game (APEX).
- Consequences: a habitation building alone (HB2) gets nothing: capacity without a job requiring those workers requests none. The trigger is the production building. Build the housing first (capacity must exist), then the production building: the reserve tops it up at once, up to the instant allowance; the rest arrives at the next weekly report. Buildings run at efficiency = workers present / required until then.
- Report cadence seen on one planet: weekly, Wednesdays ~08:00 UTC (report #289 on 16 Sep 2026).
- The old handoff detail "bases keep 75% of workforce between reports" is not in these sources; treat as unverified.