RetroAchievements Reference

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. Download the required v0.1.0-alpha.17 release.

RiptOPL's real-hardware stabilization was contributed by oMrRexD through PRs #702–#705, covering the ee_core stack squeeze, MMCE DEV9 dependency, cold-launch network bring-up / unusable-IP fallback, and the misplaced RA settings rows.

Mode 6 (IGR disabled)

When per-game Compatibility Mode 6 disables IGR, the RA build keeps the in-game snapshot tick through a dedicated VBLANK handler, but only when telemetry successfully initialized. It does not install an IGR worker or pad-open hooks. Achievements can still be recorded; controller IGR and client-triggered RESET CONSOLE are unavailable. The physical console buttons retain their normal hardware behavior. Mode 6 does not cure incompatibility with games that reject a VBLANK handler itself. This behavior follows xeRAbora alpha.17; console compatibility varies by game and launch transport.

RA Mode: Xerabora or Caduceus

In the RA build, open Settings → Network → RA Mode and choose Xerabora (the default) or Caduceus. Save settings to retain the choice. Old configurations without ra_mode keep Xerabora. The normal build has no RA mode row or telemetry code.

This selector chooses the PC service protocol; it does not enable telemetry by itself. Keep RA Telemetry enabled when you want tracking. No PC application or server binaries are bundled by this change; the companion service is managed separately through PS2-Servers.

Mode	Menu and launch behavior
Xerabora	Existing xeRAbora discovery, watch-list transfer and in-game telemetry
Caduceus	Signed-in session checks, compatible watch lists/telemetry, account and game achievement browsing, and in-game gold-pulse notices; the card renderer remains test-only

Caduceus adds a UDP 18197 catalog/session bridge (CADQ2 / CADR2). Once a ready bridge is found, RiptOPL requests watch lists from the engine on that same PC at UDP 18194. For local-device launches, the in-game module repeats bridge discovery only against the configured SMB host IPv4 address before contacting that PC's engine; a standalone Xerabora reply or a faster responder elsewhere on the LAN cannot substitute for the Caduceus bridge. Xerabora mode keeps automatic broadcast discovery. UDP 18195 is the console's telemetry/notice port, and UDP 18196 is its menu reply port. Permit these connections in the companion PC's firewall. Run one intended achievement service per host to avoid port conflicts. By default, Caduceus's pairing bridge uses the configured SMB server IPv4 address, never the fastest LAN responder. Network → RA companion IP can override it independently of the SMB and HTTP game servers; set 0.0.0.0 to retain the legacy fallback. This host is used by Caduceus pairing, support checks, link tests, in-game discovery and POPStarter. When explicitly set, Xerabora is also probed by unicast, not broadcast. A NetBIOS-only SMB address without an IPv4 fallback requires the separate RA host setting.

Every tracked Caduceus launch rechecks its session. If the bridge is offline or unavailable, the game launches normally without achievement telemetry. If Caduceus reports OFFLINE, sign in through the companion service and retry. RiptOPL never stores your RetroAchievements password or API key. A successful bridge query only proves the session bridge answered; the subsequent watch-list transfer and game telemetry must also succeed. An unknown catalog hash is not interpreted as an offline session: the engine's watch-list result remains authoritative.

The wire format follows Caduceus's bridge implementation. Caduceus's bundled engine version can differ from the standalone version recommended above; protocol compatibility does not establish identical game coverage or timing. This new mode has host tests for discovery, malformed/offline replies and host selection; Caduceus end-to-end console tracking remains unverified. The Xerabora hardware results below apply only to the tested Xerabora configuration.

Both modes retain the existing restrictions: external Neutrino and Ember launches do not load RiptOPL's telemetry core (USB POPStarter uses its own IOP reader), UDP storage owns the NIC and blocks menu RA queries and clears loaded telemetry before an incompatible UDP-backed launch, and SMB/HTTP never let RA drain the game's receive descriptors or poll its sockets. In those modes RA observes notices already received by the normal SMAP driver and uses the known host's ARP entry for transmission. Missing host/MAC disables telemetry rather than disturbing game I/O. For saved watch lists launched without a fresh peer discovery, SMB/HTTP passive telemetry uses an explicitly configured RA companion IP if provided, otherwise the existing verified peer or legacy SMB/HTTP game server fallback. In passive SMB/HTTP mode a queued receive FIFO defers telemetry snapshots, leaving the disc stream's pending receive traffic ahead of achievement traffic. The send path is still hardware-unverified and may still interfere during continuous streaming. Choosing Caduceus does not bypass these guards or add hardcore support.

