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

Removed the last remnants of the usage of /etc and updated the documenation accordingly.

Browse source
This commit is contained in:
Leon Styhre 2020-06-22 19:46:09 +02:00
parent 672026632d
commit 0a02d710f3
6 changed files with 465 additions and 430 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
GAMELISTS.md
View file

@ -1,27 +1,27 @@
Gamelists Gamelists
========= =========
The gamelist.xml file for a system defines metadata for a system's games, such as a name, image (like a screenshot or box art), 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 will check three places for a gamelist.xml in the following order, using the first one it finds: ES only checks for the gamelist.xml files in the user's home directory:
* `[SYSTEM_PATH]/gamelist.xml`
* `~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml` * `~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
* `/etc/emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
An example gamelist.xml: An example gamelist.xml:
```xml ```xml
<gameList> <gameList>
<game> <game>
<path>/home/pi/ROMs/nes/mm2.nes</path> <path>./mm2.nes</path>
<name>Mega Man 2</name> <name>Mega Man 2</name>
<desc>Mega Man 2 is a classic NES game which follows Mega Man as he murders eight robot masters in cold blood.</desc> <desc>Mega Man 2 is a classic NES game which follows Mega Man as he murders eight robot masters in cold blood.</desc>
<image>~/.emulationstation/downloaded_images/nes/Mega Man 2-image.png</image>
</game> </game>
</gameList> </gameList>
``` ```
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.
Please refer to [INSTALL.md](INSTALL.md) for more information on how the ROM and media directories are configured.
Reference Reference
========= =========

73
INSTALL.md
View file

