△◯✕□ RiptOPL DOCS
Downloads GitHub
/
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.

Troubleshooting

Step-by-step fixes for the most common RiptOPL problems — boot hangs, blank screens, video mode locks, white-screen game failures, BDMA driver errors, and PS1/VCD list issues.

i Still stuck after reading this page?
Report RiptOPL regressions in our issue tracker. Include version/SHA, SDK flavour, console model, game ID, source/protocol, core, steps, settings and any known-good build comparison. The upstream OPL forum remains a community resource. For PS1 internals (IGR, cheats, multi-disc, config table), see the sister POPStarter docs.

Symptom: RiptOPL hangs at the animated logo or a grey screen on every boot — the game list never appears.

First isolation check: Try skipping saved configuration. A bad config is one possible cause; a startup screen alone does not identify the failing subsystem.

Skip config on boot

Power on your PS2 and immediately hold START while RiptOPL initializes. Keep it held until the interface appears. This tells OPL to skip loading the saved config and boot with defaults instead. Expect to land on the start menu with no game-list tabs — that is what the defaults look like, since every device ships off — not on a game list.

Open and re-save settings

With the loader running (config skipped), open Settings and configure the options you need — at minimum, enable the device mode(s) you use. Then Save so a fresh, valid settings_riptopl.cfg is written.

Verify the fix

Reboot OPL normally (without holding any buttons). If it reaches the game list or settings screen without freezing, the bad config has been replaced. If it still freezes, record the exact build and active settings location and report the result; do not assume the file lives on the memory card.

Why does RiptOPL have its own config file?

RiptOPL's master settings use settings_riptopl.cfg (with migration from conf_riptopl.cfg). That filename is separate from stock OPL's master config, but conf_network.cfg, app lists, per-game configuration and support files can still be shared. Favorites import from uOPL/wOPL is one-way: the next write saves RiptOPL's own OFAV format to favourites.bin, which those loaders cannot read back. Keep an original copy if you use them too. The settings home follows boot-directory discovery or Custom Settings Path; do not assume it is always mc0:/OPL/.

Game stops on a white screen

A white or black launch screen alone does not diagnose fragmentation or a corrupt dump. Record the build/SDK, console, game ID, source and core before changing anything.

  1. Check the image against a known-good dump and verify that the copy completed.
  2. Try the title with game overrides disabled, checking inherited global defaults as well.
  3. If the loader reports a fragment-limit error, try a fresh sequential copy with sufficient free space. OPL's BDM table is shared across game image parts; Neutrino counts ISO and VMC fragments together against its 64-entry block-device budget.
  4. Compare a known-good build on the same setup and report where the launch stops.

Back up all data before considering a reformat. Do not reformat solely because of a screen colour. A successful retry after several changes does not establish which change fixed it.

No display on boot (blank or black screen)

Hold Triangle + Cross while RiptOPL initializes to force 480p for the menu. The display and connection must accept that signal. On a TV that only takes interlaced signals (a CRT, for example), hold Triangle + Circle instead: it forces Auto, the region's interlaced mode. Once visible, select a suitable mode under Interface, save, and retry. Holding START skips saved configuration and uses defaults.

Changing the video mode can't strand you this way: keeping a new mode takes a hold of Accept (about 2 seconds, until the bar fills), and Back or 10 seconds without an answer restores the previous mode. See Keeping a new video mode.

Menu works, but launching a game loses the picture

The menu recovery combo does not clear per-game GSM settings. Open the affected game's settings and disable/change its GSM override, or its Neutrino video options for that core. Check global video defaults too. Retry with the game's normal output before adding overrides again.

Internal HDD — code 402, 500, or "Formatted: NO"

Code 402: the HDD answered, but its APA partition table can't be read. wLaunchELF shows the same disk as "Connected: YES / Formatted: NO". Your games are almost certainly still on it. Do not format it. Stop using the disk, then follow the recovery steps under Internal HDD — Disk safety and code 402. Code 401 means the drive did not answer at all.

Code 500: a drive was not mounted because its sectors are not 512 bytes, as on a 4Kn drive. This applies to any USB, iLink, MX4SIO or internal exFAT drive: RiptOPL only reads 512-byte sectors. Ordinary 512e drives are unaffected.

Delete is missing on the HDD, or Rename on an HDD PS2 game: by design. RiptOPL does not edit the APA partition table, so the HDD library is managed from a PC with HDL-Dump.

PS1/VCD — "my VCDs don't show up" (works elsewhere)

