ps2build C++ migration

This repository is the C++/ps2build transition of RiptOPL. These guides include the production project's full documentation; feature and hardware parity are still being validated. The release targets are Korium, RetroAchievements and IncebtIon, all on ps2build. Check the migration ledger before treating an imported production feature as verified here.

Favorites

Press R3 on any game or app to star it. A virtual Favorites page gathers every starred title from every connected device into one list — no matter which drive it lives on.

Favorites Page Start Mode ships Off

The Favorites tab ships Off under Settings → Game Sources → Favorites Page Start Mode — set it to Manual or Auto before the tab appears and R3 does anything. Use Manual to show the tab and control it yourself, Auto to have OPL manage it the same way it manages other device tabs, or Off to hide the tab and disable R3 entirely.

Quick start

Enable the Favorites tab

Open Settings → Game Sources and set Favorites Page Start Mode to Manual (or Auto). Save settings. A Favorites tab now appears alongside your device pages.

Star a game

Navigate to any game or app on any device page — USB, HDD, SMB, MMCE, anywhere. Highlight the title and press R3 (click the right analogue stick). A small star icon appears next to the title name to confirm it is starred. Press R3 again on the same title to remove the star.

Open the Favorites page

Switch to the Favorites tab. Every starred game you have, across all connected devices, appears here in one list. Cover art, per-game settings, Options — everything works exactly as it does on the source device page.

Launch normally

Select a title on the Favorites page and press Cross to launch it. The game boots through the same path it would on its source device (OPL core or Neutrino, depending on your per-game settings).

How it works

The Favorites page is a virtual aggregator — it does not copy or move games. Each entry is a live proxy to the original item on its source device list. Launching, cover art lookups, per-game config, and the Options/Info menu all forward to the source device as if you had selected the game there directly.

Stars are visible everywhere: a small star mark is drawn next to the title on both the source device page and the Favorites page.
If a device is disconnected (USB drive unplugged, SMB share unreachable, etc.) its starred titles are hidden from the Favorites list but are not lost — they reappear automatically when the device becomes available again.
BDM devices (USB, MX4SIO, iLink) can move between bus slots; RiptOPL re-matches the item by game ID and title across all slots, so a favorite does not break just because a drive appeared on a different port.
Rename and Delete are blocked on favorited titles and on any game accessed through the Favorites page. Un-star the game first if you need to rename or delete it.

Persistence and compatibility

Starred games are stored in favourites.bin, written into the same shared OPL config directory as your artwork, themes, and VMCs — typically mc0:/OPL/ or the root of whichever device holds your OPL config.

Shared with uOPL and wOPL

favourites.bin sits in the shared OPL folder, not in the RiptOPL-private settings area. If you have an existing favourites.bin written by uOPL or wOPL, RiptOPL will read it automatically on first boot and carry your starred games over. Your favorites will then be saved in RiptOPL's own versioned OFAV format on the next write. That OFAV format is RiptOPL's own — uOPL and wOPL cannot read it back, so the carry-over is one-way only.

The on-disk format uses an OFAV magic header, a version number, and an explicit record count, followed by one record per favorite. The reader checks the complete bounded file, including text terminators, trailing data and successful reads and close. A salvageable prefix may still appear, but an incomplete or unreadable list cannot be silently saved over.

Field	Value / limit
File name	`favourites.bin` (shared OPL config dir)
Format magic	`OFAV` (0x4641464F, little-endian)
Format version	3 (v1/v2 remain readable; v3 uses the old byte as an ISO / VCD / CUE / ELF kind)
Maximum favorites	512 entries
Maximum title length	255 characters + NUL (256 bytes)
Import from uOPL / wOPL	Automatic, read-only (one-way carry-over)

Saving and recovering Favorites

Each edit first writes favourites.bin.new, closes it and reads it back. Only after that copy matches does RiptOPL rewrite and verify favourites.bin. A failed primary write keeps the recovery copy. If the device has too little free space for staging, the edit fails and the old list stays intact; free space before retrying.

A complete readable primary always wins, including a list edited on a PC or a valid empty OFAV list. If the primary is missing or structurally incomplete, a complete native OFAV recovery copy can supply the list. Before another edit, RiptOPL restores and verifies that copy as the primary. Unknown versions, oversized files and read or allocation failures keep edits blocked, even if recovery entries can be shown.

