mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-21 21:55:38 +00:00
Removed the last remnants of the usage of /etc and updated the documenation accordingly.
This commit is contained in:
Leon Styhre
parent
672026632d
commit
0a02d710f3
12
GAMELISTS.md
12
GAMELISTS.md
|
|
@ -1,27 +1,27 @@
|
|||
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:
|
||||
* `[SYSTEM_PATH]/gamelist.xml`
|
||||
ES only checks for the gamelist.xml files in the user's home directory:
|
||||
* `~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
|
||||
* `/etc/emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
|
||||
|
||||
An example gamelist.xml:
|
||||
```xml
|
||||
<gameList>
|
||||
<game>
|
||||
<path>/home/pi/ROMs/nes/mm2.nes</path>
|
||||
<path>./mm2.nes</path>
|
||||
<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>
|
||||
<image>~/.emulationstation/downloaded_images/nes/Mega Man 2-image.png</image>
|
||||
</game>
|
||||
</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.
|
||||
|
||||
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
|
||||
=========
|
||||
|
|
|
|||
107
INSTALL.md
107
INSTALL.md
|
|
@ -62,8 +62,33 @@ Remember to copy the necessary .DLL files into the same folder as the executable
|
|||
Configuring
|
||||
===========
|
||||
|
||||
|
||||
**~/.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!**
|
||||
|
||||
|
|
@ -110,78 +135,82 @@ 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`.
|
||||
|
||||
|
||||
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. \
|
||||
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:
|
||||
* `~/.emulationstation/es_systems.cfg`
|
||||
* `/etc/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.
|
||||
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 example es_systems.cfg:
|
||||
Here's an overview of the es_systems.cfg file layout:
|
||||
|
||||
```xml
|
||||
<!-- This is the EmulationStation Systems configuration file.
|
||||
All systems must be contained within the <systemList> tag.-->
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<!-- This is the EmulationStation-DE game systems configuration file. -->
|
||||
<systemList>
|
||||
<!-- Here's an example system to get you started. -->
|
||||
<system>
|
||||
<!-- A short name, used internally. -->
|
||||
<name>snes</name>
|
||||
<!-- Here's an example system to get you started. -->
|
||||
<system>
|
||||
<!-- A short name, used internally. -->
|
||||
<name>snes</name>
|
||||
|
||||
<!-- A "pretty" name, displayed in the menus and such. This one is optional. -->
|
||||
<fullname>Super Nintendo Entertainment System</fullname>
|
||||
<!-- A "pretty" name, displayed in the menus and such. This one is optional. -->
|
||||
<fullname>Super Nintendo Entertainment System</fullname>
|
||||
|
||||
<!-- The path to start searching for ROMs in. '~' will be expanded to $HOME or %HOMEPATH%, depending on platform.
|
||||
All subdirectories (and non-recursive links) will be included. -->
|
||||
<path>~/roms/snes</path>
|
||||
<!-- 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. -->
|
||||
<path>%ROMPATH%/snes</path>
|
||||
|
||||
<!-- 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. -->
|
||||
<extension>.smc .sfc .SMC .SFC</extension>
|
||||
<!-- 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. -->
|
||||
<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). -->
|
||||
<command>snesemulator %ROM%</command>
|
||||
<!-- This example would run the bash command "snesemulator /home/user/roms/snes/Super\ Mario\ World.sfc". -->
|
||||
<!-- The command executed when a game is launched. A few special variables are replaced if found in a command, like %ROM% (see below).
|
||||
This example would run RetroArch with the the snes9x_libretro core. -->
|
||||
<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.
|
||||
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" -->
|
||||
<platform>snes</platform>
|
||||
<!-- 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.
|
||||
You can use multiple platforms too, delimited with any of the whitespace characters (", \r\n\t"), e.g.: "megadrive, genesis" -->
|
||||
<platform>snes</platform>
|
||||
|
||||
<!-- 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>
|
||||
</system>
|
||||
<!-- The theme to load from the current theme set. See THEMES.md for more information. -->
|
||||
<theme>snes</theme>
|
||||
</system>
|
||||
</systemList>
|
||||
```
|
||||
|
||||
The following "tags" are replaced by ES in launch commands:
|
||||
The following variables are replaced by ES in launch commands:
|
||||
|
||||
`%ROM%` - Replaced with absolute path to the selected ROM, with most Bash special characters escaped with a backslash.
|
||||
`%ROMPATH%` - Replaced with the path defined for the setting ROMDirectory in es_settings.cfg.
|
||||
|
||||
`%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example, a path of "/foo/bar.rom", this tag would be "bar". This tag is useful for setting up AdvanceMAME.
|
||||
`%ROM%` - Replaced with absolute path to the selected ROM, with most Bash special characters escaped with a backslash.
|
||||
|
||||
`%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example, a path of "/foo/bar.rom", this tag would be "bar". This tag is useful for setting up AdvanceMAME.
|
||||
|
||||
`%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.
|
||||
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).
|
||||
|
||||
|
|
@ -212,4 +241,4 @@ https://gitlab.com/recalbox/recalbox-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
5
NEWS.md
|
|
@ -20,16 +20,17 @@ v1.0.0
|
|||
* 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
|
||||
* 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.
|
||||
* 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
|
||||
* 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
|
||||
|
||||
* Metadata editor insisted that changes were made although nothing was updated
|
||||
* Game images were sometimes scaled incorrectly
|
||||
* 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
|
||||
* Lots and lots of small bugs and inconsistencies fixed
|
||||
|
|
|
|||
|
|
@ -117,7 +117,7 @@ bool SystemData::populateFolder(FileData* folder)
|
|||
bool showHidden = Settings::getInstance()->getBool("ShowHiddenFiles");
|
||||
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)
|
||||
return false;
|
||||
|
||||
|
|
@ -380,7 +380,7 @@ std::string SystemData::getConfigPath(bool forWrite)
|
|||
if (forWrite || Utils::FileSystem::exists(path))
|
||||
return path;
|
||||
|
||||
return "/etc/emulationstation/es_systems.cfg";
|
||||
return "";
|
||||
}
|
||||
|
||||
bool SystemData::isVisible()
|
||||
|
|
@ -430,13 +430,15 @@ std::string SystemData::getGamelistPath(bool forWrite) const
|
|||
|
||||
filePath = Utils::FileSystem::getHomePath() + "/.emulationstation/gamelists/" +
|
||||
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)
|
||||
Utils::FileSystem::createDirectory(Utils::FileSystem::getParent(filePath));
|
||||
if (forWrite || Utils::FileSystem::exists(filePath))
|
||||
return filePath;
|
||||
|
||||
return "/etc/emulationstation/gamelists/" + mName + "/gamelist.xml";
|
||||
return "";
|
||||
}
|
||||
|
||||
std::string SystemData::getThemePath() const
|
||||
|
|
|
|||
|
|
@ -197,9 +197,9 @@ private:
|
|||
int mMaxHeight;
|
||||
};
|
||||
|
||||
// About the same as:
|
||||
// "~/.emulationstation/downloaded_images/[system_name]/[game_name].[url's extension]".
|
||||
// Will create the "downloaded_images" and "subdirectory" directories if they do not exist.
|
||||
// Downloads to the home directory, using this subdirectory structure:
|
||||
// ".emulationstation/downloaded_media/[system_name]/[media_type]/[game_name].[file_extension]".
|
||||
// The subdirectories are automatically created if they do not exist.
|
||||
std::string getSaveAsPath(const ScraperSearchParams& params,
|
||||
const std::string& filetypeSubdirectory, const std::string& url);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue