mirror of
https://github.com/Aloshi/EmulationStation.git
synced 2024-05-16 03:10:26 -04:00
Split gamelist.xml documentation into its own text file.
Removed signature in THEMES.md.
This commit is contained in:
Aloshi
parent
9350ed3615
commit
ff2fd4ee80
87
GAMELISTS.md
Normal file
87
GAMELISTS.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
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.
|
||||
|
||||
ES will check three places for a gamelist.xml in the following order, using the first one it finds:
|
||||
* `[SYSTEM_PATH]/gamelist.xml`
|
||||
* `~/.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>
|
||||
<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.
|
||||
|
||||
|
||||
Reference
|
||||
=========
|
||||
|
||||
(if you suspect this section is out of date, check out `src/MetaData.cpp`)
|
||||
|
||||
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!
|
||||
* `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`).
|
||||
|
||||
#### `<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. *Currently not used.*
|
||||
* `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
|
||||
* `lastplayed` - statistic, datetime, the last date and time this game was played.
|
||||
|
||||
|
||||
#### `<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. *Currently not used.*
|
||||
|
||||
|
||||
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).
|
||||
|
||||
* 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.
|
||||
|
||||
* `folder` metadata will only be used if a game is found inside of that folder.
|
||||
|
||||
* ES will keep entries for games and folders that it can't find the files for.
|
||||
|
||||
* 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.
|
||||
73
README.md
73
README.md
|
|
@ -10,26 +10,27 @@ I found a bug! I have a problem!
|
|||
================================
|
||||
|
||||
- First, try to check the [issue list](https://github.com/Aloshi/EmulationStation/issues?state=open) for some entries that might match your problem. Make sure to check closed issues too!
|
||||
|
||||
- If you're running EmulationStation on a on Raspberry Pi and have problems with config file changes not taking effect, content missing after editing, etc., check if your SD card is corrupted (see issues [#78](https://github.com/Aloshi/EmulationStation/issues/78) and [#107](https://github.com/Aloshi/EmulationStation/issues/107)). You can do this with free tools like [h2testw](http://www.heise.de/download/h2testw.html) or [F3](http://oss.digirati.com.br/f3/).
|
||||
|
||||
- Try to update to the latest version of EmulationStation using git (you might need to delete your `es_input.cfg` and `es_settings.cfg` after that to reset them to default values):
|
||||
```bash
|
||||
cd EmulationStation
|
||||
cd YourEmulationStationDirectory
|
||||
git pull
|
||||
export CXX=g++-4.7
|
||||
cmake .
|
||||
make
|
||||
```
|
||||
|
||||
- If your problem still isn't gone, the best way to report a bug is to post an issue on GitHub. Try to post the simplest steps possible to reproduce the bug. Include files you think might be related (except for ROMs, of course). If you haven't re-run ES since the crash, the log file `~/.emulationstation/es_log.txt` is also helpful.
|
||||
|
||||
Building
|
||||
========
|
||||
|
||||
EmulationStation uses some C++11 code, which means you'll need to install at least g++-4.7 on Linux, or VS2010 on Windows.
|
||||
For installing and switching to g++-4.7 see [here](http://lektiondestages.blogspot.de/2013/05/installing-and-switching-gccg-versions.html). You can also just use `export CXX=g++-4.7` to explicitly specify the compiler for CMake (make sure you delete your CMake cache files if it's not working).
|
||||
EmulationStation uses some C++11 code, which means you'll need to use at least g++-4.7 on Linux, or VS2010 on Windows, to compile.
|
||||
|
||||
EmulationStation has a few dependencies. For building, you'll need SDL2, Boost (System, Filesystem, DateTime), FreeImage, FreeType, Eigen3, and cURL.
|
||||
|
||||
**On Linux:**
|
||||
**On Debian/Ubuntu:**
|
||||
All of this be easily installed with apt-get:
|
||||
```bash
|
||||
sudo apt-get install libsdl2-dev libboost-dev libboost-system-dev libboost-filesystem-dev libboost-date-time-dev libfreeimage-dev libfreetype6-dev libeigen3-dev libcurl-dev libasound2-dev
|
||||
|
|
@ -40,12 +41,9 @@ Unless you're on the Raspberry Pi, you'll also need OpenGL:
|
|||
sudo apt-get install libgl1-mesa-dev
|
||||
```
|
||||
|
||||
On the Raspberry Pi, there are also a few special libraries, located in /opt/vc/: the Broadcom libraries, libEGL, and GLES. You shouldn't need to install them; they are used by the Raspberry Pi port of SDL 2.
|
||||
|
||||
**Generate and Build Makefile with CMake:**
|
||||
```
|
||||
cd EmulationStation
|
||||
export CXX=g++-4.7
|
||||
```bash
|
||||
cd YourEmulationStationDirectory
|
||||
cmake .
|
||||
make
|
||||
```
|
||||
|
|
@ -119,13 +117,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 check two places for an es_systems.cfg file, in the following order:
|
||||
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`
|
||||
|
||||
The order EmulationStation displays systems reflects the order you define them in.
|
||||
|
||||
**NOTE:** A system *must* have at least one game present in its "path" directory, or ES will ignore it! If no systems are found, ES won't even start!
|
||||
**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:
|
||||
|
||||
|
|
@ -168,65 +166,40 @@ The following "tags" are replaced by ES in launch commands:
|
|||
|
||||
`%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.
|
||||
`%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.
|
||||
|
||||
|
||||
gamelist.xml
|
||||
============
|
||||
|
||||
The gamelist.xml 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 games, such as a name, image (like a screenshot or box art), description, release date, and rating.
|
||||
|
||||
ES will check three places for a gamelist.xml, in the following order:
|
||||
* `[SYSTEM_PATH]/gamelist.xml`
|
||||
* `~/.emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
|
||||
* `/etc/emulationstation/gamelists/[SYSTEM_NAME]/gamelist.xml`
|
||||
|
||||
This file allows you to define images, descriptions, and different names for files. Note that only standard ASCII characters are supported for text (if you see a weird [X] symbol, you're probably using Unicode!).
|
||||
Images will be automatically resized to fit within the left column of the screen. Smaller images will load faster, so try to keep your resolution low.
|
||||
An example gamelist.xml:
|
||||
```xml
|
||||
<gameList>
|
||||
<game>
|
||||
<path>/home/pi/ROMs/nes/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.</desc>
|
||||
<image>/home/pi/Screenshots/megaman2.png</image>
|
||||
</game>
|
||||
</gameList>
|
||||
```
|
||||
|
||||
The path element should be either the absolute path of the ROM, or a path relative to the system games folder that starts with "./". For example:
|
||||
|
||||
`<path>/home/pi/ROMs/nes/mm2.nes</path>`
|
||||
|
||||
or
|
||||
|
||||
`<path>./mm2.nes</path>`
|
||||
|
||||
ES will attempt to encode paths as relative to the system's `path` setting whenever it writes a gamelist.xml. Special characters SHOULD NOT be escaped. The image element is the path to an image to display above the description (like a screenshot or boxart). Most popular image formats can be used (png, jpg, gif, etc.). Not all elements need to be used.
|
||||
|
||||
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).
|
||||
|
||||
*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 "SCRAPE NOW".
|
||||
* **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.
|
||||
|
||||
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."
|
||||
|
||||
If you're writing a tool to generate gamelist.xml files, you can see the complete list of possible elements at the top of `src/MetaData.cpp`.
|
||||
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."
|
||||
|
||||
A command-line version of the scraper is also provided - just run emulationstation with `--scrape` *(currently broken)*.
|
||||
|
||||
The switch `--ignore-gamelist` can be used to ignore the gamelist and force ES to use the non-detailed view.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Themes
|
||||
======
|
||||
|
||||
By default, EmulationStation looks pretty ugly. You can fix that. If you want to know more about making your own themes (or editing existing ones), read THEMES.md!
|
||||
By default, EmulationStation looks pretty ugly. You can fix that. If you want to know more about making your own themes (or editing existing ones), read [THEMES.md](THEMES.md)!
|
||||
|
||||
I've put some themes up for download on my EmulationStation webpage: http://aloshi.com/emulationstation#themes
|
||||
|
||||
If you're using RetroPie, you should already have a nice set of themes automatically installed!
|
||||
|
||||
-Aloshi
|
||||
|
||||
-Alec "Aloshi" Lofquist
|
||||
http://www.aloshi.com
|
||||
http://www.emulationstation.org
|
||||
|
|
|
|||
|
|
@ -476,6 +476,3 @@ 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)
|
||||
|
||||
-Aloshi
|
||||
http://www.aloshi.com
|
||||
|
|
|
|||
Loading…
Reference in a new issue