Contributing Collections

Contributing Collections

Anyone can contribute pre-made collections to the tonkatsu-collections repository. Your collection will be available to all Tonkatsu Box users through the Browse Online Collections feature.

The easy way

1. Build your collection in Tonkatsu Box
2. Export it (Menu > Export - choose .xcoll for light or .xcollx for full)
3. Fork the tonkatsu-collections repo
4. Place the file in the correct folder (see below)
5. Create a Pull Request
6. CI validates your file automatically
7. Get merged!

Where to put your collection

Type	Location
Platform-specific (all SNES games, best NES RPGs)	platforms/{platform}/your-collection.xcoll
Movies / TV Shows / Anime	media/{type}/your-collection.xcoll
Cross-platform / mixed media	curated/your-collection.xcoll

Rules

1. One collection = one file - don't edit multiple collections in one PR
2. Don't edit index.json - it's auto-generated by CI
3. Use the correct folder - see table above
4. Filename must be kebab-case - best-rpgs.xcoll, not Best RPGs.xcoll
5. Export from Tonkatsu Box - this guarantees valid format

File formats

Both formats are accepted:

• .xcoll (light) - item IDs and metadata only, small file size
• .xcollx (full) - includes cover images and canvas layout, works offline on import

See RCOLL_FORMAT.md for the full file specification.

Adding a new platform

If your platform doesn't have a folder yet:

1. Create platforms/{platform-id}/
2. Add a _platform.json file:

{
  "id": "platform-id",
  "name": "Full Platform Name",
  "shortName": "SHORT",
  "igdbId": 123
}

3. Add your .xcoll/.xcollx file

Find IGDB platform IDs at docs/IGDB_PLATFORMS.md in the repository.

Adding a new media type

1. Create media/{type-id}/
2. Add a _media.json file:

{
  "id": "type-id",
  "name": "Type Name",
  "shortName": "Short",
  "source": "TMDB"
}

3. Add your .xcoll/.xcollx file

CI validation

Every pull request is automatically validated:

• File format (must be XcollFile v2)
• Required fields: name, author, created
• Each item must have media_type and external_id
• No duplicate items
• Filename is kebab-case
• ZIP files: checked for path traversal, size limits, valid contents

After merge, index.json is regenerated automatically.

Ideas for collections

• Best games of a specific decade (80s, 90s, 2000s)
• Genre-specific (metroidvanias, shmups, fighting games)
• Regional exclusives (Japan-only, PAL-only)
• Games with specific features (co-op, 4-player, link cable)
• Personal "best of" lists
• Challenge sets (beat these 12 games in 2026)
• Best sci-fi movies, horror TV shows, studio Ghibli films

Questions?

Open an issue on the collections repository.

See also

• Browse Online Collections - download collections from the app
• Import / Export - exporting your collections