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

Documentation update for the 3.0.0 release

Browse source
This commit is contained in:
Leon Styhre 2024-02-17 17:28:23 +01:00
parent 9da1fbd9d5
commit 99cdf9cc11
9 changed files with 1043 additions and 805 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
CHANGELOG.md
View file

@ -1,11 +1,17 @@
# ES-DE (EmulationStation Desktop Edition) - Changelog
## Version 3.0.0 (in development)
## Version 3.0.0
**Release date:** TBD
**Release date:** 2024-02-17
### Release overview
The 3.0 release rebrands the application from EmulationStation Desktop Edition to simply ES-DE. And as part of this the application data directory has changed from .emulationstation to ES-DE and its internal structure has been improved. There is also a new default theme named Linear that is bundled with the application.
Support for configurable font sizes has also been added, so assuming the theme supports it, it's now possible to select between these sizes from the _UI settings_ menu.
A number of minor improvements and bug fixes are also part of this release.
### Detailed list of changes
* Renamed the application from EmulationStation Desktop Edition to ES-DE
@ -22,7 +28,7 @@
* Changed the custom slideshow image directory setting from ScreensaverSlideshowImageDir to ScreensaverSlideshowCustomDir
* The HTTP error code will now be shown on scraper errors instead of the "File is smaller than 350 bytes" message
* Removed the ScraperHaltOnInvalidMedia option and corresponding menu entry as it has been superseded by the HTTP error code logic
* Added a ScraperIgnoreHTTP404Errors option that can be manually set in es_settings.xml to ignore 404 errors (resource not found)
* Added a ScraperIgnoreHTTP404Errors option that can be manually set in es_settings.xml to ignore 404 errors (i.e. resource not found)
* Added Mednafen standalone as an alternative emulator for the gb, gba, gbc and supergrafx systems
* Added Mesen standalone as an alternative emulator for the gamegear, mastersystem and multivision systems on Linux, Unix and Windows
* Added Mesen standalone as an alternative emulator for the sg-1000 and supergrafx systems on Linux, Unix and Windows
@ -58,6 +64,8 @@
* The relevant SDL error message is now printed to the log if a controller could not be added
* Added rendering workarounds for some mobile GPUs which do not support all OpenGL operations when using the BGRA pixel format
* Added the UTF8-CPP library as a dependency
* Updated SDL to 2.30.0 on Windows, macOS and the Linux AppImage builds
* Bundled the December 2023 release of the Mozilla TLS/SSL certificates
### Bug fixes

38
FAQ.md
View file

