Catalogue - cressie176/Load64 GitHub Wiki

The LoadC64 Catalogue is a set of plain-text files maintained by the LoadC64 project. It provides ROMSet lookup, game metadata, and suggested third-party catalogue IDs used during game import.

The catalogue URL is configured in General Settings. If not set, catalogue features are unavailable.

The source files are organised as follows:

catalogue/
├── catalogue.toml
└── games/
    ├── 0-9/
    │   └── 1942--capcom--1985--jkl012.toml
    ├── a/
    │   └── addams-family-the--ocean--1992--abc123.toml
    ├── b/
    │   └── bubble-bobble--taito--1987--def456.toml
    └── ...

Top-level metadata for the catalogue.

version = "1"
generated_at = "2026-04-04T00:00:00Z"

One file per abstract game. Each file contains the game metadata, known third-party catalogue IDs, and all known ROMSets for the game.

LoadC64_global_id = "abc123"
title = "The Last Ninja"
publisher = "System 3"
year = 1987
colour_encoding = "pal"
true_drive_emulation = false
multiplayer_mode = "single"
notes = ""

[third_party_ids]
gamebase64 = "1234"
mobygames = "5678"
csdb = "9012"
tosec = "Last Ninja, The (1987)(System 3)"

[[romsets]]
rsid = "a3f9c2d1..."
label = "PAL release"

[[romsets.roms]]
label = "Disk 1"
order = 1
sha1 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

[[romsets.roms]]
label = "Disk 2"
order = 2
sha1 = "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"

[[romsets]]
rsid = "b7e10f92..."
label = "NTSC release"

[[romsets.roms]]
label = "Disk 1"
order = 1
sha1 = "d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35"

Optional map of third-party catalogue keys to their identifiers for this game.

One entry per known ROMSet for this game. Many ROMSets may map to the same abstract game (e.g. PAL release, NTSC release, trained crack).

One entry per ROM file in the ROMSet.

The filename (without extension) follows the same slugification rules as local game folders, replacing the rsid suffix with the LoadC64 Global ID:

<sort-title-slug>--<publisher-slug>--<year>--<LoadC64-global-id>

Publisher and year are omitted when not set, matching the local convention:

The file lives in the subdirectory named after the first character of the slug (a–z, or 0-9 for digits).

The source files are maintained in a Git repository. A GitHub Actions workflow publishes a release containing a ZIP archive of the catalogue whenever a new version is tagged. This is the artifact that LoadC64 downloads.

When the user triggers a catalogue update from the Admin Hub, LoadC64:

1. Downloads the ZIP from the configured Catalogue URL
2. Expands the archive
3. Parses each game file and imports the data into a local SQLite database
4. Replaces any previously imported catalogue data

Once imported, all catalogue lookups are performed against the local database.

The initial LoadC64 Catalogue is seeded from TOSEC DAT files. TOSEC DAT files are XML documents that enumerate ROM images for a given system, each with a SHA-1 hash and a structured filename encoding metadata about the image.

The seeding process:

1. Parse each TOSEC DAT file for the target platform (e.g. Commodore 64)
2. For each ROM entry, decode the metadata from the TOSEC filename — see TOSEC for the full parsing rules
3. Apply exclusion rules to skip demos, compilations, bad dumps, data disks, and other non-game entries
4. Group multi-disk/multi-tape entries into ROMSets by matching on title, publisher, date, and non-media flags
5. For each ROMSet, compute the rsid from the SHA-1 hashes of its ROM files
6. Map TOSEC fields to LoadC64 Catalogue fields — see the mapping table in TOSEC
7. Assign a new LoadC64 Global ID to each abstract game (grouping ROMSets that represent variants of the same game)
8. Write one .toml file per abstract game

Step 7 — grouping ROMSets into abstract games — requires human curation. The seeding utility creates one abstract game per distinct (title, publisher) pair as a starting point, but variants (PAL/NTSC, cracked, trained) must be reviewed and merged or split manually.

The third_party_ids.tosec field stores the canonical TOSEC filename (without extension) for the game, allowing future re-seeding runs to match existing catalogue entries.

When LoadC64 imports a game it computes a ROMSet ID from the ROM files and looks up the rsid in the local catalogue database. If found, the corresponding game record seeds the import suggestion with title, publisher, year, colour encoding, true drive emulation setting, player count, and any associated third-party catalogue IDs.

If no match is found, the game is treated as unrecognised and only filename information is available.