Free components: extra="true" and <extras>

Why a component you add does not show up — and the two ways to declare it.

Two families of components

Within a view, Recalbox distinguishes:

• the elements it builds itself — the carousel, the game list, the help bar, the game's box art… They have a reserved name, and the theme merely adjusts them;
• the components you add — a text, an image, a color block, a video. These are the free components.

A free component must be declared as such

A free component placed directly in the view is not drawn: the machine only builds the elements marked extra. Two possible spellings, and they do exactly the same thing:

<image name="monLogo" extra="true">…</image>

<extras>
    <image name="monLogo">…</image>
    <text name="maMention">…</text>
</extras>

<extras> is a container: each of its children receives extra="true", in one go. It is shorter and more readable as soon as there are several components — it is what the studio writes.

What to remember

• <extras> is not a component: it is not drawn, it is not positioned.
• It does not nest in itself: an <extras> inside an <extras> has no extra effect.
• It works in the Systems view, the Game list and the Screensaver. ⚠️ Not in the Menu: the engine looks for no free component there. An <extras> written for the Menu view is read without error… and never draws anything.
• Elements with a reserved name stay outside: they already exist, you only adjust them.

In the studio, there is nothing to do: the components you add are automatically written inside <extras>, and the reserved elements outside.