Skip to content

Add a worked create-mode probe example - #4

Merged
wormeyman merged 1 commit into
mainfrom
docs/pumpjack-terminals-example
Aug 17, 2026
Merged

Add a worked create-mode probe example#4
wormeyman merged 1 commit into
mainfrom
docs/pumpjack-terminals-example

Conversation

@wormeyman

Copy link
Copy Markdown
Contributor

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-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. 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:

Facing 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)

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_mirroring and migrate_horizontal_mirroring on 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-data being byte-identical across those platforms for a given build.

Two traps it documents

Factorio 2.1 deleted LuaEntity.fluidbox and the entire LuaFluidBox class, flattening it onto LuaEntity as get_fluid_box_*. entity.prototype.fluidbox_prototypes[i].pipe_connections still works in both, so prototype-level reads need no branching.

Feature detection needs a pcall. Reading an unknown key on LuaEntity raises in 2.0 rather than returning nil, so if entity.get_fluid_box_pipe_connections then throws on the older version instead of being false.

Verification

Ran end to end through the CLI on macOS:

factorio-oracle run --probe examples/pumpjack-terminals/probe.json --work-dir /tmp/pj

reports "ok": true, writes oracle-dump.json, and loads all six bundled mods. Output matches the Windows run exactly.

cargo fmt, cargo clippy -D warnings and cargo test --all-targets all pass. Docs and example data only - no library code changes.

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
wormeyman force-pushed the docs/pumpjack-terminals-example branch from 0b8a0b3 to 02bc867 Compare August 17, 2026 19:09
@wormeyman
wormeyman merged commit eec89b1 into main Aug 17, 2026
1 check passed
@wormeyman
wormeyman deleted the docs/pumpjack-terminals-example branch August 17, 2026 19:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant