Theme Engine

A RiptOPL/OPL theme is a folder of images, fonts and one text file — conf_theme.cfg — that lays out the whole UI on a virtual 640×480 canvas. This page is the complete authoring reference: every block family, every element type, every property and value token the parser in src/themes.c actually understands, including this fork's Coverflow carousel and the two-layer overlay system. Nothing here is invented — if a key isn't listed, the engine ignores it.

1 · File & folder structure

Themes live in the THM support folder. Each theme is its own sub-folder whose name must start with thm_; the loader strips that prefix to form the name you see in the theme picker. Inside the folder, all the artwork/fonts sit alongside a single conf_theme.cfg.

THM/
  thm_MyTheme/
    conf_theme.cfg      ← the layout (this page)
    incebtion.png       ← background, fonts, case art, screenshots… (any names you reference)
    case.png
    myfont.ttf

RiptOPL also ships two built-in themes you can study as references without copying any files: the classic <OPL> theme and this fork's default <Coverflow> theme. Their sources are misc/conf_theme_OPL.cfg and misc/theme_coverflow.cfg in the repository — both are reproduced and annotated lower down.

conf_theme.cfg is a plain key/value file with exactly two kinds of line:

• Global (top-level) properties — bare key=value lines, written before any block.
• Element blocks — a blockname: header line followed by indented key=value lines.

# lines beginning with '#' are comments — comment a whole block to disable it
bg_color=#182580          # a global property

main0:                    # an element block
    type=Background
    pattern=BG

2 · Block families & the contiguous-numbering rule

Element block names carry a family prefix plus an index — e.g. main0, main1, appsMain2, vcdInfo3. Each family targets one screen/view. The base families are main<N> (the games list/menu page) and info<N> (the game info page). On top of those, this fork adds three per-slot override families. For every slot N the engine looks for the family's block; if it's absent it falls back down a fixed chain — so you override only what differs and inherit the rest.

The parser reads as many base main<N> blocks as you define, then for each slot 0…N resolves every family against that chain. Practically:

• A theme with only main*/info* blocks looks identical on the games, apps, Favourites and PS1 views — every family inherits the base.
• Define appsMain5 to give the apps cover its own (square) box while games keep their portrait box; everything else still inherits main*.
• The VCD/PS1 main family falls back to appsMain before main, so a PS1 disc with no vcdMain blocks automatically uses the square apps box (jewel-case art is square), while vcdInfo falls back to the rich game info page.

3 · Global properties

These go at the top of the file, outside any block.

Colours (#RRGGBB)

Colours are 8 bits per channel in hex; alpha is fixed internally (the parser sets it for you).

Fonts

Reference a font from an element with font=N (0 = default). font1=builtin is not a real token: the parser builds the path <theme>/builtin, that file doesn't exist, so the load fails and the slot falls back to the embedded default font. The <Coverflow> theme relies on this file-not-found fallback (and for the built-in <Coverflow> the font keys aren't parsed at all, since font loading is skipped for buffer-loaded built-in themes).

Other global keys

4 · Common element properties

Every element block starts with type=<ElementType> (see §5). Almost all of them also accept these positioning/appearance properties:

Value tokens: POS_MID and DIM_INF (above), and #RRGGBB for colours. Negative x/y anchor to the right/bottom edge — let those and the tokens do the work instead of hard-coding resolution-specific numbers.

5 · Element types

Set with type=. Elements marked (item) redraw whenever you move the selection.

Text-element extras

List extras

Per-device placement (devices=) — this fork

Normally one MenuIcon, one ItemsList and one HintText serve every device page, so they share a single position. devices= lets a theme place them differently per device: an element with the key draws only on the listed pages, and an unfiltered element of the same type automatically stands down there (no key needed on it), staying the default everywhere else.

# The shared icon spot, used by every page not claimed below.
main3:
type=MenuIcon
x=POS_MID
y=400

# On the MMCE and APA-HDD pages, pin the icon top-right instead.
main4:
type=MenuIcon
devices=mmce,hdd
x=-40
y=24

Device names (comma-separated, case-insensitive):

Rules worth knowing:

