diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e1258a52..94579c16e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ ### Detailed list of changes * Added alternative emulators support where additional emulators can be defined in es_systems.xml and be selected system-wide or per game via the user interface +* Added the ability to make complementary game system customizations without having to replace the entire bundled es_systems.xml file * Added a menu option to change the application exit key combination * Expanded the themeable options for "helpsystem" to support custom button graphics, dimmed text and icon colors, upper/lower/camel case and custom spacing * Removed the "Choose" entry from the help prompts in the gamelist view diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 273b4e4c3..cad4304cd 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1399,16 +1399,16 @@ For the following options, the es_settings.xml file is immediately updated/saved ## es_systems.xml -The es_systems.xml file contains the system configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use. +The es_systems.xml file contains the game systems configuration data for ES-DE, written in XML format. This defines the system name, the full system name, the ROM path, the allowed file extensions, the launch command, the platform (for scraping) and the theme to use. -ES-DE ships with a comprehensive `es_systems.xml` configuration file and normally you shouldn't need to modify this. However there may be special circumstances such as wanting to use alternative emulators for some game systems or perhaps you need to add additional systems altogether. +ES-DE ships with a comprehensive `es_systems.xml` file and most users will probably never need to make any customizations. But there may be special circumstances such as wanting to use different emulators for some game systems or perhaps wanting to add additional systems altogether. -To make a customized version of the systems configuration file, it first needs to be copied to `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden using the --home command line option.) +To accomplish this, ES-DE supports customizations via a separate es_systems.xml file that is to be placed in the `custom_systems` folder in the application home directory, i.e. `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden via the --home command line option.) + +This custom file functionality is designed to be complementary to the bundled es_systems.xml file, meaning you should only add entries to the custom configuration file for game systems that you actually want to add or override. So for the example of customizing a single system, this file should only contain a single `` tag. The structure of the custom file is identical to the bundled file with the exception of an additional optional tag named ``. If this is placed in the custom es_systems.xml file, ES-DE will not load the bundled file. This is normally not recommended and should only be used for special situations. At the end of this section you can find an example of a custom es_systems.xml file. The bundled es_systems.xml file is located in the resources directory that is part of the application installation. For example this could be `/usr/share/emulationstation/resources/systems/unix/es_systems.xml` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS or `C:\Program Files\EmulationStation-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed. -Note that when copying the bundled es_systems.xml file to ~/.emulationstation/custom_systems/, it will completely replace the default file processing. So when upgrading to future ES-DE versions, any modifications such as additional game systems will not be enabled until the customized configuration file has been manually updated. - It doesn't matter in which order you define the systems as they will be sorted by the full system name inside the application, but it's still probably a good idea to add them in alphabetical order to make the file easier to maintain. Keep in mind that you have to set up your emulators separately from ES-DE as the es_systems.xml file assumes that your emulator environment is properly configured. @@ -1424,7 +1424,7 @@ Below is an overview of the file layout with various examples. For the command t + special situations so it's normally recommended to keep this tag unique. --> snes @@ -1567,6 +1567,42 @@ And finally one for Windows: ``` +As well, here's an example on Unix of a custom es_systems.xml file placed in ~/.emulationstation/custom_systems/ that overrides a single game system from the bundled configuration file: +```xml + + + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + +``` + +If adding the `` tag to the file, the bundled es_systems.xml file will not be processed. For this example it wouldn't be a very good idea as NES would then be the only platform that could be used in ES-DE. + +```xml + + + + + + nes + Nintendo Entertainment System + %ROMPATH%/nes + .nes .NES .zip .ZIP + /usr/games/fceux %ROM% + nes + nes + + +``` + ## es_find_rules.xml This file makes it possible to define rules for where to search for the emulator binaries and emulator cores. diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 8999bee1b..a42c00152 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -864,9 +864,9 @@ EmulationStation borrows the concept of "nine patches" from Android (or "9-Slice - Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. * `textColor` - type: COLOR. Default is 777777FF. -* `textColorDimmed` - type: COLOR. Default is the same value as textColor. +* `textColorDimmed` - type: COLOR. Default is the same value as textColor. Must be placed under the 'system' view. * `iconColor` - type: COLOR. Default is 777777FF. -* `iconColorDimmed` - type: COLOR. Default is the same value as iconColor. +* `iconColorDimmed` - type: COLOR. Default is the same value as iconColor. Must be placed under the 'system' view. * `fontPath` - type: PATH. * `fontSize` - type: FLOAT. * `entrySpacing` - type: FLOAT. Default is 16.0. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index dcbb2d736..83dd4cae3 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -77,9 +77,9 @@ On Unix this means /home/\/.emulationstation/, on macOS /Users/\