Something does not work? Read Before you report a problem first: one version everywhere, one client, a clean reset of the PC and the console, and the two logs that make a report useful.

xeRAbora

RetroAchievements on a real PlayStation 2. You play on the console, and the achievements you earn go to your RetroAchievements profile. The TV flashes gold on each one. No emulator. PS1 games too, through POPStarter, with their own sets.

Without a PS2, the same client shows your play on any emulator with RetroAchievements: library, achievements, leaderboards. See Without a PS2.

On a phone, the Android app runs the whole client: the console finds the phone on the Wi-Fi, and each unlock arrives as a notification. No PC needed.

Project page: hacan359.github.io/xerabora, the setup as a walkthrough: How to start.

[!IMPORTANT] 1.0.0 is the first stable release. Still on an alpha? Update both halves, the ELF on the console and the client, to 1.0.0. Alphas get no more fixes, and bug reports and pull requests should start from 1.0.0.

How it works

The console runs a patched Open PS2 Loader, OPL-RA.ELF. The PC runs xeRAbora. Both sit on the same home network.

Before you play a game for the first time, choose RA: check game support in its OPL menu. The PC finds the game on RetroAchievements and tells the console what to watch.

While you play, the console sends the PC what happens in the game. When you earn an achievement, the PC records it on your profile and the TV flashes gold.

What you need

• A PS2 with a network adapter and a way to run OPL (FMCB, FHDB or similar).
• Your games as .iso images wherever OPL runs them (USB stick, internal HDD over BDM, an SD card in an MMCE device), or the original disc in the drive. PS1 games as .VCD images in POPS/ on a USB stick, played through POPStarter.
• A PC on the same local network, Windows, Linux or macOS, or an Android phone on the same Wi-Fi (the Android app).
• A RetroAchievements account.

Setup

An unlock needs three things, in this order: xerabora running on the PC and signed in, the game checked once with RA: check game support, and only then the game started. Step 6 is the one people skip. A game you never checked starts as plain OPL, without telemetry, and the client shows nothing for it.

1. Download OPL-RA.ELF and the client for your PC from the releases: xerabora.exe (Windows), xerabora-linux-x86_64 (Linux on a PC), xerabora-linux-aarch64 (Linux on 64-bit ARM: a Raspberry Pi 4 or 5) or xerabora-macos (macOS, Intel and Apple Silicon in one file). On Linux and macOS, chmod +x the file after downloading. On an Android phone, install xerabora-android.apk instead; the steps below are the same in the app.
2. Put OPL-RA.ELF where you keep your OPL and launch it instead of OPL.
3. The RA menu items report their result as an on-screen notice whatever OPL's Notifications setting says. Turn that setting on if you also want OPL's own notices.
4. Run xerabora on the PC. It opens its page in your browser. On the SETTINGS tab sign in with your RetroAchievements login (needed for unlocks) and paste the Web API key from your RA profile settings (it fills the library, leaderboards and profile). The login token and the key are kept in your user profile (%LOCALAPPDATA%\xerabora on Windows, ~/.config/xerabora on Linux and macOS); the password is not stored.
5. On the console, select a game, open its menu (triangle) and choose RA: test PC connection. A notice tells you whether xerabora answered, from which address and how fast. If nothing answers, check that the PC is on the same network and that the firewall allows inbound UDP 18194.
6. In the same menu choose RA: check game support. Do this before you start the game, once per game: it fetches the list of addresses the console will read, and without it there is nothing to track. The notice shows the game title and the achievement counts (total, unlocked, unsupported). Supported games get an RA prefix in the list and a badge on the cover art. RetroAchievements does not know this image means the game plays without achievements; a set the PC refuses is named with its reason (wrong dump, server down).
7. Start the game. Within about 30 seconds the LIVE tab shows the console connected, the set and the first snapshot. An unlock shows on the page, on your profile, and as a short gold flash over the game on the console.

The full walkthrough is in docs/USAGE.md; the same steps are on the project page.

Playing from the original disc

Put the disc in the drive, press START for OPL's main menu and choose RA: check disc support, then RA: launch disc. The check reads the disc through the console's own driver and asks the PC the same way it does for an image; the launch boots the disc under OPL's in-game hooks, so telemetry and unlocks work as they do from USB. In this mode OPL's virtual memory cards, per-game compatibility patches and cheats are not available: they live inside the part of OPL that emulates the drive, which a real disc does not use.

Without a PS2

Without the console, xeRAbora shows your RetroAchievements account while you play on an emulator: the current game, new unlocks, what to go for next and what you can miss. Progress inside an achievement ("3 of 10") and live leaderboards work only with the PS2.

What it shows, and where the data comes from

