mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-22 06:05:38 +00:00
Documentation files update.
This commit is contained in:
Leon Styhre
parent
0a02d710f3
commit
8d2842af7d
|
|
@ -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 `<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.
|
||||
|
||||
|
|
|
|||
38
INSTALL.md
38
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:
|
||||
'<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:**
|
||||
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
|
||||
<?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>
|
||||
|
||||
<!-- 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. -->
|
||||
<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.
|
||||
|
||||
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:
|
||||
|
||||
`<string name="MediaDirectory" value="~/games/images/emulationstation" />`
|
||||
|
||||
The default game media directory is `~/.emulationstation/downloaded_media`.
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
22
THEMES.md
22
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 `<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.
|
||||
|
||||
|
||||
|
||||
#### 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. <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
|
||||
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
|
||||
<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.
|
||||
|
||||
[*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
|
||||
|
|
|
|||
Loading…
Reference in a new issue