memscan

Tool tools/triage/memscan.py (program, Triage). Find where a running game keeps a value, from memory dumps taken while you watch the value change: the gold, a unit's health, the turn counter, the random seed.

Run it with ./gameframe run memscan ARGS or python3 tools/triage/memscan.py. Source on GitHub.

Its own help

This is the help text in the tool itself, as ./gameframe tool memscan prints it.

Find where a running game keeps a value, from memory dumps taken while you watch the value
change: the gold, a unit's health, the turn counter, the random seed.

Usage: memscan.py DUMP:RULE [DUMP:RULE ...] [--type T] [--base ADDR] [--max N]
       memscan.py DUMP --pointers ADDR [--base ADDR] [--type u16|u32|u64]

  DUMP:RULE    a dump file and what the value was when it was taken. RULE is one of
                 =N        the value was N (500, -3, 0x1f4, 2.5)
                 changed   different from the previous dump
                 same      equal to the previous dump
                 up, down  larger or smaller than in the previous dump
                 any       no rule (a starting dump)
  --type T     u8 i8 u16 i16 u32 i32 u64 f32 f64 (default u16 for a dump under 1 MB, else
               u32); add "be" for big-endian, as in u16be
  --base ADDR  the address of the dump's first byte, so results print as addresses
  --pointers   list every place in DUMP that holds ADDR: pointers to a value found with a scan,
               which lead to the structure around it

Start with =N when you know the value: the first dump is then searched as bytes, which is
fast. Starting with `any` checks every offset, which takes seconds per megabyte.

Each dump must cover the same memory: the same segment, the same heap range, or the whole
emulated memory. Take the first one, change the value in the game (spend gold, take damage),
take another, and so on. Every offset whose value fits every rule is printed. Three or four
dumps usually leave a handful. The tool scans every alignment, so a value inside a packed
structure is found too.

Then confirm the address. Put a memory breakpoint on it (DOSBox-X: BPM; tools/dos/dbx_control.py),
or find the code that refers to it in the Ghidra export (decomp_query.py). The instruction
that writes it is the rule to trace. Dumps come from DOSBox-X's debugger (MEMDUMPBIN), an
emulator's save state, tools/emu, or a debugger on the original. They are game material:
keep them in derived/. Standard library only.

Named by

Skills: re-observe, re-trace.