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.

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: Ember and ordinary/custom Neutrino 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.

Neutrino in the RA edition

The full RetroAchievements kit includes the existing ORBIT v1.0.2 Neutrino runtime by Daniel / danielnuld, based on Neutrino by Maximus32 and the achievement protocol by hacan359 / xeRAbora. Its AFL-3.0 license, exact source commit and archive SHA-256 ship beside the runtime. Standard builds and install kits retain ordinary upstream Neutrino. An ELF-only update does not install the external runtime; copy the RA kit's complete neutrino/ folder to your chosen supported device.

The RA kit's neutrino/ is ORBIT's RA-Neutrino, labelled by neutrino/RA-EDITION-NEUTRINO.txt. It keeps the usual folder name so RA setups find it, but it is not the standard kit's Neutrino: ORBIT v1.0.2 is built on Neutrino v1.8.0, so in the RA edition every Neutrino launch, tracked or not, uses that base and lacks later upstream changes, including Neutrino cheat support. Use the standard kit for Neutrino cheats. Keep each kit's neutrino/ with its own loader rather than mixing them.

Select RA Mode: Xerabora, enable telemetry and set RA companion IP to the signed-in xeRAbora PC. ORBIT is a loader runtime, so it does not need a third RA protocol mode. Run RA: check game support for a local image or APA install to identify that exact image and save RA/<serial>.wl under its support-file prefix. xeRAbora alpha.17 persists the serial-to-hash mapping in its own configuration; keep that mapping with the companion profile. A watch list copied from another PC does not identify the game to a fresh profile. Recheck support after replacing an image, especially another revision with the same serial.

On launch, RiptOPL writes ript-ra.wl and ript-ra.toml into the selected Neutrino configuration directory, honoring its effective -cwd and chaining the user's -cfg and generated cheat configuration (the v1.8.0-based runtime has no cheat engine, so the codes do not apply). That directory must be writable and remain accessible to Neutrino. The runtime can reside on any supported mounted device; a raw hdd0: partition path is not a filesystem directory. RiptOPL adds the RA arguments only after preparation succeeds and validates the full launch argument budget before teardown. A game without a saved watch list launches without a notice. If the two RA arguments would push the launch past Neutrino's 256-byte budget, the game launches without achievements and shows the untracked notice instead of being refused.

The pinned agent accepts direct watch entries totaling at most 1,216 snapshot bytes. Pointer chains, larger lists, an unavailable runtime/companion address, or failed configuration writes leave the launch untracked. Caduceus, console unlock cards/pulses and remote reset are not provided by this external runtime. Neutrino's own IGR behavior remains governed by its settings, independently of the OPL-core Mode 6 behavior above.

UDPFS/UDPBD launches reuse the runtime's storage network stack; the adapter does not load a second SMAP/ministack or open menu RA sockets. These launches currently require a static PS2 IP, an explicit companion address (or a previously verified peer), and a saved watch list plus a matching serial/hash mapping already known by that companion. Prepare the support check on an accessible local copy of the same image before using UDP storage; first-time UDP game identification is still outstanding. This is an integration candidate with host-test coverage, not current-build physical-console acceptance. ORBIT's published console results establish upstream evidence only. Test game I/O, telemetry, reconnects, IGR and both runtime locations before treating this handoff as release-validated.

The ORBIT runtime watch uses the same schedule as the ordinary Neutrino watch: 05:41 UTC on the 1st, 11th and 21st of each month. It opens or updates one compatibility-review issue when the release tag or archive digest changes. It does not automatically replace the reviewed pin.

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 when explicitly enabled; 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.

Caduceus experimental cards defaults to Off. In the RA build, open Settings > Network, select RA Mode: Caduceus, enable telemetry, and enable Caduceus experimental cards only if you accept possible flicker or game freezes. Save settings and launch a tracked PS2 game with the OPL core. The choice takes effect on the next launch and is saved as ra_experimental_cards=1; old configurations without that key remain Off. Xerabora always uses the gold pulse, and POPStarter PS1 unlocks remain companion-only.

This is the upstream-style IMAGE renderer with additional event and GIF-state checks, not a proven safe GS ownership scheme. An idle GIF/DMA check or observed DISPFB write cannot guarantee that the game has finished or preserved a pending image transfer. If a game flickers or freezes with cards enabled, disable the setting before relaunching. The setting help also states this risk.

