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

Updated THEMES.md for the 1.2.0 release.

Browse source
This commit is contained in:
Leon Styhre 2021-12-28 17:22:22 +01:00
parent b09e85d75f
commit e5c6021ba8
1 changed files with 250 additions and 148 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

398
THEMES.md
View file

@ -1,143 +1,150 @@
# EmulationStation Desktop Edition (ES-DE) v1.1 - Themes # EmulationStation Desktop Edition (ES-DE) v1.2 - Themes
**Note:** If creating theme sets specifically for ES-DE, please add `-DE` to the theme name, as in `rbsimple-DE`. Because the ES-DE theme support has already deviated somehow from the RetroPie EmulationStation fork and will continue to deviate further in the future, the theme set will likely not be backwards compatible. It would be confusing and annoying for a user that downloads and attempts to use an ES-DE theme set in another EmulationStation fork only to get crashes, error messages or corrupted graphics. At least the -DE extension is a visual indicator that it's an ES-DE specific theme set. If creating theme sets specifically for ES-DE, please add `-DE` to the theme name, as in `rbsimple-DE`. Because the ES-DE theme support has already deviated somehow from the RetroPie EmulationStation fork and will continue to deviate further in the future, the theme set will likely not be backwards compatible. It would be confusing and annoying for a user that downloads and attempts to use an ES-DE theme set in another EmulationStation fork only to get crashes, error messages or corrupted graphics. At least the -DE extension is a visual indicator that it's an ES-DE specific theme set.
ES-DE allows each system to have its own "theme." A theme is a collection **views** that define some **elements**, each with their own **properties**. Table of contents:
The first place ES-DE will check for a theme is in the system's `<path>` folder, for a theme.xml file: [[_TOC_]]
* `[SYSTEM_PATH]/theme.xml`
If that file doesn't exist, ES-DE will try to find the theme in the current **theme set**. Theme sets are just a collection of individual system themes arranged in the "themes" folder under some name. A theme set can provide a default theme that will be used if there is no matching system theme. Here's an example: ## Introduction
ES-DE allows the grouping of themes for multiple game systems into a **theme set**. Each theme is a collection of **views** that define some **elements**, each with their own **properties**.
Every game system has its own subdirectory within the theme set directory structure, and these 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 set directory, that file will be processed as a default if there is no game-specific theme.xml file available.
In the example below, we have a theme set named `mythemeset-DE` which includes the `snes` and `nes` systems. Assuming you have some games installed for these systems, the files `mythemeset-DE/nes/theme.xml` and `mythemeset-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 of our example theme set could look something like the following:
``` ```
... ...
themes/ themes/
my_theme_set/ mythemeset-DE/
snes/ core/
theme.xml font.ttf
my_cool_background.jpg bold_font.ttf
frame.png
nes/ nes/
theme.xml theme.xml
my_other_super_cool_background.jpg background.jpg
logo.svg
logo_video.svg
common_resources/
my_font.ttf
theme.xml (Default theme)
another_theme_set/
snes/ snes/
theme.xml theme.xml
some_resource.svg background.jpg
logo.svg
logo_video.svg
fonts.xml
theme.xml
``` ```
The theme set system makes it easy for users to try different themes and allows distributions to include multiple theme options. Users can change the currently active theme set in the "UI Settings" menu. The option is only visible if at least one theme set exists. The theme set approach makes it easy for users to install different themes and choose between them from the _UI Settings_ menu.
There are two places ES-DE can load theme sets from: There are two places that ES-DE can load theme sets from:
* `[HOME]/.emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` * `[HOME]/.emulationstation/themes/[THEME_SET]/`
* `[INSTALLATION PATH]/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` * `[INSTALLATION PATH]/themes/[THEME_SET]/`
An example installation path would be: \ An example installation path would be: \
`/usr/share/emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` `/usr/share/emulationstation/themes/rbsimple-DE/`
`[SYSTEM_THEME]` is the `<theme>` tag for the system, as defined in `es_systems.xml`. If the `<theme>` tag is not set, ES-DE will use the system's `<name>`. If a theme set with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped.
If both files happen to exist, ES-DE will pick the first one (the one located in the home directory). ## Simple example
Again, the `[CURRENT_THEME_SET]` value is set in the "UI Settings" menu. If it has not been set yet or the previously selected theme set is missing, the first available theme set will be used as the default. Here is a very simple theme that changes the color of the game description text:
# Simple Example
Here is a very simple theme that changes the description text's color:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
<color>00FF00</color> <color>00FF00</color>
</text> </text>
<image name="my_image" extra="true"> <image name="frame" extra="true">
<pos>0.5 0.5</pos> <pos>0.5 0.5</pos>
<origin>0.5 0.5</origin> <origin>0.5 0.5</origin>
<size>0.8 0.8</size> <size>0.8 0.8</size>
<path>./my_art/my_awesome_image.jpg</path> <path>./core/frame.png</path>
</image> </image>
</view> </view>
</theme> </theme>
``` ```
# How it works ## How it works
Everything must be inside a `<theme>` tag. All configuration must be contained within a `<theme>` tag pair.
**The `<formatVersion>` tag *must* be specified**. This is the version of the theming system the theme was designed for. The `<formatVersion>` tag **must** be specified. This is the version of the theming system the theme was designed for.
The current version is 6. The current version is 7.
A *view* can be thought of as a particular "screen" within ES-DE. Views are defined like this: A _view_ can be thought of as a particular "screen" within ES-DE. Views are defined like this:
```xml ```xml
<view name="ViewNameHere"> <view name="ViewNameHere">
... define elements here ... ... define elements here ...
</view> </view>
``` ```
An *element* is a particular visual element, such as an image or a piece of text. You can either modify an element that already exists for a particular view (as is done in the "description" example), like this: An *element* is a particular visual element, such as an image or a piece of text. You can modify an element that already exists for a particular view, as was done for the "description" example:
```xml ```xml
<elementTypeHere name="ExistingElementNameHere"> <elementTypeHere name="ExistingElementNameHere">
... define properties here ... ... define properties here ...
</elementTypeHere> </elementTypeHere>
``` ```
Or, you can create your own elements by adding `extra="true"` (as is done in the "my_image" example) like this: Or you can create your own elements by adding `extra="true"`, as was done for the "frame" example:
```xml ```xml
<elementTypeHere name="YourUniqueElementNameHere" extra="true"> <elementTypeHere name="YourUniqueElementNameHere" extra="true">
... define properties here ... ... define properties here ...
</elementTypeHere> </elementTypeHere>
``` ```
"Extra" elements will be drawn in the order they are defined (so define backgrounds first!). When they get drawn relative to the pre-existing elements depends on the view. Make sure "extra" element names do not clash with existing element names! An easy way to protect against this is to just start all your extra element names with some prefix like "e_". "Extra" elements will be drawn in the order they are defined (so make sure to define backgrounds first). In what order they get drawn relative to the pre-existing elements depends on the view. Make sure "extra" element names do not clash with existing element names. An easy way to protect against this is to start all your extra element names with a prefix such as "e_".
*Properties* control how a particular *element* looks - for example, its position, size, image path, etc. The type of the property determines what kinds of values you can use. You can read about the types below in the "Reference" section. Properties are defined like this: *Properties* control how a particular *element* looks - for example its position, size, image path etc. The type of the property determines what kinds of values you can use. You can read about the types below in the "Reference" section. Properties are defined like this:
```xml ```xml
<propertyNameHere>ValueHere</propertyNameHere> <propertyNameHere>ValueHere</propertyNameHere>
``` ```
# Advanced Features ## Advanced features
It is recommended that if you are writing a theme you launch ES-DE with the `--debug` and `--windowed` switches. This way you can read error messages without having to check the log file. You can also reload the current gamelist view and system view with `Ctrl-R` if `--debug` is specified. If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. If on Unix you can also pass the `--windowed` and `--resolution` flags to avoid having the application window fill the entire screen. On macOS and Windows you only need to pass the `--resolution` flag to accomplish this. By doing so, you can read error messages directly in the terminal window without having to open the log file. You can also reload the current gamelist view and system view with `Ctrl-R` if the `--debug` flag has been set.
### The `<include>` tag ### The \<include\> tag
You can include theme files within theme files, similar to `#include` in C (though the internal mechanism is different, the effect is the same). Example: You can include theme files within theme files, for example:
`~/.emulationstation/all_themes.xml`: `~/.emulationstation/themes/mythemeset-DE/fonts.xml`:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
<fontPath>./all_themes/myfont.ttf</fontPath> <fontPath>./core/font.ttf</fontPath>
<fontSize>0.035</fontSize>
<color>00FF00</color> <color>00FF00</color>
</text> </text>
</view> </view>
</theme> </theme>
``` ```
`~/.emulationstation/snes/theme.xml`: `~/.emulationstation/themes/mythemeset-DE/snes/theme.xml`:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<include>./../all_themes.xml</include> <include>./../fonts.xml</include>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
<color>FF0000</color> <color>FF0000</color>
@ -146,84 +153,77 @@ You can include theme files within theme files, similar to `#include` in C (thou
</theme> </theme>
``` ```
Is equivalent to this `snes/theme.xml`: The above is equivalent to the following:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="description"> <text name="description">
<fontPath>./all_themes/myfont.ttf</fontPath> <fontPath>./core/font.ttf</fontPath>
<fontSize>0.035</fontSize>
<color>FF0000</color> <color>FF0000</color>
</text> </text>
</view> </view>
</theme> </theme>
``` ```
Notice that properties that were not specified got merged (`<fontPath>`) and the `snes/theme.xml` could overwrite the included files' values (`<color>`). Also notice the included file still needed the `<formatVersion>` tag. Note that properties can get merged. In the above example the `<color>` tag from `fonts.xml` got overwritten by the equivalent tag in `snes/theme.xml`. This happens because that tag was effectively declared after the first `<color>` tag. Be aware that the included file also needs the `<formatVersion>` tag.
### Theming multiple views simultaneously ### Theming multiple views simultaneously
Sometimes you want to apply the same properties to the same elements across multiple views. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). So, for example, to easily apply the same header to the basic, grid, and system views: Sometimes you want to apply the same properties to the same elements across multiple views. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). So for example, to apply the same logo to the basic and detailed views you could write the following:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<view name="basic, grid, system"> <view name="basic, detailed">
<image name="logo"> <image name="logo">
<path>./snes_art/snes_header.png</path> <path>./snes/logo.svg</path>
</image> </image>
</view> </view>
<view name="detailed"> <view name="video">
<image name="logo"> <image name="logo">
<path>./snes_art/snes_header_detailed.png</path> <path>./snes/logo_video.svg</path>
</image> </image>
</view> </view>
</theme> </theme>
``` ```
This is equivalent to: The above is equivalent to:
```xml
```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<view name="basic"> <view name="basic">
<image name="logo"> <image name="logo">
<path>./snes_art/snes_header.png</path> <path>./snes/logo.svg</path>
</image> </image>
</view> </view>
<view name="detailed"> <view name="detailed">
<image name="logo"> <image name="logo">
<path>./snes_art/snes_header_detailed.png</path> <path>./snes/logo.svg</path>
</image> </image>
</view> </view>
<view name="grid"> <view name="video">
<image name="logo"> <image name="logo">
<path>./snes_art/snes_header.png</path> <path>./snes/logo_video.svg</path>
</image> </image>
</view> </view>
<view name="system">
<image name="logo">
<path>./snes_art/snes_header.png</path>
</image>
</view>
... and any other view that might try to look up "logo" ...
</theme> </theme>
``` ```
### Theming multiple elements simultaneously ### Theming multiple elements simultaneously
You can theme multiple elements *of the same type* simultaneously. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas), just like it does for views, as long as the elements have the same type. This is useful if you want to, say, apply the same color to all the metadata labels: You can theme multiple elements *of the same type* simultaneously. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). This is useful if you want to, say, apply the same color to all the metadata labels:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<view name="detailed"> <view name="detailed">
<!-- Weird spaces/newline on purpose! --> <!-- Weird spaces/newline on purpose -->
<text name="md_lbl_rating, md_lbl_releasedate, md_lbl_developer, md_lbl_publisher, <text name="md_lbl_rating, md_lbl_releasedate, md_lbl_developer, md_lbl_publisher,
md_lbl_genre, md_lbl_players, md_lbl_lastplayed, md_lbl_playcount"> md_lbl_genre, md_lbl_players, md_lbl_lastplayed, md_lbl_playcount">
<color>48474D</color> <color>48474D</color>
@ -234,9 +234,8 @@ You can theme multiple elements *of the same type* simultaneously. The `name` a
Which is equivalent to: Which is equivalent to:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<view name="detailed"> <view name="detailed">
<text name="md_lbl_rating"> <text name="md_lbl_rating">
<color>48474D</color> <color>48474D</color>
@ -266,20 +265,16 @@ Which is equivalent to:
</theme> </theme>
``` ```
Just remember, *this only works if the elements have the same type!* Just remember, _this only works if the elements have the same type._
### Element rendering order with z-index
You can now change the order in which elements are rendered by setting `zIndex` values. Default values correspond to the default rendering order while allowing elements to easily be shifted without having to set `zIndex` values for every element. Elements will be rendered in order from smallest z-index to largest.
#### Navigation sounds ### Navigation sounds
The navigation sounds are configured globally per theme set, so it needs to be defined as a feature and with the view set to the special 'all' category. Navigation sounds are configured globally per theme set, so it needs to be defined as a feature and with the view set to the special "all" category.
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>`). 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>`).
There are seven different navigation sounds that can be configured. The names as well as the element structure should be self-explanatory based There are seven different navigation sounds that can be configured. The names as well as the element structure should be self-explanatory based
on the example below. on the example below.
Starting ES-DE with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sound is provided by the theme, ES-DE will use the bundled navigation sound file as a fallback. This is done per sound, so the theme could provide for example one or two custom sound files while using the bundled ES-DE sounds for the other samples. Starting ES-DE with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sounds are provided by the theme, 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.
Example debug output: Example debug output:
``` ```
@ -293,9 +288,8 @@ Jul 12 11:28:58 Debug: Sound::getFromTheme(): Tag not found, using fallback sou
Example `navigationsounds.xml`, to be included from the main theme file: Example `navigationsounds.xml`, to be included from the main theme file:
```xml ```xml
<theme> <theme>
<formatVersion>6</formatVersion> <formatVersion>7</formatVersion>
<feature supported="navigationsounds"> <feature supported="navigationsounds">
<view name="all"> <view name="all">
<sound name="systembrowse"> <sound name="systembrowse">
@ -324,14 +318,18 @@ Example `navigationsounds.xml`, to be included from the main theme file:
</theme> </theme>
``` ```
#### Defaults ### Element rendering order using zIndex
##### system 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.
Below are the default zIndex values per element type:
#### system
* Extra Elements `extra="true"` - 10 * Extra Elements `extra="true"` - 10
* `carousel name="systemcarousel"` - 40 * `carousel name="systemcarousel"` - 40
* `text name="systemInfo"` - 50 * `text name="systemInfo"` - 50
##### basic, detailed, grid, video #### basic, detailed, video, grid
* `image name="background"` - 0 * `image name="background"` - 0
* Extra Elements `extra="true"` - 10 * Extra Elements `extra="true"` - 10
* `textlist name="gamelist"` - 20 * `textlist name="gamelist"` - 20
@ -362,25 +360,29 @@ Example `navigationsounds.xml`, to be included from the main theme file:
* `text name="md_description"` * `text name="md_description"`
* `text name="md_name"` * `text name="md_name"`
* System Logo/Text - 50 * System Logo/Text - 50
* `text name="logoText"`
* `image name="logo"` * `image name="logo"`
* `text name="logoText"`
* `image name="logoPlaceholderImage"`
* `text name="logoPlaceholderText"`
* Gamelist information - 50 * Gamelist information - 50
* `text name="gamelistInfo"` * `text name="gamelistInfo"`
* Badges - 50
* `badges name="md_badges"`
### Theme variables ### Theme variables
Theme variables can be used to simplify theme construction. There are 2 types of variables available. Theme variables can be used to simplify theme construction. There are 2 types of variables available.
* System Variables * System variables
* Theme Defined Variables * Theme defined variables
#### System Variables #### System variables
System variables are system specific and are derived from the values in es_systems.xml. System variables are system specific and are derived from the values in es_systems.xml.
* `system.name` * `system.name`
* `system.fullName` * `system.fullName`
* `system.theme` * `system.theme`
#### Theme Defined Variables #### Theme defined variables
Variables can also be defined in the theme. Variables can also be defined in the theme.
``` ```
<variables> <variables>
@ -402,9 +404,32 @@ or to specify only a portion of the value of a theme property:
```` ````
# Reference ## Reference
### Views, their elements, and themeable properties
#### system
* `helpsystem name="help"` - ALL
- The help system style for this view.
* `carousel name="systemcarousel"` - ALL
- The system logo carousel
* `image name="logo"` - PATH | COLOR
- A logo image, to be displayed in the system logo carousel.
* `image name="logoPlaceholderImage"` - ALL
- A logo image, to be displayed system name in the system logo carousel when no logo is available. Set the position
to `0.5 0.5` to center the image.
* `text name="logoPlaceholderText"` - ALL
- Logo text, to be displayed system name in the system logo carousel when no logo is available. The logo text is
displayed on top of `logoPlaceholderImage`. Set the position to `0.5 0.5` to center the text.
* `text name="logoText"` - FONT_PATH | COLOR | FORCE_UPPERCASE | LINE_SPACING | TEXT
- **Deprecated:** A logo text, to be displayed system name in the system logo carousel when no logo is available.
Ignored when `logoPlaceholderImage` or `logoPlaceholderText` are set.
* `text name="systemInfo"` - ALL
- Displays details of the system currently selected in the carousel.
* You can use extra elements (elements with `extra="true"`) to add your own backgrounds, etc. They will be displayed
behind the carousel, and scroll relative to the carousel.
## Views, their elements, and themeable properties:
#### basic #### basic
* `helpsystem name="help"` - ALL * `helpsystem name="help"` - ALL
@ -418,7 +443,6 @@ or to specify only a portion of the value of a theme property:
* `textlist name="gamelist"` - ALL * `textlist name="gamelist"` - ALL
- The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Centered by default. - The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Centered by default.
---
#### detailed #### detailed
* `helpsystem name="help"` - ALL * `helpsystem name="help"` - ALL
@ -434,8 +458,8 @@ or to specify only a portion of the value of a theme property:
* `text name="gamelistInfo"` - ALL * `text name="gamelistInfo"` - ALL
- 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, 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. Left aligned by default. - 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, 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. Left aligned by default.
* Metadata - Metadata
* Labels - Labels
* `text name="md_lbl_rating"` - ALL * `text name="md_lbl_rating"` - ALL
* `text name="md_lbl_releasedate"` - ALL * `text name="md_lbl_releasedate"` - ALL
* `text name="md_lbl_developer"` - ALL * `text name="md_lbl_developer"` - ALL
@ -446,8 +470,7 @@ or to specify only a portion of the value of a theme property:
* `text name="md_lbl_playcount"` - ALL * `text name="md_lbl_playcount"` - ALL
* Values * Values
* All values will follow to the right of their labels if a position isn't specified. - _All values will follow to the right of their labels if a position isn't specified._
* `image name="md_image"` - POSITION | SIZE | Z_INDEX * `image name="md_image"` - POSITION | SIZE | Z_INDEX
- Path is the "image" metadata for the currently selected game. - Path is the "image" metadata for the currently selected game.
* `rating name="md_rating"` - ALL * `rating name="md_rating"` - ALL
@ -462,6 +485,8 @@ or to specify only a portion of the value of a theme property:
- The "genre" metadata. - The "genre" metadata.
* `text name="md_players"` - ALL * `text name="md_players"` - ALL
- The "players" metadata (number of players the game supports). - The "players" metadata (number of players the game supports).
* `badges name="md_badges"` - ALL
- The "badges" metadata. Displayed as a group of badges that indicate metadata such as favorites and completed games.
* `datetime name="md_lastplayed"` - ALL * `datetime name="md_lastplayed"` - ALL
- The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago"). - The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago").
* `text name="md_playcount"` - ALL * `text name="md_playcount"` - ALL
@ -471,6 +496,7 @@ or to specify only a portion of the value of a theme property:
* `text name="md_name"` - ALL * `text name="md_name"` - ALL
- The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default
#### video #### video
* `helpsystem name="help"` - ALL * `helpsystem name="help"` - ALL
- The help system style for this view. - The help system style for this view.
@ -485,8 +511,8 @@ or to specify only a portion of the value of a theme property:
* `text name="gamelistInfo"` - ALL * `text name="gamelistInfo"` - ALL
- 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, 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. Left aligned by default. - 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, 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. Left aligned by default.
* Metadata - Metadata
* Labels - Labels
* `text name="md_lbl_rating"` - ALL * `text name="md_lbl_rating"` - ALL
* `text name="md_lbl_releasedate"` - ALL * `text name="md_lbl_releasedate"` - ALL
* `text name="md_lbl_developer"` - ALL * `text name="md_lbl_developer"` - ALL
@ -497,8 +523,7 @@ or to specify only a portion of the value of a theme property:
* `text name="md_lbl_playcount"` - ALL * `text name="md_lbl_playcount"` - ALL
* Values * Values
* All values will follow to the right of their labels if a position isn't specified. - _All values will follow to the right of their labels if a position isn't specified._
* `image name="md_image"` - POSITION | SIZE | Z_INDEX * `image name="md_image"` - POSITION | SIZE | Z_INDEX
- Path is the "image" metadata for the currently selected game. - Path is the "image" metadata for the currently selected game.
* `image name="md_marquee"` - POSITION | SIZE | Z_INDEX * `image name="md_marquee"` - POSITION | SIZE | Z_INDEX
@ -517,6 +542,8 @@ or to specify only a portion of the value of a theme property:
- The "genre" metadata. - The "genre" metadata.
* `text name="md_players"` - ALL * `text name="md_players"` - ALL
- The "players" metadata (number of players the game supports). - The "players" metadata (number of players the game supports).
* `badges name="md_badges"` - ALL
- The "badges" metadata. Displayed as a group of badges that indicate metadata such as favorites and completed games.
* `datetime name="md_lastplayed"` - ALL * `datetime name="md_lastplayed"` - ALL
- The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago"). - The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago").
* `text name="md_playcount"` - ALL * `text name="md_playcount"` - ALL
@ -526,7 +553,6 @@ or to specify only a portion of the value of a theme property:
* `text name="md_name"` - ALL * `text name="md_name"` - ALL
- The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default
---
#### grid #### grid
* `helpsystem name="help"` - ALL * `helpsystem name="help"` - ALL
@ -546,8 +572,8 @@ or to specify only a portion of the value of a theme property:
* `text name="gamelistInfo"` - ALL * `text name="gamelistInfo"` - ALL
- 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, 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. Left aligned by default. - 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, 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. Left aligned by default.
* Metadata - Metadata
* Labels - Labels
* `text name="md_lbl_rating"` - ALL * `text name="md_lbl_rating"` - ALL
* `text name="md_lbl_releasedate"` - ALL * `text name="md_lbl_releasedate"` - ALL
* `text name="md_lbl_developer"` - ALL * `text name="md_lbl_developer"` - ALL
@ -558,8 +584,7 @@ or to specify only a portion of the value of a theme property:
* `text name="md_lbl_playcount"` - ALL * `text name="md_lbl_playcount"` - ALL
* Values * Values
* All values will follow to the right of their labels if a position isn't specified. - _All values will follow to the right of their labels if a position isn't specified._
* `rating name="md_rating"` - ALL * `rating name="md_rating"` - ALL
- The "rating" metadata. - The "rating" metadata.
* `datetime name="md_releasedate"` - ALL * `datetime name="md_releasedate"` - ALL
@ -572,6 +597,8 @@ or to specify only a portion of the value of a theme property:
- The "genre" metadata. - The "genre" metadata.
* `text name="md_players"` - ALL * `text name="md_players"` - ALL
- The "players" metadata (number of players the game supports). - The "players" metadata (number of players the game supports).
* `badges name="md_badges"` - ALL
- The "badges" metadata. Displayed as a group of badges that indicate metadata such as favorites and completed games.
* `datetime name="md_lastplayed"` - ALL * `datetime name="md_lastplayed"` - ALL
- The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago"). - The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago").
* `text name="md_playcount"` - ALL * `text name="md_playcount"` - ALL
@ -581,23 +608,8 @@ or to specify only a portion of the value of a theme property:
* `text name="md_name"` - ALL * `text name="md_name"` - ALL
- The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default
---
#### system ### Types of properties
* `helpsystem name="help"` - ALL
- The help system style for this view.
* `carousel name="systemcarousel"` -ALL
- The system logo carousel
* `image name="logo"` - PATH | COLOR
- A logo image, to be displayed in the system logo carousel.
* `text name="logoText"` - FONT_PATH | COLOR | FORCE_UPPERCASE | LINE_SPACING | TEXT
- A logo text, to be displayed system name in the system logo carousel when no logo is available.
* `text name="systemInfo"` - ALL
- Displays details of the system currently selected in the carousel.
* You can use extra elements (elements with `extra="true"`) to add your own backgrounds, etc. They will be displayed behind the carousel, and scroll relative to the carousel.
## Types of properties:
* NORMALIZED_PAIR - two decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5`. Most commonly used for position (x and y coordinates) and size (width and height). * NORMALIZED_PAIR - two decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5`. Most commonly used for position (x and y coordinates) and size (width and height).
* NORMALIZED_RECT - four decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5 0.10 0.30`. Most commonly used for padding to store top, left, bottom and right coordinates. * NORMALIZED_RECT - four decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5 0.10 0.30`. Most commonly used for padding to store top, left, bottom and right coordinates.
@ -608,7 +620,7 @@ or to specify only a portion of the value of a theme property:
* STRING - a string of text. * STRING - a string of text.
## Types of elements and their properties: ### Types of elements and their properties
Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type. They are normalized in terms of their "parent" object's size; 99% 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). `pos` almost always refers to the top left corner of your element. You *can* use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen. Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type. They are normalized in terms of their "parent" object's size; 99% 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). `pos` almost always refers to the top left corner of your element. You *can* use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen.
@ -630,7 +642,7 @@ Can be created as an extra.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the image will be rotated. Defaults to `0.5 0.5`. - Point around which the image will be rotated. Default is `0.5 0.5`.
* `path` - type: PATH. * `path` - type: PATH.
- Path to the image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). - Path to the image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif).
* `default` - type: PATH. * `default` - type: PATH.
@ -704,7 +716,7 @@ Can be created as an extra.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the text will be rotated. Defaults to `0.5 0.5`. - Point around which the text will be rotated. Default is `0.5 0.5`.
* `delay` - type: FLOAT. Default is false. * `delay` - type: FLOAT. Default is false.
- Delay in seconds before video will start playing. - Delay in seconds before video will start playing.
* `default` - type: PATH. * `default` - type: PATH.
@ -733,7 +745,7 @@ Can be created as an extra.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the text will be rotated. Defaults to `0.5 0.5`. - Point around which the text will be rotated. Default is `0.5 0.5`.
* `text` - type: STRING. * `text` - type: STRING.
* `color` - type: COLOR. * `color` - type: COLOR.
* `backgroundColor` - type: COLOR; * `backgroundColor` - type: COLOR;
@ -805,7 +817,7 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the rating will be rotated. Defaults to `0.5 0.5`. - Point around which the rating will be rotated. Default is `0.5 0.5`.
* `filledPath` - type: PATH. * `filledPath` - type: PATH.
- Path to the "filled star" image. Image must be square (width equals height). - Path to the "filled star" image. Image must be square (width equals height).
* `unfilledPath` - type: PATH. * `unfilledPath` - type: PATH.
@ -829,7 +841,7 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the text will be rotated. Defaults to `0.5 0.5`. - Point around which the text will be rotated. Default is `0.5 0.5`.
* `color` - type: COLOR. * `color` - type: COLOR.
* `backgroundColor` - type: COLOR; * `backgroundColor` - type: COLOR;
* `fontPath` - type: PATH. * `fontPath` - type: PATH.
@ -860,9 +872,95 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place - Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place
the component exactly in the middle of the screen. the component exactly in the middle of the screen.
* `textColor` - type: COLOR. Default is 777777FF. * `textColor` - type: COLOR. Default is 777777FF.
* `textColorDimmed` - type: COLOR. Default is the same value as textColor. Must be placed under the 'system' view.
* `iconColor` - type: COLOR. Default is 777777FF. * `iconColor` - type: COLOR. Default is 777777FF.
* `iconColorDimmed` - type: COLOR. Default is the same value as iconColor. Must be placed under the 'system' view.
* `fontPath` - type: PATH. * `fontPath` - type: PATH.
* `fontSize` - type: FLOAT. * `fontSize` - type: FLOAT.
* `entrySpacing` - type: FLOAT. Default is 16.0.
- Spacing in pixels between the help system components.
* `iconTextSpacing` - type: FLOAT. Default is 8.0.
- Spacing in pixels within a help system component between it's icon and text.
* `textStyle` - type: STRING. Default is `uppercase`.
- The style of the text. Options: `uppercase`, `lowercase`, `camelcase`.
* `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_a_SNES`,
`button_b_SNES`,
`button_x_SNES`,
`button_y_SNES`,
`button_back_SNES`,
`button_start_SNES`,
`button_a_PS`,
`button_b_PS`,
`button_x_PS`,
`button_y_PS`,
`button_back_PS4`,
`button_start_PS4`,
`button_back_PS5`,
`button_start_PS5`,
`button_a_XBOX`,
`button_b_XBOX`,
`button_x_XBOX`,
`button_y_XBOX`,
`button_back_XBOX`,
`button_start_XBOX`,
`button_back_XBOX360`,
`button_start_XBOX360`.
#### badges
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).
* `pos` - type: NORMALIZED_PAIR.
* `size` - 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.03`, maximum value is `1.0`. Default is `0.15 0.20`.
* `origin` - type: NORMALIZED_PAIR.
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. Default is `0 0`.
* `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. Default is `0.5 0.5`.
* `direction` - type: STRING.
- Valid values are "row" or "column". Controls the primary layout direction (line axis) for the badges. Lines will fill up in the specified direction. Default is `row`.
* `lines` - type: FLOAT.
- The number of lines available. Default is `2`.
* `itemsPerLine` - type: FLOAT.
- 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 margins between badges. Possible combinations:
- `x y` - horizontal and vertical margins. Minimum value per axis is `0`, maximum value is `0.2`. Default is `0.01 0.01`. If one of the axis is set to `-1` the margin of the other axis (in pixels) will be used, which makes it possible to get identical spacing between all items regardless of screen aspect ratio.
* `slots` - type: STRING.
- The badge types that should be displayed. Should be specified as a list of strings delimited by any characters of `\t\r\n ,` - that is, whitespace and commas. The order will be followed when placing badges on the screen. Available badges are:
- `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.
- `altemulator`: Will be shown when an alternative emulator is setup for the game.
* `controllerPos` - type: NORMALIZED_PAIR.
- The position of the controller icon relative to the parent `controller` badge. Minimum value per axis is `-1.0`, maximum value is `2.0`. Default is `0.5 0.5` which centers the controller icon on the badge.
* `controllerSize` - type: FLOAT.
- The size of the controller icon relative to the parent `controller` badge. Minimum value is `0.1`, maximum value is `2.0`. Setting the value to `1.0` sizes the controller icon to the same width as the parent badge. The image aspect ratio is always maintained.
* `customBadgeIcon` - type: PATH.
- A badge icon override. Specify the badge type in the attribute `badge`. The available badges are the ones listed above.
* `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_playstation`, `gamepad_sega_md_3_buttons`, `gamepad_sega_md_6_buttons`, `gamepad_xbox`, `joystick_generic`, `joystick_arcade_no_buttons`, `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`, `unknown`.
* `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. Default is `50`.
#### carousel #### carousel
@ -886,7 +984,7 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
- Default is 7.5 - Default is 7.5
- This property only applies when `type` is "horizontal_wheel" or "vertical_wheel". - This property only applies when `type` is "horizontal_wheel" or "vertical_wheel".
* `logoRotationOrigin` - type: NORMALIZED_PAIR. * `logoRotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the logos will be rotated. Defaults to `-5 0.5`. - Point around which the logos will be rotated. Default is `-5 0.5`.
- This property only applies when `type` is "horizontal_wheel" or "vertical_wheel". - This property only applies when `type` is "horizontal_wheel" or "vertical_wheel".
* `logoAlignment` - type: STRING. * `logoAlignment` - type: STRING.
- Sets the alignment of the logos relative to the carousel. - Sets the alignment of the logos relative to the carousel.
@ -898,11 +996,15 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
- Default is 3 - Default is 3
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for component. Components will be rendered in order of z-index value from low to high.
* `legacyZIndexMode` - type: BOOLEAN
- If true, the carousel will ignore zIndex and always render on top of other components. Default is `true`.
The help system is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Keep in mind the "default" settings (including position) are used whenever the user opens a menu. The help system is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Keep in mind the "default" settings (including position) are used whenever the user opens a menu.
To see some examples of EmulationStation themes, the following resources are recommended: ## Example theme sets
To see some example EmulationStation themes, the following resources are recommended:
https://aloshi.com/emulationstation#themes https://aloshi.com/emulationstation#themes