Caduceus achievement browser and in-game cards

Choose Caduceus achievements from the main menu to browse account games and progress. Select a game to see its achievements, points, descriptions and unlock dates. L1/R1 changes pages, Square cycles All / Earned / Locked / Hardcore, Select refreshes, and Back returns to the previous view. Hardcore is a filter for existing account history; it does not enable hardcore tracking.

For a local ISO, View achievements in the game's menu hashes the image and opens that game's set directly. Formats that cannot be hashed on the console can still be browsed through the account library. The browser uses the I/O worker; Back remains available during network requests. Requests finish with bounded retries and cannot overwrite each other's shared state.

The browser requires a configured, accessible SMB share containing ART/CADUCEUS.KEY, created by the companion service, even when games are on USB, MMCE or internal exFAT storage. The key is a 64-character pairing capability, not an RA password/API key. The service also supplies optional ART/_RA.png badge images; only the visible page is cached. Permit UDP 18198 for browser queries. Pairing requests go only to the explicit RA companion IP, or to the configured SMB server IPv4 address when that setting is 0.0.0.0, never to LAN broadcast. Restrict the share to trusted devices: the LAN protocol is unencrypted. To revoke pairing, stop the service, remove its key file and restart it.

Caduceus unlock notices use the existing gold pulse by default. Its experimental card renderer can display a compact upper-right achievement title and points in controlled builds; older notices without a title show the ID. Duplicate notices are suppressed, while a richer title-bearing copy can upgrade a legacy notice. Xerabora retains its gold pulse. The new card and browser are adapted from Rian6's PS2 implementation, under AFL-3.0.

The card renderer is disabled by default until GS transfer ownership can be proven. An idle GIF/DMA check or observed DISPFB write cannot guarantee that a game has finished a pending host-to-local IMAGE transfer. For controlled developer-only experiments, RA_EXPERIMENTAL_CARD_DMA=1 must be set consistently in both loader and EE core. This does not create an additional release variant or a user setting. Do not enable production notification cards until safe GS transfer ownership is proven. The retained renderer uses a bounded, loader-owned packet, skips busy GIF transfers and unsupported framebuffers, and records game display writes without forcing a video mode. Normal RA builds reserve no card workspace and install no GS tracker; the optional experimental renderer reserves about 30 KiB only for Caduceus launches with a watch list. If that reservation would cross protected memory bounds, telemetry continues without the card. No host test can establish game timing or graphics compatibility. The existing network-share stability warning still applies.

---

Status

Implemented, and telemetry has run end to end on real PS2 hardware in oMrRexD's session for PRs #702–#705: an SCPH-50001 with an expansion-bay network adapter, a static IP and xeRAbora v0.1.0-alpha.10. Launched from MMCE, Need for Speed: Underground 2 streamed 25,200 snapshots with none lost and unlocked an achievement with the overlay on screen; the same build also tracked the game from USB. That is one console, one game and a static address. DHCP, the other launch paths and the edge cases below remain development-grade and should still be validated individually before being treated as finished.

