Overlay System

FAQ
,
1

This is for the 2601.0 JACARANDA and 2606.0 ANDROMEDA releases only!

The overlay system allows PNG images to be layered with different functionality. When content starts, the system searches for overlays in a fixed order. As soon as a valid overlay is found, the search immediately stops and all images are cached for performance.

While the overlay system supports the majority of content, some external emulators or ports may not support overlays at all. This is expected behaviour.

Should also note that this is separate from the RetroArch overlay system. The MustardOS overlays can work in-conjunction with the RetroArch overlay system if you are creative. For example, you could place low battery images on top of the RetroArch Gameboy overlay to realistically show you the low battery signal.

This system opens up massive creative opportunities for supported systems and devices. We can’t wait to see what you can come up with. Hopefully in the future we are able to expand this functionality to offer shader support, but we cannot make any promises at this stage!

Overlay Overview

Overlays generally follow the same order:

  1. Overlay priority
  2. Resolution specific paths before generic paths
  3. Catalogue paths before theme paths
  4. Content > Core > Default

Each overlay type is resolved independently, meaning a base overlay may come from one location while indicators come from another.

Overlay Types and Priority

Overlays are drawn in a strict visual priority order, from highest to lowest:

  1. Volume indicator
  2. Brightness indicator
  3. Low battery indicator
  4. Base overlay image

This means:

  • Volume will always appear above everything else
  • The base overlay is always the bottom-most layer

Resolution Handling

The overlay stage system always checks resolution specific directories first. Resolution directories must be named exactly:

<width>x<height>

Examples:

  • 720x720
  • 1280x720

If no resolution specific overlay is found, the system falls back to a generic directory.

Filename Resolutions

Once a directory has been selected, filenames are checked in the following order:

Priority Type Example filename
1 Content Specific Battlezone (Japan, USA).png
2 Core Specific stella2014.png
3 Default Fallback default.png

Keep in mind that:

  • Content overrides core
  • Core overrides default
  • RetroArch core names must not include the _libretro suffix

Overlay Sources

Overlays can be loaded from two sources. The Catalogue and the Active Theme. Overlays check the catalogue system first then will fall back to the active theme paths.

Base Overlays

Base overlays provide the primary decorative, or frame, above content.

Base Overlay Directory

overlay/base/

Base Path Examples

info/catalogue/Atari 2600/overlay/base/640x480/Battlezone (Japan, USA).png
info/catalogue/Atari 2600/overlay/base/640x480/stella2014.png
info/catalogue/Atari 2600/overlay/base/640x480/default.png

info/catalogue/Atari 2600/overlay/base/Battlezone (Japan, USA).png
info/catalogue/Atari 2600/overlay/base/stella2014.png
info/catalogue/Atari 2600/overlay/base/default.png

theme/MustardOS/640x480/overlay/Atari 2600/base/Battlezone (Japan, USA).png
theme/MustardOS/640x480/overlay/Atari 2600/base/stella2014.png
theme/MustardOS/640x480/overlay/Atari 2600/base/default.png

theme/MustardOS/640x480/overlay/base/Battlezone (Japan, USA).png
theme/MustardOS/640x480/overlay/base/stella2014.png
theme/MustardOS/640x480/overlay/base/default.png

theme/MustardOS/overlay/Atari 2600/base/Battlezone (Japan, USA).png
theme/MustardOS/overlay/Atari 2600/base/stella2014.png
theme/MustardOS/overlay/Atari 2600/base/default.png

theme/MustardOS/overlay/base/Battlezone (Japan, USA).png
theme/MustardOS/overlay/base/stella2014.png
theme/MustardOS/overlay/base/default.png

Indicator Overlays

Indicator overlays are system-driven overlays shown in response to specific events.

There are three built-in indicators currently available:

  • Brightness
  • Low battery
  • Volume

Indicator Requirements

Each indicator must provide a complete 10 step image set.

  • All 10 images must exist (PNG of course)
  • Partial image sets are not supported
  • If any image is missing, the indicator will not be loaded

Indicator Naming Conventions

Indicator Directory Filename pattern
Brightness bright bright_0.png … bright_9.png
Low Battery battery battery_0.png … battery_9.png
Volume volume volume_0.png … volume_9.png

Value meaning:

  • 0 = minimum level
  • 9 = maximum level

Indicator Directory Layout

Example for volume overlays:

overlay/volume/

Resolution specific variants may be placed inside:

overlay/volume/720x720/

Indicator Path Examples

info/catalogue/Atari 2600/overlay/volume/640x480/volume_0.png
info/catalogue/Atari 2600/overlay/volume/volume_0.png

theme/MustardOS/640x480/overlay/Atari 2600/volume/volume_0.png
theme/MustardOS/640x480/overlay/volume/volume_0.png

theme/MustardOS/overlay/Atari 2600/volume/volume_0.png
theme/MustardOS/overlay/volume/volume_0.png

Position, Transparency, and Scale

You can adjust all currently supported overlay options within the Overlay Options menu found in Configuration. These options allow you to change:

  • Transparency - 0% to 100%
  • Position - 9 positions from Top Left to Bottom Right
  • Scale
    • None - The image will be presented at its original resolution
    • Scale - Image will take up the whole display but keep aspect ratio
    • Stretch - Places the image across the entire screen device
2 Likes