# catalog

> **Tool `tools/formats/catalog.py`** (program, Formats). A first resource viewer: every file of a game, what it is, and what the project's decoders make of it, as a static HTML page for people and a JSON manifest for agents.

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

## Its own help

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

```text
A first resource viewer: every file of a game, what it is, and what the project's decoders
make of it, as a static HTML page for people and a JSON manifest for agents.

Usage: catalog.py GAME_DIR OUT_DIR [--decoder GLOB=DECODER.py ...] [--palette FILE]
                  [--palette-offset N] [--dac shift|scale] [--hex N]

  GAME_DIR              the game's files (walked recursively)
  OUT_DIR               where index.html, catalog.json and the pictures go. It holds game
                        material: keep it in an ignored folder (derived/catalog), never in git
  --decoder GLOB=FILE   run a decoder (the validate.py kind: `decode(reader)`) on every file
                        whose path relative to GAME_DIR matches GLOB (fnmatch, case-blind).
                        Repeat it for each format. The first matching decoder is used
  --palette FILE        256 RGB entries for palette-indexed pictures (6-bit VGA values are
                        scaled up when none is above 63); --palette-offset N reads it from
                        inside a bigger file. Without it, the default VGA palette
  --dac shift|scale     how 6-bit values become 8 bits: scale (default, 63 -> 255) or shift
                        (<< 2, 63 -> 252, as many games' palette loaders do). A palette with
                        fewer than 256 colours is filled with magenta
  --hex N               bytes of each file shown in hex (default 256)

A decoder may also define `images(result)`, returning a list of pictures to show:
`(label, width, height, pixels)` with `pixels` one palette index per byte, row by row, or
`(label, width, height, pixels, 'rgb')` with three bytes per pixel. Each becomes a PNG on the
page. Use it to look at what a decoder found: a wrong width, offset or palette is obvious in a
picture and hidden in a table.

Prints one summary line, also in catalog.json: how many files and bytes decode completely,
how many fail, and how many have no decoder yet. That line is the format coverage of the
project; re-run the catalogue after each decoder to see it grow (docs/working/viewer.md).

It does not play sound, draw 3D or run the game: that is the project's own viewer
(re-browse skill). Standard library only, plus the toolkit's reader, filetypes and rawimage.
```

## Named by

Skills: [re-browse](/skills/re-browse), [re-format](/skills/re-format), [re-inventory](/skills/re-inventory), [re-start](/skills/re-start).

Agents: [re-surveyor](/agents/re-surveyor), [re-decoder](/agents/re-decoder).