From 7a0246c1eb49fc28cc52c10a4eae676b910c6f44 Mon Sep 17 00:00:00 2001 From: Eric J Date: Mon, 17 Aug 2026 11:04:24 -0700 Subject: [PATCH 1/2] Record the Friday Facts blog as a reference source The oracle section listed three machine-readable sources plus a note that data/changelog.txt exists. All of those answer what the game accepts. None answers why a value changed, which is the question you have after an update. Split them into two kinds. Authoritative sources ship with the install, read offline, and may gate a capture. Reference sources explain a change and must never gate one, because they cannot be read reproducibly. The blog is the second kind: Wube writes it, so it outranks forum and wiki advice, but it describes intent and the shipped game can differ. Measured 2026-08-17: Atom feed at factorio.com/blog/rss, 10 most recent posts only with full bodies embedded, older posts at /blog/post/fff-. It is the only source here needing the network. The worked example is issue #81. The pumpjack's output_fluid_box positions went from [[1,-1],[1,-1],[-1,1],[-1,1]] to [[1,-1],[1,1],[-1,1],[-1,-1]] between 2.0.77 and 2.1.14. The dump shows that. FFF #442 explains it, and the same release added use_mirroring and migrate_horizontal_mirroring, which is how you learn the change is about entity mirroring. Also note on the reference list that the blog counts as official, so it does not fall under the existing "prefer official docs over forum/blog/wiki" line. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01P9FADuTnjE7SFEQWnpNhfc --- CLAUDE.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8957e187..0ece5ef6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -124,7 +124,8 @@ Use the script rather than your own `luac`. Homebrew no longer ships Lua 5.2, so - Runtime API: - Libraries/functions Factorio adds or modifies (incl. `require()` restrictions): - Lua 5.2 manual: -- Prefer official Factorio docs over forum/blog/wiki advice when changing runtime behavior. +- Friday Facts blog (Wube's own, so it counts as official): . Best source for *why* a behavior changed. See the oracle section below for how to use it and its limits. +- Prefer official Factorio docs over forum/blog/wiki advice when changing runtime behavior. The Friday Facts blog is written by Wube, so it is on the official side of that line. ### The Factorio oracle (re-capture after a game update) @@ -138,7 +139,14 @@ So don't trust memory or the wiki. The game is the only authority on what the ga | `data/*/migrations/*.json` | Every rename, as a table. This is a complete list, not a guess | | `doc-html/runtime-api.json` | The `defines.*` tables, version-stamped to the install. See the caveat below: it publishes a documentation index, not the values | -A fourth source, `data/changelog.txt`, records behavior changes per patch. It is worth reading after an update, but nothing automates it - no code in `tools/` touches it. +Those three are *authoritative*: they say what the game accepts, they ship with the install, and a capture reads them offline and gets the same bytes every time. + +Two more sources are *reference* rather than authoritative. They say **why** something changed, which is what tells you which captured value now needs review. Nothing automates either one, and nothing should. + +- **`data/changelog.txt`** records behavior changes per patch, terse, in the install. No code in `tools/` touches it. +- **The Friday Facts blog, **, is Wube's own writing, so it outranks forum, wiki and third-party blog advice. It is still not authoritative in the sense above - it describes intent, and the shipped game can differ, so check any claim from it against a capture. The feed is Atom at and carries the **10 most recent posts only**, so it cannot answer "what shipped in version X" by itself; older posts live at `https://factorio.com/blog/post/fff-`. It is also the only source here that needs the network, which is why it can never gate a capture. + + Worked example: the pumpjack change behind issue #81 shows up in a dump as `output_fluid_box` pipe connections going from `[[1,-1],[1,-1],[-1,1],[-1,1]]` to `[[1,-1],[1,1],[-1,1],[-1,-1]]`. The dump does not say why. FFF #442, "Flip, Flow, and Fresh Paint", does, and the same release added `use_mirroring` and `migrate_horizontal_mirroring` to that prototype - which is how you learn the change is about entity mirroring rather than a typo fix. `tools/capture-factorio-oracle.sh` pulls those three into `test/FactorioTools.Test/OilField/factorio-oracle.json`: From efd58d4e88418f2d0138af66167fd9d526a505c6 Mon Sep 17 00:00:00 2001 From: Eric J Date: Mon, 17 Aug 2026 12:12:06 -0700 Subject: [PATCH 2/2] Point at the blog's search, not just the feed The first version said the blog "carries the 10 most recent posts only", which is true of the Atom feed and wrong about the blog. There is a search endpoint, https://factorio.com/blog/search/, and it covers the whole archive: a search for "mirroring" returns FFF #80 from 2015. That matters because the feed alone cannot answer "what shipped in version X", which is the actual question after a game update. The search can. Measured 2026-08-17: HTML only, no JSON, about 10 results with no total shown. Word choice matters more than expected - searching "mirroring" does NOT return FFF #442, the post that introduced entity mirroring, while "flip" and "fluid" both do. So the note now says to try two or three wordings before concluding a post does not exist. A bare number works too: search/442. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01P9FADuTnjE7SFEQWnpNhfc --- CLAUDE.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0ece5ef6..31e7db06 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,7 +144,11 @@ Those three are *authoritative*: they say what the game accepts, they ship with Two more sources are *reference* rather than authoritative. They say **why** something changed, which is what tells you which captured value now needs review. Nothing automates either one, and nothing should. - **`data/changelog.txt`** records behavior changes per patch, terse, in the install. No code in `tools/` touches it. -- **The Friday Facts blog, **, is Wube's own writing, so it outranks forum, wiki and third-party blog advice. It is still not authoritative in the sense above - it describes intent, and the shipped game can differ, so check any claim from it against a capture. The feed is Atom at and carries the **10 most recent posts only**, so it cannot answer "what shipped in version X" by itself; older posts live at `https://factorio.com/blog/post/fff-`. It is also the only source here that needs the network, which is why it can never gate a capture. +- **The Friday Facts blog, **, is Wube's own writing, so it outranks forum, wiki and third-party blog advice. It is still not authoritative in the sense above - it describes intent, and the shipped game can differ, so check any claim from it against a capture. It is also the only source here that needs the network, which is why it can never gate a capture. + + **Searching it: `https://factorio.com/blog/search/`.** This is the way in, and it covers the whole archive - a search for `mirroring` returns FFF #80 from 2015. Measured 2026-08-17: HTML only, no JSON, about 10 results with no total shown. **Word choice matters more than you would expect.** Searching `mirroring` does *not* return FFF #442, the post that introduced entity mirroring, while `flip` and `fluid` both do. So try two or three wordings before concluding a post does not exist. A bare number works too: `search/442`. + + Direct post URLs are `https://factorio.com/blog/post/fff-`. There is also an Atom feed at , but it carries the **10 most recent posts only**, so it answers "what changed lately" and not "what shipped in version X" - use the search for that. Worked example: the pumpjack change behind issue #81 shows up in a dump as `output_fluid_box` pipe connections going from `[[1,-1],[1,-1],[-1,1],[-1,1]]` to `[[1,-1],[1,1],[-1,1],[-1,-1]]`. The dump does not say why. FFF #442, "Flip, Flow, and Fresh Paint", does, and the same release added `use_mirroring` and `migrate_horizontal_mirroring` to that prototype - which is how you learn the change is about entity mirroring rather than a typo fix.