// OPENBOX DOCS

RetroAchievements

Connect RetroAchievements, match ROMs to achievement sets, and track progress.

OpenBoxGL integrates with RetroAchievements to match your ROMs to achievement sets, show earned and hardcore progress, serve badges, and inject your credentials into emulator configs so emulators enable achievements themselves.

What it does

  • Matches ROMs to achievement sets by content hash.
  • Shows progress per game: earned, hardcore, beaten, mastered.
  • Serves achievement badges in the game detail pane.
  • Injects credentials into RetroArch, Dolphin, and PCSX2 configs so those emulators can enable achievements during play.

Set it up

  1. Get credentials. Create a RetroAchievements account and generate a web API key on your RetroAchievements profile page.
  2. Enter them in Settings > RetroAchievements (username + web API key), or set the environment variables in ~/.env:
    • RETROACHIEVEMENTS_USERNAME (aliases RA_USERNAME, OPENBOX_RA_USERNAME)
    • RETROACHIEVEMENTS_API_KEY (aliases RA_API_KEY, RETROACHIEVEMENTS_KEY, OPENBOX_RA_API_KEY)
  3. Credentials are validated against API_GetUserProfile.php before saving and stored in retroachievements.json (mode 0o600).
  4. Open a game's detail pane. If its platform supports auto-matching, use the RetroAchievements section to match the ROM.

Matching

RetroAchievements matching is by ROM hash, so the local file must be the exact ROM the achievement set expects. Hashing supports:

PlatformNotes
NES, SNESHeader stripping applied
Nintendo 64Byte-swapped .v64/.n64 handled
Game Boy / Color / Advance—
Sega Genesis / Mega Drive—
Master System, Game Gear—
Atari 2600 / 7800, LynxHeader stripping applied
PC EngineHeader stripping applied
ArcadeMatched by set name

ROMs inside ZIP and 7z archives are hashed too. For other platforms, enter a RetroAchievements Game ID manually in Edit metadata.

Playing with achievements

  • Inject credentials (Settings or the RA section) writes cheevos_* settings into RetroArch and the equivalent configs for Dolphin and PCSX2, for both native and Flatpak paths. With credentials injected, RetroArch enables achievements in-game (hardcore mode included) without further setup.
  • Progress — earned, hardcore, beaten, mastered — is fetched from the RetroAchievements API and shown per game.
  • Badges load from media.retroachievements.org on demand and are cached locally.

Troubleshooting

ProblemCause / fix
"Configure RetroAchievements first."No credentials saved. Add username + API key in Settings or ~/.env and restart.
"Rejected credentials"The username/key did not validate against API_GetUserProfile.php. Double-check the API key (it is not your password).
No match found for a ROMThe hash does not match a set on RetroAchievements, or the platform is not auto-matched. Verify the ROM is the exact dump; use a different ROM set; or enter the Game ID manually.
Achievements not showing in emulatorRun Inject credentials after launching once with the emulator, and confirm the emulator's achievements setting is enabled (RetroArch: Settings > Achievements).
System/game lists staleLists are cached for 7 days under cache/retroachievements/.

See also