# markers

> **Tool `tools/formats/markers.py`** (program, Formats). Mark the fields of a data file with unique values, then find where the game puts each one in memory.

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

## Its own help

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

```text
Mark the fields of a data file with unique values, then find where the game puts each one in
memory. It maps a save or data file onto the game's structures.

Usage: markers.py plant FILE OUT [--every N] [--size 2|4] [--from A] [--to B] [--be]
       markers.py find  OUT.markers DUMP[@BASE] [DUMP@BASE ...]

  plant   copy FILE to OUT with a marker in each chosen field, and write OUT.markers listing
          each marker and its offset. --every N (default 4) marks every N bytes between
          --from and --to (default: the whole file); --size is the marker's width.
  find    list where each marker appears in one or more memory dumps taken after the game
          has loaded OUT: the file offset, the marker, and each address it was found at.

A tracer in a medical scan shows where the blood goes. A marker does the same for a value
the game reads from a file: a number that occurs nowhere else, written into the field. After
the game loads the marked file, the marker turns up in memory at the address where the game
keeps that field, often inside an object whose other fields came from the same record. A
memory breakpoint on that address (docs/observe/debuggers.md) then finds the code that uses
the field. Each marker encodes its own offset (0xC0DE0000 + the field's number for 4 bytes,
0xA000 + the number for 2 bytes), so a match names its field.

A game may check the file (a checksum, a version, a count that must be small) and refuse it, or
crash on a marker in a field such as a count or an offset. Plant markers in a few fields at a
time, keep the header untouched (--from), and fix the checksum if the game checks one. Work on
copies in derived/: marked files and dumps are game material. Standard library only.
```

## Named by

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