# Emulating a whole system routine: stubs, whole records, and stale registers

## What to know

*2026-10-24, Hardwar's `economy_truth.py`, `crates/economy/tests/emulated.rs`.*

The economy's routines call message posting, searches over the world, sound and the updates
of systems not yet ported. Four practices made them testable bit for bit.

**Stub internal functions at their entry.** `pe32.py` stubs only imports. For a function in
the game's own code, hook its entry address with `UC_HOOK_CODE` and, in the hook, record the
registers (and whatever the pointers in them point at), pop the return address into EIP and
set EAX. Watcom's register convention keeps every register but EAX across a call, so that is
a faithful return. A hook can also skip a routine for one run only (keep a set of addresses
to skip): `bg_set_function` runs the first factory or shop update at its end, and the
configuration test wants the state without it. Hook only the addresses you stub or skip; a
skip set the hook never sees does nothing (the first run of the script walked straight into
the Moth roll-out that way).

**Compare whole records, not chosen fields.** Each case writes the 900-byte building record
and its function memory before and after, and the port reads the record into typed fields
while keeping every other byte (`Building::raw`), then writes it back. A field the port
forgot to write, or wrote at the wrong offset, shows as a byte difference without anyone
having to think of it: the five `0x4000` halfwords at `+0x32c` (not four) were found that way.

**Mind state that carries between cases.** Globals the routine steps keep their value from
case to case unless the script resets them: `bg_create`'s light-group counter `0x582140`
made every configuration after the first differ until the test followed it.

**Following constant arguments through a disassembly needs care.** To read which kind and
subtype `bg_table_build` gives each building, a scan tracked `mov reg, imm` before each call.
EBX survives calls in Watcom code, so a value set for one call (`bg_create`'s EBX = 7) looked
like the next call's subtype; the real subtype came from a global tested a few instructions
earlier. Forget a register on any other write to it, and check odd results by hand.

A small trap on the way: a helper script named `dis.py` shadows the standard library's `dis`,
which Capstone imports through `inspect`, and Capstone then fails with a circular import.