RetroAchievements

RiptOPL can report a running game's memory to a PC client that runs rcheevos on the console's behalf, so achievements unlock on real PlayStation 2 hardware.

The console does two things: it works out which game an image or physical disc is (a hash), and once the game is running it streams the handful of memory addresses that game's achievements depend on. Everything else — talking to the RetroAchievements servers, deciding what unlocked, your login — happens on the PC.

Based on the RetroAchievements implementation by hacan359 (yoba). Use the upstream xeRAbora PC client with RiptOPL's RA build.

Status

Implemented, not yet validated on PS2 hardware. Every part below exists in the build; not one of them has run on a PlayStation 2. Treat the RA variant as a development build until that changes.

Using it

Two settings, on the Network settings page:

Two actions on a game's own menu:

• check game support — hashes the image, asks the PC client about it, and writes <device>/RA/<serial>.wl if the game is tracked.
• test PC link — confirms the console can find the client at all, without touching a game.

A game the console has a watch list for shows the badge and the cover mark after the next list refresh. Switch telemetry on and launch it.

Physical discs

Use an RA build and the upstream xeRAbora PC client. Insert a PS2 game disc, then open RiptOPL's main menu:

1. Choose RA: check disc support. RiptOPL hashes the disc's boot executable and asks the PC client for its watch list. The check runs in the background and reports its result on screen.
2. Enable RetroAchievements telemetry in Network settings.
3. Choose RA: launch disc. This action requires a watch list for the disc currently in the tray.

Disc watch lists and hash logs use RA/ inside the active settings folder: for example, mc0:/OPL/RA/SLUS_201.74.wl and mc0:/OPL/RA/hashes.txt. The settings device must remain available through the support check and launch preparation. RiptOPL also keeps the returned list in memory for the current session, so a failed file save does not discard that result. If the menu is using UDPBD or UDPFS, switch that network protocol off before asking the PC client for support; it cannot take over their network stack. A previously saved watch list can still be used.

Launch PS2 Disc keeps the existing normal disc boot path. Use it when you want to launch without achievements, including when the PC has no watch list for that game.

The RA path retains the console's physical-disc drivers and PS2LOGO authentication, then adds the OPL telemetry core. It accepts PS2 CD/DVD boot executables in the disc root, with names up to 15 characters. Nested boot paths, PS1 discs and video DVDs are not supported by this RA action. Physical memory cards are used; image-specific VMC, cheats, GSM, pad emulation, language overrides and storage-emulation patches are not applied. The thread/pad fixes for Eutechnyx titles, Shaun Palmer's Pro Snowboarder and PAL .hack selectors remain enabled because disc launches retain OPL's hooks. The power-off controller combo is unavailable on this path. Disc boot, telemetry across game IOP resets and the IGR return path still need PS2 validation.

Which launch paths can work

Telemetry lives inside OPL's own loader core, which only exists for launches OPL performs itself.

Neutrino, UDPFS and PS1 hand the console over to an external ELF and never load OPL's core, so there is nothing to take a snapshot from. This is structural, not an oversight.

Do not expect a game with achievements to run from a network share

A game that streams its own disc over the NIC is competing with telemetry for that NIC. This build no longer reads from the network in play on such a launch — raudp stops walking the SMAP receive ring and stops polling the stack, because the game's disc stream arrives through both — but hacan359 reports on hardware (2026-09-05) that this is not enough: a game with an achievement set still stops loading about a minute in from a share, so the send path disturbs the stream on its own. xeRAbora's own documentation says the same, and names the USB stick and the original disc as the only tested ways to play.

That defect is upstream's and ours alike; we have not reproduced or ruled it out on our own hardware, because none of this has been hardware-tested here yet. Until it is, keep the images you play with achievements on a local device. The same reasoning applies to HTTP, which streams down the same path.

HDD (APA) games are stored in HDLoader format and have no image file to hash, so while a watch list placed by hand still loads and streams, the console cannot work out the hash for them itself.

Networking

Telemetry is UDP, sent by an IOP module that builds Ethernet frames by hand rather than going through the network stack — the stack's mailbox is shared with the game's own traffic, and 60 sends a second pushed the game out of it.

Because of that, the console needs a valid IP even when the game was not launched over the network. OPL's own network settings supply it: whatever address, netmask and gateway are configured there are handed to the in-game Ethernet driver on every RA launch. If those are wrong or unset, the game runs normally but nothing reaches the PC.

The PC client is found automatically: the console broadcasts a query on UDP port 18194 and the client answers. Nothing is stored between runs.

Files on the card

<device root>/RA/<serial>.wl        e.g. mass0:/RA/SLUS_210.65.wl

