Add a worked create-mode probe example - #4
Merged
Conversation
The repo had no example of a probe mod, only integration tests. This is a
real one that earned its place: it settled FactorioTools issue #81 and
caught a breaking runtime API change nobody had noticed.
It places pumpjacks in all four rotations and reads
PipeConnection.target_position - the tile the connecting pipe actually
occupies - from the running game. That matters because a --dump-data
capture answers a different question. The prototype's
output_fluid_box.pipe_connections gives the connection point inside the
entity, and the pipe sits one tile further out in the facing direction, so
deriving one from the other means trusting a convention rather than reading
an answer.
Measured against real 2.0.77 and 2.1.14 installs:
2.0.77 2.1.14
north (1,-2) (1,-2)
east (2,-1) (2,1)
south (-1,2) (-1,2)
west (-2,1) (-2,-1)
Running both versions is the part worth copying. The 2.0.77 column
reproduces what FactorioTools has hardcoded, so the probe is shown to give
the known-good answer before being believed about the new one. The 2.1.14
column was also produced twice, on Windows and macOS builds of 87180, and
matches.
Two traps the example documents, both hit while writing it:
Factorio 2.1 deleted LuaEntity.fluidbox and the entire LuaFluidBox class,
flattening it onto LuaEntity as get_fluid_box_*. And feature detection needs
a pcall, because reading an unknown key on LuaEntity raises in 2.0 rather
than returning nil, so the obvious guard throws on the older version.
Verified end to end through the CLI on macOS: run --probe reports ok with
oracle-dump.json written and all six bundled mods loaded.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P9FADuTnjE7SFEQWnpNhfc
wormeyman
force-pushed
the
docs/pumpjack-terminals-example
branch
from
August 17, 2026 19:09
0b8a0b3 to
02bc867
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The repo had no example of a probe mod, only integration tests. This is a real one that earned its place: it settled FactorioTools issue #81 and caught a breaking runtime API change nobody had noticed.
What it does
Places pumpjacks in all four rotations and reads
PipeConnection.target_position- the tile the connecting pipe actually occupies - from the running game.That matters because a
--dump-datacapture answers a different question. The prototype'soutput_fluid_box.pipe_connectionsgives the connection point inside the entity, and the pipe sits one tile further out in the facing direction. Deriving one from the other means trusting a convention rather than reading an answer.What it measured
Against real 2.0.77 and 2.1.14 installs, offsets relative to the pumpjack center:
(1,-2)(1,-2)(2,-1)(2,1)(-1,2)(-1,2)(-2,1)(-2,-1)2.0 gave four rotations only two distinct corners: east reused north's, west reused south's. 2.1 gives each its own. FFF #442 is the release that did it, alongside
use_mirroringandmigrate_horizontal_mirroringon the same prototype.Running both versions is the part worth copying. The 2.0.77 column reproduces what FactorioTools already has hardcoded, so the probe is shown to give the known-good answer before being believed about the new one. A probe that only runs against the version you care about cannot tell you that.
The 2.1.14 column was also produced twice, on Windows and macOS builds of 87180, and matches - consistent with
--dump-databeing byte-identical across those platforms for a given build.Two traps it documents
Factorio 2.1 deleted
LuaEntity.fluidboxand the entireLuaFluidBoxclass, flattening it ontoLuaEntityasget_fluid_box_*.entity.prototype.fluidbox_prototypes[i].pipe_connectionsstill works in both, so prototype-level reads need no branching.Feature detection needs a
pcall. Reading an unknown key onLuaEntityraises in 2.0 rather than returning nil, soif entity.get_fluid_box_pipe_connections thenthrows on the older version instead of being false.Verification
Ran end to end through the CLI on macOS:
reports
"ok": true, writesoracle-dump.json, and loads all six bundled mods. Output matches the Windows run exactly.cargo fmt,cargo clippy -D warningsandcargo test --all-targetsall pass. Docs and example data only - no library code changes.