Practical caveats

Living page: the sharp edges of this machine and toolchain. Moved out of the repository on 2026-09-18, because it goes stale faster than anything it documents.

Practical caveats

• Godot headless churn. Running Godot headless against godot/ ("<Godot install>\Godot_..._console.exe" --headless --path godot --quit-after 2) regenerates godot/project.godot's header and flips godot/MapViewer.cs's line endings. scripts/check-godot-churn.ps1 reverts the two files when the diff is header/whitespace-only. Run it after any headless Godot run, before committing; CI's godot-headless job runs it after its checks.
• The Godot lane in CI. CI's godot-headless job builds the Godot project and runs each check scene listed in .github/workflows/ci.yml headless. A check scene a new Godot task adds runs in CI only once its own step is added there, as a one-line follow-up after the task merges. The screenshot tours stay on the user's machines: headless Godot has no texture to capture.
• Build order for the inspector. Build IC2.Data before IC2.Inspect when both have changed, because they share an obj directory. The IC2.Inspect commands are listed in the README.
• Ghidra's reference manager misses some string references in this Delphi build, for example the DAT filename and "falls to". Grep all_app_functions.txt instead; the decompiler inlines string literals even when no reference was recorded. Call xrefs work, except across virtual method calls.
• Tables loaded from the DAT at runtime (unit-type stats, the combat matrix, mercenary names) are uninitialised in the EXE. Search the DAT by the data's known name strings instead.
• Mid-turn saves can legitimately contain 0xFFFF army tombstones: combat writes them, and the end-of-turn tick compacts them. IC2.Data skips and reports them.
• Local corpus drift. IC2.Data.Tests' corpus sweep compares the configured saves folders against a committed table of expected outcomes. Moving saves between saves/ and saves-processed/, or adding new ones, makes it fail locally until the table is regenerated (bug #57, fixed by T34). CI runs it against the private fixtures repository's copy of the corpus (since T53), which does not drift this way.

---