# call_trace

> **Tool `tools/emu/call_trace.py`** (library, Emulators). Record the calls an emulated function makes to chosen functions, in order, with call sites.

A library: other tools and your own scripts import it. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/emu/call_trace.py).

## Its own help

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

```text
Record the calls an emulated function makes to chosen functions, in order, with call sites.

The usual use is the game's random number generator: most "almost right" reimplementations of
a simulation draw random numbers in a different order or count. Record the original's draws
here, record the port's draws the same way, and compare with tools/verify/seqdiff.py.

    from call_trace import CallTrace
    trace = CallTrace(emu, {emu.export('engine.dll', 'rng_next'): 'rng_next',
                            emu.export('engine.dll', 'rng_float'): 'rng_float'})
    emu.call(simulate, 1234, 600, out)
    trace.write('orig.trace')   # one line per call: "label<TAB>module+offset" of the return address

Only outermost calls are recorded: rng_float calling rng_next logs one line, as the port would
count one draw. Pass `args=N` to record the first N integer arguments too (`label(a, b)`).
```

## Named by

Skills: [re-observe](/skills/re-observe), [re-emulate](/skills/re-emulate).

Agents: [re-measurer](/agents/re-measurer), [re-randomiser](/agents/re-randomiser).