@ -1,20 +1,16 @@
# ES-DE (EmulationStation Desktop Edition) - Frequently Asked Questions
## What is this project and how is it related to other EmulationStation forks?
## What's the correct name for the application? ES-DE, EmulationStation etc?
This project started in 2020 as a fork of RetroPie EmulationStation and it has been in very active development ever since. Large parts of the application have been rewritten and much functionality has been added, so overall it's a quite different application by now.
## What's the correct name? EmulationStation, ES-DE, Emulation Station, EmuStation etc?
The correct name is EmulationStation Desktop Edition, which is for practical reasons often shortened to EmulationStation-DE or more commonly ES-DE. It's not spelled Emulation Station (i.e. two separate words) in the same manner as you don't write Sony Play Station or Nintendo Game Cube.
As of the 3.0.0 release the official name for the project and application is ES-DE or sometimes ES-DE Frontend. This stands for EmulationStation Desktop Edition as the project originated from the RetroPie fork of EmulationStation in 2020, and was originally intended for desktop computers. However the application has now changed so much that it would just cause confusion to keep the EmulationStation name. During a transition period EmulationStation Desktop Edition will be included as a subtitle on the splash screen and mentioned in some documentation entries, but long term this will be dropped entirely. The red version of the EmulationStation logo will however remain as it's part of the application legacy.
## Is this software available for free, and is it open source?
ES-DE is available for free. Voluntary donations to support the project are however very welcome. The application is released under the MIT open source license with the source code readily available to anyone via the project's [GitLab site](https://gitlab.com/es-de/emulationstation-de).
ES-DE is available for free on Windows, macOS and Linux and it's released under the MIT open source license.
## Which operating systems are supported?
ES-DE runs on Windows, macOS and BSD Unix as well as on multiple Linux distributions including Ubuntu, Fedora, Arch, Manjaro, SteamOS etc.
ES-DE runs on Windows, macOS and multiple Linux distributions including Ubuntu, Fedora, Arch, Manjaro, SteamOS etc.
## What is the relationship between ES-DE and RetroDECK?
@ -22,7 +18,7 @@ ES-DE and [RetroDECK](http://retrodeck.net) are completely separate projects, bu
## What is the relationship between ES-DE and EmuDeck?
[EmuDeck](http://www.emudeck.com) is an installer that installs ES-DE and a number of emulators. There is no relationship between the two projects apart from this, and it's generally not recommended to use EmuDeck as this will lead to a non-standard installation. There are few tangible benefits to using EmuDeck over a manual installation apart from some convenience for the initial setup. Instead it's recommended to setup your emulators manually which will allow you to configure everything exactly to your liking. That is also a fun and interesting experience.
EmuDeck is an installer that installs ES-DE and a number of emulators. There is no relationship between the two projects apart from this, and it's not recommended to use EmuDeck as this will lead to a non-standard installation and can cause a lot of other issues as well. Instead it's recommended to setup your emulators manually which will allow you to configure everything exactly to your liking.
## What game systems/platforms and emulators are supported by ES-DE?
@ -34,7 +30,7 @@ Menus in ES-DE are not lists but grids, sometimes there is only a list but somet
## Can I change the system sorting to not sort by full system names?
Yes the systems sorting configuration file can be selected via the _Systems sorting_ option in the _UI Settings_ menu. There are four such files bundled with ES-DE to sort by _"Release year", "Manufacturer, release year", "Hardware type, release year"_ and _"Manufacturer, hardware type, release year"_. If you don't want to use any of the bundled files then you can create your own custom sorting file and place it into the ~/.emulationstation/custom_systems/ directory. More details about this setup can be found in the _es_systems_sorting.xml_ section of the [Building and advanced configuration](INSTALL.md#es_systems_sortingxml) document.
Yes the systems sorting configuration file can be selected via the _Systems sorting_ option in the _UI Settings_ menu. There are four such files bundled with ES-DE to sort by _"Release year", "Manufacturer, release year", "Hardware type, release year"_ and _"Manufacturer, hardware type, release year"_. If you don't want to use any of the bundled files then you can create your own custom sorting file and place it into the ~/ES-DE/custom_systems/ directory. More details about this setup can be found in the _es_systems_sorting.xml_ section of the [Building and advanced configuration](INSTALL.md#es_systems_sortingxml) document.
## I'm missing some systems like SNES MSU-1 and WiiWare, could those get added to ES-DE?
@ -46,7 +42,7 @@ ES-DE comes preconfigured with support for many alternative emulators, see the [
## I'm on Windows and ES-DE can't find my emulators, what is wrong?
On Windows ES-DE is shipped as a portable installation and as a regular installer. If you're using the portable installation you need to drop your emulators inside the Emulators directory. Make sure to read the README.txt file directly in the EmulationStation-DE folder for more details. For the regular installer many emulators do not provide a method to inform ES-DE where they are installed, so you will need to add their installation directories to the Path environment variable in Windows. It's strongly recommended to read the _Specific notes for Windows_ section of the [User guide](USERGUIDE.md#specific-notes-for-windows) before attempting to setup and use ES-DE on Windows.
On Windows ES-DE is shipped as a portable installation and as a regular installer. If you're using the portable installation you need to drop your emulators inside the Emulators directory. Make sure to read the README.txt file directly in the ES-DE folder for more details. For the regular installer many emulators do not provide a method to inform ES-DE where they are installed, so you will need to add their installation directories to the Path environment variable in Windows. It's strongly recommended to read the _Specific notes for Windows_ section of the [User guide](USERGUIDE.md#specific-notes-for-windows) before attempting to setup and use ES-DE on Windows.
## I'm on Windows and ES-DE refuses to start, is the application broken?
@ -54,7 +50,7 @@ You're probably missing the OpenGL drivers required to run ES-DE. Try to downloa
## I'm on Windows and there is only a black screen shown on startup or when launching a game, is there a way to fix this?
This behavior has been observed for some specific AMD GPUs in the past. In some instances there is only a black screen on startup and in some instances the application starts and runs correctly but launching a game only shows a black screen. The issue is seemingly caused by GPU driver bugs and it only affects Windows as Linux works fine with the same hardware. The workaround is to make ES-DE run in windowed mode. You accomplish this by using the --resolution flag and setting the width to one pixel wider than your screen resolution. So if for instance running at a 1280x800 display resolution, run ES-DE such as this: `EmulationStation.exe --resolution 1281 800`
This behavior has been observed for some specific AMD GPUs in the past. In some instances there is only a black screen on startup and in some instances the application starts and runs correctly but launching a game only shows a black screen. The issue is seemingly caused by GPU driver bugs and it only affects Windows as Linux works fine with the same hardware. The workaround is to make ES-DE run in windowed mode. You accomplish this by using the --resolution flag and setting the width to one pixel wider than your screen resolution. So if for instance running at a 1280x800 display resolution, run ES-DE such as this: `ES-DE.exe --resolution 1281 800`
## The emulators don't seem to be properly configured?
@ -84,13 +80,9 @@ See the question above for a possible solution. Another approach would be to hid
No, by default games are not removed from the gamelists when they are hidden and are instead only marked with a much lower opacity. You need to disable the setting _Show hidden games_ from the _Other Settings_ menu to make them disappear entirely. The reason this option is not disabled by default is that new users could very easily make a mistake by hiding some files accidentally without realizing it, only to have the entries being immediately removed from the gamelist view. It's also good practice to hide all your games with this option enabled and verify that it's all correct before going ahead and disabling it.
## I'm using Linux or macOS and I can't find the .emulationstation directory, where is it located?
The .emulationstation directory is normally located in your home directory, but on these Unix-based operating systems files and directories starting with a dot are hidden by default. So you need to enable hidden files and directories in your file manager. On macOS this is done in Finder using the Shift + Command + . (a dot) keyboard combination. On Linux it depends on which file manager you're using, but in KDE's Dolphin it's accomplished by using the Alt + . (a dot) keyboard combination or via the corresponding entry in the hamburger menu.
## I can't find a ROM directory setting in the user interface, so how do I relocate my games?
There is no need for such a setting as ES-DE will not start unless it finds at least one game. So you simply need to move your ROM directory to its new location using your operating system's file manager or terminal and then the next time you start ES-DE you will be shown a dialog where you can enter the new directory. Optionally you can manually change the ROMDirectory setting in ~/.emulationstation/es_settings.xml
There is no need for such a setting as ES-DE will not start unless it finds at least one game. So you simply need to move your ROM directory to its new location using your operating system's file manager or terminal and then the next time you start ES-DE you will be shown a dialog where you can enter the new directory. Optionally you can manually change the ROMDirectory setting in ~/ES-DE/es_settings.xml
## What are miximages precisely and why don't they get updated when I change my miximage settings?
@ -98,7 +90,7 @@ As the name implies these are images, and more specifically they are generated b
## Is there a way to customize existing systems, and/or to add more systems than those shipped by default?
Yes it's possible to both customize existing systems that are part of the bundled configuration as well as to add more systems than those shipped with ES-DE. Almost nothing is hardcoded in the application so there is a huge flexibility when it comes to such configuration. How this is done is covered in the _Game system customizations_ section of the [User guide](USERGUIDE.md#game-system-customizations). Just make sure to never modify the es_systems.xml and es_find_rules.xml files included in the application installation directory as these will be overwritten when upgrading ES-DE in the future. Always place your customizations in ~/.emulationstation/custom_systems/ as is also described in the user guide.
Yes it's possible to both customize existing systems that are part of the bundled configuration as well as to add more systems than those shipped with ES-DE. Almost nothing is hardcoded in the application so there is a huge flexibility when it comes to such configuration. How this is done is covered in the _Game system customizations_ section of the [User guide](USERGUIDE.md#game-system-customizations). Just make sure to never modify the es_systems.xml and es_find_rules.xml files included in the application installation directory as these will be overwritten when upgrading ES-DE in the future. Always place your customizations in ~/ES-DE/custom_systems/ as is also described in the user guide.
## Can I use the Steam release of RetroArch?
@ -110,7 +102,7 @@ You would normally use the built-in theme downloader to install additional theme
## I added some EmulationStation themes manually but they don't seem to show up inside ES-DE?
Only themes made specifically for ES-DE can be used. If you want to use a theme from Batocera, Recalbox, RetroBat, RetroPie etc. then it first needs to be ported to the ES-DE theme engine. If you place a non-supported theme in the ~/.emulationtation/themes/ directory then this will be ignored on startup, meaning it will not be selectable from the _UI Settings_ menu.
EmulationStation themes are not supported by ES-DE. If you want to use a theme from Batocera, Recalbox, RetroBat, RetroPie etc. then it first needs to be ported to the ES-DE theme engine. If you place a non-supported theme in the ES-DE/themes/ directory then this will be ignored on startup, meaning it will not be selectable from the _UI Settings_ menu.
## I used to be a Batocera/Recalbox user and ES-DE can't seem to find some of my games?
@ -122,15 +114,11 @@ There is a built-in application updater that works with the Linux AppImage relea
## I can't find any game media links in the gamelist.xml files, where is this data stored?
ES-DE works differently compared to all other EmulationStation forks when it comes to handling of game media. There are no links in the gamelist.xml files, instead media files are matched against the ROM/game file names which makes for a much simpler, faster and completely portable setup. Migrating game media from other EmulationStation forks (and potentially from other frontends as well) can be accomplished quite easily. See the next question below for more information. Make sure to also read the _Migrating from other EmulationStation forks_ section of the [User guide](USERGUIDE.md#migrating-from-other-emulationstation-forks) to avoid data loss if running ES-DE with existing data from another EmulationStation fork.
ES-DE works differently compared to EmulationStation when it comes to handling of game media. There are no links in the gamelist.xml files, instead media files are matched against the ROM/game file names which makes for a much simpler, faster and completely portable setup. Migrating game media from EmulationStation (and potentially from other frontends as well) can be accomplished quite easily. Make sure to also read the _Migrating from EmulationStation_ section of the [User guide](USERGUIDE.md#migrating-from-emulationstation) to avoid data loss if running ES-DE with existing data from EmulationStation.
## It seems like gamelist.xml files in the ROM directory tree are not getting loaded?
These files are not loaded by default as of ES-DE 2.0.0, only files placed in .emulationstation/gamelists/ are processed. If you insist on retaining the old logic of also looking for gamelist.xml files in the ROM directory tree then you can enable the LegacyGamelistFileLocation setting in es_settings.xml as explained in the _Settings not configurable via the GUI_ section of the [Building and advanced configuration](INSTALL.md#settings-not-configurable-via-the-gui) document.
## Why do I sometimes get error messages when scraping stating that files are less than 350 bytes in size?
This issue can occur occassionally as the ScreenScraper servers sometimes return invalid responses, in this case simply pressing the _RETRY_ button often works. But there is also a ScreenScraper bug where their cache could include entries that no longer exist. When a media file is removed from the ScreenScraper database, the cached link to that file is retained for some time and will be returned as a valid media file URL to ES-DE. However, when attempting to scrape such a file, it will only contain the text string _NOMEDIA_ which will trigger this error in ES-DE. The cache bug only affects the multi-scraper API call, so a workaround is to manually scrape such games using the single-game scraper (reachable via the metadata editor). The invalid cache entries seem to disappear within 24 hours so waiting for a while and rescraping should also resolve the problem. The issue has been reported to the ScreenScraper team but it's unclear if and when it will be resolved.
These files are not loaded by default, only files placed in ES-DE/gamelists/ are processed. If you insist on also looking for gamelist.xml files in the ROM directory tree then you can enable the LegacyGamelistFileLocation setting in es_settings.xml as explained in the _Settings not configurable via the GUI_ section of the [Building and advanced configuration](INSTALL.md#settings-not-configurable-via-the-gui) document.
## Can I use an external scraper application instead of the built-in scraper?

1150
INSTALL.md
View file

File diff suppressed because it is too large Load diff

2
THEMES-DEV.md
View file

@ -2,7 +2,7 @@
**Note:** This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [THEMES.md](THEMES.md) instead.
If creating themes specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Themes made for ES-DE are not compatible with any other EmulationStation forks (and vice versa) and the -es-de extension makes it clear that it's an ES-DE theme. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting themes from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu.
If creating themes for ES-DE, please add `-es-de` to the repository/directory name to clearly indicate that it's a theme for this frontend. Two examples would be `linear-es-de` and `modern-es-de`. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting themes from the _UI Settings_ menu. For example linear-es-de will be listed simply as _Linear_ in this menu.
Before your start, make sure to download the _Theme engine examples_ theme that contains a number of example variants for things like vertical and horizontal carousels, wheel carousels, system view text lists, grids etc:

139
THEMES.md
View file

@ -1,6 +1,6 @@
# ES-DE (EmulationStation Desktop Edition) v2.2 - Themes
# ES-DE (EmulationStation Desktop Edition) v3.0 - Themes
If creating themes specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Themes made for ES-DE are not compatible with any other EmulationStation forks (and vice versa) and the -es-de extension makes it clear that it's an ES-DE theme. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting themes from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu.
If creating themes for ES-DE, please add `-es-de` to the repository/directory name to clearly indicate that it's a theme for this frontend. Two examples would be `linear-es-de` and `modern-es-de`. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting themes from the _UI Settings_ menu. For example linear-es-de will be listed simply as _Linear_ in this menu.
Before your start, make sure to download the _Theme engine examples_ theme that contains a number of example variants for things like vertical and horizontal carousels, wheel carousels, system view text lists, grids etc:
@ -651,6 +651,95 @@ Here's an example configuration:
</theme>
```
## Font sizes
The optional font sizes functionality makes it possible to use a set of predefined size options and connect these to theme variables that can be used to apply different text sizes and related design changes. The font sizes declared for the theme can be selected via the _Theme font size_ setting in the _UI Settings_ menu.
To understand the basics on how to use variables, make sure to read the _Theme variables_ section elsewhere in this document.
To use the font size entries you first need to declare them using `<fontSize>` tag pairs in the `capabilities.xml` file. The following sizes are available:
| capabilities.xml name | UI Settings label |
| :-------------------- | :--------------- |
| medium | medium |
| large | large |
| small | small |
| x-large | extra large |
| x-small | extra small |
The options will always be listed in the above order in the _UI Settings_ menu.
Here's an example of a theme that implements three of these sizes:
```xml
<!-- Theme capabilities for mytheme-es-de -->
<themeCapabilities>
<themeName>My theme</themeName>
<fontSize>medium</fontSize>
<fontSize>small</fontSize>
<fontSize>x-small</fontSize>
</themeCapabilities>
```
In the theme configuration you'll also use a `<fontSize>` tag pair combined with a `<variable>` tag pair to define the variables you want to apply per font size.
These `<fontSize>` tag pairs can be placed directly inside the `<theme>` tags, inside the `<variants>` tags or inside the `<aspectRatio>` tags.
The mandatory name attribute is used to specificy which font size to use, and multiple values can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks).
Here's an example configuration:
```xml
<theme>
<fontSize name="medium">
<variables>
<gameCounterFontSize>0.025</gameCounterFontSize>
<gameCounterPos>0.5 0.6437</gameCounterPos>
<gameNameFontSize>0.022</gameNameFontSize>
<publisherFontSize>0.016</publisherFontSize>
</variables>
</fontSize>
<fontSize name="small">
<variables>
<gameCounterFontSize>0.015</gameCounterFontSize>
<gameCounterPos>0.45 0.6437</gameCounterPos>
<gameNameFontSize>0.013</gameNameFontSize>
</variables>
</fontSize>
<fontSize name="x-small">
<variables>
<gameCounterFontSize>0.008</gameCounterFontSize>
<gameCounterPos>0.4 0.6437</gameCounterPos>
<gameNameFontSize>0.006</gameNameFontSize>
</variables>
<fontSize name="small, x-small">
<variables>
<publisherFontSize>0.011</publisherFontSize>
</variables>
</fontSize>
<view name="system">
<text name="gameCounter">
<pos>${gameCounterPos}</pos>
<size>1 0.056</size>
<fontSize>${gameCounterFontSize}</fontSize>
</text>
<view name="gamelist">
<text name="gameName">
<pos>0.2 0.3412</pos>
<size>0.2 0.040</size>
<fontSize>${gameNameFontSize}</fontSize>
</text>
<text name="publisher">
<pos>0.33 0.3412</pos>
<size>0.18 0.040</size>
<fontSize>${publisherFontSize}</fontSize>
</text>
</view>
</theme>
```
## Aspect ratios
The aspect ratio support works almost identically to the variants and color schemes with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme can still decide which of the aspect ratios to support (or none at all in which case the theme aspect ratio is left undefined) but it can't create entirely new aspect ratio entries.
@ -876,15 +965,18 @@ The variant, color scheme and transitions names as well as their labels can be s
Unlike the types just mentioned, aspectRatio entries can not be set to arbitrary values, instead they have to use a value from the _horizontal name_ or _vertical name_ columns in the following table:
| Horizontal name | Vertical name | Common resolutions |
| :--------------- | :------------- | :--------------------------------------------- |
| 16:9 | 16:9_vertical | 1280x720, 1920x1080, 2560x1440, 3840x2160 |
| 16:10 | 16:10_vertical | 1280x800, 1440x900, 1920x1200 |
| 3:2 | 3:2_vertical | 2160x1440 |
| 4:3 | 4:3_vertical | 320x240, 640x480, 800x600, 1024x768, 1600x1200 |
| 5:4 | 5:4_vertical | 1280x1024 |
| 21:9 | 21:9_vertical | 2560x1080, 3840x1600, 5120x2160 |
| 32:9 | 32:9_vertical | 3840x1080, 5120x1440 |
| Horizontal name | Vertical name | Common resolutions |
| :--------------- | :-------------- | :--------------------------------------------- |
| 16:9 | 16:9_vertical | 1280x720, 1920x1080, 2560x1440, 3840x2160 |
| 16:10 | 16:10_vertical | 1280x800, 1440x900, 1920x1200 |
| 3:2 | 3:2_vertical | 2160x1440 |
| 4:3 | 4:3_vertical | 320x240, 640x480, 800x600, 1024x768, 1600x1200 |
| 5:4 | 5:4_vertical | 1280x1024 |
| 19.5:9 | 19.5:9_vertical | 2340x1080, 2532x1170 |
| 20:9 | 20:9_vertical | 2400x1080, 1600x720 |
| 21:9 | 21:9_vertical | 2560x1080, 3840x1600, 5120x2160 |
| 32:9 | 32:9_vertical | 3840x1080, 5120x1440 |
| 1:1 | 1:1 | Any square resolution |
The 21:9 and 32:9 aspect ratios are approximate as monitors of slightly different ratios are collectively marketed using these numbers.
@ -1327,10 +1419,11 @@ It's important to understand how the theme configuration files are parsed in ord
1) Transitions
2) Variables
3) Color schemes
4) Included files
5) "General" (non-variant) configuration
6) Variants
7) Aspect ratios
4) Font sizes
5) Included files
6) "General" (non-variant) configuration
7) Variants
8) Aspect ratios
When including a file using the `<include>` tag (i.e. step 4 above) then all steps listed above are executed for that included file prior to continuing to the next line after the `<include>` tag.
@ -1339,7 +1432,7 @@ For any given step, the configuration is parsed in the exact order that it's def
## Property data types
* NORMALIZED_PAIR - two decimal values delimited by a space, for example `0.25 0.5`
* PATH - path to a resource. If the first character is a tilde (`~`) then it will be expanded to the user's home directory (`$HOME` for Unix and macOS and `%HOMEPATH%` for Windows) unless overridden using the --home command line option. If the first character is a dot (`.`) then the resource will be searched for relative to the location of the theme file, for example `./myfont.ttf` or `./../core/fonts/myfont.ttf`
* PATH - path to a resource. If the first character is a tilde (`~`) then it will be expanded to the user's home directory (`$HOME` for Linux, BSD Unix and macOS and `%HOMEPATH%` for Windows) unless overridden using the --home command line option. If the first character is a dot (`.`) then the resource will be searched for relative to the location of the theme file, for example `./myfont.ttf` or `./../core/fonts/myfont.ttf`
* BOOLEAN - `true`/`1` or `false`/`0`
* COLOR - a hexadecimal RGB or RGBA color value consisting of 6 or 8 digits. If a 6 digit value is used then the alpha channel will be set to `FF` (completely opaque)
* UNSIGNED_INTEGER - an unsigned integer value
@ -1912,6 +2005,10 @@ Properties:
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the textlist exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0`
* `selectorWidth` - type: FLOAT
- Width of the selector bar. If an image has been defined using `selectorImagePath` then setting this property to zero will retain the aspect ratio for that image.
- Minimum value is `0` and maximum value is `1`
- Default is the equivalent value as the width of the overall element.
* `selectorHeight` - type: FLOAT
- Height of the selector bar. This is expanded downwards so you'll probably want to adjust its position using `selectorVerticalOffset` if making use of this property.
- Minimum value is `0` and maximum value is `1`
@ -2073,6 +2170,10 @@ Properties:
- `always` - Set element as stationary during all transitions.
- `never` - Don't set element as stationary during any transitions.
- Default is `never`
* `renderDuringTransitions` - type: BOOLEAN
- This special property which is only usable for slide transitions between the system and gamelist views makes it possible to for example have a background image stay seamlessly in place when transitioning, or being able to use semi-transparent stationary elements without having them render on top of each other during transitions. For this to work correctly only define `stationary` for one view and set `renderDuringTransitions` to false for the corresponding element in the other view. This way the element from the former view will keep rendering until the slide animation has been completed, after which the latter view will "take over" by rendering the element normally.
- This property can only be used if slide transitions are used, and only when moving from the system view to the gamelist view, or vice versa.
- Default is `true`
* `flipHorizontal` - type: BOOLEAN
- Flips the image texture horizontally.
- Default is `false`
@ -2643,7 +2744,7 @@ Properties:
- `sourceSystemName` - The source short system name of the game. For regular systems this value will be identical to `systemName` but for collections it will show the actual system that the game is located in instead of the collection system name.
- `sourceSystemFullname` - The source full system name of the game. For regular systems this value will be identical to `systemFullname` but for collections it will show the actual system that the game is located in instead of the collection system name.
* `defaultValue` - type: STRING
- This property makes it possible to override the default "unknown" text that is displayed if `metadata` has been set to `developer`, `publisher`, `genre` or `players` and there is no metadata available for the defined type. Any string can be used but you can't set it to a blank value. If you don't want to display anything when there is no metadata available, then set this property to `:space:` in which case a blankspace will be used. This property has no effect on the metadata editor where "unknown" will still be shown for blank values.
- This property makes it possible to override the default "unknown" text that is displayed if `metadata` has been set to `developer`, `publisher`, `genre` or `players` and there is no metadata available for the defined type. Any string can be used but you can't set it to a blank value. If you don't want to display anything when there is no metadata available, then set this property to `:space:` in which case a blankspace will be used. This property has no effect on the metadata editor where "unknown" will still be shown for blank values. A secondary use for this property is to set a default value if `metadata` has been set to `systemName`, `systemFullname`, `sourceSystemName` or `sourceSystemFullname` in which case the value will be used if the metadata value is blank. This is useful for defining a specific string at the root of the custom collections system.
* `systemNameSuffix` - type: BOOLEAN
- Whether to add the system name in square brackets after the game name when inside a collection system (automatic as well as custom collections). If `metadata` has been set to `description` then this property will only apply when inside the root of the grouped custom collections system where a summary of available games for the currently selected collection is displayed.
- Default is `true`
@ -2924,6 +3025,9 @@ Properties:
- `always` - Set element as stationary during all transitions.
- `never` - Don't set element as stationary during any transitions.
- Default is `never`
* `hideIfZero` - type: BOOLEAN
- If set to true then the element will not get rendered if the rating value is zero.
- Default is `false`
* `gameselector` - type: STRING
- If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view.
* `gameselectorEntry` - type: UNSIGNED_INTEGER
@ -2988,7 +3092,6 @@ Properties:
The helpsystem 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. Note that this element does not have a zIndex value, instead it's always rendered on top of all other elements. It also has to have its name attribute set to `help` or the configuration will not get loaded.
It's possible to set this element as right-aligned or center-aligned using a combination of the `pos` and `origin` properties. For example `<pos>1 1</pos>` and `<origin>1 1</origin>` will place it in the lower right corner of the screen.
Keep in mind that the width of this element can vary depending on a number of factors, for example the _Toggle favorites_ and _Random system or game_ buttons can be enabled or disabled via the _UI Settings_ menu. Test extensively with the menu system as well, especially the virtual keyboard which displays a number of helpsystem entries.

24
USERGUIDE-DEV.md
View file

@ -324,26 +324,13 @@ Instructions on how to customize the es_systems.xml file can be found in [INSTAL
In addition to the above it's also possible to customize the find rules via the `es_find_rules.xml` file. The logic is essentially identical to what is described for es_systems.xml, and details regarding this file can be found in [INSTALL-DEV.md](INSTALL-DEV.md#es_find_rulesxml) as well.
## Migrating from other EmulationStation forks
## Migrating from EmulationStation
**IMPORTANT!!! IMPORTANT!!! IMPORTANT!!!**
ES-DE is designed to be backward compatible to a certain degree. That is, it should be able to read data from other/previous EmulationStation versions such as the RetroPie and Batocera forks. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that previous ES versions will see as data loss. For instance ES-DE does not use tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively disabling the game media if the files are opened in another ES fork.
ES-DE is partially compatible with EmulationStation as both frontends originally shared the same source code. That is, ES-DE should generally be able to read data from EmulationStation. But the opposite is not true and it's a one-way ticket for your gamelist.xml files and your custom collection files when migrating to ES-DE as they will be modified in ways that EmulationStation will see as data loss. For instance ES-DE does not use tags inside the gamelist.xml files to find game media but instead matches the media to the names of the game/ROM files. So it will not save any such tags back to the gamelist files during updates, effectively disabling the game media if the files are opened in EmulationStation.
Due to this, always make backups of at least the following directories before testing ES-DE for the first time:
```
~/ES-DE/gameslists/
~/ES-DE/collections/
```
If you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/ES-DE/gamelists/ tree.
It's also strongly adviced to not rename an old es_settings.cfg file to es_settings.xml for use in ES-DE as it may cause undefined behavior and crashes.
If migrating from Batocera, RetroBat or Recalbox, be aware that ES-DE follows the RetroPie naming conventions for most game systems. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera, RetroBat and Recalbox has the _sg1000_ system name, but is _sg-1000_ in RetroPie and ES-DE. See the [Supported game systems](USERGUIDE-DEV.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE.
Another potential issue when migrating from another EmulationStation fork is that the path tag requires a leading ./ in ES-DE while that may not be present in other forks. If you don't see any metadata for your games inside ES-DE, then simply add the ./ characters to each path tag and it should hopefully work.
Another potential issue when migrating gamelist.xml files from EmulationStation is that the path tag requires a leading ./ in ES-DE while that may not be present in files coming from EmulationStation. If you don't see any metadata for your games inside ES-DE, then simply add the ./ characters to each path tag and it should hopefully work.
Example of an unreadable path tag:
```
@ -355,6 +342,11 @@ Example of a correct path tag readable by ES-DE:
<path>./Another World.lha</path>
```
And if you have gamelist.xml files in your ROMs directory tree then ES-DE will ignore those by default, so you need to move them to the ~/ES-DE/gamelists/ tree.
If migrating from Batocera, RetroBat or Recalbox, be aware that ES-DE does not always use the same system names as those frontends. This means that your game files may not be found unless the folders are renamed accordingly. Such an example is the Sega SG-1000 system which in Batocera, RetroBat and Recalbox has the _sg1000_ system name, but is _sg-1000_ in ES-DE. See the [Supported game systems](USERGUIDE-DEV.md#supported-game-systems) table at the bottom of this guide for the correct system names in ES-DE.
## Removing orphaned data
Manually removing game files from the ROMs directory tree instead of deleting them from ES-DE using the metadata editor will make any corresponding scraped media files, gamelist.xml entries and custom collection entries orphaned, i.e. they will refer to non-existent files. Although this is correctly handled by ES-DE and is not causing any serious issues, it does lead to unnecessary disk space usage and it does produce log warnings in es_log.txt on application startup. If a huge amount of game files have been manually removed it can also lead to performance problems.

478
USERGUIDE.md
View file

File diff suppressed because it is too large Load diff

3
es-app/assets/org.es_de.frontend.appdata.xml
View file

@ -38,6 +38,9 @@
</screenshot>
</screenshots>
<releases>
<release version="3.0.0" date="2024-02-17">
<url>https://gitlab.com/es-de/emulationstation-de/-/releases</url>
</release>
<release version="2.2.1" date="2023-11-12">
<url>https://gitlab.com/es-de/emulationstation-de/-/releases</url>
</release>

BIN
images/es-de_application_updater.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 117 KiB

After

Width:  |  Height:  |  Size: 80 KiB