# frida_trace

> **Tool `tools/live/frida_trace.py`** (program, The running game). Trace calls to chosen functions in a running game, with Frida.

Run it with `./gameframe run frida_trace ARGS` or `python3 tools/live/frida_trace.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/live/frida_trace.py).

## Its own help

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

```text
Trace calls to chosen functions in a running game, with Frida.

Usage: frida_trace.py (--spawn PROGRAM [ARG ...] | --attach PID_OR_NAME)
                      [--hook SPEC ...] [--watch SPEC:SIZE ...] [--rearm MS]
                      [--args N] [--seconds S] [--out FILE]

SPEC names one function, with an optional label after `=`:
  game.exe+0x1a2b30=rng_next     an offset in a module (the address Ghidra shows minus the base)
  engine.dll!Random_Next          an exported name
  libc.so.6!rand=rand             any module the process has loaded

Each call becomes one line, `label<TAB>module+offset`, where the offset is the call's return
address: the same format as tools/emu/call_trace.py. tools/verify/seqdiff.py then compares a
live run of the original with a run of the port. `--args N` adds the first N integer arguments
as `label(a, b)`. Only outermost calls are logged on each thread, so a traced function calling
another traced function logs one line, as the port would count one call.

--watch logs reads and writes of chosen memory: `game.exe+0x2a1000:256=table` or
`game.exe!g_units:4096`. Each access becomes `label:r+0x10<TAB>module+offset`, with the offset
into the watched block and the instruction that made it. Frida's memory access monitor reports
the first access to a page, then stops watching that page. The tracer starts it again
--rearm milliseconds (default 20) after each report, so further accesses to the same page in
that time are not logged. An instruction that reads and then writes (`add [x], 1`) shows as a
read. Use it to find which code touches a value. Use --hook to count calls.

The emulator traces one function with chosen inputs. This traces the whole game while you
play, on its real platform: Windows, Linux, macOS or Android, wherever Frida runs. Install it
with scripts/setup.sh --install (requirements-live.txt). On macOS, Frida can trace programs
you built yourself. Signed applications and system programs need System Integrity Protection
relaxed, or a copy without the hardened runtime. Some protected games detect Frida. Trace a
copy you own, for analysis only ([Legal](../../docs/LEGAL.md)).
```