claudetools/projects/factorio-quality-mod/DESIGN.md

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.