RetroAchievements
How achievements work on ArchR, and how to turn them on
RetroAchievements adds achievements and leaderboards to retro games. On ArchR the whole thing lives inside RetroArch. There is no RetroAchievements screen in EmulationStation, so you turn it on by editing one configuration file over SSH.
Why there is no menu for it
EmulationStation's RetroAchievements pages (the account screen, the achievement browser and the per-game progress view) are compiled in only when whoever builds the image supplies a RetroAchievements developer key. The published ArchR images are built without one, so those pages are not in the binary and the menu entries that would open them never appear.
That is a build-time decision, not a bug and not something a setting can undo. It also does not stop achievements from working, because the client that unlocks them is RetroArch, not EmulationStation.
Turning it on
setsettings.sh rewrites RetroArch's configuration before every launch, reading from /storage/.config/system/configs/system.cfg. Anything you set in RetroArch's own menu is overwritten the next time you start a game, so system.cfg is the place to edit.
Create an account
Free at retroachievements.org.
Get the console on the network
ES → Network Settings → Enable WiFi, then fill in WiFi SSID and WiFi key.
Open a shell
Over SSH, or edit the file from a computer over Samba.
Edit system.cfg
Find these three lines in /storage/.config/system/configs/system.cfg and fill them in:
global.retroachievements=1
global.retroachievements.username=yourname
global.retroachievements.password=yourpasswordStart a game
The next launch writes cheevos_enable = "true" into RetroArch's config along with your credentials, and RetroArch logs in while the game loads.
Your password sits in plain text in system.cfg, which is readable by anyone with access to the console or to the Samba share. Keep that in mind if you reuse passwords.
The other settings
Each of these is read from system.cfg and copied into RetroArch's config. Use 1 for on and 0 for off.
Key in system.cfg | What it does |
|---|---|
global.retroachievements.hardcore | Hardcore mode, see below |
global.retroachievements.leaderboards | Leaderboard submissions |
global.retroachievements.richpresence | Publishes what you are playing on your profile |
global.retroachievements.badges | Shows the achievement badge with the notification |
global.retroachievements.verbose | Extra on-screen messages from the client |
global.retroachievements.screenshot | Takes a screenshot on every unlock |
global.retroachievements.challengeindicators | Shows an indicator while a challenge is in progress |
global.retroachievements.testunofficial | Includes achievements that are still unofficial |
global.retroachievements.active | Encore mode, re-triggers achievements you already have |
global.retroachievements.sound | Filename of a sound to play on unlock |
The same keys work per system if you drop the global. prefix and use the system name instead, so snes.retroachievements=0 turns achievements off for the SNES only.
Which systems are covered
The launcher only enables achievements for platforms on its own list, which covers 63 of the systems ArchR ships:
3do, arcade, arduboy, atari2600, atari7800, atarilynx, cdi, colecovision, cps1, cps2, cps3, dreamcast, famicom, fbn, fds, gamegear, gb, gba, gbc, genesis, intellivision, mastersystem, megacd, megadrive, megadrive-japan, msx, msx2, n64, nds, neogeo, nes, ngp, ngpc, odyssey2, pcengine, pcenginecd, pcfx, pokemini, psp, psx, saturn, sega32x, segacd, sfc, sg-1000, snes, snesmsu1, supergrafx, supervision, tg16, tg16cd, vectrex, virtualboy, wonderswan and wonderswancolor, plus the hack variants (gbh, gbah, gbav, gbch, genh, ggh, nesh, snesh).
Two more names are on the list but have no folder on ArchR: neogeocd and ps2.
Anything outside that list launches with cheevos_enable = "false".
Only libretro cores count
Achievements come from RetroArch. The launcher only writes the achievement configuration when the emulator is RetroArch, so the standalone emulators (DraStic, PPSSPP standalone, melonDS standalone, DuckStation standalone, Flycast standalone, Mupen64Plus standalone, Yabasanshiro standalone) never talk to RetroAchievements.
Three systems on the achievement list ship with a standalone emulator as their default:
| System | Default | Switch to |
|---|---|---|
| nds | DraStic | melonds, melondsds, desmume or skyemu |
| psp | PPSSPP standalone | there is no libretro PPSSPP option for psp on ArchR |
| saturn | Yabasanshiro standalone | yabasanshiro under RetroArch |
To change it, open a game list, press SELECT for the system's options and pick Advanced system options, or set it for a single game through Advanced game options in that game's menu. Everything else on the achievement list already defaults to a libretro core.
Hardcore mode
Hardcore is what earns the Mastered badge. With it on, RetroArch turns off rewind, refuses to apply cheats and disables slow motion. You can still save a state, but the moment you load one, RetroArch drops out of hardcore for the rest of the session and tells you so on screen.
Most people leave hardcore off for normal play and turn it on for a run they want on record.
Where unlocks show up
- On screen, as a notification from RetroArch when the achievement fires.
- On your profile at
https://retroachievements.org/user/<your-username>, which is where the achievement lists, leaderboards and mastery sets live. - As a PNG in
/storage/roms/screenshots/if you turned the screenshot option on.
From the console you can print a summary of your profile without a browser:
archr-retroachievements-infoWith no argument it reads the username from system.cfg. Give it a name to look at someone else's profile. The output is XML.
Marking which games have achievements
EmulationStation can still tell you which of your ROMs have an achievement set, even without the achievement browser. It hashes each file and checks it against RetroAchievements' public hash list.
ES → System Settings → Frontend Developer Options → Find all games with netplay/achievements. It takes a while on a large library.
After that, User Interface Settings → Show RetroAchievements icon puts a marker on those games, and the automatic retroachievements collection under Game Collection Settings gathers them into one list. Both need global.retroachievements=1, otherwise the icon stays hidden.
Troubleshooting
Nothing unlocks even though the game is on RetroAchievements. The service matches games by hash. A ROM that differs from the verified dump, even by a header, produces a different hash and no achievements. Use no-intro or Redump dumps.
Login fails. Check the username and password in system.cfg, and check that the console can reach the site:
curl -sI https://retroachievements.orgHardcore turned itself off. You loaded a save state. Reset the core from the RetroArch quick menu (SELECT + X) to start a fresh session in hardcore.
Changes in the RetroArch menu do not stick. They cannot. setsettings.sh rewrites the relevant keys on every launch from system.cfg.