# Factorio Production Calculator — v1.0.0 specification

This file is the durable project contract for the Factorio 2.1.17 + Space Age calculator.

## Shared rules

- The downloadable local release includes its verified production build and starts without `npm ci` or native package installation.
- Static browser application; calculation engine remains reusable and independent from the UI.
- Factorio 2.1.17 Space Age prototype values, normal through legendary quality.
- Official in-game names and icons. Supported locales: English, German, Spanish, French, Italian, Japanese, Russian, Simplified Chinese and Traditional Chinese.
- The language selector renders every language name in the currently active language.
- Only `EMP` may be abbreviated. Other machine names are written out.
- Product selection is product-first and grouped like the in-game inventory: Logistics, Production, Intermediate products, Space and Combat, plus Fluids. Every search uses the same icon tabs, official subgroup rows and prototype ordering.
- Items and fluids are valid targets. Alternative recipe routes and machines are selectable.
- The footer hint is intentionally absent so the desktop workspace fits without a second page scrollbar.
- Product and recursive-chain scopes use distinct border accents, and the current-product heading has no placeholder icon before selection.
- The integrated Help workspace is the final top-level tab and is available in every supported interface language.

## Production and quality production

- Output-target and input-limited directions with `/s`, `/min` and `/h`.
- Multiple simultaneous product cards with Add product.
- Every result card on the right can be collapsed independently without removing its calculation, production chain or contribution to global totals.
- Normal Production and Quality Production preserve fully separate state, including modules and beacons.
- Automatic module priority is productivity > speed > quality > efficiency. Normal mode also permits Quality modules and shows the resulting expected quality split whenever they are actually installed.
- Quality mode automatically uses the highest selected quality module and reports the expected quality distribution up to a selected research cap.
- Normal Production has no target-quality selector; it always sizes total production. Manual or automatic Quality modules still produce a full expected quality distribution.
- Ingredients remain clickable calculation targets. The calculated output row itself is also clickable and opens a grouped downstream-product menu containing products whose recipes consume it (for example, Iron gear wheel → Automation science pack); choosing one replaces the current target rather than adding one. Route-independent settings are retained and an invalid beacon count is clamped to the next valid value.
- Biochambers consume nutrients and Captive biter spawners consume bioflux as operating fuel; these appear in all relevant balances and chains.
- Passive spoilage is available as a route, including iron/copper bacteria to ore.
- Per-machine logistics calculates item/fluid load, inserters by quality/research/handoff, pumps and 240 item/s stacked-turbo-belt warnings.
- The Product & route section intentionally has no decorative icon. Once selected, the active product icon is used in the current-product heading.

## Science

- Input and output units are independently selectable as `/s`, `/min` or `/h`.
- The output unit always initializes to `/min`, regardless of the selected input unit.

## Production chains

