libretro/platforms

Platform Configs

How platform YAML files work and where subdirectory requirements come from.

Files

• _registry.yml -- platform metadata (name, status, display order)
• _shared.yml -- shared file groups with canonical destinations
• <platform>.yml -- per-platform BIOS declarations
• Inheritance: lakka.yml inherits retroarch, retropie.yml inherits retroarch

Shared groups (_shared.yml)

The subdirectory a BIOS goes into is determined by the libretro core, not the platform. NP2kai expects np2kai/BIOS.ROM whether you're on RetroArch, Batocera, or Recalbox. Only base_destination varies (system/ vs bios/).

Shared groups define files with correct destinations once. Platforms reference them via includes: [group_name] in their system definitions. load_platform_config() in common.py resolves includes at load time, deduplicating by filename.

When to use shared groups: whenever 2+ platforms share files that a core expects in a specific subdirectory. The group carries the correct destination so platforms can't drift.

For RetroArch specifically, libretro_scraper.py injects includes: references and applies subdirectory prefixes via CORE_SUBDIR_MAP during generation. Manual edits to retroarch.yml will be overwritten on next scrape.

Data directories (_data_dirs.yml)

Some cores need entire directory trees, not just individual BIOS files. Dolphin needs dolphin-emu/Sys/ (GameSettings, DSP firmware, fonts), PPSSPP needs PPSSPP/ (font assets, shaders), blueMSX needs Databases/ and Machines/ (machine configs).

These are defined in _data_dirs.yml as a central registry with upstream source URLs. The pack generator auto-refreshes from upstream before building (use --offline to skip). Data directories live in data/ (not bios/) and are NOT indexed in database.json.

Adding a data directory:

1. Add entry to _data_dirs.yml with source URL, extraction path, cache location
2. Reference via data_directories: [{ref: key, destination: path}] in platform systems
3. For scraper-generated platforms, add to SYSTEM_DATA_DIRS in the scraper
4. Run python scripts/refresh_data_dirs.py --key <name> to populate the cache

Subdirectory reference

Each entry documents where the requirement comes from. Check these source files to verify or update the paths.

Core	Subdirectory	Source
NP2kai	np2kai/	libretro-np2kai/sdl/libretro.c
PX68k	keropi/	px68k/libretro/libretro.c
QUASI88	quasi88/	quasi88/src/libretro.c
Kronos	kronos/	libretro-kronos/libretro/libretro.c
ep128emu	ep128emu/rom/	ep128emu-core/src/libretro.cpp
Flycast	dc/	flycast/shell/libretro/libretro.cpp
FBNeo NeoCD	neocd/	fbneo/src/burn/drv/neogeo/neo_run.cpp
Fuse	fuse/	fuse-libretro/fuse/settings.c
hatari	hatari/tos/	hatari/src/tos.c

Full libretro docs: https://docs.libretro.com/library/<core>/

Adding a platform

1. Create platforms/<name>.yml
2. Set base_destination (system or bios), verification_mode, hash_type
3. Use includes: [group] for systems with subdirectory requirements
4. Use inherits: retroarch to share RetroArch's file set
5. Add platform-specific overrides in overrides.systems
6. Test: python scripts/verify.py --platform <name>

Adding a shared group

1. Add the group to _shared.yml with a source ref comment
2. Include: filename, destination with subdirectory prefix, required flag, hashes
3. Reference via includes: [group_name] in platform system definitions
4. For scraper-generated platforms, add the mapping in the scraper's SYSTEM_SHARED_GROUPS dict so it persists across regeneration

Verification modes

Platform	Mode	Native logic	Upstream source
RetroArch	existence	path_is_valid() -- file exists	core_info.c
Lakka	existence	inherits RetroArch	idem
RetroPie	existence	inherits RetroArch	idem
Batocera	md5	md5sum() + checkInsideZip()	batocera-systems
RetroBat	md5	MD5 check via JSON config	batocera-systems.json
EmuDeck	md5	MD5 whitelist per system	checkBIOS.sh
Recalbox	md5	multi-hash comma-separated	es_bios.xml + Bios.cpp
RetroDECK	md5	MD5 per file via component manifests	api_data_processing.sh
RomM	md5	size + any hash (MD5/SHA1/CRC32)	firmware.py