Folders and files

A single rule, and a lot of freedom.

A theme is a folder placed in /recalbox/share/themes/.

The only rule

This folder must contain a file named theme.xml.

That is all. theme.xml is the entry point: Recalbox looks for it at the root of the folder, and if it is not there, the theme does not exist.

Nothing else is imposed. No subfolder names, no layout, no organization. You can write an entire theme in that single file.

Splitting, because it is more practical

A serious theme quickly grows to thousands of lines. So you split it into several XML files, arranged however you like, which theme.xml includes:

mon-theme/
  theme.xml            ← the only imposed name
  variables.xml
  views/
    system.xml
    detailed.xml
    menu.xml
  data/
    fonts/
    images/

Those names are yours: call them whatever you want. The custom, in published themes as in the studio's exports, is to write them in English — views/, data/, fonts/ — because that is the language of the tags they contain.

The include mechanism is explained in Splitting your theme.

Paths

A path written in a file is relative to that file. As soon as you split into subfolders, this becomes a source of errors.

Go through ${root}, which always points to the theme's root:

<path>${root}/data/images/fond.jpg</path>   <!-- ✅ works from any file -->
<path>../data/images/fond.jpg</path>        <!-- fragile: depends on where the line is written -->