@ -62,8 +62,33 @@ Remember to copy the necessary .DLL files into the same folder as the executable
Configuring Configuring
=========== ===========
**~/.emulationstation/es_systems.cfg:** **~/.emulationstation/es_systems.cfg:**
When first run, an example systems configuration file will be created at `~/.emulationstation/es_systems.cfg`. `~` is `$HOME` on Linux, and `%HOMEPATH%` on Windows. This example has some comments explaining how to write the configuration file. See the "Writing an es_systems.cfg" section for more information. 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%`
**~/.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.
**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.\
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.
**Keep in mind you'll have to set up your emulator separately from EmulationStation!** **Keep in mind you'll have to set up your emulator separately from EmulationStation!**
@ -110,29 +135,27 @@ 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. \
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
========================= =========================
Complete configuration instructions at [emulationstation.org](http://emulationstation.org/gettingstarted.html#config).
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 check two places for an es_systems.cfg file, in the following order, stopping after it finds one that works: ES will only check in your home directory for an es_systems.cfg file, for example `~/.emulationstation/es_systems.cfg`.
* `~/.emulationstation/es_systems.cfg`
* `/etc/emulationstation/es_systems.cfg`
The order EmulationStation displays systems reflects the order you define them in. 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 example es_systems.cfg: Here's an overview of the es_systems.cfg file layout:
```xml ```xml
<!-- This is the EmulationStation Systems configuration file. <?xml version="1.0"?>
All systems must be contained within the <systemList> tag.--> <!-- This is the EmulationStation-DE game systems configuration file. -->
<systemList> <systemList>
<!-- Here's an example system to get you started. --> <!-- Here's an example system to get you started. -->
<system> <system>
@ -143,30 +166,32 @@ All systems must be contained within the <systemList> tag.-->
<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.
All subdirectories (and non-recursive links) will be included. --> All subdirectories (and non-recursive links) will be included. -->
<path>~/roms/snes</path> <path>%ROMPATH%/snes</path>
<!-- A list of extensions to search for, delimited by any of the whitespace characters (", \r\n\t"). <!-- A list of extensions to search for, delimited by any of the whitespace characters (", \r\n\t").
You MUST include the period at the start of the extension! It's also case sensitive. --> You MUST include the period at the start of the extension! It's also case sensitive. -->
<extension>.smc .sfc .SMC .SFC</extension> <extension>.smc .SMC .sfc .SFC .swc .SWC .fig .FIG .bs .BS .bin .BIN .mgd .MGD .7z .7Z .zip .ZIP</extension>
<!-- The shell command executed when a game is selected. A few special tags are replaced if found in a command, like %ROM% (see below). --> <!-- The command executed when a game is launched. A few special variables are replaced if found in a command, like %ROM% (see below).
<command>snesemulator %ROM%</command> This example would run RetroArch with the the snes9x_libretro core. -->
<!-- This example would run the bash command "snesemulator /home/user/roms/snes/Super\ Mario\ World.sfc". --> <command>retroarch -L ~/.config/retroarch/cores/snes9x_libretro.so %ROM%</command>
<!-- The platform(s) to use when scraping. You can see the full list of accepted platforms in src/PlatformIds.cpp. <!-- The platform(s) to use when scraping. You can see the full list of accepted platforms in src/PlatformIds.cpp.
It's case sensitive, but everything is lowercase. This tag is optional. It's case sensitive, but everything is lowercase. This tag is optional.
You can use multiple platforms too, delimited with any of the whitespace characters (", \r\n\t"), eg: "genesis, megadrive" --> You can use multiple platforms too, delimited with any of the whitespace characters (", \r\n\t"), e.g.: "megadrive, genesis" -->
<platform>snes</platform> <platform>snes</platform>
<!-- The theme to load from the current theme set. See THEMES.md for more information. <!-- The theme to load from the current theme set. See THEMES.md for more information. -->
This tag is optional; if not set, it will use the value of <name>. -->
<theme>snes</theme> <theme>snes</theme>
</system> </system>
</systemList> </systemList>
``` ```
The following "tags" are replaced by ES in launch commands: The following variables are replaced by ES in launch commands:
`%ROMPATH%` - Replaced with the path defined for the setting ROMDirectory in es_settings.cfg.
`%ROM%` - Replaced with absolute path to the selected ROM, with most Bash special characters escaped with a backslash. `%ROM%` - Replaced with absolute path to the selected ROM, with most Bash special characters escaped with a backslash.
@ -176,12 +201,16 @@ The following "tags" are replaced by ES in launch commands:
See [SYSTEMS.md](SYSTEMS.md) for some live examples in EmulationStation. 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. 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`.
If at least one game in a system has an image (mix image, screenshot or box cover), ES will use the detailed view for that system (which displays metadata alongside the game list). If at least one game in a system has an image (mix image, screenshot or box cover), ES will use the detailed view for that system (which displays metadata alongside the game list).
@ -212,4 +241,4 @@ https://gitlab.com/recalbox/recalbox-themes
https://wiki.batocera.org/themes https://wiki.batocera.org/themes
For information on how to make your own theme or edit an existing one, read [THEMES.md](THEMES.md)! For information on how to make your own theme or edit an existing one, read [THEMES.md](THEMES.md).

5
NEWS.md
View file

