242 KiB
ES-DE Frontend (development version) - Themes
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 instead.
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:
https://gitlab.com/es-de/themes/theme-engine-examples-es-de
More themes to use as a starting point can be found on the official themes list:
https://gitlab.com/es-de/themes/themes-list
There is also some documentation written by lilbud covering general tips and tricks as well as how to port themes from the legacy RetroPie theme engine to ES-DE:
https://github.com/lilbud/es-de-theme-stuff
To test whether your theme includes support for all ES-DE systems, download one of the following archives which contain ROM directory trees fully populated with dummy files:
ROMs_ALL_Linux.zip
ROMs_ALL_macOS.zip
ROMs_ALL_Windows.zip
If you unzip and temporarily replace your ROMs directory with one of these, every system will be enabled on startup. Just make sure to use 7-Zip if you are using Windows as there is a bug in the built-in compression utility which leads to extensionless files not getting unpacked.
It's recommended to use a proper code editor for theme development, such as VSCode with the Red Hat XML extension.
A general comment regarding SVG graphic files is that fonts are not supported by the LunaSVG library so these need to be converted to paths in order for them to get rendered inside ES-DE. In Inkscape the relevant command is named Object to Path but there should be equivalent functionality in other vector graphics editors. Embedded bitmaps are also not supported but this is generally a good thing as it's sometimes abused by simply embedding a raster image inside an SVG file, which is very misleading.
Another general remark is that Linux almost always uses case-sensitive file systems (that's sometimes true for macOS as well). Therefore it's a good idea to always name files with lowercase characters only. Also make sure to regularly test on Linux if that's not your primary operating system.
Table of contents:
[[TOC]]
Introduction
An ES-DE theme is a collection of assets like images, videos and fonts as well as XML configuration files which contain various elements, each with their own properties that define the way the theme looks and behaves. These elements include things like text, images, videos, animations, carousels, grids etc.
Internally ES-DE uses the concept of components to actually implement the necessary building blocks to parse and render the elements, and although this is normally beyond the scope of what a theme author needs to consider, it's still good to be aware of the term as it's sometimes used in the documentation.
Every game system may have its own subdirectory within the theme directory tree, and these directory names are defined in the systems configuration file es_systems.xml either via the optional <theme> tag, or otherwise via the mandatory <name> tag. When ES-DE populates a system on startup it will look for a file named theme.xml in each such directory.
By placing a theme.xml file directly in the root of the theme directory, that file will be processed as a default if there is no system-specific theme.xml file available. This means that the structure of having a separate directory per supported game system is entirely optional.
In the example below, we have a theme named mytheme-es-de which includes the snes and nes systems. Assuming you have some games installed for these systems, the files mytheme-es-de/nes/theme.xml and mytheme-es-de/snes/theme.xml will be processed on startup. If there are no games available for a system, its theme.xml file will be skipped.
The directory structure for our example theme could look something like the following:
...
themes/
mytheme-es-de/
core/
font.ttf
font_bold.ttf
frame.png
nes/
background.jpg
logo.svg
theme.xml
snes/
background.jpg
logo.svg
theme.xml
fonts.xml
theme.xml
An alternative approach would be to instead rely on variables for populating system-specific information and media files, and this way it's not necessary to setup separate directories per system:
...
themes/
mytheme-es-de/
core/
font.ttf
font_bold.ttf
frame.png
systems/
backgrounds/
nes.jpg
snes.jpg
logos/
nes.svg
snes.svg
metadata/
nes.xml
snes.xml
fonts.xml
theme.xml
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]/ES-DE/themes/[INSTALLATION PATH]/themes/
An installation path could be something like this:
/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.
Differences to legacy RetroPie themes
If you are not familiar with theming for RetroPie or similar forks of EmulationStation then you can skip this section as it only describes the key differences between the updated ES-DE themes and these legacy themes. The term legacy is used throughout this document to refer to this older style of themes. ES-DE as of 2.2.0 can no longer load legacy themes, so if you need to view them when porting them to ES-DE, either use a legacy EmulationStation fork or ES-DE 2.1.1.
With ES-DE 2.0.0 a new theme engine was introduced that fundamentally changed some aspects of how theming works. The previous design used specific view styles (basic, detailed, video and grid) and this was dropped completely and replaced with variants that can accomplish the same thing while being much more powerful and flexible.
In the past EmulationStation basically had hardcoded view styles with certain elements always being present and only a limited ability to manipulate these via positioning, resizing, coloring etc. As well so-called extras were provided to expand theming support somehow but even this was quite limited.
With the new theme engine the view presets were removed and the only views now available, system and gamelist, were rewritten to be much more flexible. Essentially the element selection and placement is now unlimited; any number of elements of any type can be used, although with a few notable exceptions as explained throughout this document.
In addition to variants, support for color schemes and aspect ratios was introduced. The former makes it possible to provide different color profiles via variable declarations, and the latter makes it possible to define different theme configurations for different display aspect ratios. That could for example be a choice between a 16:9 and a 4:3 layout, and perhaps also a vertical screen orientation layout. All these options are selectable via the UI Settings menu.
New theming abilities like GIF and Lottie animations were also added to the new theme engine.
The NanoSVG rendering library has been replaced with LunaSVG which greatly improves SVG file support as NanoSVG had issues with rendering quite some files. There might be some slight regressions with LunaSVG, but most of these are probably due to issues in NanoSVG that caused some non-conformant files to render seemingly correct. Make sure to compare any SVG files that don't seem to render correctly in ES-DE with what they look like if opened in for example Firefox or Chrome/Chromium.
As for more specific changes, the following are the most important ones compared to legacy themes:
- View styles are now limited to only system and gamelist (there is a special all view style as well but that is only used for navigation sounds as explained later in this document)
- The hardcoded metadata attributes like md_image and md_developer are gone, but a new
<metadata>property is available for populating views with metadata information - The concept of extras is gone as all element can now be used however the theme author wishes
- The concept of features is gone
- The
<formatVersion>tag is gone as tracking theme versions doesn't make much sense after all - The
videoelement propertiesshowSnapshotNoVideoandshowSnapshotDelayhave been removed - The ambiguous
alignmentproperty has been replaced with thehorizontalAlignmentandverticalAlignmentproperties (the same is true forlogoAlignmentfor thecarouselelement) - The
forceUppercaseproperty has been replaced with the more versatileletterCaseproperty - Many property names for the carousel have been renamed, with logo being replaced by item as this element can now be used in both the gamelist and system views. As well, setting the alignment will not automatically add any margins as is the case for legacy themes. These can still be set manually using the
horizontalOffsetandverticalOffsetproperties if needed. The way that alignment works in general for both carousel items and the overall carousel has also changed - The rating elements were previously not sized and overlaid consistently, this has now been fixed and rating images should now be centered on the image canvas in order for this element to render correctly rather than being left-adjusted as has previously been done by some theme authors (likely as a workaround for the previous buggy implementation). Images of any aspect ratios are now also supported where previously only square images could be used
- The carousel text element hacks
systemInfoandlogoTexthave been removed and replaced with proper carousel properties - The carousel property
maxItemCount(formerly named maxLogoCount) is now in float format for more granular control of logo placement compared to integer format for legacy themes. However some legacy theme authors thought this property supported floats (as the theme documentation incorrectly stated this) and have therefore set it to fractional values such as 3.5. This was actually rounded up when loading the theme configuration, and this logic is retained for legacy themes for backward compatibility. But for current themes the float value is correctly interpreted which means a manual rounding of the value is required in order to retain an identical layout when porting themes to the new theme engine. As well carousels of the wheel type now have the amount of entries controlled by the two new propertiesitemsBeforeCenteranditemsAfterCenter. This provides more exact control, including the ability to setup asymmetric wheels. - The full names of unthemed systems (or systems where the defined staticImage file is missing) will now be displayed in the system carousel instead of the short names shown for legacy themes. So for instance, instead of "cps" the full name "Capcom Play System" (as defined in es_systems.xml) will be displayed.
- The carousel now has a zIndex value of 50 instead of 40. This means it's aligned with the textlist element which already had a zIndex value of 50.
- The textlist property
selectorOffsetYhas been renamed toselectorVerticalOffsetand aselectorHorizontalOffsetproperty has been added as well. - The helpsystem
textColorDimmedandiconColorDimmedproperties (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 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.
Except the points mentioned above, theme configuration looks pretty similar to the legacy theme structure, so anyone having experience with these older themes should hopefully feel quite at home with the new theme engine. Probably the most important thing to keep in mind is that as there are no longer any view presets available, some more effort is needed from the theme developer to define values for some elements. This is especially true for zIndex values as elements could now be hidden by other elements if care is not taken to explicitly set the zIndex for each of them. This additional work is however a small price to pay for the much more powerful and flexible theming functionality provided by the new theme engine.
Note that the legacy theme engine had quite inaccurate text sizing and font rendering and while this has been greatly improved in the new engine, for legacy themes most old bugs are retained for maximum backward compatibility. This means that you may need to revise font sizes and text placements when porting a legacy theme to the new engine. Here are some examples:
- Line spacing for the textlist element was not consistently applied across different screen resolutions
- Carousel text entries did not multiply the font size by the itemScale (logoScale) property value
- The defined line spacing was not always applied for automatically sized text elements
- Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly)
Theme assets repositories
There are several useful repositories hosted by the ES-DE project that provide system metadata and system graphics files. Using these greatly simplifies the work of adding support for all ES-DE systems to your theme.
Make sure to regularly check for updates in these repositories as corrections, improvements and additions of new systems are made continuously.
Metadata
The metadata repository provides descriptions, release dates, per-system color palettes etc. and it can be found here:
https://gitlab.com/es-de/themes/system-metadata
By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Check the README.md file in the repository for details on how to actually use the variables.
Here's how to add this repository as a subtree inside your theme's Git repository:
git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git
git subtree add --prefix=system-metadata --squash system-metadata master
To later pull in repository updates you'll run the following:
git subtree pull --prefix=system-metadata --squash system-metadata master
The directory name can be changed to whatever you like using the --prefix flag.
Controller outline graphics
This repository provides controller graphics files for each system in an outline style and it can be found here:
https://gitlab.com/es-de/themes/system-controllers-outline
Here's how to add this repository as a subtree inside your theme's Git repository:
git remote add system-controllers-outline https://gitlab.com/es-de/themes/system-controllers-outline.git
git subtree add --prefix=system-controllers-outline --squash system-controllers-outline master
To later pull in repository updates you'll run the following:
git subtree pull --prefix=system-controllers-outline --squash system-controllers-outline master
The directory name can be changed to whatever you like using the --prefix flag.
Mini system graphics
This repository provides graphics files for each system in a "mini" style and it can be found here:
https://gitlab.com/es-de/themes/system-graphics-mini
Here's how to add this repository as a subtree inside your theme's Git repository:
git remote add system-graphics-mini https://gitlab.com/es-de/themes/system-graphics-mini.git
git subtree add --prefix=system-graphics-mini --squash system-graphics-mini master
To later pull in repository updates you'll run the following:
git subtree pull --prefix=system-graphics-mini --squash system-graphics-mini master
The directory name can be changed to whatever you like using the --prefix flag.
Logos
This repository provides logos for each system in color and white (the latter for use with color shifting) and it can be found here:
https://gitlab.com/es-de/themes/system-logos
Here's how to add this repository as a subtree inside your theme's Git repository:
git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git
git subtree add --prefix=system-logos --squash system-logos master
To later pull in repository updates you'll run the following:
git subtree pull --prefix=system-logos --squash system-logos master
The directory name can be changed to whatever you like using the --prefix flag.
Adding remotes
Note that the remotes are only setup for your local repository, so if you clone a theme you'll need to manually add the repository remotes to be able to pull from these subtrees. That means you'll need to run one or more of the following commands on a freshly cloned theme repository:
git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git
git remote add system-controllers-outline https://gitlab.com/es-de/themes/system-controllers-outline.git
git remote add system-graphics-mini https://gitlab.com/es-de/themes/system-graphics-mini.git
git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git
After doing this you'll be able to pull repository updates as described above.
Simple example theme
Here is a very simple theme that changes the color of the game name text:
<theme>
<view name="gamelist">
<text name="gameName">
<color>00FF00</color>
</text>
<image name="frame1">
<pos>0.5 0.5</pos>
<origin>0.5 0.5</origin>
<size>0.8 0.8</size>
<path>./core/frame.png</path>
<zIndex>10</zIndex>
</image>
</view>
</theme>
How it works
All configuration must be contained within a <theme> tag pair. That is true for each separate .xml file used to build the complete theme.
The <view> tag pair refers to the available views within ES-DE, which is either system or gamelist. There is a special all view available as well, but that is only used for defining the navigation sounds as these are always applied globally to both view types.
Views are defined like this:
<view name="viewNameHere">
... define elements here ...
</view>
An element is a particular visual component such as an image, an animation or a piece of text. It has a mandatory name attribute which is used by ES-DE to track each element entry. By using this name attribute it's possible to split up the definition of an element to different locations. For example you may want to define the color properties separately from where the size and position are configured (see the example below). The name attribute can be set to any string value.
This is the element structure:
<ElementTypeHere name="elementNameHere">
... define properties here ...
</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 section. Properties are defined like this:
<propertyNameHere>valueHere</propertyNameHere>
Let's now put it all together. The following is a simple example of a text element which has its definition split across two separate XML files.
themes.xml:
<theme>
<view name="gamelist">
<text name="systemName">
<pos>0.27 0.32</pos>
<origin>0.5 0.5</origin>
<size>0.12 0.41</size>
<zIndex>40</zIndex>
</text>
</view>
</theme>
colors.xml:
<theme>
<view name="gamelist">
<text name="systemName">
<color>707070</color>
</text>
</view>
</theme>
As long as the name attribute is identical, the element configuration will be combined automatically. But that is only true for elements of the same type, so for instance an image element could be defined that also uses systemName for its name attribute without colliding with the text element:
<theme>
<view name="gamelist">
<text name="systemName">
<pos>0.27 0.32</pos>
<origin>0.5 0.5</origin>
<size>0.12 0.41</size>
<zIndex>40</zIndex>
</text>
<!-- Does not cause a collision, but is probably a bad idea for readability reasons -->
<image name="systemName">
<pos>0.49 0.8</pos>
<maxSize>0.4 0.28</maxSize>
<zIndex>35</zIndex>
</text>
</view>
</theme>
Whether this is a good idea is another question, it would probably be better to set the name attribute for the image to systemLogo or similar for this example.
In addition to this, if the name is used for the same element type but for different views, then there will also not be any collision:
<theme>
<view name="system">
<text name="systemName">
<pos>0.04 0.73</pos>
<origin>0.5 0.5</origin>
<size>0.12 0.22</size>
<zIndex>40</zIndex>
</view>
<!-- This will not cause a collision as these two text elements are defined for different views -->
<view name="gamelist">
<text name="systemName">
<pos>0.27 0.32</pos>
<origin>0.5 0.5</origin>
<size>0.12 0.41</size>
<zIndex>40</zIndex>
</view>
</theme>
Debugging during theme development
If you are writing a theme it's recommended to enable the Debug mode setting from the Other settings menu or to launch ES-DE with the --debug flag from a terminal window. You can also pass the --resolution flag to avoid having the application window fill the entire screen. By doing so you can read error messages directly in the terminal window without having to open the es_log.txt file. With debug mode enabled you can also reload the current gamelist or system view with Ctrl + r and you can highlight the size and position of each image and animation element by using the Ctrl + i key combination. Likewise you can highlight each text element via Ctrl + t.
Here's an example of launching ES-DE in debug mode at a limited resolution, which will make it run in a window:
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/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.
Sanitization for valid data format and structure is done in this manner, but verification that property values are actually correct (or reasonable) is handled by the individual component that takes care of creating and rendering the specific theme element. What happens in many instances is that a warning log entry is created and the invalid property is reset to its default value. So for these situations, the system will not become unthemed. Here's an example where a badges element accidentally had its horizontalAlignment property set to leftr instead of left:
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 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:
Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property "imageType" for element "gamelistVideo" defined as "covr"
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/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/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.
By default all debug messages regarding missing files will be logged for regular systems and automatic collections and suppressed for custom collections. This behavior can be changed by modifying the DebugSkipMissingThemeFiles and DebugSkipMissingThemeFilesCustomCollections settings in es_settings.xml. You can read more about those settings here.
Variants
A core concept of ES-DE is the use of theme variants to provide different theme profiles. These are not fixed presets and a theme author can instead name and define whatever variants he wants for his theme (or possibly use no variants at all as they are optional).
The variants could be purely cosmetic, such as providing different designs for a theme, or they could provide distinctive functionality by for instance using different primary elements like a carousel or a text list.
Before a variant can be used it needs to be declared, which is done in the capabilities.xml file that must be located in the root of the theme directory tree. How to setup this file is described in detail later in this document.
The use of variants is straightforward, a section of the configuration that should be included for a certain variant is enclosed inside the <variant> tag pair. This has to be placed inside the <theme> tag pair, and it can only be used at this level of the hierarchy and not inside a <view> tag pair for example.
The mandatory name attribute is used to specificy which variants to use, and multiple variants can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks). It's also possible to use the special all variant that will apply the configuration to all defined variants (although this is only a convenient shortcut and you can explicitly define every variant individually if you prefer that). Note that all is a reserved name and attempting to use it in the capabilities.xml file will trigger a warning on application startup.
It could sometimes be a good idea to separate the variant configuration into separate files that are then included from the main theme file as this could improve the structure and readability of the theme configuration.
It's also possible to apply only portions of the theme configuration to the variants and keep a common set of elements that are shared between all variants. This is accomplished by simply adding the shared configuration without specifying a variant, as is shown in the first example below for the infoText01 text element. Just be aware that the variant-specific configuration will always be loaded after the general configuration even if it's located above the general configuration in the XML file. As this is potentially confusing and error-prone it's instead generally recommended to use the special all variant to define common configuration used by all variants in the theme rather than mixing variants configuration with non-variants configuration.
Here are some example uses of the <variant> functionality:
<theme>
<!-- Implementing the variants via separate include files could be a good idea -->
<variant name="gamelistTextlist">
<include>./gamelist_textlist.xml</include>
</variant>
<variant name="gamelistCarousel">
<include>./gamelist_carousel.xml</include>
</variant>
<!-- The special "all" variant is a convenient shortcut for some situations -->
<variant name="all">
<include>./${system.theme}/systeminfo.xml</include>
</variant>
<!-- This will be parsed before the variant-specific configuration -->
<view name="gamelist">
<text name="infoText01">
<fontPath>./core/font.ttf</fontPath>
<fontSize>0.035</fontSize>
<pos>0.3 0.56</pos>
</text>
</view>
</theme>
<!-- In other instances it may make more sense to apply the variant configuration inline -->
<theme>
<variant name="withVideos">
<view name="gamelist">
<video name="gameVideo">
<imageType>cover</imageType>
<delay>1.7</delay>
<scrollFadeIn>true</scrollFadeIn>
<zIndex>42</zIndex>
</video>
</view>
</variant>
<variant name="withoutVideos">
<view name="gamelist">
<image name="gameImage">
<imageType>titlescreen</imageType>
<scrollFadeIn>true</scrollFadeIn>
<zIndex>42</zIndex>
</image>
</view>
</variant>
</theme>
<!-- The following is NOT supported as <variant> tags can't be located inside <view> tag pairs -->
<theme>
<view name="gamelist">
<variant name="lightModeNoVideo">
<image name="gameImage">
<imageType>titlescreen</imageType>
<scrollFadeIn>true</scrollFadeIn>
<zIndex>42</zIndex>
</image>
</variant>
</view>
</theme>
Variant triggers (overrides)
Variant triggers is an optional feature which can be used to replicate the automatic view style switching functionality of the legacy theme engine. This can be used to automatically override the selected variant based on two triggers, either when there are no game videos found for a system, or if there are no game media files of some specified types found for a system. These two trigger types are named noVideos and noMedia respectively.
For the noMedia trigger there's an optional mediaType tag that can be used to specify precisely which media files should be checked for to determine whether to switch to the override variant. Valid values are miximage, marquee, screenshot, titlescreen, cover, backcover, 3dbox, physicalmedia, fanart and video. Multiple values can be defined, in which case they are separated by a comma, or by a whitespace character (tab, space or line break). If no value is defined, it will be set to miximage.
The useVariant tag specifies which variant to use to override the selected variant.
You'll probably rarely need to use the noVideos trigger as video can be defined also when using the noMedia trigger. The reason for including both trigger types is that it makes it possible to apply a specific variant only when videos are missing and another variant when no media files at all are present.
The following example (from the capabilities.xml file) defines a noGameMedia variant which is used as the override for the withVideos variant if no miximages, screenshots, covers and videos are found for any game in a system. For this example the noGameMedia variant has been set as non-selectable from the UI Settings menu by defining the selectable property as false.
As can be seen here, the overall variant trigger configuration needs to be enclosed within an override tag pair. And you can only define a single trigger type inside an override tag pair.
<variant name="withVideos">
<label>Textlist with videos</label>
<selectable>true</selectable>
<override>
<trigger>noMedia</trigger>
<mediaType>miximage, screenshot, cover, video</mediaType>
<useVariant>noGameMedia</useVariant>
</override>
</variant>
<variant name="noGameMedia">
<label>No game media</label>
<selectable>false</selectable>
</variant>
It's also possible to define both the noVideos and noMedia triggers for the same variant like the following example:
<variant name="withVideos">
<label>Textlist with videos</label>
<selectable>true</selectable>
<override>
<trigger>noVideos</trigger>
<useVariant>withoutVideos</useVariant>
</override>
<override>
<trigger>noMedia</trigger>
<mediaType>miximage, screenshot, cover</mediaType>
<useVariant>noGameMedia</useVariant>
</override>
</variant>
<variant name="withoutVideos">
<label>Textlist without videos</label>
<selectable>false</selectable>
</variant>
<variant name="noGameMedia">
<label>No game media</label>
<selectable>false</selectable>
</variant>
In this case the withoutVideos variant will be selected if there are no videos but if there is other media available. If there is however no media matching the mediaType property then the noGameMedia variant will be selected instead. Note that noMedia always takes precedence over noVideos. If you would like to trigger the withoutVideos variant if there are videos but no other media, then you'll need to add video to the mediaType property for the noMedia trigger.
It's however not possible to define multi-step variant triggers like this:
<!-- This is NOT allowed, you can't have two-step triggers -->
<variant name="withVideos">
<label>Textlist with videos</label>
<selectable>true</selectable>
<override>
<trigger>noVideos</trigger>
<useVariant>withoutVideos</useVariant>
</override>
</variant>
<variant name="withoutVideos">
<label>Textlist without videos</label>
<selectable>false</selectable>
<override>
<trigger>noMedia</trigger>
<mediaType>miximage, screenshot, cover</mediaType>
<useVariant>noGameMedia</useVariant>
</override>
</variant>
<variant name="noGameMedia">
<label>No game media</label>
<selectable>false</selectable>
</variant>
If the above configuration is used, then the trigger will work correctly if there are no videos, i.e. the withoutVideos variant will be selected, but the override tag in the withoutVideos variant will be ignored so the noGameMedia variant will never be triggered even if there is no media whatsoever.
Note that variant triggers will only apply to the gamelist view and not the system view. Also be aware that it will add a potentially noticeable application slowdown as game media files need to be scanned for at various points when using the application, as well as during startup. The impact of the performance penalty depends on multiple factors such as the game collection size, how many games have been scraped, as well as disk I/O and filesystem performance. So only use variant triggers if really necessary for your theme design. As well, specifying many values for the mediaType tag will lead to more files potentially being scanned which could introduce further lag and latency.
As a final note, variant triggers can also be globally disabled by the user via the Enable theme variant triggers option in the UI Settings menu. Not everyone may want the variant auto-switching to take place, and if all systems contain scraped media then disabling the functionality will eliminate the performance penalty described above.
Color schemes
Color schemes are essentially a collection of variables that can be selected between from the UI Settings menu. This makes it possible to define different values that will be applied to the overall theme configuration based on this menu selection. Only variables can be used for the color schemes, but since variables can be used for almost everything this makes the functionality very flexible. In most cases you'll probably want to apply different color values to <color> properties and similar, but it's also possible to apply different images, animations, fonts etc. per color scheme.
To understand the basics on how to use variables, make sure to read the Theme variables section elsewhere in this document.
Before a color scheme can be used it needs to be declared, which is done in the capabilities.xml file that must be located in the root of the theme directory tree. How to setup this file is described in detail later in this document.
The <colorScheme> tag pair 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 color scheme 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).
Note that the use of color schemes for a theme is entirely optional.
Here's an example configuration:
<theme>
<colorScheme name="dark">
<variables>
<backgroundColor>404040</backgroundColor>
<defaultTextColor>F0F0F0</defaultTextColor>
</variables>
</colorScheme>
<colorScheme name="light">
<variables>
<backgroundColor>707070</backgroundColor>
<defaultTextColor>262626</defaultTextColor>
</variables>
</colorScheme>
<variant name="withVideos, withoutVideos">
<colorScheme name="dark, light">
<panelColor>74747488</panelColor>
</colorScheme>
<view name="system">
<image name="background">
<pos>0 0</pos>
<size>1 1</size>
<path>./core/images/background.png</path>
<tile>true</tile>
<color>${backgroundColor}</color>
</image>
<text name="gameCounter">
<pos>0.5 0.6437</pos>
<size>1 0.056</size>
<color>${defaultTextColor}</color>
</text>
</view>
</variant>
</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:
<!-- 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:
<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>
<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>
<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>
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) |
| ca_ES | Catalan | Català |
| de_DE | German | Deutsch |
| es_ES | Spanish (Spain) | Español (España) |
| fr_FR | French | Français |
| it_IT | Italian | Italiano |
| nl_NL | Dutch | Nederlands |
| 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 | 日本語 |
| ko_KR | Korean | 한국어 |
| 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:
<!-- 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:
<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:
<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:
<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:
<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.
In the same manner as for the variants and color schemes, the aspect ratios that the theme provides need to be declared in the capabilities.xml file that must be located in the root of the theme directory tree. How to setup this file is described in detailed later in this document.
The <aspectRatio> tag pair can be placed directly inside the <theme> tags or inside the <variants> tags.
Once the aspect ratios have been defined, they are applied to the theme configuration like the following examples:
<!-- Implementing the aspect ratios by separate include files could be a good idea -->
<theme>
<aspectRatio name="4:3, 5:4">
<include>./../layout_narrow.xml</include>
</aspectRatio>
<aspectRatio name="16:9, 16:10">
<include>./../layout_wide.xml</include>
</aspectRatio>
<aspectRatio name="21:9">
<include>./../layout_ultrawide.xml</include>
</aspectRatio>
<view name="gamelist">
<text name="infoText01">
<fontPath>./core/font.ttf</fontPath>
<fontSize>0.035</fontSize>
</text>
</view>
</theme>
<!-- In other instances it may make more sense to apply the aspect ratio configuration inline -->
<theme>
<aspectRatio name="4:3, 5:4">
<view name="gamelist">
<image name="imageLogo">
<pos>0.3 0.56</pos>
</image>
</view>
</aspectRatio>
<aspectRatio name="16:9, 16:10, 21:9">
<view name="gamelist">
<image name="imageLogo">
<pos>0.42 0.31</pos>
</image>
</view>
</aspectRatio>
</theme>
<!-- Placing aspectRatio tags inside the variants tags is also supported -->
<theme>
<variant name="withVideos, withoutVideos">
<aspectRatio name="4:3, 5:4">
<view name="gamelist">
<image name="imageLogo">
<pos>0.3 0.56</pos>
</image>
</view>
</aspectRatio>
</variant>
</theme>
<!-- The following is NOT supported as <aspectRatio> tags can't be located inside <view> tag pairs -->
<theme>
<view name="gamelist">
<aspectRatio name="4:3, 5:4">
<image name="imageLogo">
<pos>0.3 0.56</pos>
</image>
</aspectRatio>
</view>
</theme>
Transitions (animation profiles)
Using the capabilities.xml file it's possible to define granular transition animation profiles. Prior to ES-DE 2.0 there was only a user-selectable option for Instant, Slide or Fade animations that was applied globally. It's now possible to select each of these animation types individually for the following transitions:
- System to system
- System to gamelist
- Gamelist to gamelist
- Gamelist to system
- Startup to system
- Startup to gamelist
This is a brief overview of the supported animations:
- Instant - as the name implies, transitions are immediate
- Slide - pans the camera to move between views which may look broken with some elements like textlists and grids when used in the system view
- Fade - fades to black when transitioning between views
Here's an example configuration:
<transitions name="instantAndSlide">
<label>instant and slide</label>
<selectable>true</selectable>
<systemToSystem>instant</systemToSystem>
<systemToGamelist>slide</systemToGamelist>
<gamelistToGamelist>instant</gamelistToGamelist>
<gamelistToSystem>slide</gamelistToSystem>
<startupToSystem>fade</startupToSystem>
<startupToGamelist>fade</startupToGamelist>
</transitions>
<transitions name="instant">
<label>instant</label>
<selectable>true</selectable>
<systemToSystem>instant</systemToSystem>
<systemToGamelist>instant</systemToGamelist>
<gamelistToGamelist>instant</gamelistToGamelist>
<gamelistToSystem>instant</gamelistToSystem>
</transitions>
The name attribute is mandatory and it must be set to a unique value for each profile. Any string can be used except the three reserved values builtin-instant, builtin-slide and builtin-fade.
The selectable property which is set to true by default defines whether the transitions profile can be selected from the Theme transitions entry on the UI Settings menu. The label defines the label to show there. If no label value is set then a default Theme profile label will be applied.
At least one of the six transition types must be defined or the transitions entry is not considered valid. Any non-defined types will be set to instant with the exception of startupToSystem which will be set to the same value as systemToSystem and startupToGamelist which will be set to the same value as gamelistToGamelist.
The profiles will be listed in the UI Settings menu in the order that they have been defined, and the first profile (regardless of whether it's set as user-selectable or not), will be used if the Automatic entry has been selected, unless a per-variant configuration is defined in the theme configuration.
In addition to defining custom transition profiles it's possible to suppress the built-in profiles. For example slide transitions will look very broken with some theme designs so in such cases it could make sense to disable this animation type altogether. Suppressing a profile simply means its entry will not show up under Theme transitions in the UI Settings menu, making it impossible to select and use it.
Here's an example where all the built-in transition profiles have been disabled:
<suppressTransitionProfiles>
<entry>builtin-instant</entry>
<entry>builtin-slide</entry>
<entry>builtin-fade</entry>
</suppressTransitionProfiles>
Regardless of whether any custom profiles have been created or whether the built-in profiles have been disabled there will always be an Automatic entry added to the Theme transition animations menu. If no theme profiles have been defined and all built-in profiles have been suppressed, then the Automatic entry will be the only available option. In this case instant animations will by applied to all transition types.
Finally it's possible to apply theme-defined transition profiles on a per-variant basis. This requires that the user has selected the Automatic profile from the Theme transitions menu as selecting any other profile will override whatever is defined in the theme configuration. Note that the built-in transition profiles can't be used in this manner, only profiles defined in capabilities.xml.
<variant name="withVideos">
<transitions>instantAndSlide</transitions>
</variant>
<variant name="withoutVideos">
<transitions>instant</transitions>
</variant>
capabilities.xml
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:
~/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.
The structure of the file is simple, as can be seen in this example:
<!-- Theme capabilities for mytheme-es-de -->
<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 language="en_US">Dark</label>
<label language="sv_SE">Mörkt</label>
</colorScheme>
<colorScheme name="light">
<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>
<gamelistToSystem>slide</gamelistToSystem>
</transitions>
<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>
<variant name="withoutVideos">
<label language="en_US">Textlist without videos</label>
<label language="sv_SE">Textlista utan video</label>
<selectable>true</selectable>
<override>
<trigger>noMedia</trigger>
<mediaType>miximage, screenshot, cover</mediaType>
<useVariant>noGameMedia</useVariant>
</override>
</variant>
<variant name="noGameMedia">
<label>No game media</label>
<selectable>false</selectable>
</variant>
</themeCapabilities>
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.
The variant, color scheme and transitions names as well as their labels can be set to arbitrary values, but the name has to be unique. If two entries are declared with the same name, a warning will be generated on startup and the duplicate entry will not get loaded. Variants, color schemes and transition animations will be listed in the UI Settings menu in the order that they are defined in capabilities.xml.
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 |
| 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.
It's normally not necessary to define all or even most of these for a theme, instead only a few are likely to be needed. The element placement will always adapt to the screen resolution as relative positions are utilized, so in most cases similar aspect ratios like 4:3 and 5:4 could be used interchangeably. The same is true for instance for 16:9 and 16:10. But if precise element placement is required, a separate configuration can still be made for each aspect ratio.
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, 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.
The <include> tag
You can include theme files within theme files, for example:
~/ES-DE/themes/mytheme-es-de/fonts.xml:
<theme>
<view name="gamelist">
<text name="infoText01">
<fontPath>./core/font.ttf</fontPath>
<fontSize>0.035</fontSize>
<color>00FF00</color>
</text>
</view>
</theme>
~/ES-DE/themes/mytheme-es-de/snes/theme.xml:
<theme>
<include>./../fonts.xml</include>
<view name="gamelist">
<text name="infoText01">
<pos>0.3 0.56</pos>
<color>FF0000</color>
</text>
</view>
</theme>
The above is equivalent to the following:
<theme>
<view name="gamelist">
<text name="infoText01">
<fontPath>./core/font.ttf</fontPath>
<fontSize>0.035</fontSize>
<pos>0.3 0.56</pos>
<!-- This may or may not be what is intended, i.e. overriding the <color> tag in fonts.xml -->
<color>FF0000</color>
</text>
</view>
</theme>
As covered earlier in this document, as long as the name attributes are identical for the same element type, the properties are combined automatically. The potential issue with the current example is that the color tag is defined in both the fonts.xml and snes/theme.xml files. As parsing is done sequentially, the property value that is defined last will overwrite the earlier value. This may be used intentionally to override a general property value, so the configuration in the example above example is not necessarily a mistake.
The paths defined for the <include> entry and <fontPath> and similar properties are set as relative to the theme file by adding "./" as a prefix. That is usually how paths would be defined as you commonly want to access files only within the theme directory structure. This prefix works for all path properties. Windows-style backslashes are also supported as directory separators but their use is not recommended.
Explicitly defining a path will lead to an error (and the system getting unthemed) if the file is missing, but if instead using a variable to populate the <include> tag then a missing file will only generate a debug log entry. This makes it possible to use system variables to build flexible theme configurations where it's not guaranteed that every file exists. Such an example would be to implement default/fallback configuration for custom systems that may get added by a user.
Note that include loops are not checked for, it's the responsibility of the theme developer to make sure no such loops exist. If you accidentally introduce a loop the application will hang indefinitely on startup.
You can add <include> tags directly inside the <theme> tags or inside the <variant> and <aspectRatio> tags, but not inside the <view> tags:
<!-- Adding <include> directly inside <theme> is supported -->
<theme>
<include>./../colors.xml</include>
<view name="gamelist">
<text name="infoText01">
<pos>0.3 0.56</pos>
</text>
</view>
</theme>
<!-- Adding <include> inside <variant> is supported -->
<theme>
<variant name="lightMode">
<include>./../colors.xml</include>
</variant>
<view name="gamelist">
<text name="infoText01">
<pos>0.3 0.56</pos>
</text>
</view>
</theme>
<!-- Adding <include> inside <aspectRatio> is supported -->
<theme>
<aspectRatio name="4:3">
<include>./../colors.xml</include>
</aspectRatio>
<view name="gamelist">
<text name="infoText01">
<pos>0.3 0.56</pos>
</text>
</view>
</theme>
<!-- Adding <include> inside <view> is NOT supported -->
<theme>
<view name="gamelist">
<include>./../colors.xml</include>
<text name="infoText01">
<pos>0.3 0.56</pos>
</text>
</view>
</theme>
<!-- Adding <include> outside <theme> is NOT supported -->
<include>./../colors.xml</include>
<theme>
<view name="gamelist">
<text name="infoText01">
<pos>0.3 0.56</pos>
</text>
</view>
</theme>
Theming the system and gamelist views simultaneously
Sometimes you may want to apply the same elements and properties to both the system and gamelist views, for instance defining a common background image. For these situations both views can simply be defined in the name attribute. The values can be separated by a comma, or by a whitespace character (tab, space or line break).
<view name="system, gamelist">
<image name="background">
<tile>true</tile>
<size>1 1</size>
<pos>0 0</pos>
<origin>0 0</origin>
<path>./core/images/background.png</path>
<zIndex>0</zIndex>
</image>
The above is equivalent to:
<view name="system">
<image name="background">
<tile>true</tile>
<size>1 1</size>
<pos>0 0</pos>
<origin>0 0</origin>
<path>./core/images/background.png</path>
<zIndex>0</zIndex>
</image>
</view>
<view name="gamelist">
<image name="background">
<tile>true</tile>
<size>1 1</size>
<pos>0 0</pos>
<origin>0 0</origin>
<path>./core/images/background.png</path>
<zIndex>0</zIndex>
</image>
</view>
Theming multiple elements simultaneously
You can theme multiple elements of the same type simultaneously, which can lead to a more compact and easier to understand theme configuration. To accomplish this you simply define multiple entries inside a single name attribute, separated by commas or whitespace characters (tabs, spaces or line breaks).
Here's an example of defining a common color to multiple text elements:
<theme>
<view name="gamelist">
<!-- Weird spaces/newline on purpose -->
<text name="labelRating, labelReleasedate labelDeveloper labelPublisher,
labelGenre, labelPlayers, labelLastplayed, labelPlaycount">
<color>48474D</color>
</text>
</view>
</theme>
The above is equivalent to:
<theme>
<view name="gamelist">
<text name="labelRating">
<color>48474D</color>
</text>
<text name="labelReleasedate">
<color>48474D</color>
</text>
<text name="labelDeveloper">
<color>48474D</color>
</text>
<text name="labelPublisher">
<color>48474D</color>
</text>
<text name="labelGenre">
<color>48474D</color>
</text>
<text name="labelPlayers">
<color>48474D</color>
</text>
<text name="labelLastplayed">
<color>48474D</color>
</text>
<text name="labelPlaycount">
<color>48474D</color>
</text>
</view>
</theme>
Just remember, this only works if the elements have the same type.
Navigation sounds
Navigation sounds are configured globally per theme, so it needs to be defined using the special all view.
It's recommended to put these elements in a separate file and include it from the main theme file (e.g. <include>./navigationsounds.xml</include>). Enabling the Debug mode setting in the Other settings menu or starting ES-DE with the --debug flag will provide feedback on whether the navigation sound elements were parsed correctly. If no navigation sounds are provided by the theme, then ES-DE will use the bundled navigation sounds as a fallback. This is done per sound file, so the theme could provide for example one or two custom sounds while using the bundled ES-DE sounds for the rest.
When fast-scrolling the textlist (by holding the up/down or shoulder buttons) the scroll and systembrowse sounds always play to completion before being played again, so it will sound weird if you have long samples such as those with reverb or silence added to the end. As such make sure to always use short samples for these sounds and test thoroughly with fast-scrolling. This is not an issue if using the carousel or grid elements.
Example debug output:
Jul 12 11:28:58 Debug: NavigationSounds::loadThemeNavigationSounds(): Theme includes navigation sound support, loading custom sounds
Jul 12 11:28:58 Debug: Sound::getFromTheme(): Looking for tag <sound name="systembrowse">
Jul 12 11:28:58 Debug: Sound::getFromTheme(): Tag found, ready to load theme sound file
Jul 12 11:28:58 Debug: Sound::getFromTheme(): Looking for tag <sound name="quicksysselect">
Jul 12 11:28:58 Debug: Sound::getFromTheme(): Tag not found, using fallback sound file
Example navigationsounds.xml file:
<theme>
<view name="all">
<sound name="systembrowse">
<path>./core/sounds/systembrowse.wav</path>
</sound>
<sound name="quicksysselect">
<path>./core/sounds/quicksysselect.wav</path>
</sound>
<sound name="select">
<path>./core/sounds/select.wav</path>
</sound>
<sound name="back">
<path>./core/sounds/back.wav</path>
</sound>
<sound name="scroll">
<path>./core/sounds/scroll.wav</path>
</sound>
<sound name="favorite">
<path>./core/sounds/favorite.wav</path>
</sound>
<sound name="launch">
<path>./core/sounds/launch.wav</path>
</sound>
</view>
</theme>
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 section.
These are the default zIndex values per element type:
| Element | zIndex value |
|---|---|
| image | 30 |
| video | 30 |
| animation | 35 |
| badges | 35 |
| text | 40 |
| datetime | 40 |
| gamelistinfo | 45 |
| rating | 45 |
| carousel | 50 |
| grid | 50 |
| textlist | 50 |
The helpsystem element does not really have a zIndex value and is always rendered on top of all other elements.
Theme variables
Theme variables can be used to simplify theme construction and there are two types available:
- System variables
- Theme defined variables
System variables
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.namesystem.name.autoCollectionssystem.name.customCollectionssystem.name.noCollectionssystem.fullNamesystem.fullName.autoCollectionssystem.fullName.customCollectionssystem.fullName.noCollectionssystem.themesystem.theme.autoCollectionssystem.theme.customCollectionssystem.theme.noCollections
system.name expands to the short name of the system as defined by the name tag in es_systems.xml
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 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.
<theme>
<view name="system">
<text name="systemName, autoCollectionName, customCollectionName">
<pos>0.05 0.83</pos>
<size>0.9 0.06</size>
<fontSize>0.06</fontSize>
<fontPath>./core/font.ttf</fontPath>
</text>
<text name="systemName">
<text>${system.fullName.noCollections}</text>
<letterCase>none</letterCase>
</text>
<text name="autoCollectionName">
<text>${system.fullName.autoCollections}</text>
<letterCase>capitalize</letterCase>
</text>
<text name="customCollectionName">
<text>${system.fullName.customCollections}</text>
<letterCase>none</letterCase>
</text>
</view>
</theme>
Theme defined variables
Variables can also be defined in the theme.
<theme>
<variables>
<themeColor>8B0000</themeColor>
</variables>
</theme>
Usage in themes
Variables can be used to specify the value of a theme property:
<color>${themeColor}</color>
It can also be used to specify only a portion of the value of a theme property:
<color>${themeColor}C0</color>
<path>./core/images/${system.theme}.svg</path>
Nesting of variables is supported, so the following could be done:
<theme>
<variables>
<colorRed>8b0000</colorRed>
<themeColor>${colorRed}</themeColor>
</variables>
</theme>
Variables can also be declared inside the <variant> and <aspectRatio> tags, but make sure to read the comments below for the implications and possibly unforeseen behavior when doing this:
<theme>
<variant name="lightMode, lightModeNoVideo">
<variables>
<colorRed>8b0000</colorRed>
<themeColor>${colorRed}</themeColor>
</variables>
</variant>
</theme>
Variables live in the global namespace, i.e. they are reachable by all configuration entries regardless of whether variants are used or not. This means that if a variable is defined directly under the <theme> tag and then redefined inside a <variant> or <aspectRatio> tag then the global variable will be modified rather than a copy specific to the variant. As well, since all general (non-variant) configuration is parsed prior to the variant configuration, any overriding of the variable will be done "too late" to apply to the general configuaration. Take this example:
<theme>
<!-- Set the value of variable themeColor to 8b0000 -->
<variables>
<colorRed>8b0000</colorRed>
<themeColor>${colorRed}</themeColor>
</variables>
<!-- Override the value of variable themeColor by defining it as 6533ff -->
<variant name="lightMode, lightModeNoVideo">
<variables>
<themeColor>6533ff</themeColor>
</variables>
</variant>
<!-- color will be set to 8b0000 as it's parsed before the variants configuration -->
<view name="gamelist">
<text name="infoText01">
<pos>0.3 0.56</pos>
<color>${themeColor}</color>
</text>
</view>
<!-- color will be set to 6533ff -->
<variant name="lightMode, lightModeNoVideo">
<view name="gamelist">
<text name="gameName">
<pos>0.8 0.12</pos>
<color>${themeColor}</color>
</text>
</view>
</variant>
</theme>
Due to the potential confusion caused by the above configuration it's recommended to never use the same variable names under the <variant> or <aspectRatio> tags as have previously been declared directly under the <theme> tag.
Configuration parsing order
It's important to understand how the theme configuration files are parsed in order to avoid potentially confusing issues that may appear to be bugs. The following order is always used:
- Transitions
- Variables
- Color schemes
- Font sizes
- Languages
- Included files
- "General" (non-variant) configuration
- Variants
- Aspect ratios
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 ($HOMEfor 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.ttfor./../core/fonts/myfont.ttf - BOOLEAN -
true/1orfalse/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
- FLOAT - a decimal value
- STRING - a string of text
Element types and their properties
There are three groups of elements available for use which are named primary, secondary and special. They are all covered in detail below.
Common to almost all elements are pos and size properties of the NORMALIZED_PAIR type. They are normalized in terms of their parent's size. Most of the time this is just the size of the screen. In this case, <pos>0 0</pos> would correspond to the top left corner, and <pos>1 1</pos> the bottom right corner (a positive Y value points further down). You can also use numbers outside the 0 to 1 range if you want to place an element partially off-screen.
The order in which you define properties for a given element does not matter and you only need to define a property if you want to override its default value. If a property is defined multiple times then the latest entry will override any previous occurances.
Primary elements
Elements from this group can only occur once per view (for a certain variant) and they handle basic functionality like controller input and navigation.
carousel
A carousel for navigating and selecting games or systems.
Supported views:
systemgamelist
Instances per view:
single
Properties:
pos- type: NORMALIZED_PAIR- Default is
0 0.38378
- Default is
size- type: NORMALIZED_PAIR- Minimum value per axis is
0.05and maximum value per axis is2 - Default is
1 0.2324
- Minimum value per axis is
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the carousel exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
type- type: STRING- Sets the carousel type and scroll direction.
- Valid values are
horizontal,vertical,horizontalWheelorverticalWheel - Default is
horizontal
staticImage- type: PATH- Path to a static image file. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
- This property can only be used in the
systemview.
imageType- type: STRING- This displays a game image of a certain media type, and can only be used in the
gamelistview. Optionally two types can be defined, in which case the entries should be delimited by commas or by whitespace characters (tabs, spaces or line breaks). The media will be searched for in the order that the entries have been defined, and any superfluous entries will be ignored. Note that defining two entries can lead to quite a performance penalty so in general it's recommended to define a single value and instead usedefaultImageas a fallback in case no image is found. - Valid values:
marquee- This will look for a marquee (wheel) image.cover- This will look for a box front cover image.backcover- This will look for a box back cover image.3dbox- This will look for a 3D box image.physicalmedia- This will look for a physical media image.screenshot- This will look for a screenshot image.titlescreen- This will look for a title screen image.miximage- This will look for a miximage.fanart- This will look for a fan art image.none- No image will be used, instead the game name will be displayed as text. Has no effect ifdefaultImagehas been defined.- Default is
marquee
- This displays a game image of a certain media type, and can only be used in the
defaultImage- type: PATH- Path to the default image file which will be displayed if the image defined via the
staticImageorimageTypeproperty is not found. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
- Path to the default image file which will be displayed if the image defined via the
defaultFolderImage- type: PATH- Path to the default image file which will be displayed if the image defined via the
staticImageorimageTypeproperty is not found and the item is a folder. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif). - Default is the same value as
defaultImage - This property can only be used in the
gamelistview.
- Path to the default image file which will be displayed if the image defined via the
maxItemCount- type: FLOAT- Sets the number of carousel items to display.
- Minimum value is
0.5and maximum value is30 - Default is
3 - This property can only be used when
typeishorizontalorvertical
itemsBeforeCenter- type: UNSIGNED_INTEGER- Sets the number of items before the center position (the currently selected item). By setting this property and
itemsAfterCenterto different values an asymmetric wheel can be configured. Combine withitemRotationto control how many entries to display in the carousel. - Minimum value is
0and maximum value is20 - Default is
8 - This property can only be used when
typeishorizontalWheelorverticalWheel
- Sets the number of items before the center position (the currently selected item). By setting this property and
itemsAfterCenter- type: UNSIGNED_INTEGER- Sets the number of items after the center position (the currently selected item). By setting this property and
itemsBeforeCenterto different values an asymmetric wheel can be configured. Combine withitemRotationto control how many entries to display in the carousel. - Minimum value is
0and maximum value is20 - Default is
8 - This property can only be used when
typeishorizontalWheelorverticalWheel
- Sets the number of items after the center position (the currently selected item). By setting this property and
itemStacking- type: STRING- Controls how to stack overlapping items. When set to
centeredthe selected item will be raised and items further from the selected item (to the left/right or above/below depending on the carousel orientation) will be progressively rendered lower than the items closer to the center. If set toascendingthen items will be rendered progressively higher from left to right or from top to bottom depending on the carousel orientation. If set todescendingthe opposite takes place with items being progressively rendered lower from left to right or top to bottom depending on the carousel orientation. FinallyascendingRaisedanddescendingRaisedwork identically toascendinganddescendingwith the only difference that the currently selected item will be raised above the other items. - Valid values are
centered,ascending,ascendingRaised,descendingordescendingRaised - Default is
centered - This property can only be used when
typeishorizontalorvertical
- Controls how to stack overlapping items. When set to
selectedItemMargins- type: NORMALIZED_PAIR- By default items are evenly spaced across the carousel area, but this property makes it possible to define margins (extra space or less space) around the currently selected item. The first value in the pair defines the margin to the left of the item if it's a horizontal carousel or above the item if it's a vertical carousel, and the second value of the pair sets the right or bottom margin for the selected item depending on the carousel orientation.
- Minimum value per axis is
-1and maximum value per axis is1 - Default is
0 0 - This property can only be used when
typeishorizontalorvertical
selectedItemOffset- type: NORMALIZED_PAIR- Offsets the selected item. The first value of the pair is the horizontal offset and the second value is the vertical offset. Applied after all other positioning calculations.
- Minimum value per axis is
-1and maximum value per axis is1 - Default is
0 0 - This property can only be used when
typeishorizontalorvertical
itemSize- type: NORMALIZED_PAIR- Size of the item prior to multiplication by the
itemScalevalue, i.e. the size of all unselected items. Both axes need to be defined. - Minimum value per axis is
0.05and maximum value per axis is1 - Default is
0.25 0.155
- Size of the item prior to multiplication by the
itemScale- type: FLOAT.- Selected item is scaled by the value defined by this property.
- Minimum value is
0.2and maximum value is3 - Default is
1.2
itemRotation- type: FLOAT- Angle in degrees that items should be rotated. This value should be positive if the
itemRotationOriginX axis has a negative value, and it should be negative if theitemRotationOriginX axis has a positive value, otherwise the wheel will rotate in the wrong direction. - Default is
7.5 - This property can only be used when
typeishorizontalWheelorverticalWheel
- Angle in degrees that items should be rotated. This value should be positive if the
itemRotationOrigin- type: NORMALIZED_PAIR- Point around which the items will be rotated. The X axis of this property is the distance from the left side of the item to the center of the wheel in multiples of the size defined by the
itemSizeX axis. So if for instance the itemSize X axis is set to 0.2 and itemRotationOrigin is set to -2, then the center of the wheel will be at a -0.4 distance from the left side of the item. In other words, if specifying a negative number the item will be located on the right side of the carousel, i.e. the wheel will be to the left and if specifying a positive number the wheel will be to the right. Note again that this is calculated from the left side of the item, so to get an identically sized wheel as the -2 wheel just mentioned you need to define 3 as the value rather than 2 if you want the wheel to the right side of the item. This is not an error but due to the way that coordinates are calculated. The Y axis should normally be left at0.5or you may get some weird results. It is however possible to use this axis value creatively if you know what you are doing. - Default is
-3 0.5 - This property can only be used when
typeishorizontalWheelorverticalWheel
- Point around which the items will be rotated. The X axis of this property is the distance from the left side of the item to the center of the wheel in multiples of the size defined by the
itemAxisHorizontal- type: BOOLEAN- Wheel carousel items are normally rotated towards the center of the wheel as defined by
itemRotationanditemRotationOrigin. But if enabling this property the items will not get rotated along their own axis, meaning they will retain their original horizontal orientation regardless of their position along the wheel. Make sure thatitemVerticalAlignmentis set tocenterwhen using this property or you'll get strange alignment issues. - Default is
false - This property can only be used when
typeishorizontalWheelorverticalWheel
- Wheel carousel items are normally rotated towards the center of the wheel as defined by
itemAxisRotation- type: FLOAT- Angle in degrees that items should be rotated around their own axis. Note that this does not work well with reflections as these are rotated too which does not look right.
- Default is
0 - This property can only be used when
typeishorizontalorvertical
imageFit- type: STRING- Controls how to fit the image within the aspect ratio defined by
itemSize. To scale and preserve the original aspect ratio, set the value tocontain, to stretch/squash the image to fill the entire area set it tofilland to crop the image to fill the entire area set it tocover - Valid values are
contain,fillorcover - Default is
contain
- Controls how to fit the image within the aspect ratio defined by
imageCropPos- type: NORMALIZED_PAIR- If the image has been cropped by setting
imageFittocoverthen this property makes it possible to position the texture within the cropped area. The first value of the pair is the X axis where0means align to the left and1means align to the right, and the second value of the pair is the Y axis where0means align on top and1means align at the bottom. Any arbitrary floating point values between 0 and 1 can be used for granular positioning. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5(texture is centered) - This property can only be used if
imageFithas been set tocover
- If the image has been cropped by setting
imageInterpolation- type: STRING- Interpolation method to use when scaling and rotating images. Nearest neighbor (
nearest) preserves sharp pixels and linear filtering (linear) makes the image smoother. This property has limited effect on scalable vector graphics (SVG) images unless rotation is applied. - Valid values are
nearestorlinear - Default is
linear
- Interpolation method to use when scaling and rotating images. Nearest neighbor (
imageCornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the images defined by
staticImage,imageTypeanddefaultImage. The radius is a percentage of the screen width and not directly related to the image size. This makes it possible to apply identically sized corners regardless of image dimensions. The size is calculated internally withitemScaleset to1. 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 width or height. It means that setting this property sufficiently high will turn a perfectly square image into a perfectly round one. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
- Setting this property higher than zero applies rounded corners to the images defined by
imageColor- type: COLOR- Applies a color shift to the images defined by
staticImage,imageTypeordefaultImageby multiplying each pixel's color by this color value. For example, an all-white image withFF0000applied would become completely red. You can also control the transparency of the images by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. This property is applied afterimageSaturationso by setting that property to0it's possible to colorize rather than color shift. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to the images defined by
imageColorEnd- type: COLOR- Works in the exact same way as
imageColorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
imageColor
- Works in the exact same way as
imageGradientType- type: STRING- The direction to apply the color gradient if both
imageColorandimageColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
imageSelectedColor- type: COLOR- Applies a color shift to the currently selected item's image as defined by
staticImage,imageTypeordefaultImageby multiplying each pixel's color by this color value. For example, an all-white image withFF0000applied would become completely red. You can also control the transparency of the images by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. This property is applied afterimageSaturationso by setting that property to0it's possible to colorize rather than color shift. - Default is the same value as
imageColor
- Applies a color shift to the currently selected item's image as defined by
imageSelectedColorEnd- type: COLOR- Works in the exact same way as
imageSelectedColorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
imageSelectedColor
- Works in the exact same way as
imageSelectedGradientType- type: STRING- The direction to apply the color gradient if both
imageSelectedColorandimageSelectedColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
imageBrightness- type: FLOAT- Controls the relative level of brightness. This is intended primarily for fine adjustments, for example if a color shift has been applied which may have lowered the overall brightness of the image.
- Minimum value is
-2and maximum value is2 - Default is
0(no brightness adjustments applied)
imageSaturation- type: FLOAT- Controls the level of color saturation.
- Minimum value is
0(grayscale) and maximum value is1(original file saturation). - Default is
1
itemTransitions- type: STRING- How to render item transitions when navigating the carousel. By default a slide, scale and opacity fade animation will be played when moving between items (the latter two assuming
itemScaleandunfocusedItemOpacityhave not been set to1) but if this property is set toinstantthen transitions will be immediate. - Valid values are
animateorinstant - Default is
animate
- How to render item transitions when navigating the carousel. By default a slide, scale and opacity fade animation will be played when moving between items (the latter two assuming
itemDiagonalOffset- type: FLOAT- Offsets all items to the left/right or above/below the selected item (depending on the carousel orientation) to achieve a diagonal layout. The defined value is the per-item offset (screen height percentage if
typeishorizontalor screen width percentage iftypeisvertical) - Minimum value is
-0.5and maximum value is0.5 - Default is
0 - This property can only be used when
typeishorizontalorvertical
- Offsets all items to the left/right or above/below the selected item (depending on the carousel orientation) to achieve a diagonal layout. The defined value is the per-item offset (screen height percentage if
itemHorizontalAlignment- type: STRING- Sets
staticImage/imageTypeandtextalignment relative to the carousel on the X axis. - Valid values are
left,centerorright - Default is
center - This property can only be used when
typeisverticalorverticalWheel
- Sets
itemVerticalAlignment- type: STRING- Sets
staticImage/imageTypeandtextalignment relative to the carousel on the Y axis. Make sure to set this tocenterif you've enableditemAxisHorizontal - Valid values are
top,centerorbottom - Default is
center - This property can only be used when
typeishorizontal,horizontalWheelorverticalWheel
- Sets
wheelHorizontalAlignment- type: STRING- Sets the horizontal alignment of the actual carousel inside the overall element area. Note that the positioning is calculated before
itemAxisHorizontalis applied. - Valid values are
left,centerorright - Default is
center - This property can only be used when
typeisverticalWheel
- Sets the horizontal alignment of the actual carousel inside the overall element area. Note that the positioning is calculated before
wheelVerticalAlignment- type: STRING- Sets the vertical alignment of the actual carousel inside the overall element area.
- Valid values are
top,centerorbottom - Default is
center - This property can only be used when
typeishorizontalWheel
horizontalOffset- type: FLOAT- Offsets the carousel horizontally inside its designated area, as defined by the
sizeproperty. The value of this property is relative to the width of the carousel (with1being equivalent to its entire width). This property can for example be used to add a margin if usingitemHorizontalAlignmentor to offset the selected item of horizontal carousels to a non-centered position. - Minimum value is
-1.0and maximum value is1 - Default is
0
- Offsets the carousel horizontally inside its designated area, as defined by the
verticalOffset- type: FLOAT- Offsets the carousel vertically inside its designated area, as defined by the
sizeproperty. The value of this property is relative to the height of the carousel (with1being equivalent to its entire height). This can be used to add a margin if usingitemVerticalAlignmentbut is even more useful ifreflectionshas been set as it allows the control of how much of the reflections to display by relocating the carousel inside its clipping area. It can also be used to offset the selected item of vertical carousels to a non-centered position. - Minimum value is
-1.0and maximum value is1 - Default is
0
- Offsets the carousel vertically inside its designated area, as defined by the
reflections- type: BOOLEAN- Enables reflections beneath the carousel items. It's probably a good idea to combine this with the
verticalOffsetproperty to define how much of the reflections should be visible. - Default is
false - This property can only be used when
typeishorizontal
- Enables reflections beneath the carousel items. It's probably a good idea to combine this with the
reflectionsOpacity- type: FLOAT- Defines the base opacity for the reflections.
- Minimum value is
0.1and maximum value is1 - Default is
0.5 - This property can only be used when
typeishorizontal
reflectionsFalloff- type: FLOAT- Defines the reflections opacity falloff, starting from the item's base opacity and ending at complete transparency. The value is set relative to the item height, so
1will fade the bottom of the item to full transparency,2will fade to full transparency at half the item height and0.5will place the full transparency point at twice the item height. - Minimum value is
0and maximum value is10 - Default is
1 - This property can only be used when
typeishorizontal
- Defines the reflections opacity falloff, starting from the item's base opacity and ending at complete transparency. The value is set relative to the item height, so
unfocusedItemOpacity- type: FLOAT- Sets the opacity for all items except the currently selected entry.
- Minimum value is
0.1and maximum value is1 - Default is
0.5
unfocusedItemSaturation- type: FLOAT- Sets the saturation for all items except the currently selected entry. This property takes precedence over
imageSaturationif that has also been defined. - Minimum value is
0(grayscale) and maximum value is1(original file saturation). - Default is
1
- Sets the saturation for all items except the currently selected entry. This property takes precedence over
unfocusedItemDimming- type: FLOAT- Sets the dimming for all items except the currently selected entry.
- Minimum value is
0(pure black) and maximum value is1(no adjustment) - Default is
1
fastScrolling- type: BOOLEAN- Normally the carousel scrolls at a constant and somehow slow pace, but via this property it's possible to introduce faster scrolling with an additional higher scrolling tier similar to the gamelist textlist (although slightly slower than that). This requires that the carousel has three or more entries, otherwise the highest scrolling tier will never be triggered. Be aware of possible performance implications when enabling this property as images have to be streamed at a higher speed which may introduce stuttering on slower machines.
- Default is
false
color- type: COLOR- Color of the carousel background panel. Setting a value of
00000000makes the background panel transparent. - Default is
FFFFFFD8
- Color of the carousel background panel. Setting a value of
colorEnd- type: COLOR- Setting this to something other than what is defined for
colorcreates a color gradient on the background panel. - Default is the same value as
color
- Setting this to something other than what is defined for
gradientType- type: STRING- The direction to apply the color gradient if both
colorandcolorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
text- type: STRING- A string literal to display if there is no
staticImageordefaultImageproperty defined and if no image is found. - Default is the full system name.
- This property can only be used in the
systemview as for the gamelist view the game name is always used as fallback.
- A string literal to display if there is no
textRelativeScale- type: FLOAT.- This property makes it possible to size the text relative to the overall item size. If using this and also defining a text background color using
textBackgroundColorortextSelectedBackgroundColorthen this color will still fill the entire item size. - Minimum value is
0.2and maximum value is1 - Default is
1
- This property makes it possible to size the text relative to the overall item size. If using this and also defining a text background color using
textBackgroundCornerRadius- 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.
- Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded) - This property can only be used if
textBackgroundColorhas a value defined.
textColor- type: COLOR- Default is
000000FF
- Default is
textBackgroundColor- type: COLOR- Default is
FFFFFF00
- Default is
textSelectedColor- type: COLOR- Sets the text color for the currently selected item.
- Default is the same value as
textColor
textSelectedBackgroundColor- type: COLOR- Sets the text background color for the currently selected item.
- Default is the same value as
textBackgroundColor
textHorizontalScrolling- type: BOOLEAN- If this property is enabled then text that does not fit within the item width will scroll horizontally. If the property is disabled, the text will instead be truncated with an ellipsis (...). Using this property will automatically convert all line breaks to spaces so that a single line of text is always displayed.
- Default is
false
textHorizontalScrollSpeed- type: FLOAT- A relative speed for how fast to scroll the text.
- Minimum value is
0.1and maximum value is10 - Default is
1 - This property can only be used when
textHorizontalScrollinghas been set totrue
textHorizontalScrollDelay- type: FLOAT- Delay in seconds before scrolling starts.
- Minimum value is
0and maximum value is10 - Default is
3 - This property can only be used when
textHorizontalScrollinghas been set totrue
textHorizontalScrollGap- type: FLOAT- As the scrolling text is looped, a second copy is rendered after the first one. This property defines a relative gap value to control the distance between these two text instances.
- Minimum value is
0.1and maximum value is5 - Default is
1.5 - This property can only be used when
textHorizontalScrollinghas been set totrue
fontPath- type: PATH- Path to a TrueType font (.ttf) used as fallback if there is no
staticImage/imageTypeimage defined or found, and ifdefaultImagehas not been defined.
- Path to a TrueType font (.ttf) used as fallback if there is no
fontSize- type: FLOAT- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
0.1, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. This property value is effectively multiplied by theitemScalevalue for the currently selected item (but if this property is omitted then the default value will not get multiplied byitemScale). - Minimum value is
0.001and maximum value is1.5. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. - Default is
0.085
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
letterCase- type: STRING- Sets the letter case for all entries.
- Valid values are
none,uppercase,lowercaseorcapitalize - Default is
none(original letter case is retained).
letterCaseAutoCollections- type: STRING- Sets the letter case specifically for automatic collection entries (all games, favorites and last played) which have their names spelled in lowercase by default.
- Valid values are
none,uppercase,lowercaseorcapitalize - Default is the same value as
letterCase - This property can only be used in the
systemview and it will take precedence overletterCaseif that has also been defined.
letterCaseCustomCollections- type: STRING- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over
letterCaseif that has also been defined. - Valid values are
none,uppercase,lowercaseorcapitalize - Default is the same value as
letterCase
- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over
lineSpacing- type: FLOAT- Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around
1.1or higher. This way overlapping glyphs or characters being cut off at the top or bottom will be prevented. - Minimum value is
0.5and maximum value is3 - Default is
1.5
- Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around
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). This assumes a fallback to text is made.
- Default is
true - This property can only be used in the
gamelistview.
letterCaseSystemNameSuffix- type: STRING- Sets the letter case for the system name suffix.
- Valid values are
uppercase,lowercaseorcapitalize - Default is
uppercase - This property can only be used in the
gamelistview and only whensystemNameSuffixistrue
fadeAbovePrimary- type: BOOLEAN- When using fade transitions, all elements in the
systemview with a zIndex value higher than the carousel are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the carousel will be dimmed to black and elements above the carousel will be faded to transparent. - Default is
false - This property can only be used in the
systemview.
- When using fade transitions, all elements in the
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
50
grid
An X*Y grid for navigating and selecting games or systems using the left/right and up/down buttons. The layout including the amount of columns and rows is automatically calculated based on the relevant property values.
Supported views:
systemgamelist
Instances per view:
single
Properties:
pos- type: NORMALIZED_PAIR- Default is
0 0.1
- Default is
size- type: NORMALIZED_PAIR- Minimum value per axis is
0.05and maximum value per axis is1 - Default is
1 0.8
- Minimum value per axis is
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the grid exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
staticImage- type: PATH- Path to a static image file. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
- This property can only be used in the
systemview.
imageType- type: STRING- This displays a game image of a certain media type, and can only be used in the
gamelistview. Optionally two types can be defined, in which case the entries should be delimited by commas or by whitespace characters (tabs, spaces or line breaks). The media will be searched for in the order that the entries have been defined, and any superfluous entries will be ignored. Note that defining two entries can lead to quite a performance penalty so in general it's recommended to define a single value and instead usedefaultImageas a fallback in case no image is found. - Valid values:
marquee- This will look for a marquee (wheel) image.cover- This will look for a box front cover image.backcover- This will look for a box back cover image.3dbox- This will look for a 3D box image.physicalmedia- This will look for a physical media image.screenshot- This will look for a screenshot image.titlescreen- This will look for a title screen image.miximage- This will look for a miximage.fanart- This will look for a fan art image.none- No image will be used, instead the game name will be displayed as text. Has no effect ifdefaultImagehas been defined.- Default is
marquee
- This displays a game image of a certain media type, and can only be used in the
defaultImage- type: PATH- Path to the default image file which will be displayed if the image defined via the
staticImageorimageTypeproperty is not found. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
- Path to the default image file which will be displayed if the image defined via the
defaultFolderImage- type: PATH- Path to the default image file which will be displayed if the image defined via the
staticImageorimageTypeproperty is not found and the item is a folder. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif). - Default is the same value as
defaultImage - This property can only be used in the
gamelistview.
- Path to the default image file which will be displayed if the image defined via the
itemSize- type: NORMALIZED_PAIR- Size of the overall item prior to multiplication by the
itemScalevalue, i.e. the size of all unselected items. If one of the axis is defined as-1then it will be set to the same pixel value as the other axis, resulting in a perfectly square item. If not using this approach then both axes need to be defined. - Minimum value per axis is
0.05and maximum value per axis is1 - Default is
0.15 0.25
- Size of the overall item prior to multiplication by the
itemScale- type: FLOAT.- Selected overall item is scaled by the value defined by this property.
- Minimum value is
0.5and maximum value is2 - Default is
1.05
itemSpacing- type: NORMALIZED_PAIR- The horizontal and vertical space between items. This value is added to the unscaled item size, i.e.
itemSizebefore it's been multiplied byitemScale. This means that if an axis is set to0then unscaled items will be perfectly adjacent to each other on that axis but ifitemScalehas been set to higher than1then the currently selected item will overlap adjacent items. If this property is omitted then spacing will be automatically calculated so that no overlaps occur during scaling. However you'd normally want to define and adjust this property for an optimal layout. If one of the axis is defined as-1then it will be set to the same pixel value as the other axis. Note that all spacing calculations are based on the value defined byitemSizewhich may or may not be the same as the actual image sizes, depending on their aspect ratios and if theimageFitproperty is used. - Minimum value per axis is
0and maximum value per axis is0.1
- The horizontal and vertical space between items. This value is added to the unscaled item size, i.e.
scaleInwards- type: BOOLEAN- Enabling this property will scale items along the outer grid boundaries towards the center of the grid. This means that it's possible to fill the entire screen width or height while still allowing scaling to take place.
- Default is
false - This property can only be used if
itemScaleis higher than1
fractionalRows- type: BOOLEAN- Whether to allow rendering of fractional rows of items. If set to false then the effective area of the overall element size will be snapped to the item height multiplied by
itemScale. Note that if settingitemScaletoo high relative to theitemSpacingY axis value then fractional rows may still be rendered even if thefractionalRowsproperty is set to false. - Default is
false
- Whether to allow rendering of fractional rows of items. If set to false then the effective area of the overall element size will be snapped to the item height multiplied by
itemTransitions- type: STRING- How to render item transitions when navigating the grid. By default a scaling and opacity fade animation will be played when moving between items (assuming
itemScaleandunfocusedItemOpacityhave not been set to1) but if this property is set toinstantthen transitions will be immediate. - Valid values are
animateorinstant - Default is
animate
- How to render item transitions when navigating the grid. By default a scaling and opacity fade animation will be played when moving between items (assuming
rowTransitions- type: STRING- How to render row transitions when navigating the grid. By default a sliding animation will be rendered when moving between rows but if this property is set to
instantthen transitions will be immediate. If setting this toinstantit's recommended to do the same foritemTransitionsor otherwise the animations will look a bit ugly. - Valid values are
animateorinstant - Default is
animate
- How to render row transitions when navigating the grid. By default a sliding animation will be rendered when moving between rows but if this property is set to
unfocusedItemOpacity- type: FLOAT- Sets the opacity for all items except the currently selected entry.
- Minimum value is
0.1and maximum value is1 - Default is
1
unfocusedItemSaturation- type: FLOAT- Sets the saturation for all items except the currently selected entry. This property takes precedence over
imageSaturationif that has also been defined. - Minimum value is
0(grayscale) and maximum value is1(original file saturation). - Default is
1
- Sets the saturation for all items except the currently selected entry. This property takes precedence over
unfocusedItemDimming- type: FLOAT- Sets the dimming for all items except the currently selected entry.
- Minimum value is
0(pure black) and maximum value is1(no adjustment) - Default is
1
imageFit- type: STRING- Controls how to fit the image within the aspect ratio defined by
itemSize. To scale and preserve the original aspect ratio, set the value tocontain, to stretch/squash the image to fill the entire area set it tofilland to crop the image to fill the entire area set it tocover - Valid values are
contain,fillorcover - Default is
contain
- Controls how to fit the image within the aspect ratio defined by
imageCropPos- type: NORMALIZED_PAIR- If the image has been cropped by setting
imageFittocoverthen this property makes it possible to position the texture within the cropped area. The first value of the pair is the X axis where0means align to the left and1means align to the right, and the second value of the pair is the Y axis where0means align on top and1means align at the bottom. Any arbitrary floating point values between 0 and 1 can be used for granular positioning. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5(texture is centered) - This property can only be used if
imageFithas been set tocover
- If the image has been cropped by setting
imageInterpolation- type: STRING- Interpolation method to use when scaling images. Nearest neighbor (
nearest) preserves sharp pixels and linear filtering (linear) makes the image smoother. This property has limited effect on scalable vector graphics (SVG) images. - Valid values are
nearestorlinear - Default is
linear
- Interpolation method to use when scaling images. Nearest neighbor (
imageRelativeScale- type: FLOAT.- This property makes it possible to size the image defined by
staticImage,imageTypeordefaultImagerelative to the overall item size. This is mostly useful when combined with thebackgroundImageandselectorImageproperties. - Minimum value is
0.2and maximum value is1 - Default is
1
- This property makes it possible to size the image defined by
imageCornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the images defined by
staticImage,imageTypeanddefaultImage. The radius is a percentage of the screen width and not directly related to the image size. This makes it possible to apply identically sized corners regardless of image dimensions. The size is calculated internally withitemScaleandimageRelativeScaleset to1. 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 width or height. It means that setting this property sufficiently high will turn a perfectly square image into a perfectly round one. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
- Setting this property higher than zero applies rounded corners to the images defined by
imageColor- type: COLOR- Applies a color shift to the images defined by
staticImage,imageTypeordefaultImageby multiplying each pixel's color by this color value. For example, an all-white image withFF0000applied would become completely red. You can also control the transparency of the images by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. This property is applied afterimageSaturationso by setting that property to0it's possible to colorize rather than color shift. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to the images defined by
imageColorEnd- type: COLOR- Works in the exact same way as
imageColorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
imageColor
- Works in the exact same way as
imageGradientType- type: STRING- The direction to apply the color gradient if both
imageColorandimageColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
imageSelectedColor- type: COLOR- Applies a color shift to the currently selected item's image as defined by
staticImage,imageTypeordefaultImageby multiplying each pixel's color by this color value. For example, an all-white image withFF0000applied would become completely red. You can also control the transparency of the images by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. This property is applied afterimageSaturationso by setting that property to0it's possible to colorize rather than color shift. - Default is the same value as
imageColor
- Applies a color shift to the currently selected item's image as defined by
imageSelectedColorEnd- type: COLOR- Works in the exact same way as
imageSelectedColorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
imageSelectedColor
- Works in the exact same way as
imageSelectedGradientType- type: STRING- The direction to apply the color gradient if both
imageSelectedColorandimageSelectedColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
imageBrightness- type: FLOAT- Controls the relative level of brightness. This is intended primarily for fine adjustments, for example if a color shift has been applied which may have lowered the overall brightness of the image.
- Minimum value is
-2and maximum value is2 - Default is
0(no brightness adjustments applied)
imageSaturation- type: FLOAT- Controls the level of color saturation.
- Minimum value is
0(grayscale) and maximum value is1(original file saturation). - Default is
1
backgroundImage- type: PATH- Path to an optional background image file which will be displayed behind the image defined by
staticImage,imageTypeordefaultImage. The aspect ratio for this image will not be preserved, it will be stretched or squashed to the aspect ratio set byitemSize. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
- Path to an optional background image file which will be displayed behind the image defined by
backgroundRelativeScale- type: FLOAT.- This property makes it possible to size the background relative to the overall item size. This is mostly useful when combined with the
selectorImageproperty. - Minimum value is
0.2and maximum value is1 - Default is
1
- This property makes it possible to size the background relative to the overall item size. This is mostly useful when combined with the
backgroundCornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the image defined by
backgroundImage, or to the colored rectangle ifbackgroundColorhas been defined without using a background image. The radius is a percentage of the screen width and not directly related to the background size. This makes it possible to apply identically sized corners regardless of image dimensions. The size is calculated internally withitemScaleandbackgroundRelativeScaleset to1. 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 width or height. It means that setting this property sufficiently high will turn a perfectly square background into a perfectly round one. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
- Setting this property higher than zero applies rounded corners to the image defined by
backgroundColor- type: COLOR- Applies a color shift or draws a colored rectangle. If an image has been defined using the
backgroundImageproperty then each pixel of that image is multiplied by this color value. For example, an all-white image withFF0000applied would become completely red. You can also control the transparency of the image by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. If no background image has been defined, then a colored rectangle will be drawn instead.
- Applies a color shift or draws a colored rectangle. If an image has been defined using the
backgroundColorEnd- type: COLOR- Works in the exact same way as
backgroundColorbut can be set as the end color to apply a color gradient. - Default is the same value as
backgroundColor
- Works in the exact same way as
backgroundGradientType- type: STRING- The direction to apply the color gradient if both
backgroundColorandbackgroundColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
selectorImage- type: PATH- Path to an optional selector image file which will be displayed for the currently selected item. The aspect ratio for this image will not be preserved, it will be stretched or squashed to the aspect ratio set by
itemSize. Most common extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
- Path to an optional selector image file which will be displayed for the currently selected item. The aspect ratio for this image will not be preserved, it will be stretched or squashed to the aspect ratio set by
selectorRelativeScale- type: FLOAT.- This property makes it possible to size the selector relative to the overall item size. This is mostly useful when combined with the
backgroundImageproperty. - Minimum value is
0.2and maximum value is1 - Default is
1
- This property makes it possible to size the selector relative to the overall item size. This is mostly useful when combined with the
selectorLayer- type: STRING- Defines at what layer position to place the selector. It can either be placed at the bottom, in the middle between the background and image/text or on top.
- Valid values are
bottom,middleortop - Default is
top
selectorCornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the image defined by
selectorImage, or to the colored rectangle ifselectorColorhas been defined without using a selector image. The radius is a percentage of the screen width and not directly related to the selector size. This makes it possible to apply identically sized corners regardless of image dimensions. The size is calculated internally withitemScaleandselectorRelativeScaleset to1. 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 width or height. It means that setting this property sufficiently high will turn a perfectly square selector into a perfectly round one. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
- Setting this property higher than zero applies rounded corners to the image defined by
selectorColor- type: COLOR- Applies a color shift or draws a colored rectangle. If an image has been defined using the
selectorImageproperty then each pixel of that image is multiplied by this color value. For example, an all-white image withFF0000applied would become completely red. You can also control the transparency of the image by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. If no selector image has been defined, then a colored rectangle will be drawn instead.
- Applies a color shift or draws a colored rectangle. If an image has been defined using the
selectorColorEnd- type: COLOR- Works in the exact same way as
selectorColorbut can be set as the end color to apply a color gradient. - Default is the same value as
selectorColor
- Works in the exact same way as
selectorGradientType- type: STRING- The direction to apply the color gradient if both
selectorColorandselectorColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
text- type: STRING- A string literal to display if there is no
staticImageordefaultImageproperty defined or if no image is found. - Default is the full system name.
- This property can only be used in the
systemview as for the gamelist view the game name is always used as fallback.
- A string literal to display if there is no
textRelativeScale- type: FLOAT.- This property makes it possible to size the text relative to the overall item size.
- Minimum value is
0.2and maximum value is1 - Default is
1
textBackgroundCornerRadius- 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.
- Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded) - This property can only be used if
textBackgroundColorhas a value defined.
textColor- type: COLOR- Default is
000000FF
- Default is
textBackgroundColor- type: COLOR- Default is
FFFFFF00
- Default is
textSelectedColor- type: COLOR- Sets the text color for the currently selected item.
- Default is the same value as
textColor
textSelectedBackgroundColor- type: COLOR- Sets the text background color for the currently selected item.
- Default is the same value as
textBackgroundColor
textHorizontalScrolling- type: BOOLEAN- If this property is enabled then text that does not fit within the item width will scroll horizontally. If the property is disabled, the text will instead be truncated with an ellipsis (...). Using this property will automatically convert all line breaks to spaces so that a single line of text is always displayed.
- Default is
false
textHorizontalScrollSpeed- type: FLOAT- A relative speed for how fast to scroll the text.
- Minimum value is
0.1and maximum value is10 - Default is
1 - This property can only be used when
textHorizontalScrollinghas been set totrue
textHorizontalScrollDelay- type: FLOAT- Delay in seconds before scrolling starts.
- Minimum value is
0and maximum value is10 - Default is
3 - This property can only be used when
textHorizontalScrollinghas been set totrue
textHorizontalScrollGap- type: FLOAT- As the scrolling text is looped, a second copy is rendered after the first one. This property defines a relative gap value to control the distance between these two text instances.
- Minimum value is
0.1and maximum value is5 - Default is
1.5 - This property can only be used when
textHorizontalScrollinghas been set totrue
fontPath- type: PATH- Path to a TrueType font (.ttf) used as fallback if there is no
staticImage/imageTypeimage defined or found, and ifdefaultImagehas not been defined.
- Path to a TrueType font (.ttf) used as fallback if there is no
fontSize- type: FLOAT- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
0.1, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. - Minimum value is
0.001and maximum value is1.5. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. - Default is
0.045
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
letterCase- type: STRING- Sets the letter case for all entries.
- Valid values are
none,uppercase,lowercaseorcapitalize - Default is
none(original letter case is retained).
letterCaseAutoCollections- type: STRING- Sets the letter case specifically for automatic collection entries (all games, favorites and last played) which have their names spelled in lowercase by default.
- Valid values are
none,uppercase,lowercaseorcapitalize - Default is the same value as
letterCase - This property can only be used in the
systemview and it will take precedence overletterCaseif that has also been defined.
letterCaseCustomCollections- type: STRING- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over
letterCaseif that has also been defined. - Valid values are
none,uppercase,lowercaseorcapitalize - Default is the same value as
letterCase
- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over
lineSpacing- type: FLOAT- Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around
1.1or higher. This way overlapping glyphs or characters being cut off at the top or bottom will be prevented. - Minimum value is
0.5and maximum value is3 - Default is
1.5
- Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around
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). This assumes a fallback to text is made.
- Default is
true - This property can only be used in the
gamelistview.
letterCaseSystemNameSuffix- type: STRING- Sets the letter case for the system name suffix.
- Valid values are
uppercase,lowercaseorcapitalize - Default is
uppercase - This property can only be used in the
gamelistview and only whensystemNameSuffixistrue
fadeAbovePrimary- type: BOOLEAN- When using fade transitions, all elements in the
systemview with a zIndex value higher than the grid are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the grid will be dimmed to black and elements above the grid will be faded to transparent. - Default is
false - This property can only be used in the
systemview.
- When using fade transitions, all elements in the
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
50
textlist
A text list for navigating and selecting games or systems.
Supported views:
systemgamelist
Instances per view:
single
Properties:
pos- type: NORMALIZED_PAIR- Default is
0 0.1
- Default is
size- type: NORMALIZED_PAIR- Minimum value per axis is
0.05and maximum value per axis is1 - Default is
1 0.8
- Minimum value per axis is
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would 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
0and maximum value per axis is1 - Default is
0 0
- Where on the element
selectorWidth- type: FLOAT- Width of the selector bar. If an image has been defined using
selectorImagePaththen setting this property to zero will retain the aspect ratio for that image. - Minimum value is
0and maximum value is1 - Default is the equivalent value as the width of the overall element.
- Width of the selector bar. If an image has been defined using
selectorHeight- type: FLOAT- Height of the selector bar. This is expanded downwards so you'll probably want to adjust its position using
selectorVerticalOffsetif making use of this property. - Minimum value is
0and maximum value is1 - Default is 1.5 times the value defined by
fontSize
- Height of the selector bar. This is expanded downwards so you'll probably want to adjust its position using
selectorHorizontalOffset- type: FLOAT- Allows moving of the selector bar left or right from its calculated position. Useful for fine tuning the selector bar position relative to the text.
- Minimum value is
-1and maximum value is1 - Default is
0
selectorVerticalOffset- type: FLOAT- Allows moving of the selector bar up or down from its calculated position. Useful for fine tuning the selector bar position relative to the text.
- Minimum value is
-1and maximum value is1 - Default is
0
selectorColor- type: COLOR- Color of the selector bar.
- Default is
333333FF
selectorColorEnd- type: COLOR- Setting this to something other than what is defined for
selectorColorcreates a color gradient. - Default is
333333FF
- Setting this to something other than what is defined for
selectorGradientType- type: STRING- The direction to apply the color gradient if both
selectorColorandselectorColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color gradient if both
selectorImagePath- type: PATH- Path to image to render in place of the selector bar.
selectorImageTile- type: BOOLEAN- If true, the selector image will be tiled instead of stretched to fit its size.
- Default is
false
primaryColor- type: COLOR- Color of the primary entry type. For the
gamelistview this means file entries and for thesystemview it means system entries. - Default is
0000FFFF
- Color of the primary entry type. For the
secondaryColor- type: COLOR- Color of the secondary entry type. For the
gamelistview this means folder entries and for thesystemview this property is not used. - Default is
00FF00FF
- Color of the secondary entry type. For the
selectedColor- type: COLOR- Color of the highlighted entry for the primary entry type.
- Default is the same value as
primaryColor
selectedSecondaryColor- type: COLOR- Color of the highlighted entry for the secondary entry type.
- Default is the same value as
selectedColor
selectedBackgroundColor- type: COLOR- Background color of the highlighted entry for the primary entry type. This follows the sizing of the selector bar and is expanded downwards so you'll probably want to adjust its position using
selectorVerticalOffsetif you have defined a custom selector height usingselectorHeight - Default is
00000000
- Background color of the highlighted entry for the primary entry type. This follows the sizing of the selector bar and is expanded downwards so you'll probably want to adjust its position using
selectedSecondaryBackgroundColor- type: COLOR- Background color of the highlighted entry for the secondary entry type. This follows the sizing of the selector bar and is expanded downwards so you'll probably want to adjust its position using
selectorVerticalOffsetif you have defined a custom selector height usingselectorHeight - Default is the same value as
selectedBackgroundColor
- Background color of the highlighted entry for the secondary entry type. This follows the sizing of the selector bar and is expanded downwards so you'll probably want to adjust its position using
selectedBackgroundMargins- type: NORMALIZED_PAIR- Adds margins to the selected 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
0and maximum value per axis is0.5 - Default is
0 0 - This property can only be used if
selectedBackgroundColororselectedSecondaryBackgroundColorhas a value defined.
selectedBackgroundCornerRadius- 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
selectedBackgroundMarginsto add some extra margins. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded) - This property can only be used if
selectedBackgroundColororselectedSecondaryBackgroundColorhas a value defined.
- 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
textHorizontalScrolling- type: BOOLEAN- If this property is enabled then text that does not fit within the element width (minus margins) will scroll horizontally. If the property is disabled, the text will instead be truncated with an ellipsis (...). Using this property will automatically convert all line breaks to spaces so that a single line of text is always displayed.
- Valid values are
verticalorhorizontal - Default is
true
textHorizontalScrollSpeed- type: FLOAT- A relative speed for how fast to scroll the text.
- Minimum value is
0.1and maximum value is10 - Default is
1 - This property can only be used when
textHorizontalScrollinghas been set totrue
textHorizontalScrollDelay- type: FLOAT- Delay in seconds before scrolling starts.
- Minimum value is
0and maximum value is10 - Default is
3 - This property can only be used when
textHorizontalScrollinghas been set totrue
textHorizontalScrollGap- type: FLOAT- As the scrolling text is looped, a second copy is rendered after the first one. This property defines a relative gap value to control the distance between these two text instances.
- Minimum value is
0.1and maximum value is5 - Default is
1.5 - This property can only be used when
textHorizontalScrollinghas been set totrue
fontPath- type: PATHfontSize- type: FLOAT- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
0.1, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. - Default is
0.045
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
horizontalAlignment- type: STRING- Controls alignment on the X axis.
- Valid values are
left,centerorright - Default is
left
horizontalMargin- type: FLOAT- Horizontal offset for text from the alignment point. If
horizontalAlignmentis "left", offsets the text to the right. IfhorizontalAlignmentis "right", offsets text to the left. No effect ifhorizontalAlignmentis "center". Given as a percentage of the element's parent's width (same unit assize's X value). - Default is
0
- Horizontal offset for text from the alignment point. If
letterCase- type: STRING- Sets the letter case for all entries.
- Valid values are
none,uppercase,lowercaseorcapitalize - Default is
none(original letter case is retained).
letterCaseAutoCollections- type: STRING- Sets the letter case specifically for automatic collection entries (all games, favorites and last played) which have their names spelled in lowercase by default.
- Valid values are
none,uppercase,lowercaseorcapitalize - Default is the same value as
letterCase - This property can only be used in the
systemview and it will take precedence overletterCaseif that has also been defined.
letterCaseCustomCollections- type: STRING- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over
letterCaseif that has also been defined. - Valid values are
none,uppercase,lowercaseorcapitalize - Default is the same value as
letterCase
- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over
lineSpacing- type: FLOAT- Controls the space between lines. This works a bit different for the textlist element compared to all other elements. In all other instances the line spacing is calculated in relation to the rasterized reference 'S' character. This will however not work for the textlist as there are no guarantees which sizes the rasterized characters may end up as. The nature of font rendering is simply not that static with glyphs being able to have any shape and size and linting/grid alignment being applied during font rasterization. Using the rasterized glyph size would be too imprecise and the spacing would be inconsistent across different display resolutions, possibly leading to a different number of textlist rows. Therefore this specific lineSpacing property is based on the defined font size regardless of what's actually being rasterized. This may seem confusing as some fonts greatly exceed the requested size, but if you simply adjust the spacing until the textlist looks correct it will look almost identical regardless of what display resolution is used.
- Minimum value is
0.5and maximum value is3 - Default is
1.5
indicators- type: STRING- Controls the style of the indicators which get displayed when an entry is a favorite, a folder or a folderlink. If set to
noneit's strongly recommended to enable the corresponding badges as it would otherwise be very confusing for the user as there would be no way to discern this important information about each entry. Thesymbolsvalue uses Font Awesome graphics to prefix the game name andasciiuses plain ASCII characters instead, as provided by the selected font. The latter sometimes looks better on "lo-fi" themes using pixelated fonts and similar. When using ASCII characters, favorites are marked as*folders as#and folderlinks as> - Valid values are
none,asciiandsymbols - Default is
symbols
- Controls the style of the indicators which get displayed when an entry is a favorite, a folder or a folderlink. If set to
collectionIndicators- type: STRING- Controls the style of the indicators which get displayed when editing a custom collection. This property can't be disabled as it's crucial for getting a visual overview when editing collections. When set to
ascii, the indicator is displayed as a! - Valid values are
asciiandsymbols - Default is
symbols
- Controls the style of the indicators which get displayed when editing a custom collection. This property can't be disabled as it's crucial for getting a visual overview when editing collections. When set to
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).
- Default is
true - This property can only be used in the
gamelistview.
letterCaseSystemNameSuffix- type: STRING- Sets the letter case for the system name suffix.
- This property can only be used in the
gamelistview and only whensystemNameSuffixistrue - Valid values are
uppercase,lowercaseorcapitalize - Default is
uppercase
fadeAbovePrimary- type: BOOLEAN- When using fade transitions, all elements in the
systemview with a zIndex value higher than the textlist are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the textlist will be dimmed to black and elements above the textlist will be faded to transparent. - Default is
false - This property can only be used in the
systemview.
- When using fade transitions, all elements in the
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
50
Secondary elements
Elements from this group can occur an unlimited number of times and they take care of displaying the bulk of the theme configuration such as text, images, videos, animations etc.
image
Displays a raster image or a scalable vector graphics (SVG) image.
Supported views:
systemgamelist
Instances per view:
unlimited
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- If only one axis is specified (and the other is zero), then the other axis will be automatically calculated in accordance with the image's aspect ratio. Setting both axes to 0 is an error and the size will be clamped to
0.001 0.001in this case. This property takes precedence overmaxSizeandcropSizeif either or both of those have also been defined. - Minimum value per axis is
0.001and maximum value per axis is3. If specifying a value outside the allowed range then no attempt will be made to preserve the aspect ratio.
- If only one axis is specified (and the other is zero), then the other axis will be automatically calculated in accordance with the image's aspect ratio. Setting both axes to 0 is an error and the size will be clamped to
maxSize- type: NORMALIZED_PAIR- The image will be resized as large as possible so that it fits within this size while maintaining its aspect ratio. Use this instead of
sizewhen you don't know what kind of image you're using so it doesn't get grossly oversized on one axis. This property takes precedence overcropSizeif that has also been defined. - Minimum value per axis is
0.001and maximum value per axis is3
- The image will be resized as large as possible so that it fits within this size while maintaining its aspect ratio. Use this instead of
cropSize- type: NORMALIZED_PAIR- The image will be resized and cropped to the exact size defined by this property while maintaining its aspect ratio. The crop is always applied centered unless
cropPoshas been set. - Minimum value per axis is
0.001and maximum value per axis is3
- The image will be resized and cropped to the exact size defined by this property while maintaining its aspect ratio. The crop is always applied centered unless
cropPos- type: NORMALIZED_PAIR- If the image has been cropped using
cropSizethen this property makes it possible to position the texture within the cropped area. The first value of the pair is the X axis where0means align to the left and1means align to the right, and the second value of the pair is the Y axis where0means align on top and1means align at the bottom. Any arbitrary floating point values between 0 and 1 can be used for granular positioning. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5(texture is centered) - This property can only be used if
cropSizeis used.
- If the image has been cropped using
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is
0
rotationOrigin- type: NORMALIZED_PAIR- Point around which the image will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.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
stationaryfor one view and setrenderDuringTransitionsto 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
- 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
flipHorizontal- type: BOOLEAN- Flips the image texture horizontally.
- Default is
false
flipVertical- type: BOOLEAN- Flips the image texture vertically.
- Default is
false
path- type: PATH- Explicit path to an image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). If
imageTypeis also defined then this will take precedence as these two properties are not intended to be used together. If you need a fallback image in case of missing game media, use thedefaultproperty instead.
- Explicit path to an image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). If
gameOverridePath- type: PATH- Defines a directory where per-game overrides for the static image defined by the
pathproperty are kept. Supported file extensions are .jpg, .png, .gif (unanimated) and .svg and they are searched for in this precise order. How this works is that the basename of the game file will be used to check for an image file in the defined path in a very similar fashion as to how downloaded media is searched. For example ifgameOverridePathhas been set to./imageOverridesa match for the game file~/ROMs/arcade/aburner.zipwould be./imageOverrides/arcade/aburner.png(or any of the other supported file extensions). In this case the image defined by thepathproperty will be replaced for this specific game. Note that only static images can be overridden, not scraped media. - This property can only be used in the
gamelistview and only ifimageTypeis undefined.
- Defines a directory where per-game overrides for the static image defined by the
default- type: PATH- Path to a default image file. This image will be displayed when the selected game does not have an image of the type(s) defined by
imageTypeor if the static image defined bypathis not found. It's also applied to any custom collection that does not contain any games when browsing the grouped custom collections system.
- Path to a default image file. This image will be displayed when the selected game does not have an image of the type(s) defined by
imageType- type: STRING- This displays a game image of a certain media type. Multiple types can be defined, in which case the entries should be delimited by commas or by whitespace characters (tabs, spaces or line breaks). The media will be searched for in the order that the entries have been defined. If no image is found, then the space will be left blank unless the
defaultproperty has been set. To use this property from thesystemview, you will first need to add agameselectorelement. Defining duplicate values is considered an error and will result in the property getting ignored. - Valid values:
image- This will look for amiximage, and if that is not foundscreenshotis tried next, thentitlescreenand finallycover. This is just a convenient shortcut and it's equivalent to explicitly definingmiximage, screenshot, titlescreen, covermiximage- This will look for a miximage.marquee- This will look for a marquee (wheel) image.screenshot- This will look for a screenshot image.titlescreen- This will look for a title screen image.cover- This will look for a box front cover image.backcover- This will look for a box back cover image.3dbox- This will look for a 3D box image.physicalmedia- This will look for a physical media image.fanart- This will look for a fan art image.
- This displays a game image of a certain media type. Multiple types can be defined, in which case the entries should be delimited by commas or by whitespace characters (tabs, spaces or line breaks). The media will be searched for in the order that the entries have been defined. If no image is found, then the space will be left blank unless the
metadataElement- type: BOOLEAN- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the Hide metadata fields setting for a game entry. Using this property it's possible to explicitly define additional image elements that should be treated as if they were game media files. This is for example useful for hiding and fading out image elements that are used as indicator icons for the various metadata types like genre, publisher, players etc. It's however not possible to do the opposite, i.e. to disable this functionality for the default game media types as that would break basic application behavior.
- 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
nameattribute value of the gameselector element. This property is only needed for thesystemview and only if theimageTypeproperty is utilized.
- 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
gameselectorEntry- type: UNSIGNED_INTEGER- This optional property which is only available in the
systemview makes it possible to select whichgameselectorentry to use to populate theimageTypeproperty. This assumes that agameCountproperty for the gameselector element has been defined with a value higher than1. By defining multipleimageelements with different values for thegameselectorEntryproperty it's possible to display multiple game entries at the same time, for example listing a couple of games that were last played, or a selection of random games. If the requested entry does not exist (for instance ifgameCounthas been set to 5 andgameselectorEntryhas been set to4but the system only contains 3 games), then the overall element will not get rendered. Note that the first entry is defined as0, the second entry as1etc. - Minimum value is
0and maximum value is the value of thegameselectorelement propertygameCountminus 1. If a value outside this range is defined, then it will be automatically clamped to a valid value. - Default is
0
- This optional property which is only available in the
tile- type: BOOLEAN- If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds. Do not combine with the
maxSizeorcropSizeproperties, instead always usesizewhen tiling. - Default is
false - This property can only be used when
pathhas been set.
- If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds. Do not combine with the
tileSize- type: NORMALIZED_PAIR- Size of the individual images making up the tile as opposed to the overall size for the element which is defined by the
sizeproperty. If only one axis is specified (and the other is zero), then the other axis will be automatically calculated in accordance with the image's aspect ratio. Setting both axes to 0 is an error and tiling will be disabled in this case. If this property is omitted, then the size will be set to the actual image dimensions. For SVG images this means whatever canvas size has been defined inside the file. - Minimum value per axis is
0and maximum value per axis is1.
- Size of the individual images making up the tile as opposed to the overall size for the element which is defined by the
tileHorizontalAlignment- type: STRING- If the images making up the tiled texture do not match precisely with the edges of the overall element, then this property can be used to define the alignment on the horizontal axis.
- Valid values are
leftorright - Default is
left
tileVerticalAlignment- type: STRING- If the images making up the tiled texture do not match precisely with the edges of the overall element, then this property can be used to define the alignment on the vertical axis.
- Valid values are
toporbottom - Default is
bottom
interpolation- type: STRING- Interpolation method to use when scaling and rotating images. Nearest neighbor (
nearest) preserves sharp pixels and linear filtering (linear) makes the image smoother. This property has limited effect on scalable vector graphics (SVG) images unless rotation is applied. - Valid values are
nearestorlinear - Default is
nearestifrotationis0,90,180or270degrees, otherwise it'slinear
- Interpolation method to use when scaling and rotating images. Nearest neighbor (
cornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the image. The radius is a percentage of the screen width and not directly related to the image size. This makes it possible to apply identically sized corners regardless of image dimensions. 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 width or height. It means that setting this property sufficiently high will turn a perfectly square image into a perfectly round one.
- Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
color- type: COLOR- Applies a color shift to the image by multiplying each pixel's color by this color value. For example, an all-white image with
FF0000applied would become completely red. You can also control the transparency of the image by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. This property is applied aftersaturationso by setting that property to0it's possible to colorize rather than color shift. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to the image by multiplying each pixel's color by this color value. For example, an all-white image with
colorEnd- type: COLOR- Works in the exact same way as
colorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
color
- Works in the exact same way as
gradientType- type: STRING- The direction to apply the color shift gradient if both
colorandcolorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color shift gradient if both
scrollFadeIn- type: BOOLEAN- If enabled, a short fade-in animation will be applied when scrolling through games in the gamelist view.
- Default is
false
brightness- type: FLOAT- Controls the relative level of brightness. This is intended primarily for fine adjustments, for example if a color shift has been applied which may have lowered the overall brightness of the image.
- Minimum value is
-2and maximum value is2 - Default is
0(no brightness adjustments applied)
opacity- type: FLOAT- Controls the level of transparency. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. If set to
saturation- type: FLOAT- Controls the level of color saturation.
- Minimum value is
0(grayscale) and maximum value is1(original file saturation). - Default is
1
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
30
video
Plays a video and provides support for displaying a static image for a defined time period before starting the video player. Although an unlimited number of videos could in theory be defined per view it's recommended to keep it at a single instance as playing videos takes a lot of CPU resources. But if still going for multiple videos, make sure to use the audio property to disable audio on all but one video as ES-DE currently has no audio mixing capabilities so the sound would not play correctly. To use videos in the system view, you either need to set a static video using the path property, or you need to create a gameselector element so game videos can be used.
Supported views:
systemgamelist
Instances per view:
unlimited(but recommended to keep at a single instance)
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- If only one axis is specified (and the other is zero), then the other axis will be automatically calculated in accordance with the static image's aspect ratio and the video's aspect ratio. Setting both axes to 0 is an error and the size will be clamped to
0.01 0.01in this case. This property takes precedence overmaxSizeandcropSizeif either or both of those have also been defined. - Minimum value per axis is
0.01and maximum value per axis is2. If specifying a value outside the allowed range then no attempt will be made to preserve the aspect ratio.
- If only one axis is specified (and the other is zero), then the other axis will be automatically calculated in accordance with the static image's aspect ratio and the video's aspect ratio. Setting both axes to 0 is an error and the size will be clamped to
maxSize- type: NORMALIZED_PAIR- The static image and video will be resized as large as possible so that they fit within this size while maintaining their aspect ratios. Use this instead of
sizewhen you don't know what kind of video you're using so it doesn't get grossly oversized on one axis. This property takes precedence overcropSizeif that has also been defined. - Minimum value per axis is
0.01and maximum value per axis is2
- The static image and video will be resized as large as possible so that they fit within this size while maintaining their aspect ratios. Use this instead of
cropSize- type: NORMALIZED_PAIR- The static image and video will be resized and cropped to the exact size defined by this property while maintaining their aspect ratios. The crop is always applied centered unless
cropPoshas been set. Can't be combined with thescanlinesproperty. - Minimum value per axis is
0.01and maximum value per axis is2
- The static image and video will be resized and cropped to the exact size defined by this property while maintaining their aspect ratios. The crop is always applied centered unless
cropPos- type: NORMALIZED_PAIR- If the static image and video has been cropped using
cropSizethen this property makes it possible to position the texture within the cropped area. The first value of the pair is the X axis where0means align to the left and1means align to the right, and the second value of the pair is the Y axis where0means align on top and1means align at the bottom. Any arbitrary floating point values between 0 and 1 can be used for granular positioning. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5(texture is centered) - This property can only be used if
cropSizeis used.
- If the static image and video has been cropped using
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the static image and video should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is
0
rotationOrigin- type: NORMALIZED_PAIR- Point around which the static image and video will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.always- Set element as stationary during all transitions.never- Don't set element as stationary during any transitions.- Default is
never
path- type: PATH- Path to a video file. Setting a value for this property will make the video static, i.e. any
imageType,gameselectoranddefaultproperties will be ignored. This is true even if the property does not point to an existing video file. As well, when defining this for the gamelist view the video will not immediately restart when navigating between games.
- Path to a video file. Setting a value for this property will make the video static, i.e. any
default- type: PATH- Path to a default video file. The default video will be played when the selected game does not have a video. This property is also applied to any custom collection that does not contain any games when browsing the grouped custom collections system. Takes precedence over
defaultImage.
- Path to a default video file. The default video will be played when the selected game does not have a video. This property is also applied to any custom collection that does not contain any games when browsing the grouped custom collections system. Takes precedence over
defaultImage- type: PATH- Path to a default image file. If the
imageTypeproperty has a value set, then the default image will be displayed if the selected game does not have an image for any of the defined types. IfimageTypeis not defined, then the default image will be shown if there is no video file found and ifdefaulthas not been set. This property is also applied to any custom collection that does not contain any games when browsing the grouped custom collections system.
- Path to a default image file. If the
imageType- type: STRING- This displays a game image of a certain media type, either before the video starts to play if
delayis set to a non-zero value, or if there is no video file found anddefaulthas not been defined. Multiple types can be defined, in which case the entries should be delimited by commas or by whitespace characters (tabs, spaces or line breaks). The media will be searched for in the order that the entries have been defined. If no image is found, then the space will be left blank unless either thedefaultordefaultImageproperties have been set. To use this property from thesystemview, you will first need to add agameselectorelement. Ifdelayis set to zero, then this property has no effect. Defining duplicate values is considered an error and will result in the property getting ignored. - Valid values:
image- This will look for amiximage, and if that is not foundscreenshotis tried next, thentitlescreenand finallycover. This is just a convenient shortcut and it's equivalent to explicitly definingmiximage, screenshot, titlescreen, covermiximage- This will look for a miximage.marquee- This will look for a marquee (wheel) image.screenshot- This will look for a screenshot image.titlescreen- This will look for a title screen image.cover- This will look for a box front cover image.backcover- This will look for a box back cover image.3dbox- This will look for a 3D box image.physicalmedia- This will look for a physical media image.fanart- This will look for a fan art image.
- This displays a game image of a certain media type, either before the video starts to play if
metadataElement- type: BOOLEAN- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the Hide metadata fields setting for a game entry. Using this property it's possible to explicitly define static video elements that should be treated as if they were game media files. This property is ignored if
pathis not set. - Default is
false
- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the Hide metadata fields setting for a game entry. Using this property it's possible to explicitly define static video elements that should be treated as if they were game media files. This property is ignored if
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
nameattribute value of the gameselector element.
- 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
gameselectorEntry- type: UNSIGNED_INTEGER- This optional property which is only available in the
systemview makes it possible to select whichgameselectorentry to use to populate theimageTypeproperty and to use for playing the video stream. This assumes that agameCountproperty for the gameselector element has been defined with a value higher than1. By defining multiplevideoelements with different values for thegameselectorEntryproperty it's possible to display multiple game entries at the same time, for example listing a couple of games that were last played, or a selection of random games. If the requested entry does not exist (for instance ifgameCounthas been set to 5 andgameselectorEntryhas been set to4but the system only contains 3 games), then the overall element will not get rendered. Note that the first entry is defined as0, the second entry as1etc. - Minimum value is
0and maximum value is the value of thegameselectorelement propertygameCountminus 1. If a value outside this range is defined, then it will be automatically clamped to a valid value. - Default is
0
- This optional property which is only available in the
iterationCount- type: UNSIGNED_INTEGER- Number of times to play the video until next time it's reset. Video resets are triggered by various events like navigation between systems and gamelists, reloading of gamelists, opening of menus etc.
- Minimum value is
0and maximum value is10 - Default is
0(infinite amount of times)
onIterationsDone- type: STRING- What to do after playing the video the number of times defined by
iterationCount nothing- Render nothing.image- Render the image defined byimageTypeordefaultImagewhich means this value can't be used ifpathhas been set- Default is
nothing - This property can only be used when
iterationCounthas a non-zero value.
- What to do after playing the video the number of times defined by
audio- type: BOOLEAN- Whether to enable or disable audio playback for the video. For static videos in the gamelist view it's strongly recommended to set this to
falseif there is also a separate video element playing game videos. - Default is
true
- Whether to enable or disable audio playback for the video. For static videos in the gamelist view it's strongly recommended to set this to
interpolation- type: STRING- Interpolation method to use when scaling and rotating static images and videos. Nearest neighbor (
nearest) preserves sharp pixels and linear filtering (linear) makes the image and video smoother. - Valid values are
nearestorlinear - Default is
nearestifrotationis0,90,180or270degrees, otherwise it'slinear
- Interpolation method to use when scaling and rotating static images and videos. Nearest neighbor (
imageCornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the static image. The radius is a percentage of the screen width and not directly related to the image size. This makes it possible to apply identically sized corners regardless of image dimensions. 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 width or height. It means that setting this property sufficiently high will turn a perfectly square image into a perfectly round one.
- Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
videoCornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the video stream. The radius is a percentage of the screen width and not directly related to the video size. This makes it possible to apply identically sized corners regardless of video dimensions. 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 width or height. You probably want to disable
pillarboxesif using this property. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
- Setting this property higher than zero applies rounded corners to the video stream. The radius is a percentage of the screen width and not directly related to the video size. This makes it possible to apply identically sized corners regardless of video dimensions. 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 width or height. You probably want to disable
color- type: COLOR- Applies a color shift to both the static image and video by multiplying each pixel's color by this color value. For example, an all-white image or video with
FF0000applied would become completely red. It's however not recommended to use this property to control opacity as this will not look right for actual videos, instead use theopacityproperty if you want to render this element as semi-transparent. Thecolorproperty is applied aftersaturationso by setting that property to0it's possible to colorize rather than color shift. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to both the static image and video by multiplying each pixel's color by this color value. For example, an all-white image or video with
colorEnd- type: COLOR- Works in the exact same way as
colorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
color
- Works in the exact same way as
gradientType- type: STRING- The direction to apply the color shift gradient if both
colorandcolorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color shift gradient if both
pillarboxes- type: BOOLEAN- Whether to render black pillarboxes (and to a lesses extent letterboxes) for videos with aspect ratios where this is applicable. This is for instance useful for arcade game videos in vertical orientation.
- Default is
true
pillarboxThreshold- type: NORMALIZED_PAIR- Normally it doesn't look very good to add really narrow pillarboxes or letterboxes, so by default they are skipped if the actual video size is not reaching a threshold value as compared to the overall defined video area size. By modifying this property it's possible to control that threshold, as for some theme designs it will look better with the consistency of always rendering the pillarboxes/letterboxes even if they are narrow. To clarify, the default X axis value of 0.85 means that if the video width is 85% or less as compared to the X axis defined by the
sizeproperty, then pillarboxes will be rendered. So setting thepillarboxThresholdvalue to1 1will always apply pillarboxes/letterboxes regardless of the video file dimension. - Minimum value per axis is
0.2and maximum value per axis is1 - Default is
0.85 0.90
- Normally it doesn't look very good to add really narrow pillarboxes or letterboxes, so by default they are skipped if the actual video size is not reaching a threshold value as compared to the overall defined video area size. By modifying this property it's possible to control that threshold, as for some theme designs it will look better with the consistency of always rendering the pillarboxes/letterboxes even if they are narrow. To clarify, the default X axis value of 0.85 means that if the video width is 85% or less as compared to the X axis defined by the
scanlines- type: BOOLEAN- Whether to use a shader to render scanlines. Can't be combined with the
cropSizeproperty. - Default is
false
- Whether to use a shader to render scanlines. Can't be combined with the
delay- type: FLOAT- Delay in seconds before video will start playing. During the delay period the game image defined via the
imageTypeproperty will be displayed. If that property is not set, then thedelayproperty will be ignored. - Minimum value is
0and maximum value is15 - Default is
1.5
- Delay in seconds before video will start playing. During the delay period the game image defined via the
fadeInTime- type: FLOAT- Time in seconds to fade in the video from pure black. This is completely unrelated to the
scrollFadeInproperty. Note that if this is set to zero it may seem as if the property doesn't work correctly as many ScreenScraper videos have a fade-in baked into the actual video stream. Setting this property to lower than 0.3 seconds or so is generally a bad idea for videos that don't have a fade-in baked in as transitions from the static image will then look like a bad jump cut. - Minimum value is
0and maximum value is8 - Default is
1
- Time in seconds to fade in the video from pure black. This is completely unrelated to the
scrollFadeIn- type: BOOLEAN- If enabled, a short fade-in animation will be applied when scrolling through games in the gamelist view.
- Default is
false
brightness- type: FLOAT- Controls the relative level of brightness. This affects both the static image and the video stream. This is intended primarily for fine adjustments, for example if a color shift has been applied which may have lowered the overall brightness of the image/video.
- Minimum value is
-2and maximum value is2 - Default is
0(no brightness adjustments applied)
opacity- type: FLOAT- Controls the level of transparency. This affects both the static image and the video stream. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. This affects both the static image and the video stream. If set to
saturation- type: FLOAT- Controls the level of color saturation. This affects both the static image and the video stream.
- Minimum value is
0(grayscale) and maximum value is1(original file saturation). - Default is
1
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
30
animation
GIF and Lottie (vector graphics) animations. The animation type is automatically selected based on the file extension with .gif for GIF animations and .json for Lottie animations. Note that Lottie animations take a lot of memory and CPU resources if scaled up to large sizes so it's adviced to not add too many of these to the same view and to not make them too large. GIF animations on the other hand are not as demanding except if they're really long and/or of high resolution.
Also be aware that the rlottie library used by ES-DE is not compatible with all Lottie animations out there so you may need to convert them to a format that rlottie can read, or use some other animations altogether.
Supported views:
systemgamelist
Instances per view:
unlimited
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- If only one axis is specified (and the other is zero), then the other will be automatically calculated in accordance with the animation's aspect ratio. Note that this is sometimes not entirely accurate as some animations contain invalid size information. Setting both axes to 0 is an error and the size will be clamped to
0.01 0.01in this case. This property takes precedence overmaxSizeif both properties are defined. - Minimum value per axis is
0.01and maximum value per axis is1. If specifying a value outside the allowed range then no attempt will be made to preserve the aspect ratio.
- If only one axis is specified (and the other is zero), then the other will be automatically calculated in accordance with the animation's aspect ratio. Note that this is sometimes not entirely accurate as some animations contain invalid size information. Setting both axes to 0 is an error and the size will be clamped to
maxSize- type: NORMALIZED_PAIR- The animation will be resized as large as possible so that it fits within this size while maintaining its aspect ratio. Note that this is sometimes not entirely accurate as some animations contain invalid size information.
- Minimum value per axis is
0.01and maximum value per axis is1
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the animation should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is
0
rotationOrigin- type: NORMALIZED_PAIR- Point around which the animation will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.always- Set element as stationary during all transitions.never- Don't set element as stationary during any transitions.- Default is
never
metadataElement- type: BOOLEAN- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the Hide metadata fields setting for a game entry. Using this property it's possible to explicitly define animation elements that should be treated as if they were game media files. This is for example useful for hiding and fading out animations that are used as indicators for the various metadata types like genre, publisher, players etc.
- Default is
false
path- type: PATH- Path to the animation file. Only .gif and .json extensions are supported.
speed- type: FLOAT.- The relative speed at which to play the animation.
- Minimum value is
0.2and maximum value is3 - Default is
1
direction- type: STRING- The direction that the animation should be played.
- Valid values are
normal(forwards),reverse(backwards),alternate(bouncing forwards/backwards) andalternateReverse(bouncing backwards/forwards, i.e. starting with playing backwards). - Default is
normal
iterationCount- type: UNSIGNED_INTEGER- Number of times to play the animation until next time it's reset. Animation resets are triggered by various events like navigation between systems and gamelists, reloading of gamelists, opening of menus etc.
- Minimum value is
0and maximum value is10 - Default is
0(infinite amount of times)
interpolation- type: STRING- Interpolation method to use when scaling and rotating animations. Nearest neighbor (
nearest) preserves sharp pixels and linear filtering (linear) makes the animation smoother. This property has limited effect on Lottie animations unless rotation is applied. - Valid values are
nearestorlinear - Default is
nearestifrotationis0,90,180or270degrees, otherwise it'slinear
- Interpolation method to use when scaling and rotating animations. Nearest neighbor (
cornerRadius- type: FLOAT- Setting this property higher than zero applies rounded corners to the animation. The radius is a percentage of the screen width and not directly related to the animation size. This makes it possible to apply identically sized corners regardless of animation dimensions. 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 width or height.
- Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded)
color- type: COLOR- Applies a color shift to the animation by multiplying each pixel's color by this color value. For example, an all-white animation with
FF0000applied would become completely red. You can also control the transparency of the animation by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. This property is applied aftersaturationso by setting that property to0it's possible to colorize rather than color shift. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to the animation by multiplying each pixel's color by this color value. For example, an all-white animation with
colorEnd- type: COLOR- Works in the exact same way as
colorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
color
- Works in the exact same way as
gradientType- type: STRING- The direction to apply the color shift gradient if both
colorandcolorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color shift gradient if both
brightness- type: FLOAT- Controls the relative level of brightness. This is intended primarily for fine adjustments.
- Minimum value is
-2and maximum value is2 - Default is
0(no brightness adjustments applied)
opacity- type: FLOAT- Controls the level of transparency. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. If set to
saturation- type: FLOAT- Controls the level of color saturation.
- Minimum value is
0(grayscale) and maximum value is1(original file saturation). - Default is
1
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
35
badges
Displays graphical symbols representing a number of metadata fields for the currently selected game. It's strongly recommended to use the same image dimensions for all badges as varying aspect ratios will lead to alignment issues. For the controller images it's recommended to keep to the square canvas size used by the default bundled graphics as otherwise sizing and placement will be inconsistent (unless all controller graphic files are customized of course).
Supported views:
gamelist
Instances per view:
unlimited
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- Possible combinations:
w h- Dimensions of the badges container. The badges will be scaled to fit within these dimensions.- Minimum value per axis is
0.03and maximum value per axis is1 - Default is
0.15 0.20
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the badges should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is
0
rotationOrigin- type: NORMALIZED_PAIR- Point around which the image will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5.
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.always- Set element as stationary during all transitions.never- Don't set element as stationary during any transitions.- Default is
never
horizontalAlignment- type: STRING.- Valid values are
left,centerorright
- Valid values are
direction- type: STRING- Controls the primary layout direction (line axis) for the badges. Lines will fill up in the specified direction.
- Valid values are
roworcolumn - Default is
row
lines- type: UNSIGNED_INTEGER- The number of lines available.
- Default is
3
itemsPerLine- type: UNSIGNED_INTEGER- Number of badges that fit on a line. When more badges are available a new line will be started.
- Default is
4
itemMargin- type: NORMALIZED_PAIR- The horizontal and vertical margins between badges. If one of the axis is set to
-1then the margin of the other axis (in pixels) will be used, which makes it possible to get identical spacing between all items regardless of the screen aspect ratio. - Minimum value per axis is
0and maximum value per axis is0.2 - Default is
0.01 0.01.
- The horizontal and vertical margins between badges. If one of the axis is set to
slots- type: STRING- The badge types that should be displayed. Specified as a list of strings delimited by commas or by whitespace characters (tabs, spaces or line breaks). The order in which they are defined will be followed when placing badges on screen. Available badges are:
collection- Will be shown when editing a custom collection and the current entry is part of that collection.folder- Will be shown when the current entry is a folder. If a folder link has been setup, then a configurable link icon will overlay this badge.favorite- Will be shown when the game is marked as favorite.completed- Will be shown when the game is marked as completed.kidgame- Will be shown when the game is marked as a kids game.broken- Will be shown when the game is marked as broken.controller- Will be shown and overlaid by the corresponding controller icon if a controller type has been selected for the game (using the metadata editor or via scraping).altemulator- Will be shown when an alternative emulator is setup for the game.manual- Will be shown when a PDF manual has been downloaded for the game.all- Including this value will enable all badges. If some badges have been added already they will be shown in the order they were defined and the remaining ones will be added at the end, in the order listed above. Using theallvalue can be used as a way to future-proof the theme, because if additional badges are added in future ES-DE releases, no theme updates would be needed to accomodate them. Just make sure to include space for a few extra badges in the layout, and increase thelinesanditemsPerLineaccordingly.
controllerPos- type: NORMALIZED_PAIR- The position of the controller icon relative to the parent
controllerbadge. - Minimum value per axis is
-1and maximum value per axis is2 - Default is
0.5 0.5which centers the controller icon on the badge.
- The position of the controller icon relative to the parent
controllerSize- type: FLOAT- The size of the controller icon relative to the parent
controllerbadge. - Setting the value to
1sizes the icon to the same width as the parent badge. The image aspect ratio is always maintained. - Minimum value is
0.1and maximum value is2 - Default is
0.5
- The size of the controller icon relative to the parent
customBadgeIcon- type: PATH- A badge icon override. Specify the badge type in the attribute
badge. The available badges are the ones listed above.
- A badge icon override. Specify the badge type in the attribute
customControllerIcon- type: PATH- A controller icon override. Specify the controller type in the attribute
controller. - These are the available types:
gamepad_generic,gamepad_nintendo_nes,gamepad_nintendo_snes,gamepad_nintendo_64,gamepad_nintendo_gamecube,gamepad_playstation,gamepad_sega_master_system,gamepad_sega_md_3_buttons,gamepad_sega_md_6_buttons,gamepad_sega_dreamcast,gamepad_xbox,joystick_generic,joystick_arcade_no_buttons,joystick_arcade_no_buttons_twin,joystick_arcade_1_button,joystick_arcade_2_buttons,joystick_arcade_3_buttons,joystick_arcade_4_buttons,joystick_arcade_5_buttons,joystick_arcade_6_buttons,keyboard_generic,keyboard_and_mouse_generic,mouse_generic,mouse_amiga,lightgun_generic,lightgun_nintendo,steering_wheel_generic,flight_stick_generic,spinner_generic,trackball_generic,wii_remote_nintendo,wii_remote_and_nunchuk_nintendo,joycon_left_or_right_nintendo,joycon_pair_nintendo,xbox_kinect,unknown
- A controller icon override. Specify the controller type in the attribute
folderLinkPos- type: NORMALIZED_PAIR- The position of the folder link icon relative to the parent
folderbadge. - Minimum value per axis is
-1and maximum value per axis is2 - Default is
0.5 0.5which centers the folder link icon on the badge.
- The position of the folder link icon relative to the parent
folderLinkSize- type: FLOAT- The size of the folder link icon relative to the parent
folderbadge. - Setting the value to
1sizes the icon to the same width as the parent badge. The image aspect ratio is always maintained. - Minimum value is
0.1and maximum value is1 - Default is
0.5
- The size of the folder link icon relative to the parent
customFolderLinkIcon- type: PATH- Folder link icon override.
badgeIconColor- type: COLOR- Applies a color shift to the badge icon by multiplying each pixel's color by this color value. For example, an all-white image with
FF0000applied would become completely red. You can also control the transparency of the image by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to the badge icon by multiplying each pixel's color by this color value. For example, an all-white image with
badgeIconColorEnd- type: COLOR- Works in the exact same way as
badgeIconColorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
badgeIconColor
- Works in the exact same way as
badgeIconGradientType- type: STRING- The direction to apply the color shift gradient if both
badgeIconColorandbadgeIconColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color shift gradient if both
controllerIconColor- type: COLOR- Applies a color shift to the controller icon by multiplying each pixel's color by this color value. For example, an all-white image with
FF0000applied would become completely red. You can also control the transparency of the image by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to the controller icon by multiplying each pixel's color by this color value. For example, an all-white image with
controllerIconColorEnd- type: COLOR- Works in the exact same way as
controllerIconColorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
controllerIconColor
- Works in the exact same way as
controllerIconGradientType- type: STRING- The direction to apply the color shift gradient if both
controllerIconColorandcontrollerIconColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color shift gradient if both
folderLinkIconColor- type: COLOR- Applies a color shift to the folder link icon by multiplying each pixel's color by this color value. For example, an all-white image with
FF0000applied would become completely red. You can also control the transparency of the image by setting the value to for exampleFFFFFFAA. This keeps all pixels at their normal color and only affects the alpha channel. - Default is
FFFFFFFF(no color shift applied)
- Applies a color shift to the folder link icon by multiplying each pixel's color by this color value. For example, an all-white image with
folderLinkIconColorEnd- type: COLOR- Works in the exact same way as
folderLinkIconColorbut can be set as the end color to apply a color shift gradient. - Default is the same value as
folderLinkIconColor
- Works in the exact same way as
folderLinkIconGradientType- type: STRING- The direction to apply the color shift gradient if both
folderLinkIconColorandfolderLinkIconColorEndhave been defined. - Valid values are
horizontalorvertical - Default is
horizontal
- The direction to apply the color shift gradient if both
interpolation- type: STRING- Interpolation method to use when scaling and rotating badge images. Nearest neighbor (
nearest) preserves sharp pixels and linear filtering (linear) makes the image smoother. This property has limited effect on scalable vector graphics (SVG) images unless rotation is applied. - Valid values are
nearestorlinear - Default is
nearestifrotationis0,90,180or270degrees, otherwise it'slinear
- Interpolation method to use when scaling and rotating badge images. Nearest neighbor (
opacity- type: FLOAT- Controls the level of transparency. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. If set to
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
35
text
Displays text. This can be literal strings or values based on game metadata or system variables, as described below. It's also possible to place text inside a scrollable container which is for example useful for longer texts like game and system descriptions.
Supported views:
systemgamelist
Instances per view:
unlimited
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- Possible combinations:
0 0- automatically size so text fits on one line (expanding horizontally).w 0- automatically wrap text so it doesn't go beyondw(expanding vertically).w h- works like a "text box". Ifhis non-zero andh<=fontSize(implying it should be a single line of text), text that goes beyondwwill be truncated with an ellipsis (...)
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Rotation is not possible if the
containerproperty has been set to true. - Default is
0
- Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Rotation is not possible if the
rotationOrigin- type: NORMALIZED_PAIR- Point around which the text will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.always- Set element as stationary during all transitions.never- Don't set element as stationary during any transitions.- Default is
never
text- type: STRING- A string literal to display.
systemdata- type: STRING- This translates to some system data including values defined in es_systems.xml as well as some statistics.
- This property can only be used in the
systemview and you can only define a single value per element. - Valid values:
name- Short system name as defined in es_systems.xml.fullname- Full system name as defined in es_systems.xml.gamecount- Number of games available for the system. Number of favorites is printed inside brackets if applicable.gamecountGames- Number of games available for the system. Does not include the favorites count.gamecountGamesNoText- Same as the above but with the text game or games omitted, i.e. only the number is shown.gamecountFavorites- Number of favorite games for the system, may be blank if favorites is not applicable.gamecountFavoritesNoText- Same as the above but with the text favorite or favorites omitted, i.e. only the number is shown.
metadata- type: STRING- This translates to the metadata values that are available for the game. To use this property from the
systemview, you will first need to add agameselectorelement. You can only define a single metadata value per text element. - Valid values:
name- Game name.description- Game description. Should be combined with thecontainerproperty in most cases.rating- The numerical representation of the game rating, for example3or4.5developer- Developer.publisher- Publisher.genre- Genre.players- The number of players.favorite- Whether the game is a favorite. Will be printed as eitheryesornocompleted- Whether the game has been completed. Will be printed as eitheryesornokidgame- Whether the game is suitable for children. Will be printed as eitheryesornobroken- Whether the game is broken/not working. Will be printed as eitheryesornomanual- Whether a PDF manual has been downloaded for the game. Will be printed as eitheryesornoplaycount- How many times the game has been played.controller- The controller for the game. Will be blank if none has been selected.altemulator- The alternative emulator for the game. Will be blank if none has been selected.emulator- The emulator used to launch the game, could as such be a per-game alternative emulator entry, a system wide alternative emulator entry or the system's default emulator. This requires that the command tag in es_systems.xml has a label defined, otherwise this value will be blank. Folders will always have blank values as these can't be launched directly.physicalName- The physical name of the game file or folder, excluding its extension. Note that for folders with dots in their names any text after the last dot will get removed. Although this is not technically correct as folders can't have extensions, it makes the name appear consistent if the directories interpreted as files functionality has been used.physicalNameExtension- The physical name of the game file or folder, including its extension.systemName- The short system name of the game.systemFullname- The full system name of the game.sourceSystemName- The source short system name of the game. For regular systems this value will be identical tosystemNamebut 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 tosystemFullnamebut for collections it will show the actual system that the game is located in instead of the collection system name.
- This translates to the metadata values that are available for the game. To use this property from the
defaultValue- type: STRING- This property makes it possible to override the default "unknown" text that is displayed if
metadatahas been set todeveloper,publisher,genreorplayersand 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 ifmetadatahas been set tosystemName,systemFullname,sourceSystemNameorsourceSystemFullnamein 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.
- This property makes it possible to override the default "unknown" text that is displayed if
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
metadatahas been set todescriptionthen 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 - This property can only be used when
metadatahas been set tonameordescription
- 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
letterCaseSystemNameSuffix- type: STRING- Sets the letter case for the system name suffix.
- Valid values are
uppercase,lowercaseorcapitalize - Default is
uppercase - This property can only be used when
systemNameSuffixistrue, and ifmetadatahas been set todescriptionthen it only applies ifletterCaseis also set tonone
metadataElement- type: BOOLEAN- By default game metadata and media are faded out during gamelist fast-scrolling. They are also hidden when enabling the Hide metadata fields setting in the metadata editor. This includes the text metadata fields (except
systemName,systemFullname,sourceSystemNameandsourceSystemFullname), ratings and badges. Using this property it's possible to explicitly define additional text elements that should be treated as if they were game metadata entries. This is for example useful for hiding and fading out text labels or icons for the various metadata types like genre, publisher, players etc. Note that it's not possible to disable the metadata hiding functionality for the default metadata fields as that would break basic application behavior. Also note that there is a slight exception to the hiding logic for text containers with the metadata value set todescription. In this case the element is by default not hidden when enabling the Hide metadata fields setting. To also hide such containers, set this property to true. - Default is
false
- By default game metadata and media are faded out during gamelist fast-scrolling. They are also hidden when enabling the Hide metadata fields setting in the metadata editor. This includes the text metadata fields (except
gameselector- type: STRING- If more than one gameselector element has been defined, then 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
nameattribute value of the gameselector element. - This property can only be used in the
systemview and only whenmetadatahas a value.
- If more than one gameselector element has been defined, then 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
gameselectorEntry- type: UNSIGNED_INTEGER- This optional property which is only available in the
systemview makes it possible to select whichgameselectorentry to use to populate themetadataproperty. This assumes that agameCountproperty for the gameselector element has been defined with a value higher than1. By defining multipletextelements with different values for thegameselectorEntryproperty it's possible to display multiple game entries at the same time, for example listing a couple of games that were last played, or a selection of random games. If the requested entry does not exist (for instance ifgameCounthas been set to 5 andgameselectorEntryhas been set to4but the system only contains 3 games), then the overall element will not get rendered. Note that the first entry is defined as0, the second entry as1etc. - Minimum value is
0and maximum value is the value of thegameselectorelement propertygameCountminus 1. If a value outside this range is defined, then it will be automatically clamped to a valid value. - Default is
0
- This optional property which is only available in the
container- type: BOOLEAN- Whether the text should be placed inside a scrollable container.
- Default is
trueifmetadatais set todescription, otherwisefalse - This property can only be used if
sizehas a width defined.
containerType- type: STRING- If
containerhas 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 forrotationwill be ignored as this container type can't be rotated. - Valid values are
verticalorhorizontal - Default is
vertical - This property can only be used when
containerhas been explicitly set totrue
- If
containerVerticalSnap- type: BOOLEAN- Whether the text should be vertically snapped to the font height. With this property enabled the container will have its height reduced as needed so that only complete rows of text are displayed at the start and end positions. This will not affect the "real" size of the container as set by the
sizeproperty which means that the overall element placement will still be predictable if a vertical origin other than zero is used. - Default is
true - This property can only be used when
containerTypeisvertical
- Whether the text should be vertically snapped to the font height. With this property enabled the container will have its height reduced as needed so that only complete rows of text are displayed at the start and end positions. This will not affect the "real" size of the container as set by the
containerScrollSpeed- type: FLOAT- For vertical containers a base speed is automatically calculated based on the container and font sizes, so this property applies relative to the auto-calculated value for that type.
- Minimum value is
0.1and maximum value is10 - Default is
1
containerStartDelay- type: FLOAT- Delay in seconds before scrolling starts. Note that for vertical containers the text fade-in animation that plays when resetting from the end position will cause a slight delay even if this property is set to zero.
- Minimum value is
0and maximum value is10 - Default is
4.5for vertical containers and1.5for horizontal containers
containerResetDelay- type: FLOAT- Delay in seconds before resetting to the start position after reaching the scrolling end position.
- Minimum value is
0and maximum value is20 - Default is
7 - This property can only be used when
containerTypeisvertical
containerScrollGap- type: FLOAT- As horizontally scrolling text is looped, a second copy is rendered after the first one. This property defines a relative gap value to control the distance between these two text instances.
- Minimum value is
0.1and maximum value is5 - Default is
1.5 - This property can only be used when
containerTypeishorizontal
fontPath- type: PATH- Path to a TrueType font (.ttf).
fontSize- type: FLOAT- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
0.1, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. - Minimum value is
0.001and maximum value is1.5. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e.fontSizecan be set to twice that of the y axis of thesizeproperty. Any value above that will be clamped. - Default is
0.045
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
horizontalAlignment- type: STRING- Controls alignment on the X axis.
- Valid values are
left,centerorright - Default is
left
verticalAlignment- type: STRING- Controls alignment on the Y axis.
- Valid values are
top,centerorbottom - Default is
center - This property can only be used if
containerisfalse
color- type: COLOR- Default is
000000FF
- Default is
backgroundColor- type: COLOR- Default is
00000000
- Default is
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
0and maximum value per axis is0.5 - Default is
0 0 - This property can only be used if
backgroundColorhas 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
backgroundMarginsto add some extra margins. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded) - This property can only be used if
backgroundColorhas a value defined.
- 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
letterCase- type: STRING- Valid values are
none,uppercase,lowercaseorcapitalize - Default is
none(original letter case is retained)
- Valid values are
lineSpacing- type: FLOAT- Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around
1.1or higher for multi-line text fields. This way overlapping glyphs or characters being cut off at the top or bottom will be prevented. - Minimum value is
0.5and maximum value is3 - Default is
1.5
- Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around
opacity- type: FLOAT- Controls the level of transparency. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. If set to
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
40
datetime
Displays a date and time as a text string. The format is ISO 8601 (YYYY-MM-DD) by default, but this can be changed using the format property. The text unknown will be shown by default if there is no time stamp available. If the property displayRelative has been set, the text will be shown as never in case of no time stamp.
Supported views:
systemgamelist
Instances per view:
unlimited
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- Possible combinations:
0 0- automatically size so text fits on one line (expanding horizontally).w 0- automatically wrap text so it doesn't go beyondw(expanding vertically).w h- works like a "text box". Ifhis non-zero andh<=fontSize(implying it should be a single line of text), text that goes beyondwwill be truncated with an ellipsis (...)
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is
0
rotationOrigin- type: NORMALIZED_PAIR- Point around which the text will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5.
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.always- Set element as stationary during all transitions.never- Don't set element as stationary during any transitions.- Default is
never
metadata- type: STRING- This displays the metadata values that are available for the game. If an invalid metadata field is defined, the text "unknown" or "never" will be printed. To use this property from the
systemview, you will first need to add agameselectorelement. You can only define a single metadata value per datetime element. - Valid values:
releasedate- The release date of the game.lastplayed- The time the game was last played. This will be displayed as a value relative to the current date and time by default, but can be overridden using thedisplayRelativeproperty.
- This displays the metadata values that are available for the game. If an invalid metadata field is defined, the text "unknown" or "never" will be printed. To use this property from the
defaultValue- type: STRING- This property makes it possible to override the default "unknown" text that is displayed if
metadatahas been set toreleasedateor the default "never" text that is displayed ifmetadatahas been set tolastplayed. 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 undefined release date values.
- This property makes it possible to override the default "unknown" text that is displayed if
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
nameattribute value of the gameselector element. This property is only needed for thesystemview and only if themetadataproperty is utilized.
- 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
gameselectorEntry- type: UNSIGNED_INTEGER- This optional property which is only available in the
systemview makes it possible to select whichgameselectorentry to use to populate themetadataproperty. This assumes that agameCountproperty for the gameselector element has been defined with a value higher than1. By defining multipledatetimeelements with different values for thegameselectorEntryproperty it's possible to display multiple game entries at the same time, for example listing a couple of games that were last played, or a selection of random games. If the requested entry does not exist (for instance ifgameCounthas been set to 5 andgameselectorEntryhas been set to4but the system only contains 3 games), then the overall element will not get rendered. Note that the first entry is defined as0, the second entry as1etc. - Minimum value is
0and maximum value is the value of thegameselectorelement propertygameCountminus 1. If a value outside this range is defined, then it will be automatically clamped to a valid value. - Default is
0
- This optional property which is only available in the
fontPath- type: PATH- Path to a TrueType font (.ttf).
fontSize- type: FLOAT- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
0.1, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. - Minimum value is
0.001and maximum value is1.5. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e.fontSizecan be set to twice that of the y axis of thesizeproperty. Any value above that will be clamped. - Default is
0.045
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
horizontalAlignment- type: STRING- Controls alignment on the X axis.
- Valid values are
left,centerorright - Default is
left
verticalAlignment- type: STRING- Controls alignment on the Y axis.
- Valid values are
top,centerorbottom - Default is
center
color- type: COLORbackgroundColor- type: COLORbackgroundMargins- 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
0and maximum value per axis is0.5 - Default is
0 0 - This property can only be used if
backgroundColorhas 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
backgroundMarginsto add some extra margins. - Minimum value is
0and maximum value is0.5 - Default is
0(corners are not rounded) - This property can only be used if
backgroundColorhas a value defined.
- 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
letterCase- type: STRING- Valid values are
none,uppercase,lowercaseorcapitalize - Default is
none(original letter case is retained)
- Valid values are
lineSpacing- type: FLOAT- Controls the space between lines (as a multiple of font height).
- Minimum value is
0.5and maximum value is3 - Default is
1.5
format- type: STRING- Specifies the date and time format. Has no effect if
displayRelativehas been set to true. - %Y: The year, including the century (1900)
- %m: The month number [01,12]
- %d: The day of the month [01,31]
- %H: The hour (24-hour clock) [00,23]
- %M: The minute [00,59]
- %S: The second [00,59]
- Default is the ISO 8601 standard notation
%Y-%m-%d
- Specifies the date and time format. Has no effect if
displayRelative- type: BOOLEAN.- Renders the datetime as a relative string (e.g. 'x days ago').
- Default is
falseifmetadatahas been set toreleasedateandtrueifmetadatahas been set tolastplayed
opacity- type: FLOAT- Controls the level of transparency. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. If set to
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
40
gamelistinfo
Displays the game count (all games as well as favorites), any applied filters, and a folder icon if a folder has been entered. If this text is left aligned or center aligned, the folder icon will be placed to the right of the other information, and if it's right aligned, the folder icon will be placed to the left.
Supported views:
gamelist
Instances per view:
unlimited
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- Possible combinations:
0 0- automatically size so text fits on one line (expanding horizontally).w 0- automatically wrap text so it doesn't go beyondw(expanding vertically).w h- works like a "text box". Ifhis non-zero andh<=fontSize(implying it should be a single line of text), text that goes beyondwwill be truncated with an ellipsis (...)
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is
0
rotationOrigin- type: NORMALIZED_PAIR- Point around which the element will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.always- Set element as stationary during all transitions.never- Don't set element as stationary during any transitions.- Default is
never
fontPath- type: PATH- Path to a TrueType font (.ttf).
fontSize- type: FLOAT- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
0.1, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. - Minimum value is
0.001and maximum value is1.5. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e.fontSizecan be set to twice that of the y axis of thesizeproperty. Any value above that will be clamped. - Default is
0.045
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of
horizontalAlignment- type: STRING- Controls alignment on the X axis.
- Valid values are
left,centerorright - Default is
left
verticalAlignment- type: STRING- Controls alignment on the Y axis.
- Valid values are
top,centerorbottom - Default is
center
color- type: COLORbackgroundColor- type: COLORopacity- type: FLOAT- Controls the level of transparency. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. If set to
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
45
rating
Displays a graphical representation of the game rating, from 0 to 5.
To display game ratings in the system view, you first need to create a gameselector element.
Supported views:
systemgamelist
Instances per view:
unlimited
Properties:
pos- type: NORMALIZED_PAIRsize- type: NORMALIZED_PAIR- These values are mutually exclusive, if an X axis value is defined then the element will be sized based on this, and if an Y axis value is defined then the element will be sized based on that. If both the X and Y axis values are defined then the Y axis value will take precedence and the X axis value will be ignored. This makes sure that the image aspect ratio is always maintained.
- Minimum value per axis is
0.01and maximum value for the X axis is1and maximum value for the Y axis is0.5 - Default is
0 0.06
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
rotation- type: FLOAT- Angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is
0
rotationOrigin- type: NORMALIZED_PAIR- Point around which the rating will be rotated.
- Minimum value per axis is
0and maximum value per axis is1 - Default is
0.5 0.5
stationary- type: STRING- If using slide transitions, then this property can be set to keep the element stationary during transition animations. This property has no effect when using instant or fade transitions.
withinView- Set element as stationary when navigating within the same view, i.e. from system to system or from gamelist to gamelist.betweenViews- Set element as stationary when navigating between views, i.e. from system to gamelist or from gamelist to system.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
nameattribute value of the gameselector element. This property is only needed for thesystemview.
- 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
gameselectorEntry- type: UNSIGNED_INTEGER- This optional property which is only available in the
systemview makes it possible to select whichgameselectorentry to use to populate the rating value. This assumes that agameCountproperty for the gameselector element has been defined with a value higher than1. By defining multipleratingelements with different values for thegameselectorEntryproperty it's possible to display multiple game entries at the same time, for example listing a couple of games that were last played, or a selection of random games. If the requested entry does not exist (for instance ifgameCounthas been set to 5 andgameselectorEntryhas been set to4but the system only contains 3 games), then the overall element will not get rendered. Note that the first entry is defined as0, the second entry as1etc. - Minimum value is
0and maximum value is the value of thegameselectorelement propertygameCountminus 1. If a value outside this range is defined, then it will be automatically clamped to a valid value. - Default is
0
- This optional property which is only available in the
interpolation- type: STRING- Interpolation method to use when scaling and rotating rating images. Nearest neighbor (
nearest) preserves sharp pixels and linear filtering (linear) makes the image smoother. This property has limited effect on scalable vector graphics (SVG) images unless rotation is applied. - Valid values are
nearestorlinear - Default is
nearestifrotationis0,90,180or270degrees, otherwise it'slinear
- Interpolation method to use when scaling and rotating rating images. Nearest neighbor (
color- type: COLOR- Multiply each pixel's color by this color. For example, an all-white image with
<color>FF0000</color>would become completely red. You can also control the transparency of an image with<color>FFFFFFAA</color>- keeping all the pixels their normal color and only affecting the alpha channel. - Default is
FFFFFFFF
- Multiply each pixel's color by this color. For example, an all-white image with
filledPath- type: PATH- Path to the "filled" rating image. Any aspect ratio is supported. Note that there is no explicit padding property, so to add spaces between each icon simply make the image content smaller on the canvas. The images should always be centered on the canvas or otherwise the filledPath and unfilledPath textures will not align properly for all rating values. Most common file extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
unfilledPath- type: PATH- Path to the "unfilled" rating image. Any aspect ratio is supported. Note that there is no explicit padding property, so to add spaces between each icon simply make the image content smaller on the canvas. The images should always be centered on the canvas or otherwise the filledPath and unfilledPath textures will not align properly for all rating values. Most common file extensions are supported (including .svg, .jpg, .png, .webp and unanimated .gif).
overlay- type: BOOLEAN- Whether to overlay the filledPath image on top of the unfilledPath image. If this property is set to false, then the unfilledPath image will only be rendered to the right of the rating value cut position. This property is useful for avoiding image aliasing artifacts that could otherwise occur when combining some rating images. It can also help with avoiding some inconsistent fade-out animations.
- Default is
true
opacity- type: FLOAT- Controls the level of transparency. If set to
0the element will be disabled. - Minimum value is
0and maximum value is1 - Default is
1
- Controls the level of transparency. If set to
visible- type: BOOLEAN- If set to false, the element will be disabled. This is equivalent to setting
opacityto0 - Default is
true
- If set to false, the element will be disabled. This is equivalent to setting
zIndex- type: FLOAT- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is
45
Special elements
Elements from this group provide special functionality not covered by the primary and secondary elements.
gameselector
Selects games from the gamelists when navigating the system view. This makes it possible to display game media and game metadata directly from this view. It's possible to make separate gameselector configurations per game system, so that for instance a random game could be displayed for one system and the most recently played game could be displayed for another system. It's also possible to define multiple gameselector elements with different selection criterias per game system which makes it possible to for example set a random fan art background image and at the same time display a box cover image of the most recently played game. The gameselector logic can be used for the image, video, text, datetime and rating elements.
Note that any games that have the metadata option Exclude from game counter set will be excluded by the gameselector. Also note that setting gameCount to a high value may introduce significant lag into the application for large systems, so try to keep this as low as possible and make thorough performance testing with huge game libraries.
Supported views:
system
Instances per view:
unlimited
Properties:
selection- type: STRING- This defines the game selection criteria. If set to
random, the games are refreshed every time the view is navigated. For the other two values the refresh takes place on gamelist reload, i.e. when launching a game, adding a game as favorite, making changes via the metadata editor and so on. - Valid values are
random,lastplayedormostplayed - Default is
random
- This defines the game selection criteria. If set to
gameCount- type: UNSIGNED_INTEGER- Minimum value is
1and maximum value is30 - Default is
1
- Minimum value is
allowDuplicates- type: BOOLEAN- If set to true then the same game may appear multiple times, i.e. the amount of entries defined by
gameCountare always fully populated. This only applies to entries higher than the amount of available games for a system, for example if a system contains 3 games andgameCounthas been set to5, then the first three entries will not contain any duplicate entries, but the last two will. - Default is
false - This property can only be used when
selectionisrandom
- If set to true then the same game may appear multiple times, i.e. the amount of entries defined by
helpsystem
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.
Supported views:
systemgamelist
Instances per view:
single
Properties:
pos- type: NORMALIZED_PAIR- Default is
0.012 0.9515for horizontally oriented screens and0.012 0.975for vertically oriented screens
- Default is
posDimmed- type: NORMALIZED_PAIR- Position when a menu is open (background is dimmed).
- Default is the same value as
pos
origin- type: NORMALIZED_PAIR- Where on the element
posrefers to. For example, an origin of0.5 0.5and aposof0.5 0.5would place the element exactly in the middle of the screen. - Minimum value per axis is
0and maximum value per axis is1 - Default is
0 0
- Where on the element
originDimmed- type: NORMALIZED_PAIR- Origin when a menu is open (background is dimmed).
- Minimum value per axis is
0and maximum value per axis is1 - Default is the same value as
origin
textColor- type: COLOR- Default is
777777FF
- Default is
textColorDimmed- type: COLOR- Text color when a menu is open (background is dimmed).
- Default is the same value as
textColor
iconColor- type: COLOR- Default is
777777FF
- Default is
iconColorDimmed- type: COLOR- Icon color when a menu is open (background is dimmed).
- Default is the same value as
iconColor
fontPath- type: PATHfontSize- type: FLOAT- This property implicitly sets the icon size and is therefore the means to change the overall size of the helpsystem element. This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Minimum value is
0.001and maximum value is1.5. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. - Default is
0.035for horizontally oriented screens and0.025for vertically oriented screens
fontSizeDimmed- type: FLOAT- Font size when a menu is open (background is dimmed).
- Minimum value is
0.001and maximum value is1.5. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. - Default is the same value as
fontSize
entrySpacing- type: FLOAT- Spacing between the help element pairs.
- Minimum value is
0and maximum value is0.04 - Default is
0.00833
entrySpacingDimmed- type: FLOAT- Spacing between the help element pairs when a menu is open (background is dimmed).
- Minimum value is
0and maximum value is0.04 - Default is the same value as
entrySpacing
iconTextSpacing- type: FLOAT- Spacing between the icon and text within a help element pair.
- Minimum value is
0and maximum value is0.04 - Default is
0.00416
iconTextSpacingDimmed- type: FLOAT- Spacing between the icon and text within a help element pair when a menu is open (background is dimmed).
- Minimum value is
0and maximum value is0.04 - Default is the same value as
iconTextSpacing
letterCase- type: STRING- Valid values are
uppercase,lowercaseorcapitalize - Default is
uppercase
- Valid values are
opacity- type: FLOAT- Controls the level of transparency.
- Minimum value is
0.2and maximum value is1 - Default is
1
opacityDimmed- type: FLOAT- Controls the level of transparency when a menu is open (background is dimmed).
- Minimum value is
0.2and maximum value is1 - Default is the same value as
opacity
customButtonIcon- type: PATH- A button icon override. Specify the button type in the attribute
button. - The available buttons are:
dpad_updown,dpad_leftright,dpad_all,thumbstick_click,button_l,button_r,button_lr,button_lt,button_rt,button_ltrt,button_a_XBOX,button_b_XBOX,button_x_XBOX,button_y_XBOX,button_back_XBOX,button_start_XBOX,button_back_XBOX360,button_start_XBOX360,button_a_PS,button_b_PS,button_x_PS,button_y_PS,button_back_PS123,button_start_PS123,button_back_PS4,button_start_PS4,button_back_PS5,button_start_PS5,button_a_switch,button_b_switch,button_x_switch,button_y_switch,button_back_switch,button_start_switch,button_a_SNES,button_b_SNES,button_x_SNES,button_y_SNES,button_back_SNES,button_start_SNES
- A button icon override. Specify the button type in the attribute