# Factorio Mod — Deterministic Quality System (design notes)

> Personal project (Mike). Status: **DESIGN / pre-build.** Not started building.
> Companion: `factorio-mod-anatomy.md` (how a 2.0 mod is structured).
> Resume by reading both files. Next concrete step = the feasibility check (bottom).

## Concept (the pitch)
Replace Factorio 2.0's **RNG quality** with a **deterministic, cost-based** one. Vanilla
raises quality by chance (quality modules roll a %-chance for a better output; recycler
upcycling loops the same gamble). Mike doesn't like the dice. Instead: raise quality by
**spending more resources** through a dedicated machine — guaranteed, no chance.

## Locked decisions (2026-06-23)
- **Full replacement.** Remove the chance element entirely; the new machine is the ONLY way up.
- **Keep vanilla quality tiers + their perks UNTOUCHED.** Normal → Uncommon → Rare → Epic →
  Legendary, with vanilla's stat bonuses (Legendary machine faster, Legendary module stronger,
  etc.). Those bonuses live in vanilla's `quality` prototypes + the engine, so the design is to
  **leave the quality prototypes alone** and only change *how a tier is obtained*. Perks inherited free.
- **The Refinery machine** runs deterministic per-tier-step recipes:
  `N × (item @ tier K) → 1 × (item @ tier K+1) [+ byproduct]`. (Mike's example: copper plates →
  a better copper plate via a "modified recycler/refiner.")
- **Cost = escalating + compounding resource expense** (no RNG). Mike's curve: "tier 2 is 3×,
  tier 3 is 4× that, and so on" → per-step ratios **3 / 4 / 5 / 6**:

  | Step | Per-step ratio | Total Normal-equivalents |
  |---|---|---|
  | Normal → Uncommon | 3× | 3 |
  | Uncommon → Rare | 4× | 12 |
  | Rare → Epic | 5× | 60 |
  | Epic → Legendary | 6× | 360 |

  Exact numbers TBD; ratios to be **startup settings** for tuning.

## Open decisions (to settle next)
- **Quality modules:** remove entirely (cleanest) vs leave inert (exist, do nothing — less likely
  to break other mods). Either way their RNG bonus is neutralized (which also kills recycler
  upcycling, same mechanic). — UNDECIDED.
- **Byproduct (slag):** keep a light byproduct you must reprocess/void (adds factory friction;
  Mike liked this earlier) vs pure-cost (input ratio is the whole balance). Lean: **keep light,
  settings-dialable to zero.** — UNDECIDED.
- **Exact cost numbers** — TBD (curve shape agreed, magnitudes not).
- **Item scope** — auto-generate refine recipes for all quality-eligible items (intermediates +
  machines + modules + equipment), gate categories via settings. Start curated (plates/gears/
  circuits) then expand? — lean auto-gen, gated.
- **Refinery details** — one generic machine vs tiered/category machines; does the Refinery's OWN
  quality speed it up (nice recursive incentive)? — UNDECIDED.
- **Extra cost dimensions** — energy/time scaling per tier, or a catalyst/reagent (a "flux" item or
  fluid) for a second supply chain. Deferred (adds depth + complexity).

## Implementation approach (sketch)
- **Data-stage recipe generation:** loop over `data.raw` quality-eligible items and emit
  `refine_<item>_<K>_to_<K+1>` recipes automatically → scales to modded items, no hand-writing.
- **New prototypes:** a `Refinery` entity (could reuse the recycler model/graphics); if byproduct
  kept, a `slag` item + a disposal/reprocess recipe (slag → small base material at energy cost).
- **Neutralize RNG:** zero out (or remove) quality-module quality bonus; audit + neutralize any
  other vanilla/Space-Age quality sources (asteroid crushing / mining quality) so nothing rolls a
  random tier.
- **Dependencies:** requires `quality`; `space-age` optional (handle its extra quality sources).

## FOUNDATION TO VERIFY FIRST (load-bearing — do before building)
1. **Can a 2.0 recipe deterministically output a HIGHER quality than its ingredients?** i.e. a
   recipe with explicit `quality` on ingredients (Normal) and on results (Uncommon), with NO RNG.
   Believed yes (recipe prototype supports per-ingredient/per-result `quality`) — must confirm
   against lua-api.factorio.com prototype docs.
2. **Cleanest way to neutralize quality-module RNG** (and thus recycler upcycling), and the full
   list of vanilla/Space-Age quality sources to disable.

Run via Grok (`ask-grok.sh`); Gemini CLI auth is currently broken on GURU-5070 (see errorlog —
needs interactive `gemini` re-login).

## Tooling / references
- API docs: `lua-api.factorio.com` — **prototype docs (data stage) are separate from runtime docs.**
- VS Code + **FMTK** (Factorio Modding Tool Kit) extension for prototype + runtime autocomplete.
- Wiki tutorial: `wiki.factorio.com/Tutorial:Modding`. Portal: `mods.factorio.com`.