- Expandable upstream chain to raw sources, miners, pumpjacks and offshore pumps. Power generation is deliberately outside the chain.
- Each node has route/machine, module/beacon and Inserter/logistics sub-tabs plus an energy-inclusion checkbox.
- The chain begins with the root product's ingredients rather than repeating the already selected root product.
- A local chain-wide master panel sets preferred machine, raw-resource mining drill, machine quality, prioritized module families, beacon configuration and Inserter type/quality/capacity/handoff. It also creates recipe/machine selectors for every upstream sub-process with multiple valid routes or machines. Per-node overrides take precedence. If Productivity is invalid, the resolver falls through to Speed, Quality and Efficiency in that order.
- The all-products chain-wide panel is visible from startup. Every selected product's complete upstream chain is generated and included in aggregate totals by default, even when its visual chain panel is collapsed. Each product has a separate inclusion switch that can explicitly fall back to direct ingredients only. Global changes, including the selected mining drill, overwrite the corresponding master and node setting in every product chain; later per-product master or per-node changes remain local. Newly added products inherit the current global setup.
- A new target also copies the active target's rate, time unit and compatible main-machine, module, Beacon, quality and Inserter settings. Global changes update all corresponding chain nodes and the same main-target setting, so subsequently added products inherit the latest global baseline plus any deliberate adjustment on the active target.
- The global setup contains research-status toggles for production machines. Automatic selection may only use enabled machines and chooses the highest-priority compatible machine within separate assembly/electronics, smelting/metallurgy, fluid/chemistry, biology and special-processing hierarchies. The existing per-product recipe/machine overrides remain available in a separate, collapsed fine-tuning panel.
- In Quality Production, the chain is solved bottom-up for its expected quality profiles and then sized top-down against the consuming recipes. Every solid ingredient quality generated upstream becomes real feedstock for its consumer and ultimately for the selected root product. The root ingredient rows, quality output, machine count, logistics and power recalculate from that mixed feedstock; unmatched higher-quality coproducts remain visible at their producing nodes.
- Quality chains offer a chain-wide and per-node quality-safe beacon mode: at most one active beacon with one occupied beacon-module slot. Standard beacon configuration remains selectable.
- Every recipe node shows its recalculated electrical load, and the chain total passed to Energy excludes the root setup to prevent double counting.
- Default routes prefer each product's canonical base recipe, with explicit canonical choices for oil fractions and other products without a same-name recipe. This prevents ordinary Nauvis chains such as Chemical science packs from silently selecting Gleba routes. Alternative routes and machines remain selectable at every node.
- Product and whole-chain energy are independently selectable inputs to the Energy calculator.

## Beacon geometry

- Real entity footprints, 3×3 beacons and 9×9 supply area. Two clear logistics tiles are reserved above and below production machines; machines and left/right beacons may be flush. Rocket silos are the sole exception and reserve no exterior logistics corridor.
- Single-machine physical maxima: 12 beacons for 3×3/4×4 machines and 16 for 5×5 machines and Rocket silos.
- Multi-machine preview places all required machines and efficient shared beacons, showing the effect count on each machine.
- Zoomable preview.
- Biolabs offer an optimized or manual mode. Optimized mode forms one continuous row of 5×5 Biolabs with two free tiles on every side. Adjacent labs share the single five-beacon column between them, and every Biolab receives the physical maximum of 16 beacon effects; beacons may also be switched off.
- Recycler rows have no gaps. Quality recycling may share beacons, but every recycler must receive exactly one beacon effect in its default configuration.

## Science

- Lab/Biolab calculator in both directions: supplied science packs to effective research and desired effective research back to the required supplied packs, selectable in `/s`, `/min` or `/h`.
- Lab quality, pack quality, speed/productivity modules and speed/efficiency beacons.
- Pack quality, lab productivity and the Biolab's 50% pack drain change effective research per supplied pack. Speed modules, beacons and lab quality change processing capacity and therefore the required lab count; they do not multiply the research value of a fixed incoming pack stream.
- Biolab built-in 50% science pack drain and optional optimized shared 16-effect layout.

## Energy

- Manual MW input or selected production/chain loads.
- Steam, solar/accumulators, heating tower, nuclear and fusion.
- Nuclear uses a real rectangular cardinal-neighbour bonus.
- Nuclear width and height define the repeated reactor grid and visibly change reactor count, cardinal neighbour links, output and geometry.
- Every energy route exposes the ideal entity ratio for the currently selected planet, quality, generator and block size; calculation totals may scale independently. Offshore pumps, pipes, heat pipes and other connection tiles remain in totals/explanations but are omitted from drawings. All buildings are drawn upright and matching types are grouped in rows.
- Boiler, nuclear and heating-tower routes allow Steam engines or Steam turbines wherever the fluid temperature permits; the 500 °C-to-165 °C loss is explicit when Steam engines are chosen.
- Solar and accumulator counts use the official planet-, day-cycle- and quality-specific ratios, including Vulcanus' accumulator charge-rate limitation.
- Fusion provides accepted 1–4-reactor blocks: 1→2 generators/100 MW, 2→8/400 MW, 3→18/900 MW and 4→28/1400 MW gross at normal quality.
- Fusion supports demand sizing and a fixed-block view, including generators, cryogenic plants, internal demand, net output, coolant and fuel-cell rate. With equal-quality unmoduled buildings, cooling speed and reactor coolant flow scale together, so one Cryogenic plant supports one Fusion reactor; a four-reactor block therefore contains four plants.
- Three- and four-reactor fusion previews retain the fixed reactor/generator/Cryogenic-plant ratio and generator orientation without attempting to draw fluid or heat-pipe tiles.

