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: 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.

Gateway (GTW) jump transit time (measured 2026-10-09)

Sources: our own live APEX Ship Flight Control DOM reads (empire/data/shipping_calibration/{hrt,ben}.json) and the official handbook (handbook.apex.prosperousuniverse.com/wiki/infrastructure-gateway). The PrUn forum thread "Gateway Question Roundup" (Oct 2024) quotes a dev (molp) saying the team was "considering a fixed transit time, independent of the link length" during pre-launch design.

• Our measured GTW segment durations contradict that design intent, if it shipped as described: 17 parsecs -> 5h41m and 5h43m; 15 parsecs -> 5h1m and 5h3m; 10 parsecs -> 3h18m. All five data points land within 19.8-20.2 minutes per parsec - a tight linear fit, not a fixed duration.
• Treat GTW transit time as scaling ~linearly with the link's parsec distance (~20 min/parsec) until a wider sample says otherwise (n=3 distinct distances, 2 routes, not independently varied against other factors). The forum statement is 2024 pre-launch discussion, not a current source - our own measurement wins per this project's source-of-truth order.
• No fuel or time model for GTW duration exists yet in puga/shipping.py (fuel-only); this is a documented fact for whoever builds that next, not wired into any tool.
• Per the handbook: LOCK fees have no public formula (gateway-operator-set, displayed in SFC); some gateway links are one-way; each gateway has its own max per-jump cargo volume (m3), separate from ship hold size - none of these are modelled anywhere in this project yet.

Placing CX orders at a remote exchange with no base/warehouse there (confirmed 2026-10-10)

Player confirms: placing a BUY order at a remote exchange (tested: NC2, Hubur Station) works with no local base, storage, or warehouse rental there beforehand - the "Storage Location: Warehouse" option in the Place Order panel is usable by default, not something you need to build/rent first. Still UNCONFIRMED: whether holding the resulting inventory there afterward incurs any ongoing storage fee - this only confirms placing the order doesn't require a prerequisite warehouse, not that storage itself is free. Also still unconfirmed: FX conversion fee size (a forum thread titled "remove FX transaction fee entirely" implies one exists, but no amount confirmed).

Planet environment-extra materials (per community handbook, confirmed live against Nike)

FIO's /planet/full/{id} -> BuildRequirements lists a superset across hazard types and is NOT a direct per-building material list - compute it instead from the planet's own Pressure/Gravity/ Temperature/Surface fields against these threshold rules (source: Prosperous Universe Handbook, building-costs page):

condition	extra material	quantity
rocky	MCG	area x 4
gaseous	AEF	area / 3
pressure < 0.25 atm	SEA	area x 1
pressure > 2.0 atm	HSE	1/building
gravity < 0.25g	MGC	1/building
gravity > 2.5g	BL	1/building
temp < -25C	INS	area x 10
temp > 75C	TSH	1/building

Applies per building (construction AND repair), area-scaled rows use the building's own AreaCost. Implemented in puga/planet.py::environment_extras(), used by tools/buildcost.py and wired into whatif.py/buy.py/scan.py's own capex numbers.

CX order cancellation penalty (UNCONFIRMED numbers, forum-sourced)

Deleting too many unfilled/partially-filled CX orders on the same ticker within a day triggers a fee (added per dev patch notes to deter bot-style requoting); a warning appears around the 4th attempt. No confirmed threshold or fee formula - forum reports range from 3 to 5-6 cancels/ticker/ day, fee said to scale with order size. Effect: rate-limits requoting, so effective spreads widen and top-of-book gets sticky/stale - chasing the top spot is still possible within the free cancel budget (~3-5/ticker/day per forum reports), just be aware each reprice spends one of those before the fee kicks in.

HQ in game vs PRUNplanner's "HQ" flag (observed 2026-09-21)

• The HQ screen (level 1, base permits 1 / 2) shows "Efficiency gains: Electronics 20.0%", and 23.3% for the next level (permits 1 / 3). That is exactly the faction bonus formula (Antares electronics 5% x 2 x (3 - 2 x used/total)), so the HQ display is the faction bonus.
• PRUNplanner's plan flag "HQ" (x1.1 on every building) is NOT visible in live efficiencies (smelters 1.3361, HWP 1.0696 both match the model without it). Keep it off. The HQ upgrade adds a base permit and raises the faction bonus.
• FIO /sites MaximumPermits (3) disagreed with the HQ screen (2). The HQ screen wins; tools/state.py supports permits_total_override.