Tab	What you see	Source	Refresh
LIVE, console streaming	The running game as the console sees it: each achievement's state, measured progress ("3 of 10"), its rarity among players and its RetroPoints, UP NEXT by the median time other players took (HIDE drops one you gave up on; the heading folds the block), missable warnings, the players' comments under a clicked row, live leaderboard trackers, and a strip with points, RetroPoints, your rank in the game and the time the set costs. Filters and orders (author, progression path, median time, rarity) sit in a drawer behind one thin bar. The CONSOLE sub-tab holds the link, the snapshot rate, the losses and the console's own counters: link mode, send time and errors, frames it skipped.	rcheevos on the console's snapshots; medians, rarity, rank and comments from the Web API	every frame
LIVE, following	The game your account is in on any emulator with RetroAchievements, the rich presence line, whether the server sees you online, this session's unlocks, UP NEXT, rarity and the missable warnings. No measured progress, no trackers and no console counters: those need a memory source.	Web API (profile, recent unlocks)	every 20 s, the online flag once a minute
LIBRARY	Every game your account has touched, up to 500: two bars per game, softcore and hardcore, the highest award in the corner of the cover, filters by status and console. Not the whole RetroAchievements catalogue: only what you have played.	Web API (completion progress)	cached 2 min
GAME	One set in full: the author's order, the intended path (progression, win condition, missables flagged), the median-time order or rarity; each achievement's points, unlock date, median, rarity and RetroPoints, and its comments on a click. The player count and your rank in the head. A game's subsets and its main set as a strip of chips, so you move between them without leaving the tab.	Web API (game info, game progression, the console's game list for subsets)	cached 30 s
BOARDS	A game's leaderboards with the top entry and your own, and, when the console plays, the trackers moving with the game.	Web API; trackers from the console	on open
Header	Your name and points. The language menu: English, Brazilian Portuguese, Spanish.	Web API (profile)	on load

Unlocks reach your profile the moment rcheevos fires them, with a toast on the page, a short sound on the PC and the gold flash on the console.

The client itself

The interface is a page the client serves to itself on localhost, compiled into the executable. One copy runs at a time; a second start opens the running copy's page. The client exits by itself about 15 seconds after its last page is closed, and at once from the red QUIT in the footer. Run as a service, --server keeps it up with no page open.

• The look follows the source. Idle, the page is blue-grey. While a console streams it turns gold and the cover spins as a disc that slows on lost snapshots. While following an emulator it turns blue. The source is named under the game's title: CONSOLE with its address, or EMULATOR.
• Settings hold the account, the Web API key, the network switch and the theme: NEON CLASSIC or 8-BIT, kept per browser. Login is optional: the library, the game view and the boards work on the key alone; unlocking needs the account.
• FOLLOW MY PLAY is the switch at the top of LIVE. On by default; the console takes over the moment it connects.
• Language is the menu in the header, remembered by the browser that chose it: a phone can read the page in Spanish while the PC stays English. #lang=es in the address does the same for one window.
• On a phone. OPEN TO THE NETWORK on SETTINGS serves the page to your Wi-Fi; type the address it shows into a phone or tablet and add the page to the home screen. Up to four pages watch at once. Other devices see everything; the login, the key, the switches and QUIT work only from the PC that runs the client. On a narrow screen the tabs move to a bar along the bottom. To run the client itself on a phone, with no PC at all, there is the Android app.
• Stream-ready. See Perfect for streaming. --obs DIR writes text labels and a data.json for a layout of your own. #tab=live opens a window straight on a tab.
• Sounds on connect, on a stream that stops for five seconds, and on an unlock. --no-sound turns them off; your own connect.wav, disconnect.wav or achievement.wav in the sounds folder next to the saved login replace them. Linux plays through paplay, aplay or pw-play; macOS through afplay.
• One file. Windows, Linux or macOS, nothing to install. On Windows a double click opens the page and no console window; --console opens one. Everything is also written to xerabora.log next to the saved login. macOS keeps a downloaded file under quarantine, so the first run stops with a warning: xattr -dr com.apple.quarantine xerabora-macos, or open the file once from Finder's right-click menu. We do not sign the build; signing takes a paid Apple developer account.

Perfect for streaming

The STREAM button in the header turns the page into one clean screen: the game's head with a red ● LIVE chip, the source, the count and the points, then the achievements, nothing else. The same filters, orders and LIST / GRID as LIVE stay one click away in the side drawer. Capture the window in OBS, or keep it on a second monitor. BACK TO TABS returns.

• Two looks. NEON CLASSIC, the default, and 8-BIT: an NES palette, pixel fonts, square corners and stepped progress bars.
• Badges as a wall. GRID shows the set the way the site does, the earned ones ringed blue for softcore, gold for hardcore.
• What is next. UP NEXT ranks the locked achievements by the median time other players took; the rare ones carry their share of players.
• The game's own line. The rich presence line runs as a bar across the top.

