Making themes

A theme is a folder of files that replace the console's own menu files. This page covers what Theme Selector expects from that folder. It doesn't cover drawing the graphics themselves.

The theme folder

Name the folder in lower snake_case, without spaces, e.g. my_theme. Don't start it with diy_theme: that name is reserved for DIY themes.

Inside it, mirror the console's own menu folder and put only the files you replace, at the same paths:

Console	Menu folder on the console
SNES (USA)	`/usr/share/ui/snes-usa`
SNES (EUR)	`/usr/share/ui/snes-eur`
Super Famicom	`/usr/share/ui/shvc`
Famicom Shonen Jump	`/usr/share/ui/hvc`
NES / Famicom	`/usr/share/clover-ui`

For example, to replace the SNES background sprite sheet, my_theme/resources/sprites/packed.png goes over /usr/share/ui/snes-usa/resources/sprites/packed.png.

my_theme/
├── resources/        same layout as the console's menu folder
├── fonts/            optional, see Fonts
├── extras/           optional, see DIY preview
└── info              optional, see Name
my_theme.png          the preview, next to the folder

Only replace, don't add

When every file in your theme replaces one the console already has, each file is mounted over its original and every option works.

If your theme adds files the stock menu doesn't have, the whole theme is mounted as an overlay instead. It still works, but the Audio Randomizer is unavailable while it's applied.

Theme Selector decides this the first time it lists the theme and writes a bind_ok or needs_overlay marker in the folder. Don't ship those markers in your theme.

Music

The menu music lives in resources/sounds/hvc/: bgm_home.wav plays on Home and bgm_boot.wav at boot. The menu sound effects (se_sys_*.wav) are in the same folder and can be replaced too. A theme with any .wav file of its own keeps its music when Audio Randomizer → All Folders is on.

Fonts

Put replacement fonts in fonts/: title.fnt, and for the menu text s.fnt, m.fnt, l.fnt (or small.fnt, medium.fnt, large.fnt). They are AngelCode BMFont files, like the console's own. Applying the theme needs the Font Remount mod, which hakchi installs by default.

A theme without a title.fnt gets the console's own title font back.

Lua scripts

The menu's .lua files (the palettes in resources/scripts/env/, for example) are compiled, so they can't be edited as they come off the console. Decompile them first, edit them, then compile them again before putting them in your theme. (S)NES Mini - Lua Compiler does both (Decode / Encode); you can also do it by hand with LuaJIT.

Other regions

You don't need a separate theme per region:

the USA/EUR firmwares name the menu fonts *.font and the Super Famicom *.fnt; dependencies.json is adjusted to whichever the console has;
each firmware reads its own palette, resources/scripts/env/colors_<region>.lua. A theme that only has another region's palette gets it applied anyway;
on a NES/Famicom, the sprites and palette named after the other console (hvc ↔ nes) are renamed to match.

Name

The grid shows the folder name in title case plus its size, e.g. my_theme → My Theme [12.3Mb]. To choose the name yourself, put a text file called info in the folder:

NAME=My Theme

Preview

Put a 569×320 PNG named after the folder next to it: my_theme.png next to my_theme/. How to make one: Guides → Theme previews.

DIY preview

If your theme has its own Base UI (packed.png), the DIY theme builder shows it as a cropped tile. To show a picture of your choice instead, add extras/preview_baseui.png.

Files in extras/ are never read by the menu and don't count as added files (see Only replace, don't add), so it can also hold anything else that isn't part of the theme.

Packaging

To share a theme, pack the folder (with the folder itself at the top of the archive) as a .tar.gz named after the console and the folder:

tar -czf SNES.my_theme.tar.gz my_theme

Use SNES. for the SNES and Super Famicom, NES. for the NES and Famicom, and SHONEN. for the Famicom Shonen Jump. Copied into the themes folder (see Usage → Adding themes by hand), the package is unpacked the next time Themes is opened. Packages with another console's prefix are left alone.

To suggest a theme for the download catalog, open an issue in om-theme-downloads with the package and its preview. I review it and add it myself.