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

Documentation update

Browse source
This commit is contained in:
Leon Styhre 2024-09-09 19:02:50 +02:00
parent 2d09905584
commit a7c1d463ca
6 changed files with 288 additions and 66 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
ANDROID-DEV.md
View file

@ -516,22 +516,14 @@ https://github.com/Vita3K/Vita3K-Android/releases
### Winlator
In order to use Winlator to run Windows games you need to use a specific fork named _Winlator Cmod_ as mainline [Winlator](https://winlator.com/) does not offer frontend support. However the official GitHub page of this fork has disappeared so it's not clear which is the official release and where it can be downloaded from. As there are now multiple builds floating around the Internet you'll need to do some web searches to find a reliable distribution.
In order to use Winlator to run Windows games you need to use a specific fork named _Winlator Cmod_ as mainline [Winlator](https://winlator.com/) does not offer frontend support. The Cmod fork can be downloaded from their GitHub page:\
https://github.com/coffincolors/winlator
There are two variants of the fork, Glibc and PRoot, both of which comes with some pros and cons with regards to compatibility and performance.
There are two variants of the fork, Glibc and PRoot, both of which come with some pros and cons with regards to compatibility and performance. The Glibc variant is the default emulator in ES-DE, so to use PRoot instead you'll need to select its alternative emulator entry.
The following builds have been successfully tested with ES-DE:
In addition to the official repository there are multiple Winlator builds floating around the Internet, but these have not been extensively tested with ES-DE.
| Filename | Type | MD5 hash |
| :-------------------------------------- | :---- |:-------------------------------- |
| cmod-v6-pre-release-v6fix1.apk | glibc | 678c6edf341f17128b071daa9756c459 |
| Winlator-7.1.3-glibc-cmod-v7fix5.apk | glibc | a3d935d7d09e7999c43511de333efbcc |
| Winlator-7.1.2-proot-cmod-v6.5-BETA.apk | proot | 540fcc6faf1f0938d1bee3c85235d9ed |
Consider these as examples only, there may very well be a lot of other builds that work fine with ES-DE.
It's beyond the scope of this document to describe how to install games in Winlator, but once it's done and you've created a shortcut to your game from inside the container you can export it via the _Export for Frontend_ option in the Winlator user interface. This will generate a .desktop file that you can place in the `ROMs/windows` folder and launch from ES-DE.
It's beyond the scope of this document to describe how to install games in Winlator, but once it's done and you've created a shortcut to your game from inside the container you can export it via the _Export for Frontend_ option in the Winlator user interface. This will generate a .desktop file that you can place in the `ROMs/pcarcade`, `ROMs/type-x` or `ROMs/windows` folder and launch from ES-DE. You can alternatively set the _Frontend Export Path_ setting from inside the Winlator Settings screen to avoid the manual step of moving the .desktop file.
### Yaba Sanshiro 2
@ -783,7 +775,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| pc | IBM PC | DOSBox-Pure | DOSBox-Core,<br>DOSBox-SVN,<br>VirtualXT | No | See the specific _DOS / PC_ section in the user guide |
| pc88 | NEC PC-8800 Series | QUASI88 | | Yes | |
| pc98 | NEC PC-9800 Series | Neko Project II Kai | Neko Project II | | |
| pcarcade | PC Arcade Systems | _Placeholder_ | | | | |
| pcarcade | PC Arcade Systems | Winlator Cmod Glibc **(Standalone)** | Winlator Cmod PRoot **(Standalone)** | No | See the _Winlator_ section elsewhere in this document |
| pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST,<br>Beetle SuperGrafx,<br>PCE.emu **(Standalone)** | No | Single archive or ROM file |
| pcenginecd | NEC PC Engine CD | Beetle PCE | Beetle PCE FAST,<br>Beetle SuperGrafx,<br>PCE.emu **(Standalone)** | Yes | |
| pcfx | NEC PC-FX | Beetle PC-FX | | Yes | |
@ -832,7 +824,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| to8 | Thomson TO8 | Theodore | | | |
| triforce | Namco-Sega-Nintendo Triforce | _Placeholder_ | | | |
| trs-80 | Tandy TRS-80 | _Placeholder_ | | | |
| type-x | Taito Type X | _Placeholder_ | | | |
| type-x | Taito Type X | Winlator Cmod Glibc **(Standalone)** | Winlator Cmod PRoot **(Standalone)** | No | See the _Winlator_ section elsewhere in this document |
| uzebox | Uzebox Open Source Console | Uzem | | | |
| vectrex | GCE Vectrex | vecx | MAME4droid 2024 **(Standalone)** | Yes for MAME4droid 2024 | Single archive or ROM file |
| vic20 | Commodore VIC-20 | VICE xvic | | No | Single archive or tape, cartridge or diskette image file |
@ -843,7 +835,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file |
| wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,<br>Dolphin MMJR **(Standalone)**,<br>Dolphin MMJR2 **(Standalone)** | No | |
| wiiu | Nintendo Wii U | _Placeholder_ | | | |
| windows | Microsoft Windows | Winlator Glibc Cmod **(Standalone)** | Winlator PRoot Cmod **(Standalone)** | No | See the _Winlator_ section elsewhere in this document |
| windows | Microsoft Windows | Winlator Cmod Glibc **(Standalone)** | Winlator Cmod PRoot **(Standalone)** | No | See the _Winlator_ section elsewhere in this document |
| windows3x | Microsoft Windows 3.x | DOSBox-Pure | | No | |
| windows9x | Microsoft Windows 9x | DOSBox-Pure | | No | |
| wonderswan | Bandai WonderSwan | Beetle Cygne | Swan.emu **(Standalone)** | No | Single archive or ROM file |

20
CHANGELOG.md
View file

@ -8,13 +8,13 @@
This release brings full localization support and includes translations to ten new languages. More specifically these are Spanish (Spain), French, Italian, Polish, Portuguese (Brazil), Romanian, Russian, Swedish, Japanese and Simplified Chinese. More languages will follow in future releases.
As part of the localization work there have been substantial changes made to the application; text rendering has been improved with proper text shaping using the HarfBuzz library and case mappings and boundary analysis are now performed by the ICU library.
As part of the localization work there have been substantial changes made to the application, for instance to the text rendering which has been improved with proper text shaping using the HarfBuzz library. Case mappings and boundary analysis are now also performed by the ICU library rather than using inaccurate built-in functions as was previously the case.
As for minor but notable improvements, entering the wrong ScreenScraper credentials will now display an error popup during scraping, specific subdirectories inside the system folders can be excluded from getting loaded, and the starting time for the video screensaver has been greatly reduced on devices with poor disk I/O performance, such as Android.
As for other notable improvements, entering the wrong ScreenScraper credentials will now display an error popup during scraping, specific subdirectories inside the system folders can be excluded from getting loaded, and the starting time for the screensaver has been greatly reduced on devices with poor disk I/O performance, such as Android. A number of new systems have also been enabled on Android, which brings game system support for this platform one step closer to being on par with the desktop ports.
The release also brings a new port with experimental support for the Haiku operating system.
And talking of ports, this release also brings experimental support for the Haiku operating system.
See the full list below for all changes like added emulators, launch command modifications and bug fixes.
See the full list below for all changes and bug fixes.
### Detailed list of changes
@ -32,10 +32,12 @@ See the full list below for all changes like added emulators, launch command mod
* Added translations for Swedish (sv_SE)
* Added translations for Japanese (ja_JP)
* Added translations for Simplified Chinese (zh_CN)
* Dramatically improved start times for the video and slideshow screensavers on devices with poor disk I/O performance (like Android)
* Added support for skipping the scanning of game system subdirectories (by using noload.txt files)
* Dramatically reduced the start time for the video and slideshow screensavers on devices with poor disk I/O performance (like Android)
* Added support for skipping game system subdirectories scanning on startup (by using noload.txt files)
* Added an error popup if incorrect credentials (username and password) are used when scraping using ScreenScraper
* Added a "Dark and red" menu color scheme to improve perceived contrast on low-contrast displays
* (Android) Added support for the PC Arcade Systems (pcarcade) game system using the Winlator emulator
* (Android) Added support for the Taito Type X (type-x) game system using the Winlator emulator
* (Android) Added support for the Microsoft Windows (windows) game system using the Winlator emulator
* (Android) Added support for the Dragon Data Dragon 32 (dragon32) game system
* (Android) Added support for the Tano Dragon (tanodragon) game system
@ -64,7 +66,9 @@ See the full list below for all changes like added emulators, launch command mod
* (Android) Added support for using the %BASENAME% variable with the %EXTRA% and %EXTRAARRAY% variables
* Text within parantheses is no longer stripped out from the game name popup when adding or removing games from custom collections
* Renamed the "Menu opening effect" setting in the UI settings menu to "Menu opening animation"
* (linear-es-de) Added translations for en_US, en_GB and sv_SE
* (linear-es-de) Added translations for all supported languages
* (modern-es-de) Added translations for all supported languages
* (slate-es-de) Added partial translations for all supported languages
* Added a "backgroundMargins" property to the datetime element
* Added a "backgroundCornerRadius" property to the datetime element
* Added a check for whether a text element has a width defined when the container property is set
@ -76,7 +80,7 @@ See the full list below for all changes like added emulators, launch command mod
* Added the HarfBuzz library as a dependency
* Added the ICU library as a dependency
* Refactored large parts of the text and font code
* Added experimental support for building on Haiku
* Added experimental support for the Haiku operating system
* Added some improvements for building and running on FreeBSD
* Removed support for NetBSD and OpenBSD
* Updated SDL to 2.30.7 on Android, Windows, macOS and the Linux AppImage builds

5
INSTALL-DEV.md
View file

@ -165,6 +165,11 @@ It could also be a good idea to use the `TSAN_suppressions` file included in the
TSAN_OPTIONS="suppressions=tools/TSAN_suppressions" ./es-de --debug --resolution 2560 1440
```
On some Linux distributions you need to modify the _vm.mmap_rnd_bits_ kernel runtime parameter or you'll see an error message such as _FATAL: ThreadSanitizer: unexpected memory mapping 0x58bd90d75000-0x58bd90dbe000_ when attempting to start ES-DE. Setting the parameter to 28 should make ThreadSanitizer work correctly. The following is how it's done on Ubuntu:
```
sudo sysctl vm.mmap_rnd_bits=28
```
To enable UndefinedBehaviorSanitizer which helps with identifying bugs that may otherwise be hard to find, build with the UBSAN option:
```
cmake -DCMAKE_BUILD_TYPE=Debug -UBSAN=on .

17
THEMES-DEV.md
View file

@ -102,9 +102,9 @@ There are two places that ES-DE can load themes from:
An installation path could be something like this:
```
/usr/share/emulationstation/themes/slate-es-de/
/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/
C:\Program Files\EmulationStation-DE\themes\
/usr/share/es-de/themes/
/Applications/ES-DE.app/Contents/Resources/themes/
C:\Program Files\ES-DE\themes\
```
If a theme with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped.
@ -145,7 +145,7 @@ As for more specific changes, the following are the most important ones compared
* The helpsystem `textColorDimmed` and `iconColorDimmed` properties (which apply when opening a menu) were always defined under the system view configuration which meant these properties could not be separately set for the gamelist views. Now these properties work as expected with the possibility to configure separate values for the system and gamelist views
* When right-aligning the helpsystem using an X origin value of 1, the element is now aligned correctly to the defined position instead of being offset by the entrySpacing width (in RetroPie ES the offset was instead the hardcoded element entry padding)
* Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail
* Many additional elements and properties have been added, refer to the [Reference](THEMES-DEV.md#reference) section for more information
* Many additional elements and properties have been added, refer to the reference section for more information
Attempting to use any of the legacy logic in the new theme structure will make the theme loading fail, for example adding the _extra="true"_ attribute to any element.
@ -298,8 +298,7 @@ This is the element structure:
</ElementTypeHere>
```
Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the
[Reference](THEMES-DEV.md#reference) section. Properties are defined like this:
Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the reference section. Properties are defined like this:
```xml
<propertyNameHere>valueHere</propertyNameHere>
@ -381,7 +380,7 @@ If you are writing a theme it's recommended to enable the _Debug mode_ setting f
Here's an example of launching ES-DE in debug mode at a limited resolution, which will make it run in a window:
```
emulationstation --debug --resolution 1280 720
es-de --debug --resolution 1280 720
```
Enforcement of a correct theme configuration is quite strict, and most errors will abort the theme loading, leading to an unthemed system. In each such situation the log output will be very clear of what happened, for instance:
@ -396,7 +395,7 @@ Sanitization for valid data format and structure is done in this manner, but ver
Jan 28 17:25:27 Warn: BadgeComponent: Invalid theme configuration, property "horizontalAlignment" for element "gamelistBadges" defined as "leftr"
```
Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the [Reference](THEMES-DEV.md#reference) section of this document for valid values for each property.
Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the reference section of this document for valid values for each property.
For more serious issues where it does not make sense to assign a default value or auto-adjust the configuration, an error log entry is generated and the element will in most instances not get rendered at all. Here's such an example where the imageType property for a video element was accidentally set to _covr_ instead of _cover_:
@ -1461,7 +1460,7 @@ Example `navigationsounds.xml` file:
## Element rendering order using zIndex
You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default value so you only need to define it for the ones you wish to explicitly change. Elements will be rendered in order from smallest to largest values. A complete description of each element including all supported properties can be found in the [Reference](THEMES-DEV.md#reference) section.
You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default value so you only need to define it for the ones you wish to explicitly change. Elements will be rendered in order from smallest to largest values. A complete description of each element including all supported properties can be found in the reference section.
These are the default zIndex values per element type:

286
THEMES.md
View file

@ -95,14 +95,14 @@ themes/
The ES-DE theme functionality makes it easy for users to install different themes and to choose between them from the _UI Settings_ menu.
There are two places that ES-DE can load themes from:
* `[HOME]/.emulationstation/themes/`
* `[HOME]/ES-DE/themes/`
* `[INSTALLATION PATH]/themes/`
An installation path could be something like this:
```
/usr/share/emulationstation/themes/slate-es-de/
/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/
C:\Program Files\EmulationStation-DE\themes\
/usr/share/es-de/themes/
/Applications/ES-DE.app/Contents/Resources/themes/
C:\Program Files\ES-DE\themes\
```
If a theme with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped.
@ -143,7 +143,7 @@ As for more specific changes, the following are the most important ones compared
* The helpsystem `textColorDimmed` and `iconColorDimmed` properties (which apply when opening a menu) were always defined under the system view configuration which meant these properties could not be separately set for the gamelist views. Now these properties work as expected with the possibility to configure separate values for the system and gamelist views
* When right-aligning the helpsystem using an X origin value of 1, the element is now aligned correctly to the defined position instead of being offset by the entrySpacing width (in RetroPie ES the offset was instead the hardcoded element entry padding)
* Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail
* Many additional elements and properties have been added, refer to the [Reference](THEMES.md#reference) section for more information
* Many additional elements and properties have been added, refer to the reference section for more information
Attempting to use any of the legacy logic in the new theme structure will make the theme loading fail, for example adding the _extra="true"_ attribute to any element.
@ -296,8 +296,7 @@ This is the element structure:
</ElementTypeHere>
```
Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the
[Reference](THEMES.md#reference) section. Properties are defined like this:
Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the reference section. Properties are defined like this:
```xml
<propertyNameHere>valueHere</propertyNameHere>
@ -379,12 +378,12 @@ If you are writing a theme it's recommended to enable the _Debug mode_ setting f
Here's an example of launching ES-DE in debug mode at a limited resolution, which will make it run in a window:
```
emulationstation --debug --resolution 1280 720
es-de --debug --resolution 1280 720
```
Enforcement of a correct theme configuration is quite strict, and most errors will abort the theme loading, leading to an unthemed system. In each such situation the log output will be very clear of what happened, for instance:
```
Jan 28 17:17:30 Error: ThemeData::parseElement(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml": Property "origin" for element "image" has no value defined (system "collections", theme "custom-collections")
Jan 28 17:17:30 Error: ThemeData::parseElement(): "/home/myusername/ES-DE/themes/mytheme-es-de/theme.xml": Property "origin" for element "image" has no value defined (system "collections", theme "custom-collections")
```
Note that an unthemed system means precisely that, the specific system where the error occured will be unthemed but not necessarily the entire theme. The latter can still happen if the error is global such as a missing variable used by all XML files or an error in a file included by all XML files. The approach is to only untheme relevant sections of the theme to be able to pinpoint precisely where the problem lies.
@ -394,7 +393,7 @@ Sanitization for valid data format and structure is done in this manner, but ver
Jan 28 17:25:27 Warn: BadgeComponent: Invalid theme configuration, property "horizontalAlignment" for element "gamelistBadges" defined as "leftr"
```
Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the [Reference](THEMES.md#reference) section of this document for valid values for each property.
Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the reference section of this document for valid values for each property.
For more serious issues where it does not make sense to assign a default value or auto-adjust the configuration, an error log entry is generated and the element will in most instances not get rendered at all. Here's such an example where the imageType property for a video element was accidentally set to _covr_ instead of _cover_:
@ -405,12 +404,12 @@ Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property "i
Error handling for missing files is handled a bit differently depending on whether the paths have been defined explicitly or via a variable. For explicitly defined paths a warning will be logged for element properties and an error will be triggered for include files. Here's an example of the latter case:
```
Jan 28 17:32:29 Error: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml" -> "./colors_dark.xml" not found (resolved to "/home/myusername/.emulationstation/themes/mytheme-es-de/colors_dark.xml")
Jan 28 17:32:29 Error: ThemeData::parseIncludes(): "/home/myusername/ES-DE/themes/mytheme-es-de/theme.xml" -> "./colors_dark.xml" not found (resolved to "/home/myusername/ES-DE/themes/mytheme-es-de/colors_dark.xml")
```
However, if a variable has been used to define the include file, only a debug message will be generated if the file is not found:
```
Jan 28 17:34:03 Debug: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml": Couldn't find file "./${system.theme}/colors.xml" which resolves to "/home/myusername/.emulationstation/themes/mytheme-es-de/amiga/colors.xml"
Jan 28 17:34:03 Debug: ThemeData::parseIncludes(): "/home/myusername/ES-DE/themes/mytheme-es-de/theme.xml": Couldn't find file "./${system.theme}/colors.xml" which resolves to "/home/myusername/ES-DE/themes/mytheme-es-de/amiga/colors.xml"
```
It works essentially the same way for element path properties as for include files. This distinction between explicit values and variables makes it possible to create a theme configuration where both include files and files for fonts, images, videos etc. will be used if found, and if not found a fallback configuration can still be applied so the system will be themed.
@ -740,6 +739,202 @@ Here's an example configuration:
</theme>
```
## Languages
Multilingual support works very similarly to color schemes and font sizes in that it's a variable-based configuration. Due to this you can set any arbitrary property values you want for a certain language, such as different texts or different images and so on. The supported languages for use in themes are the same as for the overall application.
Note that the word _language_ is not technically the correct term as it's rather _locales_ that are used within ES-DE. For instance the en_US and en_GB locales are both for the English language but rather variations for different countries (United States and United Kingdom). Still, as the term _language_ is colloquially used to describe locales in many applications and operating systems this is also used in ES-DE even if it's not entirely correct. The term _language_ is as such also used throughout this document.
While it's possible to use the theme engine language support to set language-specific date formats this is generally discouraged as it's better to use the ISO 8601 (YYYY-MM-DD) standard instead. This is an international standard that makes sense to use in all countries in the world.
The following languages are supported:
| Language | English name | Native name |
| :------------ | :----------------------- | :----------------------- |
| en_US | English (United States) | English (United States) |
| en_GB | English (United Kingdom) | English (United Kingdom) |
| es_ES | Spanish (Spain) | Español (España) |
| fr_FR | French | Français |
| it_IT | Italian | Italiano |
| pl_PL | Polish | Polski |
| pt_BR | Portuguese (Brazil) | Português (Brasil) |
| ro_RO | Romanian | Română |
| ru_RU | Russian | Русский |
| sv_SE | Swedish | Svenska |
| ja_JP | Japanese | 日本語 |
| zh_CN | Simplified Chinese | 简体中文 |
Note that the native name is what is shown inside the _UI Settings_ menu for the _Theme Language_ and _Application Language_ settings.
You can find more information about locales/languages here:\
https://simplelocalize.io/data/locales
The languages a theme supports need to be declared in the `capabilities.xml` file using `<language>` tag pairs, such as the following example:
```xml
<!-- Theme capabilities for mytheme-es-de -->
<themeCapabilities>
<themeName>My theme</themeName>
<language>en_US</language>
<language>es_ES</language>
<language>pt_PR</language>
<language>sv_SE</language>
<language>zh_CN</language>
</themeCapabilities>
```
Although language support is optional for a theme, if you have declared at least one language then you have to include support for en_US as well. Attempting to skip an entry for this language will output an error message and the language configuration will not get loaded. The reason for this is that en_US is the default language for the ES-DE application so all themes have to support it, either implicitly (by not having any multilingual support) or explicitly by declaring it and providing localization for it.
It's also possible to provide label translations for variants, color schemes and transitions, as displayed in the _UI Settings_ menu. This is done using the `language` attribute for these `label` entries, as in this example `capabilities.xml` file:
```xml
<themeCapabilities>
<themeName>My theme</themeName>
<language>en_US</language>
<language>sv_SE</language>
<colorScheme name="dark">
<label language="en_US">Dark</label>
<label language="sv_SE">Mörkt</label>
</colorScheme>
<variant name="withVideos">
<label language="en_US">Textlist with videos</label>
<label language="sv_SE">Textlista med video</label>
<selectable>true</selectable>
<override>
<trigger>noMedia</trigger>
<mediaType>miximage, screenshot, cover, video</mediaType>
<useVariant>noGameMedia</useVariant>
</override>
</variant>
<transitions name="instantAndSlide">
<label language="en_US">instant and slide</label>
<label language="sv_SE">direkt och glidande</label>
<selectable>true</selectable>
<systemToSystem>instant</systemToSystem>
<systemToGamelist>slide</systemToGamelist>
<gamelistToGamelist>instant</gamelistToGamelist>
<gamelistToSystem>slide</gamelistToSystem>
<startupToSystem>slide</startupToSystem>
<startupToGamelist>slide</startupToGamelist>
</transitions>
</themeCapabilities>
```
Leaving out the `language` property will make ES-DE set the language to en_US.
The actual language-specific values in the theme configuration are defined using variables, like the following example:
```xml
<theme>
<language name="en_US">
<variables>
<langLogo>logo.svg</langLogo>
<langLabelDeveloper>Developer</langLabelDeveloper>
<langLabelPublisher>Publisher</langLabelPublisher>
</variables>
</language>
<language name="sv_SE">
<variables>
<langLogo>logo-sv-se.svg</langLogo>
<langLabelDeveloper>Utvecklare</langLabelDeveloper>
<langLabelPublisher>Utgivare</langLabelPublisher>
</variables>
</language>
<view name="gamelist">
<image name="logo">
<pos>0.38 0.1781</pos>
<size>0.158 0.12</size>
<path>./assets/${langLogo}</path>
</image>
<text name="labelDeveloper">
<pos>0.88 0.511</pos>
<size>0.165 0.03</size>
<text>${langLabelDeveloper}</text>
</text>
<text name="labelPublisher">
<pos>0.88 0.5935</pos>
<size>0.165 0.03</size>
<text>${langLabelPublisher}</text>
</text>
</view>
</theme>
```
It could also be a good idea to include the translations from a separate file:
```xml
<theme>
<include>./languages.xml</include>
<view name="gamelist">
<image name="logo">
<pos>0.38 0.1781</pos>
<size>0.158 0.12</size>
<path>./assets/${langLogo}</path>
</image>
<text name="labelDeveloper">
<pos>0.88 0.511</pos>
<size>0.165 0.03</size>
<text>${langLabelDeveloper}</text>
</text>
<text name="labelPublisher">
<pos>0.88 0.5935</pos>
<size>0.165 0.03</size>
<text>${langLabelPublisher}</text>
</text>
</view>
</theme>
```
Including separate files per language is also supported but it's probably not a good idea as it will add a lot of unnecessary files to the theme:
```xml
<theme>
<language name="en_US">
<include>./lang-en-us.xml</include>
</language>
<language name="sv_SE">
<include>./lang-sv-se.xml</include>
</language>
<view name="gamelist">
<image name="logo">
<pos>0.38 0.1781</pos>
<size>0.158 0.12</size>
<path>./assets/${langLogo}</path>
</image>
<text name="labelDeveloper">
<pos>0.88 0.511</pos>
<size>0.165 0.03</size>
<text>${langLabelDeveloper}</text>
</text>
<text name="labelPublisher">
<pos>0.88 0.5935</pos>
<size>0.165 0.03</size>
<text>${langLabelPublisher}</text>
</text>
</view>
</theme>
```
Note the naming convention when using localized versions of files such as images. These should include the locale/language in their name and they should be in lowercase characters, using only dashes as separators. For the default language the locale could be omitted from the filename (as language-specific images and similar will likely be exceptions with most files rather shared across all locales). Here are some examples:
```
logo.svg
logo-fr-fr.svg
logo-pt-br.svg
logo-sv-se.svg
auto-allgames.webp
auto-allgames-fr-fr.webp
auto-allgames-pt-br.webp
auto-allgames-sv-se.webp
```
## 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.
@ -898,9 +1093,9 @@ Finally it's possible to apply theme-defined transition profiles on a per-varian
## capabilities.xml
Variants, variant triggers, color schemes, aspect ratios and transition animation profiles need to be declared before they can be used inside the actual theme configuration files and that is done in the `capabilities.xml` file. This file needs to be located in the root of the theme directory, for example:
Variants, variant triggers, color schemes, font sizes, languages, aspect ratios and transition animation profiles need to be declared before they can be used inside the actual theme configuration files and that is done in the `capabilities.xml` file. This file needs to be located in the root of the theme directory, for example:
```
~/.emulationstation/themes/mytheme-es-de/capabilities.xml
~/ES-DE/themes/mytheme-es-de/capabilities.xml
```
The capabilities.xml file is mandatory and if it doesn't exist ES-DE will not attempt to load the theme.
@ -912,19 +1107,29 @@ The structure of the file is simple, as can be seen in this example:
<themeCapabilities>
<themeName>My theme</themeName>
<language>en_US</language>
<language>sv_SE</language>
<aspectRatio>16:9</aspectRatio>
<aspectRatio>4:3</aspectRatio>
<aspectRatio>4:3_vertical</aspectRatio>
<fontSize>medium</fontSize>
<fontSize>large</fontSize>
<colorScheme name="dark">
<label>Dark mode</label>
<label language="en_US">Dark</label>
<label language="sv_SE">Mörkt</label>
</colorScheme>
<colorScheme name="light">
<label>Light mode</label>
<label language="en_US">Light</label>
<label language="sv_SE">Ljust</label>
</colorScheme>
<transitions name="instantAndSlide">
<label language="en_US">instant and slide</label>
<label language="sv_SE">direkt och glidande</label>
<systemToSystem>instant</systemToSystem>
<systemToGamelist>slide</systemToGamelist>
<gamelistToGamelist>instant</gamelistToGamelist>
@ -932,7 +1137,8 @@ The structure of the file is simple, as can be seen in this example:
</transitions>
<variant name="withVideos">
<label>Textlist with videos</label>
<label language="en_US">Textlist with videos</label>
<label language="sv_SE">Textlista med video</label>
<selectable>true</selectable>
<override>
<trigger>noMedia</trigger>
@ -942,7 +1148,8 @@ The structure of the file is simple, as can be seen in this example:
</variant>
<variant name="withoutVideos">
<label>Textlist without videos</label>
<label language="en_US">Textlist without videos</label>
<label language="sv_SE">Textlista utan video</label>
<selectable>true</selectable>
<override>
<trigger>noMedia</trigger>
@ -957,7 +1164,8 @@ The structure of the file is simple, as can be seen in this example:
</variant>
</themeCapabilities>
```
The file format is hopefully mostly self-explanatory; this example provides three aspect ratios, two color schemes, one transition animation profile and three variants, one of which is a variant trigger override. The `<label>` tag for the variants and transitions is the text that will show up in the _UI Settings_ menu, assuming `<selectable>` has been set to true. The same is true for color schemes, although these will always show up in the GUI and can't be disabled.
The file format is hopefully mostly self-explanatory; this example provides two languages, three aspect ratios, two font sizes, two color schemes, one transition animation profile and three variants, one of which is a variant trigger override. The `<label>` tag for the variants and transitions is the text that will show up in the _UI Settings_ menu, assuming `<selectable>` has been set to true. The same is true for color schemes, although these will always show up in the GUI and can't be disabled.
The optional `<themeName>` tag defines the name that will show up in the _Theme_ option in the _UI Settings_ menu. If no such tag is present, then the physical directory name will be displayed instead, for example _MYTHEME-ES-DE_. Note that theme names will always be converted to uppercase characters when displayed in the menu.
@ -984,7 +1192,7 @@ It's normally not necessary to define all or even most of these for a theme, ins
The declared aspect ratios will always get displayed in the _UI settings_ menu in the order listed in the table above, so they can be declared in any order in the capabilities.xml file. If an unsupported aspect ratio value is entered, a warning will be generated on startup and the entry will not get loaded.
The use of variants, variant triggers, color schemes, aspect ratios and transition animation profiles is optional, i.e. a theme does not need to provide any of them. There must however be a capabilities.xml file present in the root of the theme directory. So if you don't wish to provide this functionality, simply create an empty file or perhaps add a short XML comment to clarify that the theme does not provide this functionality. In this case the theme will still load and work correctly but the menu options for selecting variants, color schemes and aspect ratios will be grayed out.
The use of variants, variant triggers, color schemes, font sizes, languages, aspect ratios and transition animation profiles is optional, i.e. a theme does not need to provide any of them. There must however be a capabilities.xml file present in the root of the theme directory. So if you don't wish to provide this functionality, simply create an empty file or perhaps add a short XML comment to clarify that the theme does not provide this functionality. In this case the theme will still load and work correctly but the menu options for selecting variants, color schemes and aspect ratios will be grayed out.
Note that changes to the capabilities.xml file are not reloaded when using the Ctrl + r key combination, instead ES-DE needs to be restarted to reload any changes to this file.
@ -992,7 +1200,7 @@ Note that changes to the capabilities.xml file are not reloaded when using the C
You can include theme files within theme files, for example:
`~/.emulationstation/themes/mytheme-es-de/fonts.xml`:
`~/ES-DE/themes/mytheme-es-de/fonts.xml`:
```xml
<theme>
<view name="gamelist">
@ -1005,7 +1213,7 @@ You can include theme files within theme files, for example:
</theme>
```
`~/.emulationstation/themes/mytheme-es-de/snes/theme.xml`:
`~/ES-DE/themes/mytheme-es-de/snes/theme.xml`:
```xml
<theme>
<include>./../fonts.xml</include>
@ -1250,7 +1458,7 @@ Example `navigationsounds.xml` file:
## Element rendering order using zIndex
You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default value so you only need to define it for the ones you wish to explicitly change. Elements will be rendered in order from smallest to largest values. A complete description of each element including all supported properties can be found in the [Reference](THEMES.md#reference) section.
You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default value so you only need to define it for the ones you wish to explicitly change. Elements will be rendered in order from smallest to largest values. A complete description of each element including all supported properties can be found in the reference section.
These are the default zIndex values per element type:
@ -1279,7 +1487,7 @@ Theme variables can be used to simplify theme construction and there are two typ
### System variables
System variables are system specific and are derived from values defined in es_systems.xml (except for collections which are derived from hardcoded application-internal values).
System variables are system-specific and derived from values defined in es_systems.xml (except for collections which are derived from hardcoded application-internal values).
* `system.name`
* `system.name.autoCollections`
* `system.name.customCollections`
@ -1297,9 +1505,11 @@ System variables are system specific and are derived from values defined in es_s
`system.fullName` expands to the full system name as defined by the `fullname` tag in es_systems.xml\
`system.theme` expands to the theme directory as defined by the `theme` tag in es_systems.xml
Note that all _name_ and _fullName_ values for the built-in collections _all games, favorites, last played and collections_ are translated to the language selected via the _Application Language_ option in the _UI Settings_ menu.
If using variables to load theme assets like images and videos, then use the `.name` versions of these variables as short system names should be stable and not change over time. The `.fullName` values could change in future ES-DE releases or they could be user-customized which would break your theme.
The `.autoCollections`, `.customCollections` and `.noCollections` versions of the variables make it possible to differentiate between regular systems, automatic collections (_all games_, _favorites_ and _last played_) and custom collections. This can for example be used to apply different formatting to the names of the collections as opposed to regular systems.
The `.autoCollections`, `.customCollections` and `.noCollections` versions of the variables make it possible to differentiate between regular systems, automatic collections (_all games, favorites_ and _last played_) and custom collections. This can for example be used to apply different formatting to the names of the collections as opposed to regular systems.
The below example capitalizes the names of the auto collections while leaving custom collections and regular systems at their default formatting (as they are defined by the user and es_systems.xml respectively). The reason this works is that the .autoCollections, .customCollections and .noCollections variables are mutually exclusive, i.e. a system is either a real system or an automatic collection or a custom collection and never more than one of these.
@ -1420,19 +1630,20 @@ It's important to understand how the theme configuration files are parsed in ord
2) Variables
3) Color schemes
4) Font sizes
5) Included files
6) "General" (non-variant) configuration
7) Variants
8) Aspect ratios
5) Languages
6) Included files
7) "General" (non-variant) configuration
8) Variants
9) 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.
When including a file using the `<include>` tag (i.e. step 6 above) then all steps listed above are executed for that included file prior to continuing to the next line after the `<include>` tag.
For any given step, the configuration is parsed in the exact order that it's defined in the XML file. Be mindful of the logic described above as for instance defining variant-specific configuration above general configuration in the same XML file will still have that parsed afterwards.
## 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 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`
* 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 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
@ -2802,8 +3013,9 @@ Properties:
* `container` - type: BOOLEAN
- Whether the text should be placed inside a scrollable container.
- Default is `true` if `metadata` is set to `description`, otherwise `false`
- This property can only be used if `size` has a width defined.
* `containerType` - type: STRING
- If `container` has been set, then it's possible to select between a vertically or horizontally scrolling type using this property. If selecting the horizontal container then all line breaks in the text will be automatically converted to spaces. If selecting the vertical container then any value defined for `rotation` will be ignored as this container type can't be rotated. If using this property make sure to set an explicit size for the element, as leaving it as `0 0` will lead to unpredictable results.
- If `container` has been set, then it's possible to select between a vertically or horizontally scrolling type using this property. If selecting the horizontal container then all line breaks in the text will be automatically converted to spaces. If selecting the vertical container then any value defined for `rotation` will be ignored as this container type can't be rotated.
- Valid values are `vertical` or `horizontal`
- Default is `vertical`
- This property can only be used when `container` has been explicitly set to `true`
@ -2941,6 +3153,16 @@ Properties:
- Default is `center`
* `color` - type: COLOR
* `backgroundColor` - type: COLOR
* `backgroundMargins` - type: NORMALIZED_PAIR
- Adds margins to the text background, assuming it has a color set. The first value of the pair is the left margin and the second value is the right margin, which means it's possible to set these margins completely independently. Margins are applied after all other positioning and sizing calculations and they are rendered outside the text debug rectangle boundaries.
- Minimum value per axis is `0` and maximum value per axis is `0.5`
- Default is `0 0`
- This property can only be used if `backgroundColor` has a value defined.
* `backgroundCornerRadius` - type: FLOAT
- Setting this property higher than zero applies rounded corners to the text background, assuming it has a color set. The radius is a percentage of the screen width. Note that the maximum allowed value is quite arbitrary as the renderer will in practice limit the maximum roundness so it can never go beyond half the text background height. It means that setting this property sufficiently high will produce perfectly rounded sides for the text background. You normally want to combine this property with `backgroundMargins` to add some extra margins.
- Minimum value is `0` and maximum value is `0.5`
- Default is `0` (corners are not rounded)
- This property can only be used if `backgroundColor` has a value defined.
* `letterCase` - type: STRING
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is `none` (original letter case is retained)

2
TRANSLATIONS.md
View file

@ -196,6 +196,6 @@ This repository can be found here:\
https://gitlab.com/es-de/themes/system-metadata
And here is a link to the language section of the theme engine documentation which contains some further relevant information:\
[THEMES-DEV.md](THEMES-DEV.md#languages)
[THEMES.md](THEMES.md#languages)
Discussions regarding theme translations are also covered in the ES-DE Discord server.