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

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: "
    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
    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