ES-DE Gamelist Migration: Repair Paths, Media Matching, and System Definitions

ES-DE is a frontend, not a universal database importer for every EmulationStation fork. A collection can contain the right games and still show blank metadata, missing systems, or absent artwork after a migration because path syntax, system identifiers, media lookup, and data directories differ. Treat migration as a schema conversion and validate it on one system before changing the whole library.

The instructions below use ES-DE’s current upstream user guide and install documentation. Exact home-directory locations vary by platform and by installer versus portable package; check the path shown by your ES-DE build rather than copying a Linux path into Windows or Android.

Freeze and inventory the source library

Close both frontends before copying files. Back up the source gamelist.xml files and media tree unchanged, then make a working copy. Record the source frontend, ES-DE version, ROM root, system folder names, and media root. Keep scraped metadata distinct from filenames and artwork: a matching screenshot is not proof that a ROM is the correct region or revision.

Start with one small system containing a few legally acquired titles. Preserve disc descriptors such as CUE, GDI, or M3U files alongside their referenced tracks. Verify every referenced path before launching anything; moving only the primary disc file can strand audio tracks or other discs.

Put gamelists where ES-DE looks for them

ES-DE stores per-system gamelist.xml files under its application data tree, normally ~/ES-DE/gamelists/<system name>/gamelist.xml on current desktop layouts. This is separate from the ROM directory tree. If the source frontend stored gamelist.xml beside ROMs, copy it into ES-DE’s corresponding gamelist directory; ES-DE does not automatically read those files from arbitrary ROM folders.

In an XML game entry, the path must resolve from the system’s ROM path or be a valid absolute filesystem path. When migrating legacy EmulationStation XML, ES-DE’s guide calls out a leading ./ for relative paths. For example:

<game>
  <path>./Example Game (Region).cue</path>
  <name>Example Game</name>
</game>

Do not add ./ to an absolute path, and do not mass-rewrite paths until the test system displays and launches correctly. Validate XML syntax, case, extension, and every descriptor-to-track reference. A filename with a title-like label is not sufficient to identify a dump.

Map system names before moving folders

ES-DE’s system identifier controls directory discovery, gamelist location, launch definition, and scraper platform mapping. Other frontends do not always use the same identifier. The official guide gives sg1000 versus sg-1000 as one example of a mismatch during migration from Batocera, RetroBat, or Recalbox.

Use ES-DE’s generated systems.txt and per-system systeminfo.txt files to inspect the installed names and supported extensions for your build. These files are useful discovery aids, not a guarantee that an emulator is installed or that a particular content file is valid. Create an explicit mapping table from old system name to ES-DE system name and path; rename only after the mapping is backed up and tested.

Understand how artwork is resolved

ES-DE’s current model does not depend on legacy <image> tags in the same way older EmulationStation setups did. It can match downloaded media to the game/ROM filename under the configured media directory, commonly ~/ES-DE/downloaded_media. Therefore a library can show titles and descriptions while missing screenshots because the media tree, basename, or system directory does not match.

Keep original media in a backup. Confirm the active media directory in the settings interface and check one game at a time for the expected image/video/manual. If you scrape again, review the target directories and avoid overwriting carefully curated files before the migration has been accepted.

Extend definitions without forking the bundled file

ES-DE ships a comprehensive es_systems.xml containing system names, ROM paths, extensions, launch commands, and platform mapping. Do not edit the bundled copy inside the application installation: upgrades can replace it. For a custom system or override, place only the additions/overrides in the documented custom_systems/es_systems.xml location. Keeping the custom file small makes it easier to compare against upstream changes and to diagnose a bad launch command.

Choose a system-specific alternative emulator only after the default launch works. Check that the emulator is installed, the expected core or executable exists, and the content format is supported. If a game opens to a shell or a wrong emulator, inspect the system definition and ES-DE log rather than changing every platform at once.

Use gamelist switches as diagnostics, not as repairs

The --gamelist-only option limits discovery to entries already listed in gamelists and persists its corresponding setting; it is useful to isolate metadata parsing but can make newly added games appear to vanish until disabled. --ignore-gamelist ignores gamelist files for that session and is a different diagnostic. After testing either mode, restore the normal setting and restart.

ES-DE writes es_log.txt in its data tree; Debug mode or the --debug argument can add detail. Sanitize personal paths before sharing a log. Do not include game files, BIOS/firmware, keys, or saves in a support bundle.

Acceptance checklist

For each migrated system, confirm: its ES-DE name and ROM path are correct; the gamelist parses; a representative title and its artwork appear; one game launches through the expected emulator; controller input and clean exit work; and a native in-game save still loads after restart. Then compare the migrated entry count against the original manifest and investigate missing, duplicate, or unexpected titles before deleting the untouched source copy.

Related:

Sources: