# Factorio Production Calculator 1.0.0

A local-first calculator for **Factorio 2.1.17 + Space Age**. It uses a product-first workflow and keeps its calculation engines separate from the interface so it can later be embedded in a larger Factorio reference website.

## Launch the source locally

Install [Node.js 22.13 or newer](https://nodejs.org/), extract the source package and run:

```bash
npm ci
npm run local
```

The development server opens the calculator on the local computer. Stop it with `Ctrl+C`.

To generate the static STRATO website instead, run `npm run build:strato` and then `npm run verify:strato`. Before packaging a public hosting release, copy `release-operator.example.json` to `release-operator.json` and fill in the website operator’s public details. This local configuration is excluded from the source archive and Git. `npm run package:release` rebuilds and packages both public release archives.

## Calculator workspaces

- **Science** — supplied science packs to effective research, or desired effective research back to required packs, in `/s`, `/min` or `/h`. Input and result units are independent, and results start at the familiar `/min` view. Pack quality, lab productivity and the Biolab's 50% pack drain determine research per supplied pack; speed determines processing capacity and therefore the lab count. Manual and optimized Beacon layouts are available directly in the geometry result.
- **Production** — multiple simultaneous product targets, output or input-limited calculations, clickable ingredients, and a clickable output row that opens all products consuming that material. Selecting one replaces the current target while retaining compatible settings. A newly added product copies the active target's rate, unit and compatible machine/module/beacon/logistics setup, while its upstream chain receives the current global chain setup. Current-product chips promote a complete calculation to the top, and every result card can be collapsed independently. Machine-level logistics, default-on full upstream chains, per-sub-process route/machine/Inserter controls, selectable raw-resource mining drills, and both local and all-products chain-wide setups are included.
- **Quality** — a completely independent configuration with expected quality distributions, maximum researched quality, quality-module defaults, a safe one-beacon default, and chain-wide mining-drill/module controls. Its automatic item routes start with quality-mined ore and direct furnace/crafting recipes instead of silently detouring through molten Foundry routes.
- **Recycling** — only actual generated recycling recipes, with throughput, recycler counts, expected returns, destroyed fluid ingredients, and gapless recycler rows.
- **Quality recycling** — reverse-sizes the required input and recycler count from a chosen returned material and target-quality output, with shared one-beacon coverage, the one-module-slot default, and no fluid-producing source recipes.
- **Rocket freight** — leads with the number of Rocket silos to place, separates flight sizing from loading/silo sizing, explains payload-wave bottlenecks, and validates platform storage with quality-scaled Cargo bays. Its clean 5×5-perimeter geometry supplies every silo without detached outer beacons. Inserter and experimental local-logistic-robot loading reserve the bottom-centre beacon position and cap each silo at 15 beacons; an explicit “ignore insertion” assumption retains 16.
- **Energy** — manually entered MW or selected calculator loads; selectable Steam engines/turbines, exact planet/quality solar ratios, heating tower, nuclear, and optimized 1–4-reactor fusion blocks. Geometry shows the ideal entity ratio for the selected configuration without speculative pipe tiles; all entities remain upright and matching types are grouped in rows.
- **Help** — a multilingual quick start, complete feature reference, direct calculator navigation, example workflow, glossary, limitation notes, privacy summary and release/legal status.

## Included behavior

- 324 exposed production routes: 314 official player recipes plus 10 passive-spoilage routes.
- 282 selectable products and fluids and 846 valid route–machine combinations.
- 286 player-accessible generated recycling recipes/products; 284 are eligible for quality recycling. Hidden/editor placeholder recycling prototypes are excluded.
- Alternative product routes and only compatible production machines.
- Fluids, catalysts and returned inputs, probabilistic products, machine fuel, Nutrients, and Bioflux.
- `/s`, `/min`, and `/h`, including multiple input constraints and the Science calculator.
- Normal through Legendary machines, ingredients, modules, beacons, inserters, and science packs.
- Automatic and manual per-slot modules with Factorio restrictions and specialized-machine base productivity.
- Separate Normal and Quality state; switching workspaces never overwrites the other setup.
- Physical beacon placement with two logistics tiles above and below production machines, flush machines and side beacons, shared coverage, per-machine effect counts, and zoomable layouts. Rocket silos uniquely reserve no exterior logistics corridor.
- Geometry maxima of 12 beacons for 3×3/4×4 machines and 16 for 5×5 machines and the Rocket silo.
- Per-machine item/fluid loads, prominently summarized selected-inserter counts by direction, inserter quality and capacity research, pump counts, belt-capacity warnings, and logistics power.
- Recursive production chains down to selectable Burner, Electric, or Big mining drills, Pumpjacks, Offshore pumps, agricultural towers, and asteroid collectors. Drill and mining-module choices are available in both the all-products setup and every per-product chain setup; module-slot count, extraction speed, quality chance, quality distribution, electrical demand, extraction-building totals, construction modules, and compatibility fallback update together. Every selected product includes its complete upstream chain by default, independently of whether its visual chain panel is expanded; each product can explicitly disable that inclusion. The all-products setup is available from startup and applies changed machine, mining drill, mining module, process module, beacon, quality, and Inserter defaults across every chain; later per-product and per-node changes remain local. A research-status selector restricts automatic choices to unlocked production machines, and ordered machine hierarchies independently govern assembly/electronics, smelting/metallurgy, fluids/chemistry, biology and special processing. Fine-grained recipe/machine choices remain in a separate collapsed sub-panel. The view starts at the root ingredients, adds recipe/machine and Inserter controls for every sub-process, retains per-node overrides, and exposes recalculated power per node. Canonical base recipes are selected by default, so ordinary Nauvis chains do not silently detour through faster planetary alternates; all alternative routes remain selectable. In Quality mode, Quality-module mining is the default, every upstream quality split is propagated forward as real feedstock, all solid ingredients are matched by tier, unmatched coproducts stay visible, and the root output, machine count, logistics, and power are recalculated from the resulting Normal-through-Legendary input mix. Quality mode also offers a one-beacon/one-slot chain preset; manual selection states the occupied slots per Beacon explicitly.
- The all-production overview automatically follows the most-used target time unit, places the compact raw-resource ledger above the full-width process list, and lets every major section and nested resource/process/material/construction group collapse independently. Each process contribution shows the chosen Inserter, explicit material-by-material input/output counts, per-machine In/Out counts and the complete Inserter total.
- The same overview calculates transport-belt requirements for every solid raw, intermediate, coproduct, and final-product stream. Belt tier, belt quality, and researched stack size from 1–4 are selectable. Shared materials default to separate streams per top-level product and can be combined with one switch. Every stream repeats the selected belt and quality icon and shows whole belts, overall capacity use, exact belt equivalents and final-belt utilization.
- A final construction bill sums extraction entities, production machines, machine and Beacon modules, physical Beacons and Inserters across every selected product and enabled chain, separated by quality.
- Per-product, per-chain-node, and per-source switches for inclusion in the Energy calculator.
- Energy-inclusion switches remain synchronized whether changed beside a calculation or inside the Energy workspace.
- Fusion ratios of 1 reactor/2 generators, 2/8, 3/18, and 4/28 with gross output, internal demand, net support, coolant circulation, and demand-sized block counts. One same-quality unmoduled Cryogenic plant supports one Fusion reactor, so the four-reactor block uses four plants.
- Energy previews show ideal entity ratios for the selected configuration; pipes, heat pipes and fluid-overlay tiles are intentionally omitted, every entity is upright, and matching types are grouped into rows.
- Nuclear grid dimensions visibly change reactor adjacency, heat output, Heat exchanger and selected Steam engine/turbine counts, and the displayed connected block geometry.
- Rocket freight uses official item weights, rocket capacity, space-route lengths and thruster behavior; the preloaded-arrival assumption is shown in the result. Cargo bays provide 20/26/32/38/50 inventory slots from Normal through Legendary quality.
- Rocket loading can use a chest and inserter, an experimental local Roboport model with up to 300 logistic robots plus speed/cargo research, or an explicit instantaneous/preloaded assumption. The selected physical loading modes include their estimated fill time in sustained silo sizing and draw the associated chest, inserter and Roboport.
- If the number of rockets in a preloaded cargo wave, rather than silo crafting speed, fixes the number of silos to place, the result says so explicitly.
- All editable fields use highlighted controls, custom steppers, and accelerated mouse-wheel adjustment; wheel input captures scrolling while hovered, and each workspace has its own reset.
- Production starts empty, while Normal and Quality workspaces retain fully independent product, module, and beacon state. Navigation order is Science, Production, Quality, Recycling, Quality recycling, Rocket freight, Energy, then Help.
- The current-product heading starts without a placeholder icon and follows the actively edited product once one is selected. Product scopes and recursive chain levels use distinct, restrained border accents for visual ownership.
- Independent scrolling for the settings and results columns on desktop.
- Every product search and downstream selector follows the official inventory groups, subgroup rows and prototype order. Group tabs are intentionally icon-only so every category remains visible in narrow menus; localized names remain available as tooltips and accessible labels.

## Languages

The interface and integrated Help guide support English, German, Spanish, French, Italian, Japanese, Russian, Simplified Chinese, and Traditional Chinese. Product, ingredient, recipe, quality, location, and entity names are generated from the official Factorio 2.1.17 locale files. `EMP` is intentionally the only abbreviated production-machine name.

## Data and accuracy scope

The bundled snapshot targets Factorio `2.1.17` and the Wube data commit `35b4e50206aa425d5be114373cf5ede194a98bf6`. Expected-value outputs are long-run averages; a small in-game sample can vary. Recycling uses the generated prototype for every selectable item: reversible solid ingredients return 25% on average, fluid ingredients are lost, irreversibles use their generated 25% self-return, and Quality-module rolls start from the recycled item's input quality.

The production engine does not apply infinite research bonuses unless a calculator exposes that bonus explicitly. Production-chain raw extraction rates use visible baseline source assumptions and are shown in the interface. Electricity generation is calculated separately and is not recursively added to a material production chain.

To regenerate metadata from a locally installed matching Factorio dataset, set `FACTORIO_DUMP` and `FACTORIO_DATA`, then run:

```bash
npm run generate:official-data
```

## Verification commands

```bash
npm run lint
npx tsc --noEmit
npm test
npm run build
```

## Project layout

- `app/data/` — versioned recipe, catalog, icon, and official locale data.
- `app/lib/calculator.ts` — production and quality mathematics.
- `app/lib/beacons.ts` — deterministic tile geometry and layouts.
- `app/lib/production-chain.ts` — recursive upstream-chain solver.
- `app/lib/logistics.ts` — inserter, pump, and per-machine load logic.
- `app/lib/belts.ts` — transport-belt capacity and whole-belt sizing.
- `app/lib/science.ts`, `energy.ts`, `recycling.ts`, `rocket-freight.ts` — dedicated calculator engines.
- `app/components/` — browser UI and reusable workspaces.
- `public/factorio-icons/` — bundled local game-symbol mirror.
- `tests/` — catalog-wide and numerical regression checks.
- `REQUIREMENTS.md` — versioned product decisions and requested behavior.

## Website operation

No application database is required. Every visitor performs calculations locally in their own browser, so concurrent traffic does not share calculator CPU. The Vinext/Vite application can be deployed through Sites or another compatible web host. A custom domain is optional; the host-provided address works without buying one. A future blueprint library, accounts, or saved factory projects would require a separate persistence and privacy design. Expensive geometry results are bounded and cached, unopened workspaces are not mounted, visited hidden workspaces are memoized, and redundant energy-state updates are suppressed.

The included STRATO build is a static public website for `https://factoriocalculatorapp.com`. The root redirects to the explicitly addressed English version at `/en/`; German, Spanish, French, Italian, Japanese, Russian, Simplified Chinese and Traditional Chinese use `/de/`, `/es-ES/`, `/fr/`, `/it/`, `/ja/`, `/ru/`, `/zh-CN/` and `/zh-TW/`. Every locale page has its own canonical URL and reciprocal `hreflang` links. The separate Sites manifest remains excluded from public source packages and keeps the existing preview independent of the public deployment.

The release footer is visible beneath every calculator workspace. Privacy, legal, GPL-3.0 and third-party notices open as styled website pages; plain-text license copies remain downloadable for redistribution. For a privacy-conscious GitHub publication workflow, see `GITHUB_PUBLISHING.md`.

## Project contact

Public contact: `factoriocalculatorapp.com@gmail.com`. No individual author name is published with release 1.0.0.

## Asset notice

This is an unofficial fan-made calculator and is not affiliated with or endorsed by Wube Software Ltd. Factorio and related game assets are property of Wube Software Ltd. and are used with permission for this free calculator. The bundled icon mirror is sourced through the community `icons-factorio` project. See `LICENSE`, `THIRD_PARTY_NOTICES.md`, `LEGAL.md`, `PRIVACY.md`, `SECURITY.md`, and `RELEASE_CHECKLIST.md` before redistribution or deployment.

## Blueprint export and expanded Help

The public website and Windows app now include the same Blueprint generator. Each generator exports one product or its own enabled production chain. It supports horizontal/vertical transport, full-reach Substations, fixed Roboports, facing-edge alignment and optional grid snapping. The preview uses existing icons and original symbols. Try exported strings in Factorio and review the displayed connection warnings. See `BLUEPRINT_GENERATOR.md`.

Help contains 17 topics in all nine languages, with panel controls, result explanations, practical examples and a dedicated generator walkthrough. It explains target-rate units, machine utilization, chain overrides, logistics, power and blueprint importing.