• Only MenuIcon, ItemsList and HintText honour the key; on other element types it parses but has no effect.
• Matching follows the page's visible device icon, so a BDM page counts as usb/mx4sio/… once its driver is identified, and as bdm before that. In the PS1/VCD (L3) view the page keeps the device's identity — filters keep working there via the vcdMain* family.
• A filtered ItemsList is an override: it does not consume one of the theme's ItemsList slots (games/apps/favs/VCD, claimed in file order), and navigation/paging automatically follows whichever list is drawn. Give it its own x/y/height (its row count comes from height); decorator= works as usual.
• Keep one unfiltered ItemsList. If every list in the theme carries devices=, OPL adds a plain default list (373×316 at 42,42) on the pages nothing covers — navigation always needs a list — and it won't match your layout.
• Unknown device names are logged and skipped; if nothing valid remains, the element behaves as if the key were absent (shared placement) rather than disappearing.
• Two filtered elements of the same type may list different devices; listing the same device twice draws both — that's an authoring error, not a picker.
• Themes without the key are untouched — the filter only activates when devices= appears.

Using RiptOPL themes on regular OPL

RiptOPL themes are designed to load on regular/upstream OPL and degrade gracefully — one theme can serve both. Regular OPL's parser never aborts on fork content: keys it doesn't know (devices=, reflection_offset, overlay2, plasma_blend_color, the entire favsMain* and vcdMain* families…) are simply never read, and unknown element types (Coverflow) are skipped without stopping the parse. What to expect there:

• Invisible: all pure-key extras above — regular OPL renders the theme as if they weren't written.
• Cosmetic: aligned=2 renders centered; #Size/#DiscType/#System attributes and the Coverflow carousel are silently absent.
• Ugly but harmless: devices= layouts — regular OPL draws every MenuIcon/HintText block on every page (overlapping), and treats a second ItemsList as the apps list while still drawing it on the games screen. Per-device layouts are effectively RiptOPL-only.
• ⚠ The one rule: always include one plain (unfiltered) ItemsList. A theme with none — e.g. a Coverflow-only theme, or one where every list carries devices= — crashes regular OPL on the first scroll (a latent upstream bug in its default-list repair; RiptOPL fixed it on our side). Ship the plain list and the theme is safe everywhere.

6 · Image & overlay properties (incl. the two-layer system)

Image-type elements (StaticImage, GameImage, Background, AttributeImage, ItemCover, Coverflow) add these:

The four overlay corners describe where the inner art sits within the overlay frame, in the element's own coordinate space (relative to width/height). They scale with the drawn element, so the cover window tracks the art at any size. Omitted corner keys default to 0.

7 · attribute= values

AttributeText (metadata text)

For type=AttributeText, set attribute= to a metadata key. The label is auto-localised (override it with title=):