Keep both files after a storage error

Copy favourites.bin and favourites.bin.new elsewhere before attempting manual recovery. Do not delete an unreadable primary just to make an edit succeed. Readback checks file contents; it does not prove that physical media has flushed writes or guarantee survival of a power cut. See the storage reference for the precedence and recovery rules.

Game Sources option

Favorites has one enable/startup option in Settings → Game Sources:

Setting	Values	Notes
Favorites Page Start Mode	Off / Manual / Auto	Off (default) hides the tab and disables R3 entirely. Manual shows the tab but does not auto-start into it. Auto behaves like Auto mode on a regular device tab.

R3 only works when Favorites Page Start Mode is on

When Favorites Page Start Mode is set to Off, pressing R3 does nothing — no star is set and nothing is written to disk. Enable the tab first.

PS2, PS1, ELF, and All in One views

Favorites keeps its own independent L3 ring. It is not pinned by the shared PS2/PS1 Game Display setting. Fresh configurations open on All in One; an existing valid saved shelf is preserved. Press L3 to cycle through:

PS2 — PS2 disc favorites only.
PS1 — POPSTARTER and Ember favorites together.
ELF — homebrew/app favorites only.
All in One — PS2, PS1, and ELF favorites together.

The mixed view keeps each row's real behavior: PS1 rows open PS1 options and launch through their own core; ELF rows use the app path; PS2 rows retain normal game options. All four stops remain available regardless of how ordinary device game pages are displayed.

Where you leave it is where you come back

The shelf you were last on is remembered across reboots, including a valid shelf saved by an older version. The same applies to every page L3 does something on — each device page and the APPS split side keep their own position. Pressing L3 never writes to storage: a position rides along with a write that already happens — launching a game, or saving settings — so toggling and then powering off without doing either is the one case that is not kept. If a remembered view stops being possible — you switched PS2/PS1 Game Display from Mixed to Both, say — it is discarded and the page opens on its default rather than on a view with no rows.

Covers in All in One keep their own shape

A PS2 case is portrait; a PS1 jewel case and an app box are square. On the mixed shelf every row's cover is drawn at the size its own media uses, instead of one shape being stretched onto all three — so PS1 and app covers stay square beside portrait PS2 covers. Themes size the three boxes with the favsMain, vcdMain and appsMain families; see Block families.

Theme support

The Favorites page renders using the favsMain element family (which falls back to the regular game-list main family when the theme defines no favsMain override). The star mark drawn beside favorited titles in any list uses the embedded fav_mark texture. Themes can override the appearance of the Favorites tab icon via the fav texture slot.

Covers are resolved per row, by media kind, so a mixed shelf never stamps one box on everything: an app favorite (sourced from the Apps tab) draws with the apps family, a PS1 favorite with the vcd family, and a PS2 favorite with the page's own favsMain element. Each brings its own geometry, case overlay and placeholder. Only the cover is redirected — the background, the texts and the list itself stay on favsMain, so nothing moves as you scroll.

For full details on element families and texture slots, see the Theme Engine reference.

What happens to a favorite when a device is not connected?

The record stays in favourites.bin — it is never deleted just because the source device is absent. When you open the Favorites tab, RiptOPL tries to resolve each stored entry against the currently loaded device lists. Any entry whose device is not available (drive unplugged, share offline, etc.) is simply hidden from the visible list. The moment that device is connected and its game list loads, the entry becomes visible again automatically — no action needed on your part.

Can I favorite a PS1 game?

Yes. PS1 titles shown on a device page can be starred with R3 just like PS2 games. In Both (L3) mode, L3 opens the PS1 page; in Mixed mode, L3 cycles to the PS1-only view. In PS1 mode, the PS1 list is already shown and L3 is disabled. They appear in Favorites and launch through the same row-specific core: POPSTARTER for VCD rows, Ember for CUE/game-folder rows. UDPFS and UDPBD can contribute Ember favorites but never POPSTARTER rows. See PS1 Games for how the PS1 view works.

Can I favorite a Neutrino-backed game?

Yes. Neutrino per-game settings are stored in the game's own per-game config file, not in the Favorites list. A favorited game that is set to use Neutrino will still launch via Neutrino when opened from the Favorites page, because the launch path proxies to the source device entry with all its settings intact.