## Recycling

- Normal Recycling and Quality Recycling are separate top-level modes.
- Multiple simultaneous recycling targets.
- Only player-accessible generated recycling recipes are selectable. Hidden/editor placeholder recycling prototypes and products without a public catalog item/icon are excluded. Every selectable route's expected solid returns, 75% average solid loss, complete fluid-ingredient loss, generated irreversible-item return, probability fields and recycling time are read from the official prototype snapshot.
- Quality Recycling excludes routes whose selected source recipe produces fluid, supports target/input/max quality, expected output distribution and defaults to one beacon with exactly one occupied beacon module slot. Its amount field is desired target-quality output; the engine solves the necessary recycled input and recycler count backwards from that value.

## Rocket freight

- Select a launchable item, origin, destination, sustained delivery rate and cargo amount per platform transit.
- Cargo capacity follows official item weight and rocket inventory limits. Fluids are excluded.
- A platform starts with 59 hub slots. Cargo bay quality is selectable and contributes 20/26/32/38/50 slots from Normal through Legendary quality. If the requested batch exceeds that storage, the effective per-platform batch is capped and a warning shows the resulting capacity, quality-aware required Cargo bays and extra freight-platform pressure.
- Silo quality, rocket-part productivity research, machine modules, beacon modules and beacon geometry affect the required sustained and preloaded silo counts.
- Results include rocket-part ingredients, rocket cycle/loading time, landing-pad hatch waves, one-way and round-trip time, launches per transit and freight platforms required.
- Platform speed can be entered directly or derived from thruster count, quality, fluid level, platform width and mass using the official behavior. The compact-width helper remains optional and editable.
- Optimal loading explicitly assumes the necessary rockets are completed and preloaded before the freight platform arrives.
- The primary Rocket Freight result is the whole number of Rocket silos to place, and its geometry updates to that count.
- Flight/platform sizing and rocket-loading/silo sizing are presented separately and recombined into one result. If one preloaded silo per cargo rocket dominates the placement count, a visually distinct notice compares batch rockets with the smaller sustained-throughput requirement and explains exactly when speed upgrades can reduce the build count.
- Multiple Rocket silos use one compact, clean-ended block: adjacent silos share the complete boundary beacon column, no detached beacon remains beyond either horizontal end, and every silo retains the requested effect count.
- Inserter loading allows inserter type, quality and capacity research. It displays a full Buffer chest and inserter below each silo, reserves the bottom-centre beacon position, clamps the maximum to 15 and adds a conservative serial payload-fill time to sustained silo throughput.
- Experimental logistic-robot loading uses the same chest and inserter plus one centered local Roboport per silo. The user selects 1–300 robots per Roboport and worker-robot speed/cargo research. Fill time is the slower of chest-to-silo insertion and the displayed 4.5-tile local robot leg; the chest starts full, while remote provider distance, congestion and charging queues are explicitly outside the model. The mode is limited to 15 beacons.
- “Ignore insertion” assumes instant or already completed payload loading, excludes chest/inserter/robot time and power, displays a warning, and retains all 16 silo beacons.

## Interaction and state

