PuGa/docs/mechanics.md

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: Deimos ALO factor 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). The old handoff 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. Handoff says "Antares Metallurgy bonus applies" on Deimos. PRUNplanner: Antares faction bonus is electronics only; metallurgy is Moria. The Deimos benefit is the COGC x1.25, not a faction bonus. Verify in-game via PROD batch time.
2. Handoff treats COGC ~25% as unverified; PRUNplanner models it as x1.25 efficiency for matching expertise.
3. Impact on BHP thesis: HWP is Metallurgy and Deimos runs an active Metallurgy COGC, so with both luxuries supplied SME/HWP run at about 125% workforce-weighted; HWP at 40/50 headcount is about 0.8 x 1.25 = 100% before expert and HQ. The handoff's 80% output figure ignores COGC.
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. Deimos smelters: 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 (AIC 21,950 on 2026-09-18). Permits: /sites InvestedPermits 1, MaximumPermits 3 (not 2).
• Use tools/state.py sync to refresh state/company.yaml; it needs the FIO extension to have uploaded recently.