mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-25 07:35:38 +00:00
Documentation and information files update.
This commit is contained in:
Leon Styhre
parent
3cfe2d8bcb
commit
1cc96a2d21
39
GAMELISTS.md
39
GAMELISTS.md
|
|
@ -20,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.
|
||||
|
||||
|
|
@ -32,51 +32,48 @@ Reference
|
|||
There are a few types of metadata:
|
||||
|
||||
* `string` - just text.
|
||||
* `image_path` - a path to an image. This path should be either the absolute to the image, a path relative to the system games folder that starts with "./" (e.g. `./mm2_image.png`), or a path relative to the home directory that starts with "~/" (e.g. `~/.emulationstation/downloaded_images/nes/mm2-image.png`). Images will be automatically resized by OpenGL to fit the corresponding `<image>` tag in the current theme. Smaller images will load faster, so try to keep resolution low!
|
||||
* `video_path` - a path to a video. Similar to `image_path`.
|
||||
* `float` - a floating-point decimal value (written as a string).
|
||||
* `integer` - an integer value (written as a string).
|
||||
* `datetime` - a date and, potentially, a time. These are encoded as an ISO string, in the following format: "%Y%m%dT%H%M%S%F%q". For example, the release date for Chrono Trigger is encoded as "19950311T000000" (no time specified).
|
||||
|
||||
Some metadata is also marked as "statistic" - these are kept track of by ES and do not show up in the metadata editor. They are shown in certain views (for example, the detailed view shows both `playcount` and `lastplayed`).
|
||||
Some metadata is also marked as "statistic" - these are kept track of by ES and do not show up in the metadata editor. They are shown in certain views (for example, the detailed and video views show `lastplayed`, although it can be disabled by the theme).
|
||||
|
||||
#### `<game>`
|
||||
|
||||
* `name` - string, the displayed name for the game.
|
||||
* `desc` - string, a description of the game. Longer descriptions will automatically scroll, so don't worry about size.
|
||||
* `image` - image_path, the path to an image to display for the game (like box art or a screenshot).
|
||||
* `thumbnail` - image_path, the path to a smaller image, displayed in image lists like the grid view. Should be small to ensure quick loading.
|
||||
* `video` - video_path, the path to a video to display for the game, for themes that support the _video_ viewstyle.
|
||||
* `rating` - float, the rating for the game, expressed as a floating point number between 0 and 1. Arbitrary values are fine (ES can display half-stars, quarter-stars, etc).
|
||||
* `releasedate` - datetime, the date the game was released. Displayed as date only, time is ignored.
|
||||
* `developer` - string, the developer for the game.
|
||||
* `publisher` - string, the publisher for the game.
|
||||
* `genre` - string, the (primary) genre for the game.
|
||||
* `players` - integer, the number of players the game supports.
|
||||
* `playcount` - statistic, integer, the number of times this game has been played.
|
||||
* `favorite` - bool, indicates whether the game is a favorite
|
||||
* `completed`- bool, indicates whether the game has been completed
|
||||
* `broken` - bool, indicates a game that doesn't work (useful for MAME)
|
||||
* `kidgame` - bool, indicates whether the game is suitable for children, used by the `kid' UI mode
|
||||
* `playcount` - integer, the number of times this game has been played.
|
||||
* `lastplayed` - statistic, datetime, the last date and time this game was played.
|
||||
* `sortname` - string, used in sorting the gamelist in a system, instead of `name`.
|
||||
|
||||
* `launchstring` - optional tag that is used to override the emulator and core settings on a per-game basis
|
||||
|
||||
#### `<folder>`
|
||||
* `name` - string, the displayed name for the folder.
|
||||
* `desc` - string, the description for the folder.
|
||||
* `image` - image_path, the path to an image to display for the folder.
|
||||
* `thumbnail` - image_path, the path to a smaller image to display for the folder.
|
||||
* `developer` - string, developer(s)
|
||||
* `publisher` - string, publisher(s)
|
||||
* `genre` - string, genre(s)
|
||||
* `players` - integer, the number of players the game supports
|
||||
|
||||
|
||||
Things to be Aware Of
|
||||
Things to be aware of
|
||||
=====================
|
||||
|
||||
* You can use ES's built-in [scraping](http://en.wikipedia.org/wiki/Web_scraping) tools to avoid creating a gamelist.xml by hand, as described in README.md.
|
||||
|
||||
* ES will try to write any image paths as relative to the current system games path or relative to the current home directory if it can. This is done to try and keep installations portable (so you can copy them between computers).
|
||||
* If a value matches the default for a particular piece of metadata, ES will not write it to the gamelist.xml (for example, if `genre` isn't specified, ES won't write an empty genre tag).
|
||||
|
||||
* One thing to be aware of: the EmulationStation text rendering code doesn't currently support Unicode. If I fix this in the future, it will probably use UTF-8. For now, you'll just have to convert names and descriptions to ASCII. Sorry!
|
||||
|
||||
* If a value matches the default for a particular piece of metadata, ES will not write it to the gamelist.xml (for example, if `genre` isn't specified, ES won't write an empty genre tag; if `players` is 1, ES won't write a `players` tag).
|
||||
|
||||
* A `game` can actually point to a folder/directory if the the folder has a matching extension.
|
||||
* A `game` can actually point to a folder/directory if the folder has a matching extension.
|
||||
|
||||
* `folder` metadata will only be used if a game is found inside of that folder.
|
||||
|
||||
|
|
@ -84,8 +81,4 @@ Things to be Aware Of
|
|||
|
||||
* The switch `--gamelist-only` can be used to skip automatic searching, and only display games defined in the system's gamelist.xml.
|
||||
|
||||
* The switch `--ignore-gamelist` can be used to ignore the gamelist and force ES to use the non-detailed view.
|
||||
|
||||
* If at least one game in a system has an image specified, ES will use the detailed view for that system (which displays metadata alongside the game list).
|
||||
|
||||
* If you want to write your own scraper, the built-in scraping system is actually pretty extendable if you can get past the ugly function declarations and your instinctual fear of C++. Check out `src/scrapers/GamesDBScraper.cpp` for an example (it's less than a hundred lines of actual code). An offline scraper is also possible (though you'll have to subclass `ScraperRequest`). I hope to write a more complete guide on how to do this in the future.
|
||||
* The switch `--ignore-gamelist` can be used to ignore the gamelist upon start of the application.
|
||||
|
|
|
|||
33
INSTALL.md
33
INSTALL.md
|
|
@ -44,7 +44,7 @@ make
|
|||
```
|
||||
Keep in mind though that a debug version will be much slower due to all compiler optimizations being disabled.
|
||||
|
||||
Running multiple compile jobs in parallel is a good thing as it speeds up the build time a lot (scaling almost linearly). Here's an example telling `make` to run 6 parallel jobs:
|
||||
Running multiple compile jobs in parallel is a good thing as it speeds up the build time a lot (scaling almost linearly). Here's an example telling make to run 6 parallel jobs:
|
||||
|
||||
```
|
||||
make -j6
|
||||
|
|
@ -76,15 +76,16 @@ Assuming the default installation prefix `/usr/local` has been used, this is the
|
|||
/usr/local/share/emulationstation/themes
|
||||
```
|
||||
|
||||
*Note: The `resources` directory is critical, without it the application won't start.* \
|
||||
**Note:** The resources directory is critical, without it the application won't start.
|
||||
|
||||
ES will look in the following two locations for the resources:
|
||||
|
||||
* `[HOME]/.emulationstation/resources/`
|
||||
* `[INSTALLATION PATH]/share/emulationstation/resources/`
|
||||
* `[INSTALL PREFIX]/share/emulationstation/resources/`
|
||||
|
||||
The home directory will always take precedence so any resources located there will override the ones in the installation path. It's not recommended to override any resources since they are by nature static. But combining this ability with the command line `--home` flag, a fully portable version of EmulationStation could be created on a USB memory stick or similar.
|
||||
The home directory will always take precedence, so any resources located there will override the ones in the installation path. It's not recommended to override any resources since they are by nature static. But using the ability to locate resource files in the home directory is very useful when combined with the command line option `--home` (see below), as a fully portable version of EmulationStation can then be created on a USB memory stick or similar.
|
||||
|
||||
Anyway, after compiling the application, either run `make install` or copy or symlink the resources directory to `~/.emulationstation/resources`:
|
||||
Anyway, after compiling the application, either run `make install` or copy or symlink the resources directory to `~/.emulationstation/resources`.
|
||||
|
||||
`cp -R resources ~/.emulationstation/` \
|
||||
or \
|
||||
|
|
@ -115,7 +116,7 @@ For RPM packages, change the comments in the `CMakeLists.txt` accordingly, from:
|
|||
#SET(CPACK_GENERATOR "RPM")
|
||||
SET(CPACK_GENERATOR "DEB")
|
||||
```
|
||||
To:
|
||||
to:
|
||||
```
|
||||
SET(CPACK_GENERATOR "RPM")
|
||||
#SET(CPACK_GENERATOR "DEB")
|
||||
|
|
@ -157,11 +158,13 @@ EmulationStation Desktop Edition ships with a comprehensive `es_systems.cfg` con
|
|||
|
||||
Upon first startup of the application, if there is no es_systems.cfg file present, it will be copied from the template subdirectory inside 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%` on Windows.
|
||||
The template file will be copied to `~/.emulationstation/es_systems.cfg`. \
|
||||
`~` is `$HOME` on Linux, and `%HOMEPATH%` on Windows.
|
||||
|
||||
**~/.emulationstation/es_settings.cfg:**
|
||||
|
||||
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. \
|
||||
When ES is first run, a configuration file will be created as `~/.emulationstation/es_settings.cfg`.
|
||||
|
||||
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.
|
||||
|
|
@ -182,9 +185,9 @@ 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 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!**
|
||||
**Keep in mind that you have to set up your emulator separately from EmulationStation!**
|
||||
|
||||
**~/.emulationstation/es_input.cfg:**
|
||||
|
||||
|
|
@ -247,7 +250,7 @@ ES will only check in your home directory for an es_systems.cfg file, for exampl
|
|||
|
||||
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 file layout:
|
||||
|
||||
|
|
@ -311,16 +314,14 @@ As of the fork to EmulationStation Desktop Edition, game media information no lo
|
|||
|
||||
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).
|
||||
|
||||
*You can use ES's [scraping](http://en.wikipedia.org/wiki/Web_scraping) tools to avoid creating a gamelist.xml by hand.* There are two ways to run the scraper:
|
||||
|
||||
* **If you want to scrape multiple games:** press start to open the menu and choose the "SCRAPER" option. Adjust your settings and press "START".
|
||||
* **If you just want to scrape one game:** find the game on the game list in ES and press select. Choose "EDIT THIS GAME'S METADATA" and then press the "SCRAPE" button at the bottom of the metadata editor.
|
||||
* **If you want to scrape multiple games:** press the Start button to open the menu and choose the "SCRAPER" option. Adjust your settings and press "START".
|
||||
* **If you just want to scrape one game:** find the game on the game list in ES and press the Select button. Choose "EDIT THIS GAME'S METADATA" and then press the "SCRAPE" button at the bottom of the metadata editor.
|
||||
|
||||
You can also edit metadata within ES by using the metadata editor - just find the game you wish to edit on the gamelist, press Select, and choose "EDIT THIS GAME'S METADATA."
|
||||
|
||||
The switch `--ignore-gamelist` can be used to ignore the gamelist and force ES to use the non-detailed view.
|
||||
The switch `--ignore-gamelist` can be used to ignore the gamelists upon start of the application.
|
||||
|
||||
If you're writing a tool to generate or parse gamelist.xml files, you should check out [GAMELISTS.md](GAMELISTS.md) for more detailed documentation.
|
||||
|
||||
|
|
|
|||
9
NEWS.md
9
NEWS.md
|
|
@ -11,7 +11,7 @@ v1.0.0
|
|||
* For single-game scraping, any values updated by the scraper are now highlighted using a different font color in the metadata editor
|
||||
* Gamelist sorting now working as expected and is persistent throughout the application session
|
||||
* Full navigation sound support, configurable per theme
|
||||
* New default theme 'rbsimple-DE' bundled with the software, this theme is largely based on 'recalbox-multi' by the Recalbox community
|
||||
* New default theme rbsimple-DE bundled with the software, this theme is largely based on recalbox-multi by the Recalbox community
|
||||
* Seamless (almost) launch of games without showing the desktop when starting and returning from RetroArch and other emulators
|
||||
* Per-game launchstring override, so that different cores or emulators can be used on a per-game basis (saved to gamelist.xml)
|
||||
* Help system updated and expanded to the complete application (previously it was only partially implemented)
|
||||
|
|
@ -24,15 +24,16 @@ v1.0.0
|
|||
* 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
|
||||
* Made pugixml an external dependency instead of bundling it
|
||||
* Updated the cmake/cpack install and package build script to work as expected (can generate .deb and .rpm installation packages)
|
||||
* Updated the cmake/cpack install and package build script to work as expected (can now generate .deb and .rpm installation packages)
|
||||
* 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 (and included new scripts to easily generate these index files)
|
||||
* Updated the MAME ROM index files to include ROMs up to MAME version 0.221 (and created scripts to easily generate these index files in the future)
|
||||
|
||||
### Bug fixes
|
||||
|
||||
* Metadata editor insisted that changes were made although nothing was updated
|
||||
Note: The editor will still ask for save confirmations after automatically rounding fractional game ratings to half-star values
|
||||
* Game images were sometimes scaled incorrectly
|
||||
* Non-transparent favorite icons were not rendered correctly
|
||||
* Restart and power-off menu entries not working (at least on my desktop OS)
|
||||
* Restart and power-off menu entries not working (at least not on my desktop OS)
|
||||
* Toggling the screensaver didn't work as expected
|
||||
* Lots and lots of small bugs and inconsistencies fixed
|
||||
|
|
|
|||
12
USERGUIDE.md
12
USERGUIDE.md
|
|
@ -1,20 +1,16 @@
|
|||
EmulationStation Desktop Edition - User Guide
|
||||
=============================================
|
||||
|
||||
Getting started
|
||||
===============
|
||||
### Getting started
|
||||
|
||||
|
||||
|
||||
Main menu
|
||||
=========
|
||||
### Main menu
|
||||
|
||||
|
||||
|
||||
Game option menu
|
||||
================
|
||||
### Game option menu
|
||||
|
||||
|
||||
|
||||
Scraper
|
||||
=======
|
||||
### Scraper
|
||||
|
|
|
|||
Loading…
Reference in a new issue