Es_systems.cfg

[Karina Edling]

Thistutorial is intended for those who wish to add a new system in EmulationStation. For example if you are looking to create a system for favourite games across different platforms or a separate system for roms hacks.

Each system in EmulationStation is defined in the file es_systems.cfg. The default version resides in the /etc/emulationstation folder. It is recommended that you make a copy of this file into the /opt/retropie/configs/all/emulationstation folder. The default version will be overwritten whenever you make updates to your RetroPie system so any manual changes such as a new system will be lost. Remember if you do make any updates to RetroPie then you should add any updates to /etc/emulationstation/es_systems.cfg to the custom version in the /opt/retropie/configs/all/emulationstation folder.

To add a new system to EmulationStation, you will need to create a new entry beginning with a tag and ending with a tag in /opt/retropie/configs/all/emulationstation/es_systems.cfg. Before you make any changes, you should exit EmulationStation first by pressing F4 on a keyboard or using the Quit EmulationStation option in the start menu.

This is the short name used by ES internally as well as the text used in the EmulationStation UI unless replaced by an image or logo in the theme. It is advised to choose something short and descriptive, e.g. favourites, hacks.

This is the folder where the roms in your new system will be located. This folder, e.g. /home/pi/RetroPie/roms/favorites, may need to be created if it does not already exist. Multiple paths are not currently permitted.

Roms can be launched using shell scripts or the runcommand script. Both methods are involved so it is your choice how you wish to proceed. The entries for these tags are covered below so check the steps required if you are unsure which is best for you.

This information is used for scraping. This tag is optional so it may be best to omit it. If you intend to use multiple emulators, for a favourites section for instance, then you can use existing gamelists to manually create a new gamelist. If you are creating a section for mods or hacks, then it's unlikely you'll be able scrape metadata.

This is the theme EmulationStation loads from the current theme set. You can use an existing theme, e.g. nes, or you can create a new one. If you do the latter, then it may an idea to make it the same as the tag.

Tip If you are creating a favourites section where you have roms in two folders, then, to save space, you can use symbolic links. For example, if you wish to have Contra available in the NES system and a new Favorites section, then you can create a symbolic link with the command:

If your system appears as above, then a theme needs to be defined for the new system. It is recommended that you copy your current theme from /etc/emulationstation/themes to the /opt/retropie/configs/all/emulationstation/themes folder for the similar reasons why the es_systems.cfg file was copied. It's a good idea to rename the copied folder, e.g. carbon-custom, so that the default and customised themes can be differentiated in the EmulationStation UI.

In the hacks example above, EmulationStation looks for a theme in the hacks folder of the current theme as defined in the tag in your custom es_systems.cfg file. The simplest way to do this is to copy an existing folder in the themes folder and rename it to hacks. You can then add or replace images or logos to the art folder and edit the theme.xml file to incorporate them.

The tag tells the runcommand script to look for a emulators.cfg file in the hacks folder in /opt/retropie/configs for launch commands. The hacks folder does not exist by default so will need to be created as well as the emulators.cfg file in that folder. The simplest way to do this is to copy an existing folder in /opt/retropie/configs/ and rename it.

For example, to launch the NES rom hack Mario Adventure, make a copy of the nes folder in /opt/retropie/configs and rename it hacks. The folder will already include an emulators.cfg file with appropriate commands to launch NES roms.

Say that you now want to add the SNES rom hack Super Metroid: Redesign to your hacks section. Open /opt/retropie/configs/snes/emulators.cfg and copy the line for the emulator you wish to use, eg lr-snes9x2010, into the emulators.cfg file in the hacks folder. This file will now read as follows:

To launch Super Metroid: Redesign from EmulationStation, you will need to bring up the runcommand menu by pressing any key on a keyboard or button 0 on your controller before the game begins. In the menu, choose the lr-snes9x2010 as the emulator for your rom and then launch.

This process can be repeated for more systems by adding launch commands to emulators.cfg and using the runcommand menu to select the appropriate emulator for each rom. Make sure to add the extensions for your roms to the entry in your custom es_systems.cfg file.

Tip: Before you begin editing files, it may be an idea to make a list of emulators you wish to use, find their launch commands and then add them to the emulators.cfg file in one go. You can do similar for the accepted extensions.

Tip: If you're not sure what the launch command for a system is, then check the emulators.cfg file for that system and copy the launch command replacing %ROM% with the full path and name of the rom.

EmulationStation displays systems based on a file called es_systems.cfg. In other distributions, this is typically the only file. However, in Batocera and higher, the /userdata/system/configs/emulationstation/es_systems_.cfg can be used as an overlay to the original /usr/share/emulationstation/es_systems.cfg file.

If preferred, the entire file can be overridden by instead using /userdata/system/configs/emulationstation/es_systems.cfg. Be careful if doing this, as the entire notion of maintaining this file as Batocera upgrades its internals (namely Python) thus rely on you. This is really only suitable if you never intend on updating Batocera again.

Whenever Batocera is upgraded, its version of Python used may also change. This means if you are using an es_systems.cfg which manually defines the (for example: /usr/lib/python2.7/site-packages/configgen/emulatorlauncher.py which is calling an older Python version), it will need to be updated accordingly.

You can create a file named es_systems_.cfg where is a name you wish to use for it. This file needs to follow the same conventions as the original es_systems.cfg, but does not need to include the entirety of the file. For example:

would only affect the 3DO system on your Batocera, with the rest of the systems still referring to /usr/share/emulationstation/es_systems.cfg for their system CFG. When both files contain the same , es_systems_.cfg will take priority.

In case you'd like to have complete control over ES systems CFG, you can still use the two previous methods to completely override it (ie. using overlays or copying the entirety of es_systems.cfg to /userdata/system/configs/emulationstation/es_systems.cfg without appending a custom system name to its filename).

Batocera is smart enough to only apply the changes you make. Such as, if the only thing you need to change for a system is its ROM path, you can use the following in your /userdata/system/configs/emulationstation/es_systems_pico8.cfg:

Here, it'll use the folder /userdata/roms/pico8real/ to look for Pico-8 games instead of the regular one, and use the rest of the configuration from the /usr/share/emulationstation/es_systems.cfg file.

The and paths in this example are kept the same such that they can still use the defaults as specified by Batocera. If you really want to use a unique , you'll have to manually specify your default emulator in batocera.conf. For instance if you were defining a new system with cps1 then the following would be added to batocera.conf:

You must use a unique field when adding a new system if you wish to keep the old one in addition. However, if using duplicate shortnames is a necessity and you still want the new and old system to exist simultaneously, you can also put both systems in a single CFG file.

Despite being specified in the es_systems_megadrivehacks.cfg file, Batocera doesn't actually use this as the default when launching an emulator. It instead looks for its own list of defaults for its configgen.

Batocera introduced the ability to copy the file to /userdata/system/configs/emulationstation/es_system.cfg and edit it there, however this meant you would have to compare and copy the file every update, as well as appending your changes and working out if something had broken (as Batocera adds new systems nearly every major release and changes the launch methods for other systems too).

The following RetroArch settings have been recommended by Vanfanel to minimize input lag. Please note that while these settings will reduce input lag, they may be more difficult for the system and cause some performance penalties on harder to emulate systems.

In AmberELEC there is a global es_systems.cfg file that is located in /usr/config/emulationstation/es_systems.cfg. This file can not be altered to make sure that future updates can still add new features to the system. However, there is still the possibility to add your own extensions. You can create your own extensions to the standard es_systems.cfg.

The directory for custom config files is /storage/.config/emulationstation/. You can create an extension to es_systems.cfg by putting a file named es_systems_custom.cfg, where custom is whatever you want, usually a description of what the extension does.

You can also name your file es_systems.cfg, but be aware that it will automatically be renamed to es_systems.oldcfg-rename-to:es_systems_custom.cfg-if-needed to make sure there is no old configuration file left from an old install. The renaming takes place on every system update. If you need this file or want to maintain your own es_systems.cfg, be sure to give it a custom tag es_systems_custom.cfg.

3a8082e126