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

Documentation files update.

Browse source
This commit is contained in:
Leon Styhre 2020-06-22 20:17:34 +02:00
parent 0a02d710f3
commit 8d2842af7d
4 changed files with 45 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
GAMELISTS.md
View file

@ -3,8 +3,9 @@ Gamelists
The gamelist.xml file for a system defines metadata for a system's games, such as a name, description, release date, and rating. The gamelist.xml file for a system defines metadata for a system's games, such as a name, description, release date, and rating.
ES only checks for the gamelist.xml files in the user's home directory: ES only checks for the `gamelist.xml` files in the user's home directory:
* `~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
`~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
An example gamelist.xml: An example gamelist.xml:
```xml ```xml
@ -19,7 +20,7 @@ An example gamelist.xml:
Everything is enclosed in a `<gameList>` tag. The information for each game or folder is enclosed in a corresponding tag (`<game>` or `<folder>`). Each piece of metadata is encoded as a string. Everything is enclosed in a `<gameList>` tag. The information for each game or folder is enclosed in a corresponding tag (`<game>` or `<folder>`). Each piece of metadata is encoded as a string.
As of EmulationStation Desktop Edition v1.0.0, there are no longer any references to game media files in gamelist.xml. Instead a media directory is used where the images and videos are simply matched against the ROM file names. As well, no absolute paths are used for the ROM files any longer. Instead a global ROM directory is configured and there are only relative references in the gamelist.xml files, starting with `./` as can be seen in the example above. As of EmulationStation Desktop Edition v1.0.0, there are no longer any references to game media files in `gamelist.xml`. Instead a media directory is used where the images and videos are simply matched against the ROM file names. As well, no absolute paths are used for the ROM files any longer. Instead a global ROM directory is configured and there are only relative references in the `gamelist.xml` files, starting with `./` as can be seen in the example above.
Please refer to [INSTALL.md](INSTALL.md) for more information on how the ROM and media directories are configured. Please refer to [INSTALL.md](INSTALL.md) for more information on how the ROM and media directories are configured.

38
INSTALL.md
View file

