Skip to content

RetroAchievements

Jump to bottom
nickybmon edited this page May 14, 2026 · 5 revisions

RetroAchievements

OpenEmu-Silicon includes built-in support for RetroAchievements — a free service that adds achievements to classic games. As you play, achievements are tracked in real time and credited to your account on the RetroAchievements website.

What it looks like

When you unlock an achievement, an overlay banner appears at the bottom of the game window showing the achievement name and point value. It fades in, holds for a few seconds, then fades out — no interruption to gameplay.

In-game achievement banner showing "Achievement Unlocked! A New Quest +10 pts" during Pokémon Emerald

A notification also lands in macOS Notification Center so you have a record of everything you earned in a session.

macOS Notification Center showing multiple OpenEmu achievement notifications

Your progress syncs to your RetroAchievements profile. You can see earned achievements, point totals, and completion percentage for every game you've played.

RetroAchievements website showing progress for Zelda: The Minish Cap and Pokémon Emerald

Setup

1. Create a RetroAchievements account

Sign up for free at retroachievements.org. Your username and progress are stored on their servers — achievements you earn in OpenEmu-Silicon will appear on your profile.

2. Sign in from OpenEmu Preferences

Open OpenEmu → Preferences → Achievements and enter your RetroAchievements username and password.

When sign-in succeeds the pane shows ✓ Signed in as <username>. Your credentials are stored securely in the macOS Keychain and restored automatically on relaunch — you only need to sign in once.

3. Load a game and play

That's it. Load any supported game and achievements are tracked automatically from the moment emulation starts. No additional setup is needed per-game.

Supported systems

RetroAchievements is supported across 9 cores and 7 systems:

System Core
Game Boy Advance mGBA
Game Boy / Game Boy Color mGBA, Gambatte
Super Nintendo SNES9x, BSNES
NES / Famicom FCEU, Nestopia
Genesis / Mega Drive Genesis Plus GX
Master System / Game Gear Genesis Plus GX
Sega CD / SG-1000 Genesis Plus GX

Coming next

Rollout is continuing in phases. Track each phase in the linked issue:

Phase Systems
Phase 2 Nintendo 64, PlayStation, PC Engine / TurboGrafx-16, PC Engine CD, Atari Lynx, Neo Geo Pocket, Sega 32X, Sega CD, Dreamcast, GameCube, Wii
Phase 3 Sega Saturn, Virtual Boy, WonderSwan, PC-FX
Phase 4 Nintendo DS, PSP, Atari 2600/5200/7800/8-bit, ColecoVision, MSX, Intellivision, 3DO, Odyssey², Vectrex, Pokémon Mini, Watara Supervision, Commodore 64

Known issue: On some slow-loading ROMs, achievements may not register on first launch. Closing and relaunching the game resolves it. (#425)

How it works

OpenEmu-Silicon integrates the open-source rcheevos library, which handles achievement evaluation entirely on-device. Here's the flow:

  1. Sign-in — When you enter your credentials, OpenEmu exchanges them for a session token via the RetroAchievements API and stores the token in the Keychain.
  2. ROM load — When a game starts, the token is passed over XPC to the emulator helper process. The helper calls rc_client_begin_login_with_token to authenticate with the RA server and load the achievement set for that ROM.
  3. Per-frame evaluation — Every emulated frame, the core calls rc_client_do_frame, which checks the game's memory against achievement trigger conditions using rcheevos's built-in logic.
  4. Unlock event — When a condition is met, rcheevos fires an event. The helper sends it back to the main app over XPC, which shows the in-game banner and fires a system notification.
  5. Score submission — rcheevos submits the unlock to the RetroAchievements server in the background. Your profile updates within seconds.

Hardcore mode

Hardcore mode (earning achievements without save states or rewind) is not yet supported. Unlocks in this release are earned in standard (softcore) mode.

Troubleshooting

No achievements loading for a game

  • Confirm the game has achievements on the RetroAchievements website — not all ROMs are supported.
  • Make sure you're signed in (Preferences → Achievements should show your username).
  • Check that you're using a clean, unmodified ROM. Patched or hacked ROMs will not match the RA hash database.

Sign-in fails

  • Double-check your username and password at retroachievements.org.
  • The password used here is your RetroAchievements account password, not a separate API key.

Banner doesn't appear

  • Open Preferences → Library and confirm "Show notifications during gameplay" is enabled (it is by default).
  • If you're on a debug build, use Preferences → Secrets → Preview achievement banner to test the overlay while a game is running.

Clone this wiki locally