Every file making up a theme is in XML format, a plain tag-based language (<tag></tag> or <tag />).
A theme is a folder placed in /recalbox/share/themes/. Its root must contain a theme.xml file: that file is what identifies the folder as a theme.
/recalbox/share/themes/
my-theme/
theme.xml <- mandatory, entry point
default/
theme.xml <- fallback theme for systems without a dedicated folder
snes/
theme.xml
logo.svg
megadrive/
theme.xml
art/
font.ttf
background.png
System sub-folder names are not free: they must match the theme folder declared by each system. The four pages below list those names, extracted from the Recalbox 10.1 system definitions:
For each system, Recalbox looks for the file to load in this order, and stops at the first hit:
<theme>/<system-folder>/theme.xml<theme>/default/theme.xml<theme>/theme.xmlA default/ folder is therefore the simplest way to cover every system you have not customised individually.
Recalbox accepts two equivalent ways of writing properties: as child tags (legacy style) or as attributes (recommended style, far more compact).
Legacy style:
<theme>
<include>path/to/include.xml</include>
<view name="system">
<image name="deco" extra="true">
<pos>0 0</pos>
<size>1 1</size>
<path>./art/background.png</path>
</image>
</view>
</theme>
Recommended style:
<theme>
<include path="path/to/include.xml" />
<view name="system">
<image name="deco" extra="true" pos="0 0" size="1 1" path="./art/background.png" />
</view>
</theme>
Both styles can be mixed inside a single object: an attribute provides the default value, a child tag can override it under a condition.
<image name="deco" extra="true" path="./art/background.png">
<path if="crt">./art/background-crt.png</path>
</image>
The theme is not loaded once and for all: it is fully reloaded and re-interpreted in the following cases.
<variables> blocks are interpreted first of all, even before <include> tags.
<theme> tagEvery theme XML file starts with <theme> and ends with </theme>. This tag accepts five attributes, all optional, but only meaningful in the theme.xml at the theme root.
nameDisplay name of the theme, which may differ from the folder name. Without this attribute, the folder name is displayed.
<theme name="My own theme">
versionTheme version. When present, it is displayed in parentheses after the name in the theme list.
<theme version="3.1">
recalboxMinimum Recalbox version required by the theme. Recalbox 10.1 considers a theme declaring less than 9.2 too old and warns the user before activating it. Without this attribute, no check is performed.
<theme recalbox="10.0">
compatibilityDisplay types supported by the theme, comma-separated.
| Value | Meaning |
|---|---|
hdmi |
HDMI displays |
crt |
CRT displays (RGB DUAL) |
jamma |
JAMMA cabinets (RGB JAMMA) |
tate |
Vertical displays (TATE) |
<theme compatibility="hdmi,jamma">
Without this attribute, the theme is considered hdmi-only. If the user is in TATE mode and the theme does not declare tate, a warning is shown at activation.
resolutionsSupported resolution ranges, comma-separated.
| Value | Screen height |
|---|---|
qvga |
up to 288 px |
vga |
289 to 576 px |
hd |
577 to 920 px |
fhd |
above 920 px |
<theme resolutions="hd,fhd">
Without this attribute, the theme is considered compatible with hd,fhd.
authorTheme author name, reported by the theme manager.
<theme author="Your nickname">
formatVersion tag
formatVersionis a leftover from the old theme engine. Recalbox 10.1 does not read it at all: you can remove it from your files.
The contents of <view> tags and the list of usable objects are described in the objects page.