@ -20,16 +20,17 @@ v1.0.0
* Speed improvements and optimizations, the application now starts faster and feels more responsive * Speed improvements and optimizations, the application now starts faster and feels more responsive
* Moved all resources to a subdirectory structure and enabled the CMake install prefix variable to generate the resources search path * Moved all resources to a subdirectory structure and enabled the CMake install prefix variable to generate the resources search path
* Changed theme directory to the install prefix (e.g. /usr/local/share/emulationstation/themes) with themes in the home directory taking precedence * Changed theme directory to the install prefix (e.g. /usr/local/share/emulationstation/themes) with themes in the home directory taking precedence
* No more attempts to open files directly under /etc, instead only the install prefix directory and the home directory are used
* Refactoring, cleanup and documentation of the source code, removal of deprecated files etc. * Refactoring, cleanup and documentation of the source code, removal of deprecated files etc.
* All required fonts bundled with the application, no dependencies on the OS to provide them any longer * All required fonts bundled with the application, no dependencies on the OS to provide them any longer
* License files included for all the libraries and resources that are bundled with the application * License files included for all the libraries and resources that are bundled with the application
* Updated the MAME ROM index files to include ROMs up to MAME version 0.221 * Updated the MAME ROM index files to include ROMs up to MAME version 0.221 (and included new scripts to easily generate these index files)
### Bug fixes ### Bug fixes
* Metadata editor insisted that changes were made although nothing was updated * Metadata editor insisted that changes were made although nothing was updated
* Game images were sometimes scaled incorrectly * Game images were sometimes scaled incorrectly
* Non-transparent favorite icons were not rendered correctly * Non-transparent favorite icons were not rendered correctly
* Restart and power-off menu entries not working (i.e. on a desktop OS) * Restart and power-off menu entries not working (at least on my desktop OS)
* Toggling the screensaver didn't work as expected * Toggling the screensaver didn't work as expected
* Lots and lots of small bugs and inconsistencies fixed * Lots and lots of small bugs and inconsistencies fixed

27
THEMES.md
View file

