From 30841fbfb19597802d673ab9235014a73ee052e7 Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Tue, 23 Jun 2026 20:25:46 -0700 Subject: [PATCH] sync: auto-sync from GURU-5070 at 2026-06-23 20:23:47 Author: Mike Swanson Machine: GURU-5070 Timestamp: 2026-06-23 20:23:47 --- errorlog.md | 4 + projects/factorio-quality-mod/DESIGN.md | 74 ++++++++++++++++++ .../factorio-mod-anatomy.md | 77 +++++++++++++++++++ 3 files changed, 155 insertions(+) create mode 100644 projects/factorio-quality-mod/DESIGN.md create mode 100644 projects/factorio-quality-mod/factorio-mod-anatomy.md diff --git a/errorlog.md b/errorlog.md index 98d2f002..6f7be373 100644 --- a/errorlog.md +++ b/errorlog.md @@ -17,6 +17,10 @@ Categories (the `[type]` tag): _(none)_ = skill/command execution failure · +2026-06-24 | GURU-5070 | agy/ask-gemini | gemini CLI auth/setup failure (throwIneligibleOrProjectIdError, _doSetupUser) - empty response after 3 attempts; needs interactive 'gemini' re-login [ctx: task=factorio-research] + +2026-06-24 | GURU-5070 | agy | gemini returned no response (empty after 3 attempts) [ctx: mode=search err= at process.processTicksAndRejections (node:internal/process/task_queues:104:] + 2026-06-23 | Howard-Home | unifi-wifi/gw-sitemanager | Site Manager API call failed (HTTP 403) [ctx: path=/v1/connector/consoles/1C6A1B1BC2470000000008B8D1B50000000009302B160000000067A67E3A:1341833834/proxy/network/integration/v1/sites] 2026-06-23 | Howard-Home | unifi-wifi/gw-sitemanager | Site Manager API call failed (HTTP 403) [ctx: path=/v1/connector/consoles/1C6A1B1BC2470000000008B8D1B50000000009302B160000000067A67E3A:1341833834/proxy/network/self/sites] diff --git a/projects/factorio-quality-mod/DESIGN.md b/projects/factorio-quality-mod/DESIGN.md new file mode 100644 index 00000000..75cb385c --- /dev/null +++ b/projects/factorio-quality-mod/DESIGN.md @@ -0,0 +1,74 @@ +# 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___to_` 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`. diff --git a/projects/factorio-quality-mod/factorio-mod-anatomy.md b/projects/factorio-quality-mod/factorio-mod-anatomy.md new file mode 100644 index 00000000..c0a4530c --- /dev/null +++ b/projects/factorio-quality-mod/factorio-mod-anatomy.md @@ -0,0 +1,77 @@ +# Anatomy of a Factorio mod (2.0 / Space Age) — reference + +> Research (Grok 4.3 live web, 2026-06-23) cross-checked against Claude's knowledge. For the +> deterministic-quality mod project — see `DESIGN.md`. + +## 1. Package +- Mod = folder or zip. **Distribution zip:** `modname_1.2.3.zip` containing one top folder + `modname_1.2.3/`. **Dev:** an unzipped folder (can be named just `modname`) in the mods dir. +- Mods dir: Windows `%APPDATA%\Factorio\mods`, Linux `~/.factorio/mods`, macOS + `~/Library/Application Support/factorio/mods`. `mod-list.json` tracks enabled mods. +- Folder/zip name must agree with `name` + `version` in `info.json`. + +## 2. `info.json` (mod root) +- **Required:** `name`, `version`, `title`, `author`. **Always set** `factorio_version` ("2.0"). +- `dependencies` prefixes: *(none)* = required · `!` incompatible · `?` optional · `(?)` hidden + optional · `~` required but does NOT affect load order. Version ops `>= <= = < >`. `base` is + auto-depended unless overridden. + +## 3. Load stages (strict phases, across all mods at once, dependency-ordered) +| Stage | Files (in order) | Purpose | Game access? | +|---|---|---|---| +| **Settings** | `settings.lua` → `settings-updates.lua` → `settings-final-fixes.lua` | Define mod settings; 3 types: `startup`, `runtime-global`, `runtime-per-user` | No | +| **Data (prototypes)** | `data.lua` → `data-updates.lua` → `data-final-fixes.lua` | Build prototypes into global `data.raw` via `data:extend{...}` (items/entities/recipes/tech/…). Build-once, frozen. Can read other mods' prototypes + `settings.startup`. | **No** (no game/state) | +| **Control (runtime)** | `control.lua` (+ `require`d files) | Only stage that runs in a loaded save. Event-driven scripting. | **Yes** | + +**Control essentials:** +```lua +script.on_init(fn) -- once, new save / mod added +script.on_load(fn) -- every load; MUST NOT write storage +script.on_configuration_changed(fn)-- mod/version/prototype change → migrations +script.on_event(defines.events.on_tick, fn) +``` +- **`storage`** = persistent per-mod saved table. **(Was `global` in 1.1 — renamed in 2.0.)** +- Also `remote` (inter-mod), `commands` (custom `/cmds`), `game`, `defines`. +- Data stage CANNOT touch runtime; control stage CANNOT define prototypes. + +## 4. Other standard files +- `locale//*.cfg` — INI with `[category]` sections (`[item-name]`, `[entity-name]`, + `[recipe-name]`, `[mod-setting-name]`, …). +- `graphics/`, `sounds/` — assets. +- `migrations/` — `*.lua` run as control code on loading an older save; `*.json` for prototype renames. +- `changelog.txt` — strict format: 99-hyphen separators, `Version:` / `Date:` headers, 2-space + category headers (`Bugfixes:`), 4-space `- ` entries. +- `thumbnail.png` — mod portal (~144px+). + +## 5. Asset paths +`"__modname__/graphics/x.png"`. Specials: `__base__` (base game assets/prototypes), `__core__` (engine). + +## 6. Settings access from control.lua +`settings.startup["k"].value` · `settings.global["k"].value` · +`settings.get_player_settings(player)["k"].value`. + +## 7. Tooling +- `lua-api.factorio.com` — versioned; **prototype docs (data) vs runtime API docs are separate**. +- VS Code + **FMTK** (Factorio Modding Tool Kit) + sumneko Lua → autocomplete/diagnostics. +- Wiki `Tutorial:Modding`; portal `mods.factorio.com`. Debug: `log()`, `serpent.block()`, F4 menu, + `--instrument-mod`, `/c` console. + +## 8. 2.0 vs 1.1 must-knows +- `global` → **`storage`**. +- **Quality / Space Age / Elevated Rails are separate mods** — depend on `quality` / `space-age` + explicitly when using their features. +- Versioned API docs; `factorio_version: "2.0"`. +- Quality fields touch nearly every item/entity prototype; rail/fluid/inserter changes; Space Age + adds planets/space platforms. + +## Minimal skeleton +``` +my-mod/ +├─ info.json +├─ settings.lua (optional) +├─ data.lua +├─ control.lua +├─ changelog.txt +├─ thumbnail.png +└─ locale/en/locale.cfg +```