RetroArch core manifest

retroarch_platforms.json lists every RomM platform this repo supports and the libretro core RetroArch uses to run it. (A libretro core is a plugin that lets RetroArch emulate one specific system.) Most cores work as soon as you download them. Some need a BIOS, firmware, or key file dropped into RetroArch's system directory first, or the game just sits on a black screen instead of booting.

This page is a summary specific to this repo, not a replacement for libretro's own documentation. For anything not covered here, or for exact file names and where to get them for each core, check libretro's core-specific BIOS documentation, the authoritative source this table was cross-referenced against.

Setup tiers used below:

• Required: the core will not boot a real game without this file in place.
• Optional: the core runs on a built-in HLE (High-Level Emulation) implementation instead of real firmware; a real file only improves accuracy or fixes specific titles.
• None: nothing to source for this platform.

A few rows are flagged because libretro's hub doesn't list this repo's exact core name (sometimes the core is newer, or just named differently than what the hub uses). Treat those as "check it yourself the first time you run into that platform," not as settled fact.

Nintendo, cartridge and handheld

Nintendo, disc and 3D

Sega

Sony

NEC PC Engine

SNK and arcade

Atari

Other handhelds and consoles

Home computers

Saves, states and imports

RetroArch sorts each core's files into a folder named for the core. The folder takes the name the core reports about itself, which isn't always the core's file name: the dolphin core reports dolphin-emu and the azahar core reports Azahar.

• In-game saves (SRAM) go in saves/<core name>/<game>.srm.
• Save states go in states/<core name>/.

The azahar core is the one exception: it nests its own Azahar/ folder under the one RetroArch already sorted it into, landing its SD card and NAND one level deeper, at saves/Azahar/Azahar/. See the 3DS bullet below.

The broker states these settings on every launch, so a setting in your own retroarch.cfg can't move saves away from where every save archive already keeps them. The platform table records each core's reported name as library_name.

A declared import can bring one .srm save into a session only on a platform whose core loads one. The platform table records this as save_ram, taken from a check of each core's source. These 25 platforms take one:

nes, famicom, snes, sfam, n64, gb, gbc, gba, virtualboy, nds, nintendo-dsi, genesis, sms, gamegear, sg1000, sega32, tg16, turbografx-cd, supergrafx, neo-geo-cd, wonderswan, wonderswan-color, jaguar, colecovision and psx.

On nds, the .srm is the melondsds core's NDS cart SRAM, exposed through the standard RETRO_MEMORY_SAVE_RAM libretro call. The older, unmaintained melonds core doesn't expose this; it manages its own .sav file instead.

On psx, the .srm is the SwanStation core's first memory card. The core loads it only while its swanstation_MemoryCards_Card1Type option stays at the default, Libretro. The broker doesn't pin this particular option, so an imported save won't load if it has been changed in RetroArch.

The other platforms refuse a .srm:

• PSP: the PPSSPP core keeps saves as SAVEDATA folders, not a .srm. The refusal names the standalone PPSSPP module instead.
• Wii and 3DS: these cores keep saves in folders, not a .srm, and a .srm is refused as unrecognised_layout. Imports place folders here instead: Wii title folders in saves/dolphin-emu/User/Wii/title/, and Azahar's SD card and NAND folders as they already sit in saves/Azahar/Azahar/ (the core nests its own Azahar/ folder under the one RetroArch already sorted it into). What each emulator takes lists the shapes.
• GameCube: the core keeps saves as GCI files in its own folders, which imports don't place yet. The refusal is shape_unverified.
• The rest: the core keeps its save in a file of its own, or has none, so it would never read a .srm. The paths below are inside the core's saves/ folder unless noted.

The broker renames an imported save after the game being launched, whatever it was called before. A save state isn't imported as a save: send it to PUT /api/session/state-file after activate.

.sav battery saves. Handhelds and sync clients often name a battery save .sav. MinUI and NextUI write <rom>.<ext>.sav, and Grout uploads files under whatever name the device gave them. On 15 platforms the core reads that file the same way it reads its own .srm, so the broker renames it to the .srm and copies the bytes unchanged. The platform table records this as sav_is_srm:

snes, sfam, gb, gbc, gba, virtualboy, nds, sms, gamegear, sg1000, sega32, tg16, turbografx-cd, supergrafx and colecovision.

Four of them have a catch:

• Game Boy and Game Boy Color: mGBA, VBA-M and cartridge dumpers add the real-time clock to the end of the file. RetroArch drops anything past the core's save size, so the save loads and the game's clock resets.
• GBA: mGBA works out the save type from its own game database, not from the file's size. A 128 KB gpSP save and a 32 KB cartridge dump both load.
• NDS: melonDS DS sizes the save from its game database. A file shorter than that is padded with zeros.

On the other platforms that take a .srm, a .sav is refused as needs_conversion, because placing it as the .srm would load the wrong data without any error. mupen64plus_next packs every N64 save type into one .srm, Mesen keeps Bandai EEPROM and CHR-battery saves in other files, and a PlayStation .srm has to be a raw memory card. Send the core's .srm on those platforms. A .rtc, .nv, .eep or .mpk file is refused the same way on every platform that takes a .srm. A platform that takes none gives these files its own refusal instead, which declared imports lists.

