batocera-roms

name	batocera-roms
description	Use when working with ROMs and gamelists on a Batocera cabinet: figuring out which directory a system's ROMs go in, why a game does not appear in the menu, which file formats and extensions a system accepts, curating a large library by hiding rather than deleting, editing gamelist.xml safely, cleaning up multi-disc games, or verifying dumps against No-Intro/Redump DATs. Covers extensionless-ROM-in-zip failures, the 3DO/Opera no-m3u trap, cave3rd, and the es_systems_custom.cfg landmine. Not for shaders/bezels (batocera-display), or ROM directories renamed by a Batocera version upgrade (batocera-maintenance).
compatibility	Requires SSH access to a Batocera host (tested on v41-v43).

Batocera ROMs

Managing the game library: where ROMs live, why they do or don't show up, how to curate a big collection without deleting anything, and how to verify dumps. Assumes the connection pattern and safety doctrine from batocera-ops.

System directories

ROMs live in /userdata/roms/<system>/, one directory per system. The directory name is Batocera's internal system name, which is not always the obvious one. Don't guess — look it up on the box:

# Every system Batocera knows, with its dir name and display name:
SSHB "grep -E '<name>|<fullname>' /usr/share/emulationstation/es_systems.cfg"

# What you actually have ROMs for:
SSHB "ls /userdata/roms/"

Names that trip people up: Cave CV1000 arcade lives in cave3rd (not cv1000); Odyssey 2 is odyssey2 (renamed from o2em); Half-Life is halflife (renamed from xash3d_fwgs). Directory renames across versions are common — the batocera-maintenance migration reference lists the ones that bite.

Why a game doesn't appear

In rough order of likelihood:

1. Wrong extension for that system. Each system accepts a fixed set of extensions; a file with any other extension is invisible to ES. Check the accepted list: SSHB "grep -A2 '<system>' /usr/share/emulationstation/es_systems.cfg | grep extension". A bare .bin is a frequent offender — for many disc systems .bin is not an ES extension (you need a .cue or .chd).
2. It's hidden. <hidden>true</hidden> in gamelist.xml, or its whole system is in the ES HiddenSystems list. Hidden games still exist on disk — this is a feature, see curation below.
3. Extensionless ROM inside a zip. ES lists the .zip, but the emulator refuses to load it because the inner file has no recognizable extension. See the formats reference — this fails silently (RetroArch exits ~1s, status 1, "Could not read content file").
4. A custom system-list file overrode the stock list. If a whole swath of systems vanished, suspect es_systems_custom.cfg — see the landmine below.

gamelist.xml anatomy

Each system's /userdata/roms/<system>/gamelist.xml is per-game metadata:

<gameList>
  <game>
    <path>./Super Mario World (USA).sfc</path>
    <name>Super Mario World</name>
    <desc>...</desc>
    <image>./media/images/Super Mario World (USA).png</image>
    <hidden>true</hidden>          <!-- present + "true" = hidden from menu -->
    <favorite>true</favorite>
  </game>
</gameList>

• <path> is relative to the system dir and includes the extension. It's the join key to the file on disk.
• Removing the <hidden> element (or setting it to anything but true) unhides.
• ES rewrites this file on exit. Never edit it while ES is running and then let ES exit cleanly — it clobbers your edit. Stop ES or SIGKILL-restart it (see batocera-ops → emulationstation reference). Back the file up first.

Curation: hide, don't delete

The core methodology for taming a large or messy library, e.g. building a focused view for an arcade cabinet: set <hidden>true</hidden>, never rm.

Why hiding wins:

• Reversible in one flag. ROMs stay on disk; flip the flag to restore.
• Non-destructive — aligns with the batocera-ops doctrine on a shared machine. A wrong call costs a flag flip, not a re-download.
• Composable — you can layer passes (per-game hides, cross-platform dedup, regional-variant dedup) and roll any one back independently by restoring that pass's gamelist backup.

Workflow:

1. Back up the gamelist(s) you'll touch: cp gamelist.xml gamelist.xml.bak-<tag>.
2. Stop ES (or plan a SIGKILL-restart) so your edits survive.
3. Edit <hidden> flags — scripted for anything past a handful.
4. Restart ES and verify counts via the API: curl -s http://127.0.0.1:1234/systems/<system>/games and count hidden entries.

Methodology detail (system-level HiddenSystems, cross-platform canonicalization / 1G1R, regional and format dedup) is in references/curation.md. It is method only — bring your own taste; there are no game lists here.

Multi-disc games

Multi-disc CD games (PSX, Saturn, 3DO, Sega CD…) each show every disc as its own menu entry by default, cluttering the list. The clean fix — one visible entry per game, remaining discs hidden, per-disc launch still possible — plus the disc-swap mechanics that differ by emulator, is in references/formats-and-quirks.md. A ready-to-adapt implementation for 3DO is scripts/fix-3do-multidisc.py. Do not reach for .m3u on 3DO/Opera — that core doesn't support playlists (a documented trap the script explains).

Format landmines

Full detail in references/formats-and-quirks.md; the ones that cost the most time:

• es_systems_custom.cfg REPLACES the stock system list, it does not merge. Drop a custom system definition in as es_systems_custom.cfg and ES boots with only your custom systems — every stock system disappears. To add a system, use a differently-named merge file, not es_systems_custom.cfg.
• Extensionless ROM inside a zip → silent load failure. unzip -Z1 *.zip and check the inner suffix; rezip with a proper extension.
• 3DO/Opera has no .m3u support; multi-disc needs the per-entry approach.
• Bare .bin disc images are invisible on systems whose ES extension list wants .cue/.chd. Generate a .cue.

Verifying dumps against DATs

To confirm your ROMs are known-good dumps (right data, not just right filename), verify against No-Intro DATs (cartridges, hash match) and Redump DATs (discs, extract + hash). Methodology, tiers, and known limits (GD-ROM CHDs that can't hash-verify, Sega CD CDDA mismatches) are in references/dat-verification.md, with a ready-to-run scripts/dat-verify.py.