A Recalbox theme is a set of XML files and graphical assets describing the whole look of EmulationStation: system list, game lists, menus, help bar and screensaver. This section documents the theme engine as implemented in Recalbox 10.1.
This documentation describes the theme format of Recalbox 10.0 and above. A theme declaring
recalbox="9.1"or lower is flagged as potentially incompatible when you activate it.
If you are new to theming, follow these pages in order:
theme.xml, attributes of the <theme> tag.${...}.A theme is made of views (<view>), each view contains objects (<image>, <text>, <carousel>…), and each object carries properties (pos, size, color…).
<theme name="My theme" version="1.0" recalbox="10.0" compatibility="hdmi" resolutions="hd,fhd">
<view name="system">
<image name="deco" extra="true" path="./art/background.png" pos="0 0" size="1 1" zIndex="5" />
</view>
</theme>
The five views available in 10.1 are system, detailed, basic, menu and gameclip. Any other value is ignored, with an error logged in themes.log.
An object whose name matches an element already managed by the interface (for instance <image name="logo">) customises that element. An object with a name of your own must carry extra="true": it is then added to the view, and drawn in declaration order.
${...} replace the old $system, $fullname, $crt… variables, which are still read but deprecated.<box>, <scrolltext>, <markdown>, <menuSection>, <menuSize>, <keyboard>.textOnly="true"), with its own colours and selector bar.ifexists and ifnotexists.grid and video views no longer exist.EmulationStation looks for themes in three folders, in this order:
| Location | Purpose |
|---|---|
/recalbox/share_init/system/.emulationstation/themes/ |
Themes shipped with Recalbox, read-only |
/recalbox/share/themes/ |
Your themes — this is where you work, and also where the theme manager installs its downloads |
/recalbox/share/system/.emulationstation/themes/ |
Legacy location, still read |
A folder is only recognised as a theme if it contains a theme.xml file at its root.
The active theme is selected from MAIN MENU > USER INTERFACE SETTINGS > THEME > THEME SET. The same menu offers the REGION, the transition style, and the options specific to the selected theme. To download more themes, use MAIN MENU > THEME MANAGER — see Theme manager and Theme options for the user-facing side.
Any question about theme creation? Join the Recalbox Discord.