NeoCD's backup RAM has a similar problem even though neo-geo-cd takes a .srm import: the core reads and writes its neocd/neocd.srm in the system directory, shared across every game, before it applies the option that would scope it per game. The broker symlinks that fixed path into SAVE_DIR (save_links in the platform table), which brings it under the same per-game archive isolation as everything else.

VICE and Hatari floppy write protection

Unlike PUAE, neither VICE (c64, c-plus-4, vic-20) nor Hatari (atari-st) has a write-redirect option; they can only be told to refuse writes to the mounted disk outright (vice_floppy_write_protection, vice_easyflash_write_protection, hatari_floppy_write_protection). Pinning that on every launch would permanently block in-game floppy/cartridge saves, so the broker only seeds it: the first time a game on any of these platforms launches with no options file on disk yet, write protection is turned on to protect the ROM library by default. After that, whatever value is already on disk is left alone, including a value a player changed from RetroArch's own Quick Menu, so choosing to re-enable in-game saves (at the cost of the ROM being writable) sticks on later launches. This is core_option_seeds in the platform table, resolved against the broker's own options file by _resolve_core_options, as opposed to core_options, which is pinned on every launch and always wins over a same-named seed.

DOSBox Pure mouse

DOSBox Pure's default virtual mouse only moves while RetroArch grabs the mouse (F11). Under the stream, that grab puts the pointer under a lock that drops the absolute mouse positions selkies sends outside Gaming Mode, so the DOS cursor never moves. The broker seeds dosbox_pure_mouse_input to direct on dos, which follows the cursor position and needs no grab. As a seed it only applies to an options file that has never had it: an install that already launched a DOS game keeps its saved value, and switching to "direct" there is a Quick Menu change. A player who wants the virtual mouse back can pick it there too.

Choosing a core

Every platform above maps to one libretro core, the one listed in its table. An operator can ask for a different core on that platform instead, in RomM's config.yml, shorthand or block form:

platforms:
  snes: retroarch:bsnes      # shorthand: emulator:core, split on the first ':'
  n64:                       # block form
    emulator: retroarch
    core: parallel_n64

snes: retroarch with an indented core: under it is invalid YAML; use one of the two forms above.

core: needs a RomM release newer than 5.3.1. RomM 5.3.1 and older read the shorthand retroarch:bsnes as the emulator's name and send it to the broker whole, and every launch on that platform fails with a 422 unknown emulator naming the upgrade. The block form's core: key is ignored with a warning there, so the platform keeps its default core. Until you upgrade, set the platform to plain retroarch.

Tiers

core: accepts one of four kinds of core:

• default: the platform's own core from the tables above, the one this repo has tested the most (the "best tested" core in the table below).
• vetted: an alternate this repo has specifically tested on that platform.
• untested: any other core in the catalog that shares a file extension with the platform. It launches with every feature a vetted core has, but the broker can't be certain of its save layout ahead of time, so it launches with a warning and a checked, rather than fixed, save/state location. It boots only files with one of those shared extensions, or a .zip or .7z holding one, which RetroArch unpacks before the core sees it.
• blocked: a core this repo has confirmed is broken on that platform. It refuses to launch unless you opt in: experimental_cores: true on the container or on a platform block in RomM's config.yml (the platform wins), or RETROARCH_EXPERIMENTAL_CORES=true on the broker container. Either is enough, and neither is on by default.

Finding your options

• GET /api/retroarch/cores?platform=<slug> lists every core offered on a platform, its tier, whether it's verified, and its library_name (the folder it sorts saves and states into, only the catalog's guess for an untested or blocked core, and null for a name activate would leave out); leave platform off to get every platform at once. It needs the X-Broker-Secret header, and a platform RetroArch has no core for answers 404.
• scripts/sync_core_info.py --tiers [--platform <slug>] prints each core's tier and display name from the command line, for every platform or just one.

Saves and states when switching cores

• An in-game save (.srm) carries over automatically when one exists for the old core and the new core also takes one; RetroArch writes it into the new core's own save folder from then on. Switching back later carries it the other way.
• On an untested or blocked core the save is copied, not moved, because that core's save folder is a guess until it writes there. The original stays in the old core's folder.
• A carry never replaces a save that is as new as the incoming one. When the incoming save is newer, the one it replaces is kept beside it as <game>.srm.bak.
• A save state never carries over. A state left behind by another core is never loaded, even if one still exists on disk for it.
• The pre-switch archive isn't deleted: it stays in RomM's own save picker, so switching cores never loses access to what was there before.

Report how a core works

Tried a core, or want to know how it did for someone else first? File a report: Report how a core works.

A core moves from untested to vetted once it passes this repo's own vetting test and has a few reports backing it up. A core moves to blocked once a report confirms it's actually broken on that platform.

A default core tagged (untested) in the table below belongs to a platform nobody has booted a real game on yet. It launches like any other, but the broker logs a warning each time and the cores route reports it as unverified. The tag comes off once a report confirms it works.

Core tiers

Generated by scripts/sync_core_info.py --docs; run it after changing retroarch_core_tiers.json or the platform table, and commit the result.

Source

Generated from webstation_broker/emulators/retroarch_platforms.json and webstation_broker/emulators/retroarch.py, cross-referenced against libretro's BIOS Information Hub. Update this table if platform mappings, core_source overrides, assets, save_subtrees, library_name, save_ram, sav_is_srm, savestate, core_options, core_option_seeds, or save_links fields change in retroarch_platforms.json.