One watch list per tracked game, generated by the PC client from that game's achievement set. RA/ follows the source’s support-file prefix, like CHT/. HTTP loads an existing watch list from the local settings home because the server is read-only; do not assume automatic image hashing/support detection works for a remote HTTP ISO. RiptOPL creates it along with the other library folders.

Image launches with a missing watch list proceed normally without telemetry or its extra modules. The explicit RA: launch disc action instead asks you to check support first; Launch PS2 Disc remains available for a normal disc boot.

Building

make clean && make RETROACHIEVEMENTS=1 release

make clean is not optional when switching the flag: it changes the layout of a structure and an enumeration shared between the menu and the loader core, and make cannot see that a stale object file is now wrong.

The rolling release publishes the flavour as its own archive, RIPTOPL-RetroAchievements-*.zip, built to the same shape as the main package: POPS/, EMBER/, neutrino/ and the PC-tool shortcuts, with loader folders in place of the standard ones:

RA is built with the ps2dev toolchain only, so these folders say PINNED/ROLLING where the main package says PS2DEVPINNED/PS2DEVROLLING. The names are kept short on purpose: a memory card file name stops at 31 characters, and the release workflow fails rather than ship a longer one. The archive also carries xeRAbora.url, because the loader does nothing without the PC client.

It is deliberately not an entry in RIPTOPL-VARIANTS-*.zip: that archive is a ~120 MB bag of every build permutation, and the release workflow excludes it from the permanent MEGA archive as a diagnostic bundle rather than installable payload. The default build is unaffected by all of this — every RA source file and every call site is behind #ifdef RETROACHIEVEMENTS, and that is checked by comparing the two builds' symbol tables, loader core and embedded IOP modules. PR CI also builds the pinned PS2DEVPINNED-RA flavour and records the RA flag in its build manifest.

Before this is called finished

Nothing below has been done. The feature is written end to end and builds clean; it has not run on a PlayStation 2. Emulator testing gets you as far as: the menu boots, the RA entries render and navigate, the flag-off build is unchanged, and a game with no .wl does not crash. That is the ceiling — GS raster timing and real SMAP behaviour are not testable there.

Hand testers a run-pinned nightly.link build, never a bare artifact link.

Notes for anyone changing this code

• Telemetry requires an OPL-core launch. BDM, ETH/SMB, HDD/APA and MMCE have this path; HTTP also loads an existing watch list from its local settings prefix. Neutrino and the PS1 cores run external ELFs, so OPL's telemetry core does not run there. Treat HTTP/RA interoperability as unvalidated until tested.

• The badge cache belongs to the I/O thread. raBadgeRefresh frees and reallocates it. Nothing on the render path may read it — that is why a row carries raBadged as a plain int, resolved when the row is built. Re-introducing a raBadgeHas-style call from a draw routine re-introduces a use-after-free that only shows up as a rare hang.

• MSG_DONTWAIT is 0x08 on the menu path, from ps2sdk's tcpip.h. The 0x40 in SMSTCPIP belongs to the in-game stack that serves raudp. They are different stacks; do not unify them.
• The texture table is positional. RA_MARK in enum INTERNAL_TEXTURE and its row in internalDefault[] are guarded by the same #ifdef for that reason. Guard one without the other and the array silently goes one short.
• Deleting obj/ is mandatory after any change to EECoreConfig_t, OPL_MODULE_ID or the submenu structs. This Makefile does not track header dependencies, so an incremental build can pass locally while CI's make clean fails.
• ee_core has about 3 KB of headroom, and RA spends it. ram84 is 77312 bytes (ee_core/linkfile). Without RA, an EXTRA_FEATURES=1 ee_core comes to 74215; with RA and without extras, 74067. Either fits; both together overflow by roughly 6.5 KB and ld refuses with .bss is not within region ram84. That is why the release builds RA at the default EXTRA_FEATURES=0, which is also what the main loader ships as — so the RA archive is the shipping loader plus achievements, not a variant. ra_snap_buf and ra_watch are most of RA's share; shrink them before trying to add anything else to that build.
• PC integration uses xeRAbora, maintained by hacan359.
• Physical discs use an EESYNC-only reset image. ROM CDVDMAN/CDVDFSV remain in place; standalone DEV9 and SMSUTILS load before the telemetry network stack. Do not call OPL CDVDMAN's shutdown RPC in this mode. Hash checks share the existing I/O worker; a launch refuses while a check is pending, before probing or tearing down devices.

Credits

• hacan359 (yoba) — the RetroAchievements design, the console implementation this port follows, and the PC client. Physical-disc integration follows the upstream disc implementation.
• src/md5.c, include/md5.h — L. Peter Deutsch, zlib licence, vendored unchanged.