EmulationStation Documentation

The gamelist.xml file provides metadata (names, images, descriptions, ratings) for games. If a system has at least one game with an image specified, ES switches to a 'detailed view'.

Scraping Metadata:

• Bulk Scraping: Press Start in the menu and choose SCRAPER. Adjust settings and select SCRAPE NOW.
• Single Game Scraping: Find the game in the list, press Select, choose EDIT THIS GAME'S METADATA, and press the SCRAPE button.
• Manual Editing: Use the metadata editor via Select -> EDIT THIS GAME'S METADATA.

Note: Use the --ignore-gamelist CLI flag to bypass gamelist.xml and force the non-detailed view.

Most elements use pos (position) and size properties of the NORMALIZED_PAIR type. These are normalized relative to the parent object's size (usually the screen).

• Coordinates: <pos>0 0</pos> is the top-left corner; <pos>1 1</pos> is the bottom-right corner.
• Y-Axis: Positive Y values point downwards.
• Off-screen: You can use values outside the [0..1] range to place elements partially or completely off-screen.
• Aspect Ratio: For image elements, if you specify only one axis in size (e.g., width) and set the other to 0, EmulationStation automatically calculates the missing dimension to maintain the image's aspect ratio.

To add support for different gaming systems in EmulationStation, you must configure the es_systems.cfg file. Each system is defined by a <system> XML block containing the following keys:

• <name>: Internal identifier for the system.
• <fullname>: The display name of the system.
• <path>: The directory where ROMs are located.
• <extension>: A space-separated list of supported file extensions.
• <command>: The shell command used to launch the emulator. Use %ROM% as a placeholder for the full path to the ROM file.
• <platform>: The platform identifier.
• <theme>: The name of the theme to use for this system.

When developing or troubleshooting themes, launch EmulationStation with the following switches:

• --debug: Enables error messages in the terminal/window so you don't have to check log files.
• --windowed: Runs ES in a windowed mode.

If --debug is enabled, you can use Ctrl-R to reload the current gamelist view and system view to see changes immediately.

You can use either RetroArch or Mupen64Plus for Nintendo 64 support.

RetroArch (requires a core like libretro-mupen64plus):

<system>
  <name>n64</name>
  <fullname>Nintendo 64</fullname>
  <path>/path/to/roms</path>
  <extension>.z64 .zip .n64</extension>
  <command>retroarch --fullscreen -L /usr/lib/libretro/mupen64plus_libretro.so %ROM%</command>
  <platform>n64</platform>
  <theme>n64</theme>
</system>

Mupen64Plus:

<system>
  <name>n64</name>
  <fullname>Nintendo 64</fullname>
  <path>/path/to/roms</path>
  <extension>.z64 .zip .n64</extension>
  <command>mupen64plus --nogui --noask --noosd --fullscreen %ROM%</command>
  <platform>n64</platform>
  <theme>n64</theme>
</system>

You can use either RetroArch or Mednafen for NES support.

RetroArch (requires a core like libretro-fceumm):

<system>
  <name>nes</name>
  <fullname>Nintendo Entertainment System</fullname>
  <path>/path/to/roms</path>
  <extension>.nes .NES .zip</extension>
  <command>retroarch --fullscreen -L /usr/lib/libretro/fceumm_libretro.so %ROM%</command>
  <platform>nes</platform>
  <theme>nes</theme>
</system>

Mednafen:

<system>
  <name>nes</name>
  <fullname>Nintendo Entertainment System</fullname>
  <path>/path/to/roms</path>
  <extension>.nes .NES .zip</extension>
  <command>mednafen -video.fs 1 %ROM%</command>
  <platform>nes</platform>
  <theme>nes</theme>
</system>

The gamelist.xml file defines metadata for a system's games (names, images, descriptions, etc.). EmulationStation (ES) searches for this file in three locations, using the first one it finds:

1. [SYSTEM_PATH]/gamelist.xml (The system's ROMs folder)
2. ~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml
3. /etc/emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml

All metadata must be enclosed within a <gameList> root tag. Individual entries are wrapped in either <game> or <folder> tags.

<gameList>
	<game>
		<path>/home/pi/ROMs/nes/mm2.nes</path>
		<name>Mega Man 2</name>
		<desc>Mega Man 2 is a classic NES game which follows Mega Man as he murders eight robot masters in cold blood.</desc>
		<image>~/.emulationstation/downloaded_images/nes/Mega Man 2-image.png</image>
	</game>
</gameList>

To include Steam games in EmulationStation, follow these steps:

1. Create a directory for Steam games:

   mkdir -p ~/.emulationstation/steam

2. For each game, create a text file in ~/.emulationstation/steam/.

   • The filename must be the game's name.
   • The file content must be the Steam Application ID (found on the game's Steam store page).

   Example for The Binding of Isaac: Rebirth (ID 250900):

   cd ~/.emulationstation/steam
   echo "250900" >> "The Binding of Isaac: Rebirth.txt"

3. Add the following system configuration to es_systems.cfg:

<system>
  <name>steam</name>
  <fullname>Steam</fullname>
  <path>~/.emulationstation/steam</path>
  <extension>.txt</extension>
  <command>steam steam://rungameid/$(tail %ROM%)</command>
  <platform>pc</platform>
  <theme>steam</theme>
</system>

To reduce redundancy, you can target multiple views or multiple elements of the same type by providing a comma-separated or whitespace-delimited list in the name attribute.

Multiple Views

Use a list in the <view> name attribute to apply properties to several screens at once (e.g., basic, grid, system).

Multiple Elements

Use a list in the element name attribute to apply properties to multiple elements of the same type (e.g., applying one color to all metadata labels).

Note: The element list method only works if all targeted elements share the same element type.

<!-- Theming multiple views -->
<view name="basic, grid, system">
	<image name="logo">
		<path>./snes_art/snes_header.png</path>
	</image>
</view>

<!-- Theming multiple elements of the same type -->
<text name="md_lbl_rating, md_lbl_releasedate, md_lbl_developer">
	<color>48474D</color>
</text>