From 8d2842af7d983b72effc842db642bc9209dc12f1 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Mon, 22 Jun 2020 20:17:34 +0200 Subject: [PATCH] Documentation files update. --- GAMELISTS.md | 7 ++++--- INSTALL.md | 38 +++++++++++++++++++++----------------- SYSTEMS.md | 5 +++++ THEMES.md | 22 +++++++++++++++------- 4 files changed, 45 insertions(+), 27 deletions(-) diff --git a/GAMELISTS.md b/GAMELISTS.md index 8e13ddc17..f413089ae 100644 --- a/GAMELISTS.md +++ b/GAMELISTS.md @@ -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. -ES only checks for the gamelist.xml files in the user's home directory: -* `~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml` +ES only checks for the `gamelist.xml` files in the user's home directory: + +`~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml` An example gamelist.xml: ```xml @@ -19,7 +20,7 @@ An example gamelist.xml: Everything is enclosed in a `` tag. The information for each game or folder is enclosed in a corresponding tag (`` or ``). 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. diff --git a/INSTALL.md b/INSTALL.md index 40aefec29..b362565d7 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -64,33 +64,39 @@ Configuring **~/.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`. -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:** -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:** 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 arcade megadrive 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: -'' -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 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:** 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 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 look for all the configuration files under `~/games/emulation/.emulationstation`. +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. 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. \ 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! -Here's an overview of the es_systems.cfg file layout: +Here's an overview of the `es_systems.cfg` file layout: ```xml @@ -166,7 +171,7 @@ Here's an overview of the es_systems.cfg file layout: Super Nintendo Entertainment System %ROMPATH%/snes @@ -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. -See [SYSTEMS.md](SYSTEMS.md) for some live examples in EmulationStation. - gamelist.xml ============ 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: + `` The default game media directory is `~/.emulationstation/downloaded_media`. diff --git a/SYSTEMS.md b/SYSTEMS.md index 7d9424652..d01feff67 100644 --- a/SYSTEMS.md +++ b/SYSTEMS.md @@ -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 This outlines how to add support for many different systems into EmulationStation through configuration of `es_systems.cfg`. diff --git a/THEMES.md b/THEMES.md index 5137a3c68..8e70f3215 100644 --- a/THEMES.md +++ b/THEMES.md @@ -36,7 +36,7 @@ There are two places ES can load theme sets from: * `[HOME]/.emulationstation/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` `[SYSTEM_THEME]` is the `` tag for the system, as defined in `es_systems.cfg`. If the `` tag is not set, ES will use the system's ``. @@ -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. + + #### 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. -It's recommended to put these elements in a separate file and include it from the main theme file (e.g. ./navigationsounds.xml). +It's recommended to put these elements in a separate file and include it from the main theme file (e.g. `./navigationsounds.xml`). 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. 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. -Example debug output: -May 12 21:12:37 lvl2: Sound::getFromTheme() looking for [all.selectSound] +Example debug output: \ +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 -Example navigationsounds.xml, to be included from the main theme file: +Example `navigationsounds.xml`, to be included from the main theme file: ```xml @@ -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. -[*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