Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2024-11-21 21:55:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation update to clarify the complementary systems customization.

Browse source
This commit is contained in:
Leon Styhre 2021-09-05 18:10:59 +02:00
parent 466bdc9b92
commit 1dbdbe04e2
2 changed files with 5 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
INSTALL-DEV.md
View file

@ -1401,11 +1401,11 @@ For the following options, the es_settings.xml file is immediately updated/saved
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` 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.
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 to add additional systems altogether.
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 `<system>` tag. The structure of the custom file is identical to the bundled file with the exception of an additional optional tag named `<loadExclusive/>`. 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.
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 to for example customize a single system, this file should only contain a single `<system>` tag. The structure of the custom file is identical to the bundled file with the exception of an additional optional tag named `<loadExclusive/>`. 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.
@ -1567,7 +1567,7 @@ And finally one for Windows:
</system>
```
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:
As well, here's an example for 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
<?xml version="1.0"?>
<!-- This is a custom ES-DE game systems configuration file for Unix -->

6
USERGUIDE-DEV.md
View file

@ -132,11 +132,9 @@ _This is the dialog shown if no game files were found. It lets you configure the
The game systems configuration file `es_systems.xml` is located in the ES-DE resources directory which is part of the application installation. As such this file is not intended to be modified directly. If system customizations are required, a separate es_systems.xml file should instead be placed in the `custom_systems` folder in the ES-DE home directory, i.e. `~/.emulationstation/custom_systems/es_systems.xml`.
Although it's possible to make a copy of the bundled configuration file, modify it and then place it in this directory, that is not how the custom file is designed to be used. Instead the intention is that the file placed in the custom_systems directory complements the bundled file, meaning only the systems that are to be customized or added should be included. For example you may want to replace the emulator, modify the full name or change the supported file extensions for a single system. In this case it wouldn't make sense to add the complete bundled file with these minor modifications. Also, future updates to ES-DE may contain changes to existing emulator entries which would then not be used as the custom file takes precedence over the bundled file.
Although it's possible to make a copy of the bundled configuration file, to modify it and then place it in this directory, that is not how the system customization is designed to be done. Instead the intention is that the file in the custom_systems directory complements the bundled configuration. This means that only systems that are to be modified should be included. For example you may want to replace the emulator launch command, modify the full name or change the supported file extensions for a single system. In this case it wouldn't make sense to copy the complete bundled file and just apply these minor modifications. As well, future updates to ES-DE may contain changes to existing emulator entries which would then not be utilized as the custom configuration file takes precedence over the bundled file.
To clarify, the custom es_systems.xml file is loaded first, followed by the bundled file.
Although unlikely to be needed, it's also possible to skip the loading of the bundled es_systems.xml file and only use the file in custom_systems. The instructions for how to accomplish this as well as how to adapt the es_systems.xml file can be found in [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml).
It's also possible to skip the loading of the bundled es_systems.xml file and only use the file in custom_systems, although this will probably rarely be needed. The instructions for how to accomplish this as well as how to customize the es_systems.xml file can be found in [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml).
## Migrating from other EmulationStation forks