AttributeImage (badge chosen by the game's value)

For type=AttributeImage, set attribute= to one of the keys below. OPL reads the game's current value for that attribute; where the glyph comes from depends on the theme:

• Built-in <OPL> theme — draws the embedded glyph whose internal name equals the value: #System=PS2 → PS2, #Media=CD → CD, #Format=ISO → ISO. Attributes with no embedded glyph (e.g. #DiscType) draw nothing here.
• Disk theme — loads <value>_<attribute>.png from the theme folder (value first, the same <name>_<suffix> shape as cover art <id>_COV.png): PS2_#System.png, CD_#Media.png, PS2DVD_#DiscType.png. A default= gives the fallback badge.

8 · Built-in default= asset names

You can point default= or overlay= at any of OPL's embedded textures — no file needed. (For a theme folder, a same-named file overrides the built-in.)

settings_bg is theme-supplied only (no embedded default). Legacy Device_* indicators were removed in this fork — use the device icons and Index_* above.

9 · The Coverflow element

type=Coverflow (this fork) renders the game/app list as a centred cover carousel with a reflection and slide animation. It behaves like a GameImage — it uses the same COV cover cache and overlay/corner system — but draws 3 or 5 covers fanned out around the selection. The first Coverflow element the parser sees flags the theme as "Coverflow active", which unlocks the live Coverflow Settings menu.

Per-theme properties (in conf_theme.cfg)

A minimal three-family Coverflow setup (the shape the fork's <Coverflow> theme uses):

main2:
    type=Coverflow
    default=cover
    reflection=1
    y=197
    width=184
    height=256        # portrait PS2 case
    overlay=case
    overlay2=case_overlay
    overlay_ulx=0    overlay_uly=0    overlay_urx=184  overlay_ury=0
    overlay_llx=0    overlay_lly=256  overlay_lrx=184  overlay_lry=256
appsMain2:
    type=Coverflow
    default=coverapp
    reflection=1
    y=239
    width=184
    height=184        # square apps box
    overlay=case
    overlay2=case_overlay
    overlay_ulx=0    overlay_uly=0    overlay_urx=184  overlay_ury=0
    overlay_llx=0    overlay_lly=184  overlay_lrx=184  overlay_lry=184
vcdMain2:
    type=Coverflow
    default=cover
    reflection=1
    y=239
    width=184
    height=184        # square PS1 jewel-case box
    overlay=case
    overlay2=case_overlay
    overlay_ulx=0    overlay_uly=0    overlay_urx=184  overlay_ury=0
    overlay_llx=0    overlay_lly=184  overlay_lrx=184  overlay_lry=184

Global Coverflow tuning (NOT in the theme)

These live in settings_riptopl.cfg and are exposed in the Coverflow Settings menu (shown while a Coverflow theme is active). They apply to any Coverflow theme and are clamped on load:

The per-theme horizontal nudge coverflow_cover_offset is the one Coverflow knob that does live in the theme (a global key — see §3). For the in-menu walkthrough of these settings, see Coverflow.

10 · Coordinates & scaling

11 · Worked examples

An info-page metadata label

info3:
    type=AttributeText
    attribute=Title       # the game's title…
    color=#ffffff
    display=0             # 0 = always show "Title: <value>"
    aligned=0            # anchor top-left at (x,y)
    x=33
    y=70

Switch display=2 to drop the "Title: " label and print the value alone; add wrap=1 with a width/height box for a long Description.

A framed cover with the two-layer case

main5:
    type=ItemCover         # selected game's cover, COV cache
    default=cover         # fallback when art is missing
    x=-128                # 128px in from the right edge
    y=240
    overlay=case          # layer 1: plastic case frame
    overlay2=case_overlay # layer 2: foliage/decoration, over the cover
    overlay_ulx=0    overlay_uly=0
    overlay_urx=184  overlay_ury=0
    overlay_llx=0    overlay_lly=256   # cover window = full 184×256 of the frame
    overlay_lrx=184  overlay_lry=256

A screenshot with a bezel overlay

info14:
    type=GameImage
    pattern=SCR           # first screenshot cache
    default=screen
    x=189
    y=-150               # 150px up from the bottom
    scaled=1             # any non-zero = ratio-correct (same as 1)
    width=200
    height=150
    overlay=screens       # 1px inset bezel around the shot
    overlay_ulx=1    overlay_uly=1    overlay_urx=199  overlay_ury=1
    overlay_llx=1    overlay_lly=149  overlay_lrx=199  overlay_lry=149

12 · A complete, annotated sample theme

This is the shipped default <OPL> theme (misc/conf_theme_OPL.cfg), annotated. It is a full, valid conf_theme.cfg — copy it into THM/thm_MyTheme/, edit, and you have a working theme. Note the contiguous numbering and the single appsMain5 override that swaps the games' portrait cover box for the apps' square one.

# ── Global colours ───────────────────────────────────────────────
bg_color=#182580          # plasma tint
sel_text_color=#ffffff    # selected list row
text_color=#324d9e        # default text
ui_text_color=#00FFFF     # menus / hints

# ── Games LIST page (main*) ──────────────────────────────────────
main0:                    # element 0 MUST be the Background
    type=Background
    pattern=BG            # plasma background
main1:
    type=StaticImage
    default=incebtion     # embedded background art
    aligned=0
    scaled=0
    width=DIM_INF         # fill the screen
    height=DIM_INF
main2:
    type=StaticImage
    default=ip            # small corner image
    x=-132               # 132px in from the right
    y=20
    aligned=0
    width=16
    height=16
main3:
    type=MenuIcon         # current device icon
    x=0                   # (add devices=mmce,hdd,… to place this per device — see §5)
    y=0
    aligned=0
    scaled=0
    width=DIM_INF
    height=DIM_INF
main4:
    type=ItemsList        # the scrolling game list (first ItemsList = games)
    x=30
    y=70
    aligned=0
    width=400
    height=350
main5:
    type=ItemCover        # selected cover, with the two-layer case frame
    default=cover
    x=-128
    y=240
    overlay=case          # layer 1 (plastic case)
    overlay2=case_overlay # layer 2 (over the cover)
    overlay_ulx=0    overlay_uly=0
    overlay_urx=184  overlay_ury=0
    overlay_llx=0    overlay_lly=256   # portrait 184×256 window
    overlay_lrx=184  overlay_lry=256
appsMain5:                # APPS override of slot 5: square cover box
    type=ItemCover
    default=coverapp
    x=-128
    y=-198               # 198px up from the bottom
    overlay=case
    overlay2=case_overlay
    overlay_ulx=0    overlay_uly=0
    overlay_urx=184  overlay_ury=0
    overlay_llx=0    overlay_lly=185   # square 184×185 window
    overlay_lrx=184  overlay_lry=185
main6:
    type=LoadingIcon      # animated spinner (one per theme)
    x=-320
    y=-240
main7:
    type=BdmIndex         # active mass-device slot indicator
    x=7
    y=-35
    width=4
    height=32

# ── Game INFO page (info*) ───────────────────────────────────────
info0:
    type=Background
    pattern=BG
info1:
    type=StaticImage
    default=incebtion
    aligned=0
    scaled=0
    width=DIM_INF
    height=DIM_INF
info2:
    type=StaticImage
    default=ip
    x=-132
    y=20
    aligned=0
    width=16
    height=16
info3:
    type=AttributeText    # Title:
    attribute=Title
    color=#ffffff
    display=0
    aligned=0
    x=33
    y=70
info4:
    type=AttributeText    # Developer:
    attribute=Developer
    color=#ffffff
    display=0
    aligned=0
    x=33
    y=89
info5:
    type=AttributeText    # Size: (auto-suffixed " MiB")
    attribute=#Size
    color=#ffffff
    display=0
    aligned=0
    x=33
    y=108
info6:
    type=AttributeText    # word-wrapped description box
    attribute=Description
    display=0
    color=#ffffff
    aligned=0
    x=33
    y=127
    width=590
    height=60
    wrap=1
info7:
    type=AttributeImage   # disc badge (CD/DVD/APP)
    attribute=#Media
    default=APP
    width=32
    height=16
    x=55
    y=-252
info8:
    type=AttributeImage   # format badge (ISO/ELF/…)
    attribute=#Format
    default=ELF
    width=32
    height=16
    x=86
    y=-252
info9:
    type=AttributeImage   # video-mode badge
    attribute=Vmode
    default=missing
    width=32
    height=16
    x=117
    y=-252
info10:
    type=AttributeImage   # aspect badge
    attribute=Aspect
    default=missing
    width=32
    height=16
    x=148
    y=-252
info11:
    type=AttributeImage   # scan-mode badge
    attribute=Scan
    default=missing
    width=32
    height=16
    x=179
    y=-252
info12:
    type=AttributeImage   # players badge
    attribute=Players
    default=missing
    width=32
    height=16
    x=210
    y=-252
info13:
    type=AttributeImage   # rating badge
    attribute=Rating
    default=no_Rating
    x=-76
    y=-252
    width=128
    height=16
info14:
    type=GameImage        # screenshot 1, with a 1px bezel overlay
    pattern=SCR
    default=screen
    x=189
    y=-150
    scaled=2              # any non-zero = ratio-correct (same as 1)
    width=200
    height=150
    overlay=screens
    overlay_ulx=1    overlay_uly=1    overlay_urx=199  overlay_ury=1
    overlay_llx=1    overlay_lly=149  overlay_lrx=199  overlay_lry=149
info15:
    type=GameImage        # screenshot 2
    pattern=SCR2
    default=screen
    x=-191
    y=-150
    width=200
    height=150
    overlay=screens
    overlay_ulx=1    overlay_uly=1    overlay_urx=199  overlay_ury=1
    overlay_llx=1    overlay_lly=149  overlay_lrx=199  overlay_lry=149

See also