@ -64,33 +64,39 @@ Configuring
**~/.emulationstation/es_systems.cfg:** **~/.emulationstation/es_systems.cfg:**
EmulationStation Desktop Edition ships with a comprehensive es_systems.cfg configuration file, and as the logic is to use a %ROMPATH% variable to locate the ROM files (with a corresponding setting in es_settings.cfg), normally you shouldn't need to modify this file to the same extent as previous versions of EmulationStation. Still, see below in this document on how to adjust es_systems.cfg file if required.
EmulationStation Desktop Edition ships with a comprehensive `es_systems.cfg` configuration file, and as the logic is to use a `%ROMPATH%` variable to locate the ROM files (with a corresponding setting in `es_settings.cfg`), normally you shouldn't need to modify this file to the same extent as previous versions of EmulationStation. Still, see below in this document on how to adjust es_systems.cfg file if required.
Upon first startup of the application, if there is no es_systems.cfg file present, it will be copied from the template directory of the resources directory. This directory is located in the installation path of the application, for instance `/usr/local/share/emulationstation/resources/templates`. Upon first startup of the application, if there is no es_systems.cfg file present, it will be copied from the template directory of the resources directory. This directory is located in the installation path of the application, for instance `/usr/local/share/emulationstation/resources/templates`.
The template file will be copied to `~/.emulationstation/es_systems.cfg`. `~` is `$HOME` on Linux, and `%HOMEPATH%` The template file will be copied to `~/.emulationstation/es_systems.cfg`. `~` is `$HOME` on Linux, and `%HOMEPATH%` on Windows.
**~/.emulationstation/es_settings.cfg:** **~/.emulationstation/es_settings.cfg:**
When first run, an example configuration file will be created at `~/.emulationstation/es_settings.cfg`. `~` is `$HOME` on Linux, and `%HOMEPATH%` on Windows. This file contains all the settings supported by ES, at their default values. Normally you shouldn't need to modify this file manually, instead you should be able to use the menu inside ES to update all the necessary settings. The exception would be the ROMDirectory setting as ES won't start if no ROM files are found.
When ES is first run, an example configuration file will be created as `~/.emulationstation/es_settings.cfg`. `~` is `$HOME` on Linux, and `%HOMEPATH%` on Windows. \
This file contains all the settings supported by ES, at their default values. Normally you shouldn't need to modify this file manually, instead you should be able to use the menu inside ES to update all the necessary settings.
The exception would be the ROMDirectory setting as ES won't start if no ROM files are found.
**Setting the ROM directory:** **Setting the ROM directory:**
By default, ES looks in `~/ROMs` for the ROM files, where they are expected to be grouped into directories corresponding to the systems, for example: By default, ES looks in `~/ROMs` for the ROM files, where they are expected to be grouped into directories corresponding to the systems, for example:
```bash ```
user@computer:~ROMs$ ls -1 user@computer:~ROMs$ ls -1
arcade arcade
megadrive megadrive
pcengine pcengine
``` ```
However, if you save your ROMs in another directory, you need to configure the ROMDirectory setting in es_settings.cfg.\ However, if you've saved your ROMs to another directory, you need to configure the ROMDirectory setting in es_settings.cfg.\
Here's an example: Here's an example:
'<string name="ROMDirectory" value="~/games/roms" />'
Keep in mind though that you still need to group the ROMs into directories corresponding to the system names. Well at least if you want to use the default es_systems.cfg file. See below how to customize that file, which gives you full control over the location of the ROMs. `<string name="ROMDirectory" value="~/games/roms" />`
**Keep in mind you'll have to set up your emulator separately from EmulationStation!** Keep in mind though that you still need to group the ROMs into directories corresponding to the system names. Well at least if you want to use the default `es_systems.cfg` file. See below how to customize that file, which gives you full control over the location of the ROMs.
**Keep in mind that you'll have to set up your emulator separately from EmulationStation!**
**~/.emulationstation/es_input.cfg:** **~/.emulationstation/es_input.cfg:**
When you first start EmulationStation, you will be prompted to configure an input device. The process is thus: When you first start EmulationStation, you will be prompted to configure an input device. The process is thus:
@ -135,8 +141,7 @@ You can use `--help` or `-h` to view a list of command-line options. Briefly out
As long as ES hasn't frozen, you can always press F4 to close the application. As long as ES hasn't frozen, you can always press F4 to close the application.
As you can see above, you can override the home directory path using the `--home` flag. \ As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `emulationstation --home ~/games/emulation`, ES will use `~/games/emulation/.emulationstation` as its base directory.
So by running for instance the command `emulationstation --home ~/games/emulation` ES will look for all the configuration files under `~/games/emulation/.emulationstation`.
Writing an es_systems.cfg Writing an es_systems.cfg
@ -145,13 +150,13 @@ Writing an es_systems.cfg
The `es_systems.cfg` file contains the system configuration data for EmulationStation, written in XML. \ The `es_systems.cfg` file contains the system configuration data for EmulationStation, written in XML. \
This tells EmulationStation what systems you have, what platform they correspond to (for scraping), and where the games are located. This tells EmulationStation what systems you have, what platform they correspond to (for scraping), and where the games are located.
ES will only check in your home directory for an es_systems.cfg file, for example `~/.emulationstation/es_systems.cfg`. ES will only check in your home directory for an `es_systems.cfg` file, for example `~/.emulationstation/es_systems.cfg`.
The order EmulationStation displays systems reflects the order you define them in, in the case of the default es_systems.cfg file, the systems are listed in alphabetical order. The order EmulationStation displays systems reflects the order you define them in. In the case of the default `es_systems.cfg` file, the systems are listed in alphabetical order.
**NOTE:** A system *must* have at least one game present in its "path" directory, or ES will ignore it! If no valid systems are found, ES will report an error and quit! **NOTE:** A system *must* have at least one game present in its "path" directory, or ES will ignore it! If no valid systems are found, ES will report an error and quit!
Here's an overview of the es_systems.cfg file layout: Here's an overview of the `es_systems.cfg` file layout:
```xml ```xml
<?xml version="1.0"?> <?xml version="1.0"?>
@ -166,7 +171,7 @@ Here's an overview of the es_systems.cfg file layout:
<fullname>Super Nintendo Entertainment System</fullname> <fullname>Super Nintendo Entertainment System</fullname>
<!-- The path to start searching for ROMs in. '~' will be expanded to $HOME or %HOMEPATH%, depending on platform. <!-- The path to start searching for ROMs in. '~' will be expanded to $HOME or %HOMEPATH%, depending on platform.
The optional %ROMPATH% variable will expand to the setting defined for ROMDirectory in es_settings.cfg. The optional %ROMPATH% variable will expand to the path defined for the setting ROMDirectory in es_settings.cfg.
All subdirectories (and non-recursive links) will be included. --> All subdirectories (and non-recursive links) will be included. -->
<path>%ROMPATH%/snes</path> <path>%ROMPATH%/snes</path>
@ -199,15 +204,14 @@ The following variables are replaced by ES in launch commands:
`%ROM_RAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes. `%ROM_RAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes.
See [SYSTEMS.md](SYSTEMS.md) for some live examples in EmulationStation.
gamelist.xml gamelist.xml
============ ============
The gamelist.xml file for a system defines metadata for games, such as a name, description, release date, and rating. The gamelist.xml file for a system defines metadata for games, such as a name, description, release date, and rating.
As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the gamelist.xml files. Instead the application will look for any media matching the ROM filename. The media path where to look for game art is configurable either manually in es_settings.cfg or via the GUI. If configured manually in es_settings.cfg, it looks something like this: As of the fork to EmulationStation Desktop Edition, game media information no longer needs to be defined in the `gamelist.xml` files. Instead the application will look for any media matching the ROM filename. The media path where to look for game art is configurable either manually in `es_settings.cfg` or via the GUI. If configured manually in `es_settings.cfg`, it looks something like this:
`<string name="MediaDirectory" value="~/games/images/emulationstation" />` `<string name="MediaDirectory" value="~/games/images/emulationstation" />`
The default game media directory is `~/.emulationstation/downloaded_media`. The default game media directory is `~/.emulationstation/downloaded_media`.