- Production opens with no product selected. Add product is the only operation that creates another simultaneous target.
- Top-level navigation order is Science, Production, Quality, Recycling, Quality Recycling, Rocket Freight, Energy and Help; Production remains the initial workspace.
- Every top-level calculator has an independent reset and Normal/Quality production state is fully isolated.
- Energy-inclusion switches are synchronized between their source calculator and the Energy workspace, survive subsequent rate/settings edits, and reset only with their owning calculator.
- Product cards and their five numbered configuration sections are collapsible; Modules and Beacons are sections 04 and 05 and start collapsed.
- Clicking a chip in Current products promotes that complete product configuration to the first position in both columns, including its result and expanded production chain.
- Production and Quality end with an all-production summary. It automatically adopts the most-used `/s`, `/min` or `/h` unit among the selected products (with the first product breaking a tie), while retaining a manual display override until the product-unit mix changes. It places merged raw-resource demand above the full-width processed-machine ledger, keeps per-chain contributions visible, and groups identical configured production sub-processes while showing the whole-machine count assigned to each chain. Beneath every machine contribution it shows the selected Inserter type/quality, explicit input/output item icons and counts, per-machine In/Out counts and the summed Inserter build count.
- The all-production summary also sizes transport belts for every solid raw, intermediate, coproduct and final-product stream. Users select Transport/Fast/Express/Turbo belt, belt quality and researched stack size 1–4. Throughput is 15/30/45/60 items/s times stack size; belt entity quality is selectable but correctly does not alter transport speed. The display includes exact belt equivalents, whole belts required and final-belt utilization.
- Shared material streams are separated per selected top-level product by default. Users may disable that behavior to size one combined stream for the material instead.
- Every belt stream repeats the selected belt/quality icon and shows whole belts, exact belt equivalents, total installed-capacity utilization and the last belt's utilization inside visually distinct material scopes.
- Combined resource demand, production processes, Belt throughput and the final construction bill are independently collapsible. Their resource, process, material-stream and construction-kind groups are collapsible as well.
- A final construction bill totals every extraction/supply entity, production machine, machine and Beacon module, physical Beacon and Inserter required by all selected products and enabled chains, retaining each item's quality.
- Machine logistics highlights the total number of the selected Inserter required in each direction, while every material row retains its per-machine and complete-build Inserter counts.
- Editable controls are visually outlined. Number fields use custom buttons and capture the mouse wheel while hovered, so neither page nor column scroll moves; adjustment accelerates while the wheel continues in one direction and resets after a pause.
- Settings and results scroll independently on desktop. Geometry previews support zoom and preserve readable per-machine beacon-effect badges.
- Direct workspace-header cards have a fixed minimum height and never shrink when a long Energy or Rocket Freight result becomes scrollable.
- Target-rate controls use a persistent amber outline and accent in Production, Quality Production, Science, Recycling, Quality Recycling and Rocket Freight.
- Quality output is displayed as separate, color-coded product tiles with the corresponding quality symbol and value. Normal is isolated at left; Uncommon/Rare and Epic/Legendary form aligned pairs at right.
- Product selectors and downstream navigation in Production, Quality, Recycling, Quality Recycling and Rocket Freight use the same official inventory-group and subgroup tabs as the game. Inventory-group tabs display only their official icons so all tabs remain visible; localized labels remain available to assistive technology and as tooltips.

## Integrated Help

- The Help workspace contains a six-step quick start, direct navigation to every calculator, a table of contents and accessible full-header disclosure panels.
- Its reference covers calculator selection, `/s` `/min` `/h`, products/recipes/machines, every calculator, the full production chain, global/local chain-wide settings, modules/priorities/quality/Beacons, Inserters/belts/throughput, totals, the construction bill, geometry, warnings, a worked example, FAQ, limitations and glossary terms.
- Version, authorship, unofficial-project attribution, privacy behavior and the blockers that must be completed before public access are visible inside the interface.
- Help content is translated into English, German, Spanish, French, Italian, Japanese, Russian, Simplified Chinese and Traditional Chinese.

## Performance

- Geometry layouts use a bounded cache and reuse identical results; large counts extrapolate from a tested exact sample and cap preview entities while totals remain exact.
- Hidden top-level workspaces are memoized and parent energy synchronization ignores equivalent updates, preventing the progressive render loop that previously caused slowdown.
- The deliverable is static and calculation-only: each visitor uses their own browser CPU, so concurrent website traffic affects CDN bandwidth rather than sharing one calculator process.