With cards Off, launches reserve no card workspace and install no extra GS tracker. An opted-in tracked Caduceus launch reserves about 30 KiB in protected module storage and observes display-register writes without forcing a video mode. If there is insufficient room, unlock and reset events fall back to the existing pulse handler. The renderer skips blocked GIF states and unsupported framebuffers, but these guards do not prove graphics compatibility; a card may not appear for an unsupported display. Current-build console card rendering and real unlock acceptance remain unverified. 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.

Using it

First tracked game

1. Start RIPTOPL-RA.ELF from the RetroAchievements package. The standard ELF has no achievement telemetry or companion requirement.
2. Run xeRAbora alpha.17 on the companion PC and sign into your RetroAchievements account in its Settings page. Keep the client running. Account login enables unlock submission; the Web API key supplies account/library data.
3. In RiptOPL Settings > Network, select RA Mode: Xerabora, enable RetroAchievements telemetry, and save settings. Telemetry defaults to Off. Give the PS2 usable network settings and connect it to the same LAN as the PC. Set RA companion IP to that PC's IPv4 address to target it explicitly.
4. For an initial PS2 image test, use USB or MMCE and select OPL explicitly as the game's loader/core for the existing OPL telemetry path. The RA kit's ORBIT Neutrino path has the separate requirements above. Other implemented paths and their validation status are below.
5. Open the game's menu and run RA: test PC connection, then RA: check game support. The first establishes reachability; the second obtains the watch list. Allow xeRAbora through the PC firewall, including inbound UDP 18194.
6. Launch after a successful support check. Verify the companion's LIVE view receives snapshots; a list badge alone does not prove in-game telemetry.

Repeat the support check for each image you want to track. A missing watch list starts an ordinary, untracked game. An unknown hash can indicate a different region/dump or an unsupported set; it does not establish that the storage source is unsupported. Caduceus users select that service's mode and complete its sign-in and pairing requirements described above instead of running competing services.

The telemetry and notification settings are 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

OPL-core launches use RiptOPL's embedded telemetry. The RA kit's ORBIT Neutrino runtime and USB POPStarter use their own agents, with the separate limitations documented above.

Neutrino and Ember hand the console over to an external ELF and never load OPL's core. The RA kit supplies ORBIT's external agent for compatible Neutrino launches; ordinary Neutrino and Ember have no achievement snapshot agent.

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.

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 dedicated RetroAchievements release publishes both inceBtion and Korium together, from one RiptOPL source revision. Choose one:

Each full kit includes POPS/, EMBER/, the pinned ORBIT neutrino/ runtime, companion shortcuts, matching artwork, APPS/APP_RIPTOPL-RA/RIPTOPL-RA.ELF and APP_RIPTOPL-RA.psu. Both themes keep these internal app paths for existing shortcuts. Installing the other theme replaces the app; rename a theme-labelled loose ELF to RIPTOPL-RA.ELF when updating it. PSU imports contain only the app; copy the shared folders separately. The ready app and loose ELF use OFFICIALROLLING with PADEMU=1. A missing theme or failed required build prevents RA publication altogether.

The labelled comparison apps inside each theme kit retain both ps2dev toolchains:

RA-RELEASE.json records the common code revision, frozen Korium theme revision, theme patch digest, ORBIT pin and every download's SHA-256. The source snapshot includes the shared source and the exact Korium patch as RA-Korium-theme.patch. RA-BUILD.json in each kit records its theme and build inputs. PR artifacts are previews and cannot be published. The release is experimental and never becomes GitHub Latest. Standard Rolling and standard Korium no longer publish RA assets; their builds and stock Neutrino remain independent. Existing historical tagged releases are retained.

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.17 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.

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.

Notes for anyone changing this code

• Each loader has its own telemetry path. BDM, ETH/SMB, HDD/APA and MMCE support the OPL-core agent; HTTP loads an existing watch list from its local settings prefix. The RA kit adds ORBIT's external Neutrino agent under the documented Xerabora/direct-watch limits. USB POPStarter uses a separate IOP module. Ordinary Neutrino and Ember remain untracked. Treat HTTP/RA interoperability and the new ORBIT handoff 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.