¶ Introduction
Themes have a certain folders and files structure. Everything is described below.
All the files that make up a theme are in XML format. This is a simple language to use. It uses classic tags such as <tag></tag> or self-closing tags <tag />.
¶ Legend
: new
: deprectaed, to not use anymore, will be removed in a future version
¶ Lots of folders...
Every theme is made up of lots of folders.
¶ System
For each system available in Recalbox, you have a folder containing all the images corresponding to that system.
¶ Basic virtual systems
Basic virtual systems correspond to systems such as favorites, last played games, multiplayer games, etc.
Here's a list of basic virtual systems and their folder names.
| Virtual system | Folder name |
|---|---|
| Arcade | arcade |
| All games | auto-allgames |
| Last played | auto-lastplayed |
| Lightgun | auto-lightgun |
| Multiplayer | auto-multiplayer |
| TATE Mode | auto-tate |
| Favorite | favorites |
¶ Virtual systems by genre
Virtual systems by genre correspond to the game genres you retrieve from your game scraps. You can also modify the genres of each of your games yourself.
Here's the list of virtual systems by genre and their folder names.
| Virtual system | Folder name |
|---|---|
| Action (all) | auto-action |
| Action - Battle Royale | auto-actionbattleroyale |
| Action - Beat'em up | auto-actionbeatemup |
| Action - Fighting | auto-actionfighting |
| Action - First Person Shooter | auto-actionfirstpersonshooter |
| Action - Platformer | auto-actionplatformer |
| Action - Platform Shooter | auto-actionplatformshooter |
| Action - Rhythm & music | auto-actionrythm |
| Action - Shoot-em up | auto-actionshootemup |
| Action - Shoot with accessories | auto-actionshootwithgun |
| Action - Infiltration | auto-actionstealth |
| Aventure | auto-adventure |
| Adventure - Adventure graphics | auto-adventuregraphics |
| Adventure - Interactive Film | auto-adventureinteractivemovie |
| Adventure - Realtime 3D Adventure | auto-adventurerealtime3d |
| Adventure - Survival Games | auto-adventuresurvivalhorror |
| Adventure - Text Adventure | auto-adventuretext |
| Adventure - Visual news | auto-adventurevisualnovels |
| Board game | auto-board |
| Casino | auto-casino |
| Casual games | auto-casual |
| Multi-game compilation | auto-compilation |
| Demo scene | auto-demoscene |
| Digital Cards | auto-digitalcard |
| Educative games | auto-educative |
| Multiplayer board game | auto-party |
| Pinball | auto-pinball |
| Puzzle & logic | auto-puzzleandlogic |
| Role-playing (all) | auto-rpg |
| Role-Playing - Action Role-Playing | auto-rpgaction |
| Role Playing - Dungeon Exploration | auto-rpgdungeoncrawler |
| Role-Playing - First Person Party based | auto-rpgfirstpersonpartybased |
| Role-playing - Japanese Role-Playing Games | auto-rpgjapanese |
| Role-Playing - Massive Multiplayer Role-Playing Games | auto-rpgmmo |
| Role-Playing - Tactical Role-Playing | auto-rpgtactical |
| Simulation | auto-simulation |
| Simulation - Construction and management | auto-simulationbuildandmanagement |
| Simulation - Hunting and fishing | auto-simulationfishandhunt |
| Simulation - Life simulation | auto-simulationlife |
| Simulation - Science fiction | auto-simulationscifi |
| Simulation - Simulation vehicle | auto-simulationvehicle |
| Sport (all) | auto-sports |
| Sport - Competitive sport | auto-sportcompetitive |
| Sport - Fighting/Violent sport | auto-sportfight |
| Sport - Racing | auto-sportracing |
| Sport - Sports simulation | auto-sportsimulation |
| Strategy (all) | auto-strategy |
| Strategy - Exploration, expansion, exploitation & extermination | auto-strategy4x |
| Strategy - Artillery | auto-strategyartillery |
| Strategy - Automated battles | auto-strategyautobattler |
| Strategy - Multiplayer battle arena | auto-strategymoba |
| Strategy - Strategy artillery games | auto-strategy-artillery |
| Strategy - Real-time strategy games | auto-strategyrts |
| Strategy - Turn-based strategy | auto-strategytbs |
| Strategy - Tower defense | auto-strategytowerdefense |
| Strategy - War game | auto-strategywargame |
| Trivia | auto-trivia |
¶ Arcade virtual systems by manufacturer
Arcade virtual systems correspond to the arcade manufacturers listed.
Here's a list of arcade virtual systems by manufacturer and their folder name.
| Système virtuel | Nom du dossier |
|---|---|
| Acclaim | auto-arcade-acclaim |
| Atari | auto-arcade-atari |
| Atlus | auto-arcade-atlus |
| BanPresto | auto-arcade-banpresto |
| Capcom | auto-arcade-capcom |
| Capcom CPS1 | auto-arcade-capcom-cps1 |
| Capcom CPS2 | auto-arcade-capcom-cps2 |
| Capcom CPS3 | auto-arcade-capcom-cps3 |
| CAVE | auto-arcade-cave |
| Data East | auto-arcade-dataeast |
| Exidy | auto-arcade-exidy |
| International Games System (I.G.S) | auto-arcade-igs |
| IREM Software Engineering | auto-arcade-irem |
| Incredible Technologies | auto-arcade-itech |
| Jaleco | auto-arcade-jaleco |
| Kaneko | auto-arcade-kaneko |
| Konami | auto-arcade-konami |
| Midway | auto-arcade-midway |
| Mitchell | auto-arcade-mitchell |
| NAMCO | auto-arcade-namco |
| Neo-Geo | auto-arcade-neogeo |
| Nichibutsu | auto-arcade-nichibutsu |
| Nintendo | auto-arcade-nintendo |
| NMK | auto-arcade-nmk |
| Psikyo | auto-arcade-psikyo |
| Raizing | auto-arcade-raizing |
| Sammy | auto-arcade-sammy |
| SEGA | auto-arcade-sega |
| SEGA System 16 | auto-arcade-sega-system16 |
| SEGA System 32 | auto-arcade-sega-system32 |
| Seibu | auto-arcade-seibu |
| SETA | auto-arcade-seta |
| SNK | auto-arcade-snk |
| TAITO | auto-arcade-taito |
| TAITO F3 | auto-arcade-taito-f3 |
| Technōs | auto-arcade-technos |
| TECMO | auto-arcade-temco |
| TOAPLAN | auto-arcade-toaplan |
| VISCO | auto-arcade-visco |
¶ ... And a few files
At the root of any theme, you'll find a file called theme.xml. This contains information about general objects such as menu configuration, help bar, etc.
In each system seen above, you'll have an xml file (the file name will depend on your preference) which will contain system information such as information texts and the colors of the 4 vertical bars on the right of your screen with the default theme.
¶ File structure
Recalbox accepts two ways of writing XML files for themes.
Old way:
<theme>
<include>path/to/include1</include>
<include>path/to/include2</include>
...
<include>path/to/includeX</include>
<view name="...">
<object>
<property1>value</property1>
<property2>value</property2>
...
<propertyX>value</propertyX>
</object>
...
</view>
...
<view name="...">
<object>
...
</object>
...
</view>
</theme>
New way:
<theme>
<include>path/to/include1</include>
<include>path/to/include2</include>
...
<include>path/to/includeX</include>
<view name="...">
<object property1="value" property2="value" propertyX="value" />
...
</view>
...
<view name="...">
<object>
...
</object>
...
</view>
</theme>
The documentation presented here will focus on the new way of designing themes. The exact content is described in the other theme tutorials.
¶ How does it work?
Each system loads and reinterprets the theme. The theme should be considered as an entity that will be loaded and completely reinterpreted in the following cases:
- Once at startup, for what we internally call the “main” theme. From this instance, we will extract everything that is general and does not concern the systems, such as menu descriptors, for example.
- Once per system X. Here, the theme is completely reloaded and, above all, reinterpreted. This means that the system variables change each time, tests may give different results, etc.
¶ How <theme> and <view> tags work
¶ Tag <theme>
For this example, any xml file for the theme begins between the <theme></theme> tags.
¶ Properties
Tthis tag can contain 5 properties:
¶ name
- Required: ❌
The name property indicates the theme name. This can be different from the theme folder name. This name will be visible in the list of available themes.
Example:
name=“My own theme”
Without this property, the theme folder name will be used.
¶ recalbox
- Required: ❌
The recalbox property indicates the minimum version of Recalbox the theme can be used with. This allows you to indicate whether the theme is compatible with the version of Recalbox installed.
Example:
recalbox=“9.2”
Without this property, the theme can be used on any version of Recalbox.
¶ version
- Required: ❌
The version property indicates the version of the theme. If this information exists, it will be visible in the list of available themes.
Example:
version=“3.1”
Without this property, the theme version will not be displayed in the theme list.
¶ compatibility
- Required: ❌
The compatibility property indicates the type of screen the theme is compatible with. The theme can be compatible with a single screen type or several.
List of possible values:
hdmi: HDMI screenscrt: CRT screensjamma: JAMMA screenstate: TATE vertical screens
Example:
compatibility=“hdmi,jamma”
Without this property, the theme will be considered hdmi compatible only.
¶ resolutions
- Required: ❌
The resolutions property is used to indicate the resolution ranges with which the theme is compatible. It can contain several values.
List of possible values:
qvga: QVGA resolutions (<= 288p)vga: VGA resolutions (<= 576p)hd: HD resolutions (<= 920p)fhd: Full HD resolutions (> 920p)
Example:
resolutions=“hd,fhd”
Without this property, the theme will be considered hd, fhd compatible only.
¶ Tag formatVersion
The formatVersion tag is used to indicate the version of the content format governing the theme.
formatVersion="5"
¶ Tag <view>
The <view></view> tag and its child objects are described in the objects page.