Symptom: A device lists PS2 games fine (or works in another loader), but its PS1 view is empty — or a listed VCD does nothing when selected.

Work down this ladder; each step isolates a different stage:

Does the device page appear at all?

If not, it's the device enables, not VCD. Every device ships OFF on a fresh install, so check Game Sources first: USB/MX4SIO/iLink need their own toggles on and BDM Devices Start Mode set to Manual or Auto, and the internal exFAT page additionally needs Internal HDD (exFAT) ON. The two internal-HDD backends are no longer mutually exclusive — APA (HDD start mode) and exFAT/BDM-ATA may both be enabled at once, since one shared ATA stack serves both, so leaving APA on does not suppress the exFAT page.

Do PS2 ISOs list from the device?

If yes, the filesystem/mount layer is proven working, so "but it works in another loader" adds no new information past this step. The release publishes four labelled flavours: PS2DEVPINNED, OFFICIALPINNED, PS2DEVROLLING, and OFFICIALROLLING. Start with the pinned primary control, and report the exact in-app suffix if behavior differs across flavours.

Check PS2/PS1 Game Display

Both (L3) switches separate PS2 and PS1 views. Mixed combines them and L3 cycles Mixed / PS2 / PS1. The locked PS2 and PS1 modes intentionally make L3 fully inert; choose PS1 to pin the PS1 view without L3.

Check the folder — root, not your games prefix

VCDs are scanned from <device-root>:/POPS/*.VCD. The game-folder prefix (usb_prefix etc.) is deliberately not applied, because POPSTARTER itself only reads /POPS at the root. A POPS folder inside your games subfolder will never be found.

Check the filename

Basenames longer than 160 characters and the reserved name POPSTARTER.VCD are skipped at scan (the debug log says which) — previously they listed but could never launch (a dead ✕ button). Rename the file.

Fails only after selecting a game?

Then scanning is fine and the handoff is the suspect: is POPSTARTER.ELF present in /POPS (or __common/POPS on APA)? On exFAT the BDMA equip below is best-effort — a failed equip toasts but the launch still proceeds and may land on the OSD.

PS2 list empty — "Could not open the CD or DVD folder"

Symptom: A USB, MX4SIO, iLink, UDPBD or internal exFAT page shows no PS2 games (its PS1 view may be fine), and RiptOPL says Could not open the CD or DVD folder in mass0: (error 5), so that device lists no PS2 games. Press SELECT on its page to try again.

RiptOPL tried to open both the CD and the DVD folder at the path it names, neither would open, and there is no ul.cfg either. The path is the device plus your BDM Prefix Path, if you set one (mass0:OPL/, for example). An empty or missing folder on a healthy device does not cause this: RiptOPL creates CD and DVD the first time it sees a device, and an empty folder is simply an empty list.

Read the error number

5 — input/output error: the device refused the read. Usually a failing card or stick, a damaged filesystem, or a device dropping off the bus. 2 — the folder is not there and could not be created (a full or read-only device, or a Prefix Path pointing somewhere that cannot be created). 13 — access denied. 0 — the driver failed without saying why. Any other number: include it in your report.

Check the path it names

If it includes a BDM Prefix Path, make sure that folder exists on that device and holds your CD/DVD folders. PS1 games are read from the device root, which is why that view can still work.

Check the device on a PC

For error 5, run a filesystem check (or reformat and re-copy) before anything else.

Press Select to try again

RiptOPL does not keep retrying on its own. It used to rescan such a page every couple of seconds for as long as it was up, rebuilding Apps and Favorites each time, which made L3 and everything else wait on every page. Now it scans once, tells you, and waits for you.

Test control: On an SCPH-39001 with the same IEEE 1394 HDD, Ember launched in all four revision 2692 flavours. Native OPL, Neutrino, and POPSTARTER did not. Both pinned and rolling builds from both SDK lineages failed, so the result is not isolated to one compiler image.

BDMA — "module files not found on source device"

Symptom: You have set a BDMA Mode (e.g. USB (exFAT), MX4SIO (exFAT), HDD (exFAT), or iLink) and a BDMA Source, but when you save or apply the equip RiptOPL reports that the module files were not found on the source device.

Cause: The BDMA module files (.irx driver pair for the chosen variant) are missing from or in the wrong location on the source device. RiptOPL does not embed these files — you supply them from the release's POPS/ folder.

Locate the module files

The BDMA module files ship loose inside the RiptOPL release archive; none is embedded in RIPTOPL.ELF. Find the POPS/ folder in the release zip — it contains the driver variants for each equip mode, including usbd.irx.ilink + usbhdfsd.irx.ilink for iLink.

Copy them to the correct location

Place the module files in a POPS/ folder at the root of whichever device you have set as the BDMA Source — USB, MX4SIO, MMCE, iLink, or Internal HDD. The path must be exactly:

POPS/        ← folder at device root
  POPSTARTER.ELF
  <module files for your chosen variant>

Note: the source must match the device's driver

RiptOPL resolves the BDMA Source by its block-device driver, not by scanning the whole massN: namespace. A USB source reads only usb slots; MX4SIO reads only mx4sio slots; iLink reads only ilink slots; and Internal HDD reads only the ata (exFAT) HDD. Set the source to match the driver of the device where the loose pair actually lives.

Re-apply the equip

With the files in place, open Settings → PS Emulation Settings — the BDMA rows are on that page, not on General & System — set BDMA Source / BDMA Mode, and save. (The two manual pickers are hidden while VCD BDMA Apply on Launch is ON, because that option equips automatically; turn it off to set them by hand.) RiptOPL will copy the modules to mc?:/POPSTARTER/ and record the equipped state in a marker file (compatible with POPSLoader).

What exactly does "equipping" BDMA do?

POPSTARTER's built-in path handles ordinary USB FAT32; the other supported block transports use matching external modules. When you change BDMA Mode or Source and save, RiptOPL copies the chosen suffixed pair from your source device's POPS/ folder to mc?:/POPSTARTER/, removing the variant suffix on the card. For example, *.ilink becomes plain usbd.irx + usbhdfsd.irx. Setting BDMA Mode back to USB (FAT32) removes the external pair so POPSTARTER falls back to its built-in driver. SMB is excluded because it is network-only and has no block device to equip.

PS1 / VCD list not showing after a settings change

Symptom: You have VCD files on a device but after changing PS2/PS1 Game Display, enabling a device, or changing BDMA settings, the PS1 list is empty or appears stuck on PS2.

Fix: First distinguish a pinned view from missing content:

i POPS UDPFS launch preparation
UDPFS Files lists uppercase POPS/*.VCD with Ember titles. For POPSTARTER, follow BDM-UDPFS Assault setup: keep non-VCD POPS runtime files on USB, save matching valid network configs on every connected USB volume, and equip the matching memory-card driver pair. A missing dummy USB VCD is not an error; absent VCDs fall back to the server. The launch refuses an unready driver pair or the known USB-only RA module before teardown. UDPBD and UDPFS IMG remain Ember-only. The C++ handoff still needs physical-console acceptance.
i Favorites always has four views
Press L3 on Favorites to cycle PS2 → PS1 → ELF → All in One. This independent ring is not pinned or disabled by PS2/PS1 Game Display. Fresh configurations open on All in One; an existing valid saved shelf is preserved, and Favorites returns to that remembered shelf.

Japanese game names show squares or garbled characters

Install an appropriate font_CJK.ttf beside the active settings_riptopl.cfg, not just the LNG/ directory, and fully restart. Fonts don't convert Shift-JIS filenames to UTF-8. See Unicode title troubleshooting.

Quick-reference button combos

Boot combos only. For every button RiptOPL responds to — the game list, menus, and the in-game In-Game Reset combinations — see Controls.

Problem Boot combo Effect
Freeze on logo / grey screen (bad config) START Skips config load; boots with defaults
Blank / black screen (unsupported video mode) Triangle + Cross Forces 480p for the menu only; requires a compatible display/connection
Blank / black screen on an interlaced-only TV (CRT) Triangle + Circle Forces Auto, the region's interlaced mode, for the menu only
Menu works; game video failsNo boot combo clears game overridesDisable/change GSM or Neutrino video settings and check global defaults

More help

PS1 Games (VCD)Full setup guide for POPSTARTER and BDMA Neutrino CoreTroubleshoot Neutrino launch failures Network BootUDPBD / UDPFS setup and common errors GSM Video ModesGame launches but the screen goes black? In-Game ResetCannot quit a game from the pad? ControlsEvery button, plus the 480p boot recovery combo Settings ReferenceEvery option explained POPStarter docsPS1 config, IGR, cheats, multi-disc Bug report threadReport game-specific compatibility issues

VMC creation or layout errors

For first-launch automatic creation, a slow working job has no two-minute cutoff. After cancellation, stay in the menu while cleanup finishes. A failed format can leave an image with the expected file size; see the known failed-format retry limitation before treating a retry as recovery.

  1. Back up any existing card. Record the exact error text and whether it appears during creation, after progress finishes, or during launch.
  2. Check that the game's device has a writable VMC/ directory and enough space. For network cards, verify the server/share allows writes.
  3. Use the current rolling release before comparing MMCE behavior; its unsupported-query fix does not prove that a USB card is contiguous.
  4. Record the core (OPL or Neutrino), transport and filesystem. Native BDM VMC needs contiguous storage; Neutrino's game and card mappings share a fragment budget. See VMC layout checks.
  5. If retrying changes the result, include the before/after error, card filename and whether reboot brings it back. Avoid recreating a card containing the only copy of your saves.

Details to include in a bug report

PS2 MODEL:
OPL VERSION:
LOADER (MMCE, HDD, SMB, UDPFS, ETC):
CORE (OPL / Neutrino / POPSTARTER / Ember):
FILESYSTEM:
SETTINGS CHANGED:
VMC ENABLED/DISABLED:
PADEMU ENABLED/DISABLED:
EXACT ERROR AND REPRODUCTION STEPS:

Report a RiptOPL UI, configuration or handoff regression in RiptOPL's tracker. If the game failure also reproduces in standalone Neutrino with the same arguments and files, report it to Neutrino and link the related report. Include a known-good version comparison when available; a black screen alone does not identify the responsible component.

Setup questions and reporting launch failures

Which build should I download?

The ready-to-copy app and the unsuffixed standalone release ELF deliberately prefer OFFICIALROLLING when available. PS2DEVPINNED is the recommended conservative comparison build because its toolchain is pinned. These are different policies: the package default is not a claim that a moving SDK is the most reproducible choice.

Use a named flavour from the same release when comparing behavior. Record its complete suffix; a successful build does not prove that it boots on your console. Keep the disk, configuration and selected core unchanged during a comparison. A failure in one flavour is evidence to investigate, not proof by itself of an SDK defect.

Does Browser mean the memory-card browser?

Exiting to Browser hands control to the PS2's OSDSYS system interface. Seeing OSDSYS is expected. The eventual screen also depends on the console's installed boot/menu modifications. This option does not launch wLaunchELF's file browser. If you want a particular homebrew menu, configure its ELF as the exit target instead.

Why is another language unavailable?

English is built in. Other menu languages need the matching lang_*.lng files and, when required, their fonts on an enabled, readable source. Keep the language pack aligned with your build: older packs can lack new strings, which fall back to English. Apply the interface language and save settings to retain it across boots. This is separate from a game's language setting and the console's OSDSYS language.

Neutrino worked, then returned to OSDSYS

Follow the complete Neutrino installation and path guide. RiptOPL may remain in APPS/; moving its own folder to the card root is not a general fix. An explicit Neutrino path must point to an ELF accompanied by its complete installation.

Record the exact build, game, game device, Neutrino installation path/version, selected core, VMC state and forced video setting. Include any displayed error and whether failure occurs before or after Neutrino takes control. Compare with forced video off and physical memory cards only after recording the original settings. A reset alone cannot distinguish an ELF handoff problem, runtime module failure, game incompatibility or unsupported launch option.

More noise at startup

Enabling an internal HDD source can initialize and spin up the disk even if another source is the startup page. Describe whether the noise comes from the HDD, optical drive or fan, and which sources are enabled. A report of increased noise alone does not identify a software regression or justify changing disk power behavior.

What do Neutrino's 1080i x1, x2 and x3 mean?

All three select 1080i output. They change the display scaling, rather than making the game render at a new resolution or frame rate. In Neutrino's scaling code, the nominal horizontal mapping uses factors of 1, 2 and 3 respectively (640, 1280 and 1920 relative to its 640-wide baseline); x1 also halves its target framebuffer/display height before calculating the scaling. These numbers describe the output mapping, not newly rendered game detail. The result depends on the game's framebuffer/field mode and your display's handling of interlaced output.

Start with forced video Off when diagnosing a launch or display failure, and choose a preset per game after establishing a working baseline. x3 is not a 1080p mode and is not universally the best choice. See Neutrino's scaling implementation.

RiptOPL, Neutrino and other frontends

Neutrino is a game-loading core; RiptOPL can launch it or use OPL's native core. LUNA is another frontend for Neutrino. Choosing a frontend and choosing a core are separate decisions. Consult each project's own release and supported-device documentation before moving a working setup; a different frontend is not automatically a fix for a storage or runtime problem.