@ -21,7 +21,7 @@ If that file doesn't exist, ES will try to find the theme in the current **theme
my_other_super_cool_background.jpg my_other_super_cool_background.jpg
common_resources/ common_resources/
scroll_sound.wav my_font.ttf
theme.xml (Default theme) theme.xml (Default theme)
another_theme_set/ another_theme_set/
@ -34,7 +34,10 @@ The theme set system makes it easy for users to try different themes and allows
There are two places ES can load theme sets from: 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`
* `/etc/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: \
`/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>`.
@ -49,7 +52,7 @@ Here is a very simple theme that changes the description text's color:
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
<color>00FF00</color> <color>00FF00</color>
@ -69,7 +72,7 @@ How it works
Everything must be inside a `<theme>` tag. Everything must be inside a `<theme>` tag.
**The `<formatVersion>` tag *must* be specified**. This is the version of the theming system the theme was designed for. The current version is 5. **The `<formatVersion>` tag *must* be specified**. This is the version of the theming system the theme was designed for. The current version is 6.
@ -124,7 +127,7 @@ You can include theme files within theme files, similar to `#include` in C (thou
`~/.emulationstation/all_themes.xml`: `~/.emulationstation/all_themes.xml`:
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
<fontPath>./all_themes/myfont.ttf</fontPath> <fontPath>./all_themes/myfont.ttf</fontPath>
@ -137,7 +140,7 @@ You can include theme files within theme files, similar to `#include` in C (thou
`~/.emulationstation/snes/theme.xml`: `~/.emulationstation/snes/theme.xml`:
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<include>./../all_themes.xml</include> <include>./../all_themes.xml</include>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
@ -150,7 +153,7 @@ You can include theme files within theme files, similar to `#include` in C (thou
Is equivalent to this `snes/theme.xml`: Is equivalent to this `snes/theme.xml`:
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
<fontPath>./all_themes/myfont.ttf</fontPath> <fontPath>./all_themes/myfont.ttf</fontPath>
@ -170,7 +173,7 @@ Sometimes you want to apply the same properties to the same elements across mult
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<view name="basic, grid, system"> <view name="basic, grid, system">
<image name="logo"> <image name="logo">
<path>./snes_art/snes_header.png</path> <path>./snes_art/snes_header.png</path>
@ -187,7 +190,7 @@ Sometimes you want to apply the same properties to the same elements across mult
This is equivalent to: This is equivalent to:
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<view name="basic"> <view name="basic">
<image name="logo"> <image name="logo">
<path>./snes_art/snes_header.png</path> <path>./snes_art/snes_header.png</path>
@ -220,7 +223,7 @@ You can theme multiple elements *of the same type* simultaneously. The `name` a
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<view name="detailed"> <view name="detailed">
<!-- Weird spaces/newline on purpose! --> <!-- Weird spaces/newline on purpose! -->
<text name="md_lbl_rating, md_lbl_releasedate, md_lbl_developer, md_lbl_publisher, <text name="md_lbl_rating, md_lbl_releasedate, md_lbl_developer, md_lbl_publisher,
@ -234,7 +237,7 @@ You can theme multiple elements *of the same type* simultaneously. The `name` a
Which is equivalent to: Which is equivalent to:
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="md_lbl_rating"> <text name="md_lbl_rating">
<color>48474D</color> <color>48474D</color>
@ -287,7 +290,7 @@ Example navigationsounds.xml, to be included from the main theme file:
```xml ```xml
<theme> <theme>
<formatVersion>5</formatVersion> <formatVersion>6</formatVersion>
<feature supported="navigationsounds"> <feature supported="navigationsounds">
<view name="all"> <view name="all">
<sound name="systembrowseSound"> <sound name="systembrowseSound">

10
es-app/src/SystemData.cpp
View file

@ -117,7 +117,7 @@ bool SystemData::populateFolder(FileData* folder)
bool showHidden = Settings::getInstance()->getBool("ShowHiddenFiles"); bool showHidden = Settings::getInstance()->getBool("ShowHiddenFiles");
Utils::FileSystem::stringList dirContent = Utils::FileSystem::getDirContent(folderPath); Utils::FileSystem::stringList dirContent = Utils::FileSystem::getDirContent(folderPath);
// If system directory exists but contain no games, return as error. // If system directory exists but contains no games, return as error.
if (dirContent.size() == 0) if (dirContent.size() == 0)
return false; return false;
@ -380,7 +380,7 @@ std::string SystemData::getConfigPath(bool forWrite)
if (forWrite || Utils::FileSystem::exists(path)) if (forWrite || Utils::FileSystem::exists(path))
return path; return path;
return "/etc/emulationstation/es_systems.cfg"; return "";
} }
bool SystemData::isVisible() bool SystemData::isVisible()
@ -430,13 +430,15 @@ std::string SystemData::getGamelistPath(bool forWrite) const
filePath = Utils::FileSystem::getHomePath() + "/.emulationstation/gamelists/" + filePath = Utils::FileSystem::getHomePath() + "/.emulationstation/gamelists/" +
mName + "/gamelist.xml"; mName + "/gamelist.xml";
// Make sure the directory exists if we're going to write to it, or crashes will happen.
// Make sure the directory exists if we're going to write to it,
// or crashes will happen.
if (forWrite) if (forWrite)
Utils::FileSystem::createDirectory(Utils::FileSystem::getParent(filePath)); Utils::FileSystem::createDirectory(Utils::FileSystem::getParent(filePath));
if (forWrite || Utils::FileSystem::exists(filePath)) if (forWrite || Utils::FileSystem::exists(filePath))
return filePath; return filePath;
return "/etc/emulationstation/gamelists/" + mName + "/gamelist.xml"; return "";
} }
std::string SystemData::getThemePath() const std::string SystemData::getThemePath() const

6
es-app/src/scrapers/Scraper.h
View file

@ -197,9 +197,9 @@ private:
int mMaxHeight; int mMaxHeight;
}; };
// About the same as: // Downloads to the home directory, using this subdirectory structure:
// "~/.emulationstation/downloaded_images/[system_name]/[game_name].[url's extension]". // ".emulationstation/downloaded_media/[system_name]/[media_type]/[game_name].[file_extension]".
// Will create the "downloaded_images" and "subdirectory" directories if they do not exist. // The subdirectories are automatically created if they do not exist.
std::string getSaveAsPath(const ScraperSearchParams& params, std::string getSaveAsPath(const ScraperSearchParams& params,
const std::string& filetypeSubdirectory, const std::string& url); const std::string& filetypeSubdirectory, const std::string& url);