Part	State
RETROACHIEVEMENTS=1 build flavour	done
In-game telemetry (raudp, ee_core snapshots)	hardware-tested from MMCE and USB, static IP (#702–#704)
Watch-list loading from <device>/RA/<serial>.wl	done
Image hashing (ISO9660 walk + MD5)	done; images on a share and on a USB stick hashed to matching values on hardware (hacan359, 2026-09-10)
Menu actions: check game support, test PC link	both used on hardware: the support check's hashing by hacan359, the PC link test in #704
List badges and the cover mark	written, not yet confirmed on hardware
Unlock overlay	hardware-tested: the gold overlay showed over the running game on an unlock (#704)
Settings: RA telemetry, RA badges	done; on the Network page since #705, where switching telemetry off and on was checked on hardware
Disc in the tray	implemented in the RA build; not hardware-tested

---

Using it

Two settings, on the Network settings page:

Setting	Default	Effect
RetroAchievements telemetry	Off	The master switch. While it is off an RA build launches a game for exactly what the standard build costs — no in-game network stack, no raudp, no snapshots.
RetroAchievements badges	On	The RA prefix in the game list and the mark over the cover. Cosmetic, and it follows the master switch: badges stay dark while telemetry is off.

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.

Launch path	Supported
BDM — USB, iLink, MX4SIO, ATA/exFAT	yes
ETH / SMB	wired, but known bad upstream — see below
HDD (APA)	yes; installed HDLoader games now support read-only automatic hashing (hardware acceptance pending)
MMCE	yes
Physical PS2 disc, RA: launch disc	implemented; not hardware-tested
HTTP	local watch-list loading is wired into OPL-core launch; combined HTTP/RA operation is not hardware-validated, and it shares the ETH/SMB risk below
Neutrino core ($CoreLoader)	no
UDPFS	no
PS1 / USB VCD (POPStarter)	yes, experimental; console validation pending
PS1 / Ember, MMCE, APA HDD, SMB and non-USB BDM	no

Neutrino, UDPFS and Ember 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. The hardware testing so far (#702–#705) launched from MMCE and USB, never from a share. Until a share is tested, 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) / HDLoader games have a new read-only automatic support check. The check reads the installed game's 1024-byte HDLoader descriptor, validates its logical-to-ATA sector map, and hashes the boot executable through the same ISO9660 walker as normal ISO images. It never rewrites an APA partition or converts the game. The resulting watch list is saved under the accessible HDD settings home in RA/<startup>.wl; an existing manually supplied list still loads. The check is deferred to the I/O worker, requires a valid HDD data home and ATA access, and rejects invalid or overlapping partition mappings. A synthetic split-partition test matches the ISO content hash, but real APA hardware validation and performance remain pending.

An image an earlier run left open on the share can still be hashed

Checking a game on a share used to fail outright once a console had played that game and been switched off: OPL logs off from nothing on power-down, the SMB session dies with the console, and a cheap server never reaps the handle. From then on the server refused every NT open of that file with a sharing violation, so "check game support" could only report that it could not open the image — while the game still booted off it, because the in-play open uses the older command, which the same server grants in compatibility mode.

This flavour now carries its own smbman (modules/network/smbman-ra) that tries NT create first and falls back to the legacy open only when the server says the file is held, and only for a read — reaching past another handle to write is not something worth asking for. If both are refused, the hash log names the image as held instead of saying nothing. hacan359 confirmed this on hardware on 2026-09-10: two images held open by earlier runs hashed anyway, and the hashes matched the ones taken from a USB stick.

Note this fixes hashing, not play: a game with an achievement set still stops about a minute in when streamed from a share, per the section above.

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.

A launch with a watch list and telemetry on brings the menu's network up first when it is not up already, so it takes a moment longer. That is not optional: the in-game DEV9 driver does not power the network adapter on, it expects the menu to have done it, and without it no packet leaves the console. It is also how the console learns its address when it uses DHCP. If the network cannot come up -- no cable, no adapter, no usable IP address or DHCP lease -- the game launches without achievements and the menu shows a notice. With the adapter powered and no link, the in-game network driver would otherwise wait for a cable for ever and the game would never start.

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

The PS2 console core follows xeRAbora v0.1.0-alpha.15 (client d36ee3a5, which pins console f4d559a3). The PS1 POPStarter bridge additionally follows alpha.16, and the Mode 6 snapshot handling follows alpha.17. Use the alpha.17 companion required above for this RA build; updating the external client alone does not update the telemetry code in your ELF.

• Larger achievement sets: up to 4,096 direct watches and 128 pointer-chain nodes, subject to the snapshot byte limit. The loader sizes the persistent module-storage block to the actual set, instead of keeping the larger tables in ee_core's limited memory.
• Bounded telemetry cadence: up to three snapshot packets per video frame on average. Sets needing four to six parts are sampled every second frame; seven to nine parts every third frame. Smaller sets remain at one sample per frame. Packets still transmit as one snapshot batch; this is a cadence budget, not packet pacing.
• Read-cost diagnostics: the PC receives COP0 ticks spent reading a snapshot and ticks per video frame, allowing it to show the read cost as a fraction of a frame.
• Watch-list validation and read safety: only 1-, 2- and 4-byte entries with an exact declared byte sum are accepted. Direct unaligned values are read bytewise; out-of-RAM addresses are reported as zero. RiptOPL retains its null-base pointer-chain guard.
• Set identification: while the PC replies WAIT, the console pauses 500 ms between up to 20 rounds. A silent PC still fails within the ordinary request timeout. A newer client's refusal reason is shown rather than replaced with a generic unknown-image message.
• PC-requested return: the client's return command takes the existing OPL IGR path. It is available only where in-game RA receive is enabled; the SMB/HTTP receive guard remains. The configured IGR return path and ordinary compatibility restrictions still apply.
• Delivery guarantees retained: 4 ms sender polling, busy/torn snapshot retries, ~1 second keepalive, and marking the staged sequence sent only after every multipart packet succeeds.

Important

Use xeRAbora v0.1.0-alpha.16 with this updated RA ELF. Older RiptOPL releases retain their original paired-client requirement. Host tests and successful builds do not establish console timing or game compatibility; the alpha.10 hardware report above is historical evidence, not validation of this update.

---

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. PS2 images use their boot serial; USB PS1 VCDs instead use a stable 15-character P-prefixed key derived from the normalized full VCD path, avoiding collisions between different PS1 images with the same BOOT executable. These PS1 lists are stored under the selected library's RA/ prefix. After renaming, moving or replacing a VCD, run the support check again. Each new USB PS1 support check saves a matching RA/<15-character-key>.md5 sidecar only after its corresponding .wl write succeeds. Tracked POPStarter launches rehash the VCD's boot executable and compare its RetroAchievements content hash to that sidecar. Old watch lists without a guard and replaced images with stale guards launch untracked, not with incorrect achievements. This adds an on-launch executable hash read for tracked PS1 VCDs; ordinary/untracked games are unaffected. 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 APPS/APP_RIPTOPL-RA/RIPTOPL-RA.ELF, matching ART/RIPTOPL-RA.ELF_*.png artwork, and APP_RIPTOPL-RA.psu. The PSU contains only the direct files of APP_RIPTOPL-RA; import it with a PS2 save manager for a memory-card installation, then copy the other folders separately.

The ready app APPS/APP_RIPTOPL-RA/ uses the official-toolchain build (OFFICIALROLLING, PADEMU=1) when that build succeeded, the same loader the release then also publishes on its own as RIPTOPL-RA.ELF. A run without it publishes no RIPTOPL-RA.ELF, and the ready app falls back to the labelled builds below, in the order listed. The archive keeps those labelled loader folders under APPS/ for comparing builds:

Folder	Build
APPS/APP_RIPTOPL-RA-PINNED/	Pinned ps2dev toolchain, PADEMU=1 (the ready app's first fallback). Start here for build comparisons.
APPS/APP_RIPTOPL-RA-ROLLING/	ps2dev:latest, PADEMU=1
APPS/APP_RIPTOPL-RA-PINNED-nopademu/	Pinned ps2dev toolchain, PADEMU=0
APPS/APP_RIPTOPL-RA-ROLLING-nopademu/	ps2dev:latest, PADEMU=0

The labelled folders are the two ps2dev builds, so they 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 (pointing directly to the paired v0.1.0-alpha.16 release), 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 OFFICIALROLLING-RA flavour and records the RA flag in its build manifest.

Two IOP modules this flavour builds instead of taking from the SDK

Both are ps2sdk sources vendored with a marked change, the way modules/network/ps2ips already is, and both are selected by USBD_MINI_IRX / SMBMAN_IRX at the top of the Makefile.

Module	Why	Diff from ps2sdk
modules/network/smbman-ra	the held-image fix above	smb.c (35 lines) and smb.h (4); every other file byte-identical to ps2sdk master
modules/usb/usbd-ra	see below	nothing — byte-identical to ps2sdk iop/usb/usbd at 314d87e7 (2024-04-01); only the Makefile is ours

The usbd swap is not a RetroAchievements feature. ps2sdk rewrote its USB host driver on 2024-09-04 (b1f7ff96: 28 files, +4446/−3336), and since then a CD-era game run off a USB stick loses its controller and its sound at the game's first IOP reboot — Dynasty Warriors 2 on real hardware, reported by hacan359 on 2026-09-10, reproducing with official OPL as much as with this fork. Swapping only that one module fixes it. usbd_mini.irx is not a separate source tree: iop/usb/usbd_mini/Makefile points IOP_SRC_DIR at iop/usb/usbd/src and adds -DMINI_DRIVER, so the rewrite lands squarely on the module every RiptOPL flavour embeds straight from its container.

It is therefore not gated: USBD_MINI_IRX sits outside the RETROACHIEVEMENTS conditional and every flavour gets the pre-rewrite driver. It is listed here only because this is where the module came from; it is not a RetroAchievements feature and does not depend on the flag.

Hardware-checked by Zack on 2026-09-10 before that promotion landed: no noticeable USB regressions on the promoted build. That is the check the promotion was waiting on — it is a no-regression result, not a confirmation that the Dynasty Warriors 2 case is cured here; that remains hacan359's finding on his own hardware. backup/pre-usbd-forkwide-58fe5529 is the tree immediately before the swap, kept as a restore point.

Before this is called finished

Most of the list below is still open. oMrRexD's hardware session for #702–#705 covered the nearest thing to 3, launched from MMCE rather than USB (25,200 snapshots with none lost after a cold boot and a straight launch; the same build also tracked the game from USB), and 13, the unlock overlay over a running game; a launch with telemetry switched off sent nothing, which is part of 2. Everything else still needs 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.

#	Test	Expected
1	Default build (RETROACHIEVEMENTS=0)	no regression on any existing path
2	RA build, telemetry Off	behaves as the default build
3	USB launch, valid .wl, telemetry On	~60 snapshots/s for ≥5 min, skip/fail counters flat
4	Same, watching frame rate	no perceptible impact
5	SMB launch with telemetry	the game's own SMB stream unaffected
6	Menu check, protocol = SMB	title + counts, .wl written
7	Menu check, protocol = Off	RA raises the stack, same result
8	Menu check, protocol = UDPBD / UDPFS	clean refusal + hash written to RA/hashes.txt, no wedge
9	Neutrino-core game	clean refusal, no hash attempt
10	USB PS1/VCD entry	support check, then POPStarter telemetry after the startup delay
11	Ember or non-USB PS1 entry	clean refusal
12	HDD/APA entry	read-only support check maps the HDL extents; a watch list still loads
13	Badge + cover mark	appear after refresh, correct game, correct device
14	Unlock overlay	gold pulse on RAU1, game keeps running
15	IGR combo during an RA launch	still resets
16	MX4SIO launch with telemetry	no navigation or art regression (that device has history)
17	Check a physical PS2 CD/DVD, then RA launch with telemetry On	correct hash/watch list, normal authentication, game and telemetry run
18	Swap the disc after checking support	launch reads the current disc identity and requires its own watch list
19	Normal Launch PS2 Disc in both builds	existing disc boot remains usable without RA
20	RA disc game performs an IOP reset; then try IGR	disc access and telemetry recover; IGR returns without waiting on the absent OPL CDVDMAN RPC

---

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 Ember run external ELFs, so OPL's telemetry core does not run there. USB POPStarter uses a separate IOP telemetry module. 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's stack is whatever ram84 leaves above .bss. ram84 is 77312 bytes (ee_core/linkfile), and the link now fails when less than 3 KB of stack is left, so the next thing that grows .bss breaks the build rather than a console. RA's two buffers, ra_snap_buf and ra_watch (about 8 KB), used to live in .bss: they left the RA build 1920 bytes of stack, which overflowed at the first IOP reset. Since #702 they sit in a work area the launcher reserves at the end of module storage (raWorkArea in EECoreConfig_t), and only for a launch that has a watch list with telemetry on. When #702 landed, the stack left was 13312 bytes in the default build, 3348 with EXTRA_FEATURES=1, and 9984 / 10112 in the RA builds (PADEMU=1 / 0). 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. Before #702, RA and EXTRA_FEATURES=1 together overflowed ram84 by roughly 6.5 KB; that pairing has not been re-measured since.

• 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.
• oMrRexD — the real-hardware RA stabilization work merged through PRs #702–#705: ee_core stack recovery, MMCE DEV9, launch-time network readiness/fallback, and the RA settings-page correction, plus the hardware investigation that exposed those failures.
• src/md5.c, include/md5.h — L. Peter Deutsch, zlib licence, vendored unchanged.

PS1 achievements through USB POPStarter

Adapted from hacan359/Open-PS2-Loader commit 531aad4584d65d1779b744739b81402150c7669c (xeRAbora alpha.16). Use the RA build and a stock POPS/POPSTARTER.ELF, with .VCD games in that USB device's root POPS/ folder. RiptOPL retains its PS1 view and mixed view, existing POPStarter resolver, and filename-based game settings. Choose the existing USB driver mode in Settings > PS emulation: FAT32 for FAT32, exFAT for exFAT, or Ask to choose on each launch. The exFAT driver pair and memory-card preparation follow the existing VCD setup.

Select RA: check game support once for the USB VCD, then launch it normally. The support check hashes the executable named by the image's SYSTEM.CNF, with PSX.EXE fallback, following RetroAchievements' PS1 algorithm. Watch lists are stored under the existing library's RA/ prefix. Favorites use their source USB device and VCD filename. Remembered menu launches use the same POPStarter path and an already checked watch list. The command-line BDM autolaunch entry point remains PS2-image-only. The separate Caduceus achievement browser opens the selected USB VCD by its content hash; unsupported PS1 sources receive an explicit notice.

The loader creates POPS/MODULE_9.IRX only for a tracked USB launch. That module contains the configured network modules and PS1 watch list. POPStarter loads it after resetting the IOP; rapull reads PS1 RAM from POPS through SIF, starting 25 seconds after launch, and raudp sends snapshots to the selected xeRAbora or Caduceus companion. Unlock notifications appear on the companion; there is no console gold pulse or Caduceus card for PS1. Scratchpad addresses are not available in this upstream reader; multi-window reads are not synchronized to a game frame. The PS1 watch-list and telemetry identity is a 15-character P-prefixed key computed from the normalized VCD path. The boot executable is only used for the PS1 image hash, not as the watch-list identity; this prevents homebrew titles sharing PSX.EXE from reusing each other's lists. Re-check game support after moving or renaming a VCD.

A user-owned MODULE_9.IRX is never overwritten or deleted. For a tracked launch, move it yourself if you want to use the reserved telemetry slot. RiptOPL marks its own module and the RA build removes stale copies before later BDM POPStarter launches. For a standard-build BDM VCD launch, an owned leftover prompts for deletion before handoff. Declining deletion offers Continue anyway, with a stale-telemetry warning; declining that confirmation cancels the launch. A failed deletion offers the same choice. File-backed SMB and MMCE VCD launches use the same safety check. Unrecognized user modules are left alone. This shared file cleanup does not add telemetry, network modules, watch lists or client requirements to the standard build. No support list, disabled telemetry, or unavailable network launches normally without installing telemetry. POPS shares the PS2 launch preflight: physical link, usable address, completed DHCP when enabled, and a fresh Caduceus session check. An explicit Xerabora companion remains pinned through the POPS handoff. Routed active and passive peers use their gateway's MAC. Passive SMB/HTTP telemetry can request a missing companion/next-hop ARP entry once after the IOP reset without opening a socket or consuming the game's receive descriptors. Optional preparation failures such as unavailable memory, an unwritable module path, or a partially written module that can be fully deleted also permit a normal, untracked launch. A user-owned module still blocks tracked injection, and a damaged module that cannot be deleted still blocks handoff rather than risking a broken POPStarter startup. Failed PS1 memory reads do not publish fabricated zero snapshots or reuse a failed read as a new frame.

Validation gate: host fixtures and a successful ELF build do not prove POPS compatibility. Test the same console with USB FAT32 and exFAT: support check, boot, play past the 25-second delay, observe sustained memory snapshots and an actual unlock, exit and relaunch another title, then launch without achievements. Also test Favorites, remembered launches, a missing/offline companion, and an existing user MODULE_9.IRX. MMCE, APA HDD, SMB, MX4SIO and iLink PS1 telemetry remain unsupported here until they have a deliberate integration and hardware validation.

PS1 library scanning distinguishes explicit I/O/resource errors from empty folders, including failures while enumerating a child game directory. An empty successful half plus a failed half preserves the last published PS1 list; a successful nonempty half can still publish. BDM schedules at most two extra scans on its existing idle refresh cadence after a failed/partial PS1 scan. SELECT/L3 or a device event rearms recovery. Legacy drivers that collapse a missing directory to EPERM/no errno retain the POPS-only compatibility behavior. This hardens discovery but does not establish the cause of Vapor's non-listing report. A permanently failing driver still needs a new refresh/device event.

Related guide: RetroAchievements.

---

Source: docs/RETROACHIEVEMENTS.md @ 679582deddf5.