# pointerpaths

> **Tool `tools/triage/pointerpaths.py`** (program, Triage). Find a way to the address of a value that moves: a chain of pointers from a fixed address (a global variable of the program) through the game's objects to the value.

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

## Its own help

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

```text
Find a way to the address of a value that moves: a chain of pointers from a fixed address
(a global variable of the program) through the game's objects to the value.

Usage: pointerpaths.py DUMP@BASE:TARGET [DUMP@BASE:TARGET ...] --static LO-HI
                       [--depth N] [--offset N] [--size 4|8|2] [--be] [--max N]

  DUMP@BASE:TARGET  a memory dump, the address of its first byte, and the address of the value
                    in that run (found with memscan.py), for example derived/mem/run1.bin@0x400000:0x1234560
  --static LO-HI    the address range that does not move between runs: the program's data
                    segment or its image, for example 0x400000-0x4fffff
  --depth N         the longest chain tried (default 4 pointers)
  --offset N        the largest offset from a pointer to the field it leads to (default 0x400)
  --size N          bytes in a pointer: 4 (default), 8 for 64-bit programs, 2 for 16-bit near pointers
  --be              big-endian pointers (68000, PowerPC, MIPS consoles)

A value inside an object on the heap lives at a different address in every run, so its address
alone cannot be used by a test or an object model. A chain such as "the pointer at 0x4a1f30,
then +0x18, then +0x4" finds it in every run. This tool searches backwards from the value: the
pointers that point at it or just before it, then the pointers to those, until it reaches the
static range. It then follows each chain in the other dumps, taken in other runs where the
value sat at another address, and keeps only the chains that lead to the value in all of them.

The chain is also the shape of the game's data: the first pointer is often a global (the
world, the player list), and each offset a field of a structure. Write each step into the
labels and the structure notes (docs/observe/memory.md). Standard library only.
```

## Named by

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