Any hardware, one protocol

The client knows nothing about the PS2. It identifies a game by the hash an agent sends, asks the RetroAchievements server for the set, derives the list of memory addresses the set reads, and hands that watch list to the agent. From then on the agent streams those addresses every frame and the client runs rcheevos. Unlock notices go the other way.

The whole exchange is a handful of UDP messages, documented in protocol/PROTOCOL.md. An agent for another console needs to read that console's memory, compute the RetroAchievements hash, and speak the protocol. The client does the rest.

---

Building

OPL fork needs the ps2dev toolchain. The simplest route is the same container the OPL project uses:

docker run --rm -v "$PWD":/src -w /src/opl ghcr.io/ps2homebrew/ps2homebrew:main make PADEMU=0 all

make RA_DEBUG=1 all builds the debug variant: it writes the loader's module results to RA/launch.txt on the share. Inside the game it does nothing extra.

PC client (client/) builds on its own, without the OPL fork: it needs only rcheevos and the headers in protocol/. make on Linux needs gcc and libcurl development headers. make windows cross-compiles a static xerabora.exe with MinGW-w64 (gcc-mingw-w64-x86-64 on Debian/Ubuntu); HTTPS goes through WinHTTP, so the Windows build has no external dependencies. make macos builds one file holding both Mac architectures, against the libcurl the system ships.

The page is written in client/ui/src: a skeleton, one stylesheet per concern, one script per tab, with Preact, htm and signals vendored in client/ui/vendor. python3 tools/build-page.py (from client/) assembles ui/index.html, embeds it into src/ui_page.c and rebuilds docs/demo.html; --watch does that on every save. While working on it, --ui-file client/ui/index.html serves the assembled page from disk without a rebuild of the client.

Android app (android/) builds the same client sources with the Android NDK into an APK: ./gradlew assembleDebug in android/, with JDK 21, the Android SDK and the NDK installed. How it hooks into the client, and how releases are signed, is in android/README.md.

Both the OPL fork and rcheevos are git submodules. Clone with --recurse-submodules, or run git submodule update --init --recursive after cloning. Building the client needs only third_party/rcheevos; the opl submodule is there to build the console loader.

Repository layout

path	contents
client/	the PC client: the RetroAchievements client, its page (ui/), the protocol side
android/	the same client as an Android app: backends for http.h and sound.h, the service and the notifications (android/README.md)
protocol/	the wire protocol — PROTOCOL.md plus the shared ra_snap.h / ra_watch.h
opl/	submodule → the OPL+RA fork, the PS2 agent. RA additions: src/ra*.c, ee_core/src/ra.c, ee_core/src/ra_overlay.c, modules/network/raudp, modules/network/ps2ips-ra, small changes in SMSTCPIP and smap-ingame
third_party/rcheevos	submodule, rcheevos, unmodified
docs/	the project page, the usage guide, screenshots
tools/	development helpers

Notes for OPL developers

• modules/network/ps2ips-ra is ps2sdk's ps2ips.irx with two fixes. In do_recvfrom the shared RPC buffer was overwritten before the DMA destination was read, so UDP receive on the EE never worked. In both do_recv and do_recvfrom the 144-byte rests_pkt was DMA'd into the EE's 128-byte _intr_data, zeroing the socket close pointer in libps2ips right behind it; every socket then leaked and the menu had one network operation per boot. The transfer is now capped at 128 bytes. EE code receiving through ps2ips should still use 64-byte aligned buffers and lengths that are multiples of 64 (see src/ranet.c). Both candidates for upstreaming to ps2sdk.
• Non-blocking receive on the menu (netman) lwIP stack: setting the socket non-blocking with fcntl(O_NONBLOCK) did not take effect on hardware; recvfrom blocked the EE I/O thread forever when no reply came. src/ranet.c therefore passes MSG_DONTWAIT (value 0x08, the lwIP/IOP value — not the EE <sys/socket.h> 0x80, since the flag is forwarded verbatim over RPC to lwip_recvfrom on the IOP) on every receive, which lwIP honours per call.
• Inside a running game lwIP is idle in both directions: the SMAP receive FIFO fills and nobody drains it, and lwip_sendto() puts nothing on the wire. raudp therefore walks the receive descriptors itself and sends its replies down the same raw path as the telemetry.
• modules/network/common/smstcpip.h declared lwip_recvfrom with six arguments; the SMSTCPIP implementation takes eight. Fixed here.
• The fork loads the network modules in every game mode, including USB, and builds cdvdman with USE_DEV9=1 for the BDM variant.

License

The OPL fork keeps OPL's license (Academic Free License 3.0). The PC client is released under the MIT license. rcheevos is MIT.

The RA mark belongs to RetroAchievements and the OPL name to the Open PS2 Loader project; they appear here to show what this project connects.