Measuring a function that calls the whole game: intercept its callees

What to know

2026-10-24, Hardwar's isolate.py, Hardwar's plot_truth.py.

The story's update (0x46eb60) calls 36 other functions: pilots, vehicles, map blocks, buildings, objects. Building enough of the world in the emulator for them to run is not practical. Instead isolate.py finds every direct call target in the function (capstone), hooks each target's first instruction, records the registers and stack words, answers with a value drawn by the harness, and returns to the caller. The port's test replays the same answers through its world trait and compares the calls one by one, with the block, the messages and the random state. Small pure helpers the function relies on (the clock split, the generator, msg_post) are left out of the hook set and run as they are.

Pitfalls met on the way:

• Callee-popped stack arguments. Watcom's register convention passes the fifth argument on and the callee drops them (ret 8, ret 0x18). The hook must drop as many bytes as the callee's first ret does, or the caller's frame shifts. ret_pops reads it.
• One hook per target. Unicorn keeps every hook added, so two Isolated objects on one emulator both fire on a shared callee and pop the return address twice. Only the running one may act (active).
• Unset words. Message bodies and command records are built in the caller's frame and only some words are written; the rest is old stack. Filling the stack with 0xcc before each run makes those words a known value (UNSET in the port).
• Registers that Ghidra loses. The start-role notice loop in plot_update reloads its counter from ECX after the call, which Watcom preserves, so the loop stops after one notice. Ghidra's pseudocode shows a three-way loop; the disassembly and the emulator agree on one.
• The worktree has no derived/. Tests that read ground truth need HARDWAR_PLOT_TRUTH=/path/to/main/derived/emu/plot when run in a worktree, or they skip.
• Do not trust a pass without a mutation. The first green run had skipped every test. Changing one comparison in the port (&& to ||) must turn the test red.

Candidate for GameFrame next to pe32_emu.