modding-build
Use when the sources of a byte-matched, exactly linked DOS decompilation are to be changed by any size (a fix, a mod, the first step of a port) and still linked into a running executable; and to audit the layout for addresses written as numbers, which matching and the exact link cannot see. Also for an armcc5 Cortex-M firmware: new code in free flash, and proof that the original's bytes changed only where the mod says.
abedegno · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add abedegno/Exhume --skill modding-build技能说明
name: modding-build description: Use when the sources of a byte-matched, exactly linked DOS decompilation are to be changed by any size (a fix, a mod, the first step of a port) and still linked into a running executable; and to audit the layout for addresses written as numbers, which matching and the exact link cannot see. Also for an armcc5 Cortex-M firmware: new code in free flash, and proof that the original's bytes changed only where the mod says.
Modding build
Paths are relative to the Exhume checkout. The exact link proves the sources; the modding build lets them change. It needs an exact link that works first (skills/link-and-diff). docs/link.md, "The modding build" and "Layout audits", has the reasons behind each step.
Steps
- Exact link once, with every source matching and verifying:
python3 examples/uw2/link.py(or the project's own link). It leaves a snapshot in<build>/LINK/base: each matched object, its source's SHA-1 and where its data sits. If any object fails to verify, no snapshot is written; fix that first. - Check the modding build against it with nothing changed:
python3 examples/uw2/link.py --mod, thencmp <build>/MODLINK/out/GAME.EXE <build>/LINK/out/GAME.EXE. They must be identical. A difference means the snapshot or thedw offsetnames in extracted data are wrong. - Audit the layout before trusting a changed build (below).
- Edit and link:
python3 examples/uw2/link.py --mod. Only sources whose text differs from the snapshot's are compiled, into<build>/MODLINK/src; the matched objects stay as they were, so reverting a source brings back the exact link. To build from a copy of the sources instead, point[project] srcat it (UW2's config readsEXHUME_SRC). - Boot and look:
node tools/rungame.mjs --data GAMEDIR --as GAME.EXE <build>/MODLINK/out/GAME.EXE shot- ... s:NAME ... m:MARKER. Read every screenshot. Go as far as the program's main scene (UW2: through character creation into the 3D view), not just the title: layout faults show where data is used, not where it is loaded.m:TEXTsearches the guest's memory; make new code change a marker string at run time and search for the changed text, so the run proves the new code ran. rungame exits 1 when a search finds nothing.
Layout audit
A literal address and a symbolic one assemble to the same bytes, so a number that should have been a name matches and links exactly, then breaks when anything before it moves.
python3 tools/addrscan.pylists every operand with no fixup that could be an address;*marks those that may go through DGROUP or an unknown segment. Set[layout]in exhume.toml first (far data entries, library objects, dispatchers; docs/config.md).--entriesand--jumpsshow the segment register states it inferred, which is how to check a surprising line.- Read each
*line against the source and the IDA listing. Write real addresses as names (offset DGROUP:_name, the variable in C), then match, verify and exact-link again: the bytes must not change. Note every line that is not an address and why (a coordinate, a divisor, a BIOS address, a table IDA decoded as code). - Boot with DGROUP shifted: add a new initialised array early in DGROUP's data and boot to the main scene. Compare with the exact build's screenshot at the same point (
python3 tools/pngdiff.py A.png B.png X0 Y0 X1 Y1, over a rectangle that does not animate). - If it differs, bisect: add a
_BSSarray to one file at a time, in link order, link--mod, boot, compare. Padding before the variable breaks the scene and padding after it does not, so the boundary is the file holding the variable. Then find who uses its address as a number, and widen the scan if it missed it. - List what still has to keep its length: extracted data with internal offsets, assembly modules that address their own far data by number (
addrscan.py --all). Those change only at the same length until they have names.
Rules
- Edit a copy or a branch, never the matched tree, unless the change keeps the bytes and passes match, verify and the exact link.
- A new source file needs a place in the link order (the link's module lists) before
--modwill take it. - Keep DGROUP's static data, stack and near heap under 64 KB (profiles/borland-tc101/linker.md).
- Report a modding build as proven only after it reaches the main scene and the marker search succeeds; a title screen is not enough.
A linked image (armcc5): new code in free flash
A Cortex-M firmware has no relocations and its code calls by PC-relative offsets, so the safe
mod leaves every original function where it is and puts new code beside the image. The modded
build, python3 tools/gate.py game (profiles/armcc5/tools/armmod.py), does that and proves it:
the gate (skills/link-and-diff) rebuilds the edited tree, and every byte that differs from the
original must be one the mod declared. It needs a gate that passes first.
- Write the new code in its own directory outside
src(or list the directory in[gate] exclude), so the exact build never sees it. It may call any original function and use any original global by its map name: every other symbol is linked at its map address. - Set
[mod]in exhume.toml (docs/config.md):sources;code, free flash after the image;ram, above everything the image uses, its data and the stack (the build checks both). - Run it with no edits first. The image must come back identical, with the new piece after it.
- Make the original reach the new code with the smallest edit that does it, as
[[mod.replace]]rules (each string must occur exactlycounttimes) or patches: a vector pointed at a new handler, an entry of a function table pointed at new code, a table's uses pointed at a larger copy in the new RAM, a range check widened. Keep every original function the same size; new behaviour goes in the new piece. - Declare each difference those edits make as a
[[mod.allow]]rule with