[Feature Request] Managing Multi-Title Game Collections using JSON Build Manifests

Open
#19,907 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
65/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
github-actions, json, python
Domain
build-system

Research direction

Create compile_cheats.py and build_targets.json in libretro-database. First read the .cht format and existing cht/ directory structure. Implement script that loads manifest, concatenates source .cht files with re-indexed cheats, and writes flat files. Done when GitHub Actions runs script on src/ changes and generates valid self-contained .cht files.

Written by the indexing model from the issue text.

Description

feature request

Summary

RetroArch currently treats each .cht file as self-contained, which creates maintenance problems when multiple game variants share overlapping cheat codes. For example:

While cheat codes can already be shared conceptually across game variants, each file currently contains redundant or mismatched entries, requiring manual synchronization across files.


Problem Description

  • Issue 1: Cheat code definitions are not synchronized across different versions or bundled titles. Updating or adding cheats remains tedious and error-prone.
  • Issue 2: There is no reliable way to associate cheats with specific sub-titles (e.g., “Super Mario Bros. 3” vs “The Lost Levels”) without messy, inconsistent manual descriptions.
  • Issue 3: Altering RetroArch's runtime parser or using custom text directives inside .cht files breaks backward compatibility for older versions of RetroArch and third-party tools.

Proposed Solution: JSON Build-Time Compiler for Multiple Titles

Introduce a build-time compiler script within the libretro-database repository that operates entirely on standard .cht files and external build configuration.

Instead of inserting inline linking syntax into cheat files, cheat codes are broken into modular, valid .cht source files for individual games. A JSON manifest maps composite titles (games containing multiple titles or game bundles) to their respective component .cht files. The repository build script reads the manifest, combines the source files, automatically prefixes sub-game descriptions, re-indexes cheat counters, and generates flat, self-contained .cht files for release.


Example Setup

1. Granular Source Files (Standard .cht Format)

Cheat sets are split into modular source files for single titles, containing only valid .cht syntax:

  • src/snes/sub/Super Mario All-Stars - Super Mario Bros. (USA).cht
  • src/snes/sub/Super Mario All-Stars - Super Mario Bros. 2 (USA).cht
  • src/snes/sub/Super Mario All-Stars - Super Mario Bros. 3 (USA).cht
  • src/snes/sub/Super Mario All-Stars - Super Mario Bros. - The Lost Levels (USA).cht
  • src/snes/sub/Super Mario World (USA).cht

Example standard contents of src/snes/sub/Super Mario All-Stars - Super Mario Bros. (USA).cht:

cheats = 2

cheat0_desc = "Infinite Lives"
cheat0_code = "C264-A40D"
cheat0_enable = false

cheat1_desc = "Always Have Super Mushroom"
cheat1_code = "CB6A-DFA4"
cheat1_enable = false

2. JSON Assembly Manifest (build_targets.json)

Composition for titles with multiple titles or bundled collections is managed using a clean JSON build configuration file:

{
  "cht/Nintendo - Super Nintendo Entertainment System/Super Mario All-Stars (USA).cht": [
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. (USA).cht",
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. 2 (USA).cht",
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. 3 (USA).cht",
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. - The Lost Levels (USA).cht"
  ],
  "cht/Nintendo - Super Nintendo Entertainment System/Super Mario All-Stars + Super Mario World (USA).cht": [
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. (USA).cht",
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. 2 (USA).cht",
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. 3 (USA).cht",
    "src/snes/sub/Super Mario All-Stars - Super Mario Bros. - The Lost Levels (USA).cht",
    "src/snes/sub/Super Mario World (USA).cht"
  ]
}

3. Build Script Execution (compile_cheats.py)

A build script integrated into libretro-database handles compilation:

  1. Iterates over target definitions in the JSON manifest.
  2. Loads all referenced source .cht files sequentially for titles with multiple titles.
  3. Automatically formats descriptions (e.g., adding sub-game tags like [SMB3] Infinite Lives) to preserve sub-title identification cleanly.
  4. Concatenates the entries while re-indexing cheats = X and cheatN_* blocks sequentially.
  5. Deduplicates identical entries to prevent code collisions.
  6. Writes the finished flat file to the production cht/ directory.

Benefits

  • 100% Backward Compatibility: Distributed .cht files remain fully standard, self-contained files. No RetroArch emulator code changes are required.
  • Single Source of Truth: Modular cheat files (e.g., Super Mario Bros. 3) are updated once, and the compiler automatically updates all collection releases.
  • Clean Configuration via JSON: Keeping title relationships in JSON avoids cluttering .cht source files with non-standard directives.
  • CI/CD Integration: Builds can run automatically on GitHub Actions whenever a pull request modifies source files in src/.
Dominant language
C
Stars
14.6k
Forks
2.4k
Avg merge
2d 5h
Merged PRs (30d)
63

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from libretro/RetroArch

All issues in libretro/RetroArch

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.