[Feature Request] Managing Multi-Title Game Collections using JSON Build Manifests
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
Summary
RetroArch currently treats each .cht file as self-contained, which creates maintenance problems when multiple game variants share overlapping cheat codes. For example:
- [Super Mario All-Stars + Super Mario World (USA).cht](https://www.google.com/search?q=https://github.com/libretro/libretro-database/blob/master/cht/Nintendo%2520-%2520Super%2520Nintendo%2520Entertainment%2520System/Super%2520Mario%2520All-Stars%2520%252B%2520Super%2520Mario%2520World%2520(USA).cht)
- [Super Mario All-Stars (USA).cht](https://github.com/libretro/libretro-database/blob/master/cht/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/Super%20Mario%20All-Stars%20(USA).cht)
- [Super Mario World (USA).cht](https://github.com/libretro/libretro-database/blob/master/cht/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/Super%20Mario%20World%20(USA).cht)
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
.chtfiles 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).chtsrc/snes/sub/Super Mario All-Stars - Super Mario Bros. 2 (USA).chtsrc/snes/sub/Super Mario All-Stars - Super Mario Bros. 3 (USA).chtsrc/snes/sub/Super Mario All-Stars - Super Mario Bros. - The Lost Levels (USA).chtsrc/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:
- Iterates over target definitions in the JSON manifest.
- Loads all referenced source
.chtfiles sequentially for titles with multiple titles. - Automatically formats descriptions (e.g., adding sub-game tags like
[SMB3] Infinite Lives) to preserve sub-title identification cleanly. - Concatenates the entries while re-indexing
cheats = XandcheatN_*blocks sequentially. - Deduplicates identical entries to prevent code collisions.
- Writes the finished flat file to the production
cht/directory.
Benefits
- 100% Backward Compatibility: Distributed
.chtfiles 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
.chtsource 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
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from libretro/RetroArch
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
libretro/RetroArch#20108 · 3 comments ·
Maintainers usually reply within 2 days
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
libretro/RetroArch#20061 · 3 comments ·
Maintainers usually reply within 2 days
-
[Feature Request] [UX] Improve descriptions for "Rewind Buffer Size" and "Rewind Buffer Size Step"Openfeature request
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
libretro/RetroArch#19915 · 2 comments ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 2 days
All issues in libretro/RetroArch
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
schrodinger/pymol-open-source#532 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
facebookexperimental/hermit#347 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 86/100
CTSRD-CHERI/cheribsd#2769 ·
Maintainers usually reply within 2 days
-
good first issue not started
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
CU-Robotics/firmware#257 ·
-
documentation good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 82/100