mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-22 22:25:38 +00:00
529c3a24c7
DESCNAME is a new, optional tag. You can now use ~/.emulationstation/SYSTEMNAME/ for theme and gamelist files!
170 lines
6.8 KiB
Markdown
170 lines
6.8 KiB
Markdown
Themes
|
|
======
|
|
|
|
EmulationStation allows each system to have its own "theme." A theme is a collection of display settings and images defined in an XML document.
|
|
|
|
ES will check 3 places for a theme, in the following order:
|
|
- a theme.xml file in the root of a system's %PATH% directory.
|
|
- $HOME/.emulationstation/%NAME%/theme.xml
|
|
- $HOME/.emulationstation/es_theme.xml
|
|
|
|
Almost all positions, dimensions, origins, etc. work in percentages - that is, they are a decimal between 0 and 1, representing the percentage of the screen on that axis to use. This ensures that themes look similar at every resolution.
|
|
|
|
Colors are hex values, either 6 or 8 characters, defined as RRGGBB or RRGGBBAA. If alpha is not included, a default value of FF will be assumed (not transparent).
|
|
|
|
|
|
Example
|
|
=======
|
|
|
|
Here's a simple theme that defines some colors and displays a background:
|
|
```
|
|
<theme>
|
|
<listPrimaryColor>0000FF</listPrimaryColor>
|
|
<listSecondaryColor>00FF00</listSecondaryColor>
|
|
|
|
<component>
|
|
<type>image</type>
|
|
<path>./theme/background.png</path>
|
|
<pos>0 0</pos>
|
|
<dim>1 1</dim>
|
|
<origin>0 0</origin>
|
|
</component>
|
|
</theme>
|
|
```
|
|
|
|
All themes must be enclosed in a `<theme>` tag.
|
|
|
|
|
|
Components
|
|
==========
|
|
A theme is made up of components, which have various types. At the moment, the only type is `image`. Components are rendered in the order they are defined - that means you'll want to define the background first, a header image second, etc.
|
|
|
|
|
|
The "image" component
|
|
=====================
|
|
Used to display an image.
|
|
|
|
`<path>` - path to the image file. Most common file types are supported, and . and ~ are properly expanded.
|
|
|
|
`<pos>` - the position, as two screen percentages, at which to display the image.
|
|
|
|
`<dim>` - the dimensions, as two screen percentages, that the image will be resized to. Make one axis 0 to keep the aspect ratio.
|
|
|
|
`<origin>` - the point on the image that `<pos>` defines, as an image percentage. "0.5 0.5", the center of the image, by default.
|
|
|
|
`<tiled />` - if present, the image is tiled instead of resized.
|
|
|
|
|
|
Display tags
|
|
============
|
|
Display tags define some "meta" display attributes about your theme. Display tags must be at the root of the `<theme>` tree - for example, they can't be inside a component tag. They are not required.
|
|
|
|
|
|
**Game list attributes:**
|
|
|
|
`<listPrimaryColor>` - the hex font color to use for games on the GuiGameList.
|
|
|
|
`<listSecondaryColor>` - the hex font color to use for folders on the GuiGameList.
|
|
|
|
`<descColor>` - the hex font color to use for the description on the GuiGameList.
|
|
|
|
`<listSelectorColor>` - the hex color to use for the "selector bar" on the GuiGameList. Default is `000000FF`.
|
|
|
|
`<listSelectedColor>` - the hex color to use for selected text on the GuiGameList. Default is the value of `<listPrimaryColor>`.
|
|
|
|
`<listLeftAlign />` - if present, the games list names will be left aligned to the value of `<listOffsetX>` (default 0.5).
|
|
|
|
`<hideHeader />` - if present, the system name header won't be displayed (useful for replacing it with an image). If you're making a complete custom theme, you probably want to use this.
|
|
|
|
`<hideDividers />` - if present, the divider between games on the detailed GuiGameList won't be displayed.
|
|
|
|
`<listOffsetX>` - the percentage to offset the list by. Default is 0.5 (half the screen). **Will also move the selector bar**.
|
|
|
|
`<listTextOffsetX>` - the percentage to offset the text in the list by. Default is 0.005. Only works in combination with `<listLeftAlign />`.
|
|
|
|
~~`<gameImageOffsetY>` - the percentage to offset the displayed game image by. Default is the height of the header font.~~
|
|
|
|
|
|
|
|
**Game image attributes:**
|
|
|
|
`<gameImagePos>` - two values for the position of the game art, in the form of `[x] [y]`, as a percentage. Default is `$infoWidth/2 $headerHeight`.
|
|
|
|
`<gameImageDim>` - two values for the dimensions of the game art, in the form of `[width] [height]`, as a percentage of the screen. Default is `$infoWidth 0` (width fits within the info column). The image will only be resized if at least one axis is nonzero *and* exceeded by the image's size. You should always leave at least one axis as zero to preserve the aspect ratio.
|
|
|
|
`<gameImageOrigin>` - two values for the origin of the game art, in the form of `[x] [y]`, as a percentage. Default is `0.5 0` (top-center of the image).
|
|
|
|
`<gameImageNotFound>` - path to the image to display if a game's image is missing. '.' and '~' are expanded.
|
|
|
|
|
|
|
|
**Fast Select box attributes:**
|
|
|
|
`<fastSelectColor>` - the hex color to use for the letter display on the Fast Select box.
|
|
|
|
`<boxBackground>` - path to a background image file. ~ and . are expanded.
|
|
|
|
`<boxBackgroundTiled />` - if present, the background will be tiled instead of stretched.
|
|
|
|
`<boxHorizontal>` - path to the "left" border image file. It will be flipped for the right border. ~ and . are expanded.
|
|
|
|
`<boxHorizontalTiled />` - if present, the horizontal image will be tiled instead of stretched downwards.
|
|
|
|
`<boxVertical>` - path to the "top" border image file. It will be flipped for the bottom border. ~ and . are expanded.
|
|
|
|
`<boxVerticalTiled />` - if present, the vertical image will be tiled instead of stretched to the right.
|
|
|
|
`<boxCorner>` - path to the "top left corner" image file. It will be flipped for the top right, bottom right, and bottom left corners. ~ and . are expanded.
|
|
|
|
|
|
|
|
Fonts
|
|
=====
|
|
|
|
Fonts are defined like so:
|
|
|
|
```
|
|
<fontTag>
|
|
<path>./path/to/font</path>
|
|
<size>0.05</size>
|
|
</fontTag>
|
|
```
|
|
|
|
You can leave off any tags you don't want to use, and they'll use the default. Size is defined as a percentage of the screen height. "." and "~" are expanded for paths.
|
|
|
|
**Font tags:**
|
|
|
|
`<listFont>` - font to use for the game list.
|
|
|
|
`<descriptionFont>` - font to use for description text.
|
|
|
|
|
|
Audio
|
|
=====
|
|
|
|
Themes can also define menu sounds. These tags go in the root of the `<theme>` tree, just like Display tags. Sounds should be in the .wav format. The relative path operator (.) and home operator (~) are properly expanded.
|
|
|
|
`<menuScrollSound>` - path to the sound to play when the game list or fast select menu is scrolling.
|
|
|
|
`<menuSelectSound>` - path to the sound to play when the user selects something from the game list.
|
|
|
|
`<menuBackSound>` - path to the sound to play when the user "goes up" from a folder in the game list.
|
|
|
|
`<menuOpenSound>` - path to the sound to play when the user opens a menu (either the "main menu" or the fast select menu).
|
|
|
|
|
|
List of variables
|
|
=================
|
|
|
|
Variables can be used in position and dimension definitions. They can be added, subtracted, multiplied, and divided. Parenthesis are valid. They are a percentage of the screen.
|
|
|
|
For example, if you wanted to place an image that covered the left half of the screen, up to the game list, you could use `<dim>$infoWidth 1</dim>`.
|
|
|
|
`$headerHeight` - height of the system name header.
|
|
|
|
`$infoWidth` - where the left of the game list begins. Will follow `<listOffsetX>`.
|
|
|
|
|
|
-Aloshi
|
|
http://www.aloshi.com
|