5
SYSTEMS.md
View file

@ -1,3 +1,8 @@
**NOTE: This information is outdated and the SYSTEMS.md file will probably be removed from the repository in the near future.**
# Systems # Systems
This outlines how to add support for many different systems into EmulationStation through configuration of `es_systems.cfg`. This outlines how to add support for many different systems into EmulationStation through configuration of `es_systems.cfg`.

22
THEMES.md
View file

@ -36,7 +36,7 @@ There are two places ES can load theme sets from:
* `[HOME]/.emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` * `[HOME]/.emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
* `[INSTALLATION PATH]/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` * `[INSTALLATION PATH]/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
An example of an installation path would be: \ An example installation path would be: \
`/usr/local/share/emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` `/usr/local/share/emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
`[SYSTEM_THEME]` is the `<theme>` tag for the system, as defined in `es_systems.cfg`. If the `<theme>` tag is not set, ES will use the system's `<name>`. `[SYSTEM_THEME]` is the `<theme>` tag for the system, as defined in `es_systems.cfg`. If the `<theme>` tag is not set, ES will use the system's `<name>`.
@ -273,20 +273,22 @@ Just remember, *this only works if the elements have the same type!*
You can now change the order in which elements are rendered by setting `zIndex` values. Default values correspond to the default rendering order while allowing elements to easily be shifted without having to set `zIndex` values for every element. Elements will be rendered in order from smallest z-index to largest. You can now change the order in which elements are rendered by setting `zIndex` values. Default values correspond to the default rendering order while allowing elements to easily be shifted without having to set `zIndex` values for every element. Elements will be rendered in order from smallest z-index to largest.
#### Navigation sounds #### Navigation sounds
The navigation sounds are configured globally per theme, so it needs to be defined as a feature and with the view set to the special 'all' category. The navigation sounds are configured globally per theme, so it needs to be defined as a feature and with the view set to the special 'all' category.
It's recommended to put these elements in a separate file and include it from the main theme file (e.g. <include>./navigationsounds.xml</include>). It's recommended to put these elements in a separate file and include it from the main theme file (e.g. `<include>./navigationsounds.xml</include>`).
There are seven different navigation sounds that can be configured. The names as well as the element structure should be self-explanatory based There are seven different navigation sounds that can be configured. The names as well as the element structure should be self-explanatory based
on the example below. on the example below.
Starting EmulationStation with the --debug flag will provide feedback on whether the navigation sound elements were read correctly, as well as Starting EmulationStation with the --debug flag will provide feedback on whether the navigation sound elements were read correctly, as well as
providing an error message if any of the .wav sound files could not be loaded. providing an error message if any of the .wav sound files could not be loaded.
Example debug output: Example debug output: \
May 12 21:12:37 lvl2: Sound::getFromTheme() looking for [all.selectSound] May 12 21:12:37 lvl2: Sound::getFromTheme() looking for [all.selectSound] \
May 12 21:12:37 lvl2: [selectSound] found, ready to play sound file May 12 21:12:37 lvl2: [selectSound] found, ready to play sound file
Example navigationsounds.xml, to be included from the main theme file: Example `navigationsounds.xml`, to be included from the main theme file:
```xml ```xml
<theme> <theme>
@ -887,7 +889,13 @@ EmulationStation borrows the concept of "nine patches" from Android (or "9-Slice
The help system is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Keep in mind the "default" settings (including position) are used whenever the user opens a menu. The help system is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Keep in mind the "default" settings (including position) are used whenever the user opens a menu.
[*Check out the "official" themes for some more examples!*](http://aloshi.com/emulationstation#themes)
To see some examples of EmulationStation themes, the following resources are recommended:
This file was last updated for EmulationStation Desktop Edition v1.0.0 https://aloshi.com/emulationstation#themes
https://github.com/RetroPie
https://gitlab.com/recalbox/recalbox-themes
https://wiki.batocera.org/themes