# 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: how and when do new workers appear? UNVERIFIED
- Claim carried from an old handoff: workers are distributed weekly at the population report (POPR), a reserve pool fills immediately if available, bases keep 75% of workforce between reports. Nothing in PRUNplanner's code, FIO or the APEX POPR screen confirms or refutes it; earlier answers repeated it too confidently.
- Verified facts: reports are WEEKLY (POPR chart points 7 days apart; #289 was Wed 16 Sep ~08:00Z, so next ~Wed 23 Sep ~08:00Z). FIO `/workforce/{user}/{planet}` gives per-tier Population, Reserve, Capacity, Required, Satisfaction, but no report time (LastWorkforceUpdateTime null).
- One base's data is consistent with both readings: the last HB1 + SME finished Wed 16 Sep 07:00Z, about an hour before report #289, and 370 pioneers are present now.
- TEST: build the HB2 (needed anyway) and poll FIO `/workforce/{user}/{planet}` (SETTLER Population/Reserve/Capacity). If settler Population rises well before Wed 23 Sep, workers arrive continuously and the report timing does not matter. Record the result here.