# fields

> **Tool `tools/formats/fields.py`** (program, Formats). Find the fields in many messages or records of one kind: which byte offsets are constant, which count up, which hold the length, which pick the kind of message, and which vary.

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

## Its own help

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

```text
Find the fields in many messages or records of one kind: which byte offsets are constant,
which count up, which hold the length, which pick the kind of message, and which vary.

Usage: fields.py FILE --stride N [--offset N] [--count N]    fixed-size records in one file
       fields.py DIR                                         one message per file (pcap.py --dump)
       options: --by-type OFFSET   group the messages by the byte at OFFSET first
                --png OUT.png      a picture: one row per record, one column per byte

A protocol message or a record in a data file is a row of fields. Laid side by side, many of
them show their layout: a byte that never changes is a magic number or a version; a value that
rises by one each message is a sequence number; a value equal to the message's length is a
length field; a byte with a few values that go with different lengths is the type. This tool
checks each offset for these, as 8-bit, 16-bit and 32-bit values in both byte orders, and
prints a table. The picture shows the same at a glance: constant columns are flat colour,
counters are smooth ramps, varying data is noise.

Start from the first bytes, where headers are. Group by the type byte (--by-type) once you
have found it: each type has its own layout. Messages that look like noise all the way through
are compressed or encrypted. Try zlib on them (filetypes.py and xorscan.py help), then look
again. The browser version is the records explorer
(https://tanepiper.github.io/game-frame/lab/records). Standard library only.
```

## Named by

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