RAOfflineProxy

Emulator Config Patching (Android) ​

Overview ​

RAOfflineProxy patches the supported emulator config so RetroAchievements traffic is redirected to the local proxy.

RetroArch stores its configuration in a file called retroarch.cfg. To redirect achievement traffic to the local proxy, RAOfflineProxy changes two settings in this file and imports your saved RetroAchievements login:

  • The custom achievement server is pointed at the proxy on your device
  • Hardcore mode is disabled
  • The saved cheevos_username and cheevos_token are imported into RAOfflineProxy's local credential cache when present
  • If no token is present, cheevos_username and cheevos_password are used once to retrieve a token through RA's login endpoint

Each supported emulator is patched and reverted independently depending on which emulator toggles are enabled in the app.

Argosy Launcher is the exception: it has its own proxy URL setting, so RAOfflineProxy does not patch it at all.

Patching and reverting happen automatically when you start and stop the proxy: there is no separate setup step. For the patched settings to be picked up reliably, fully close the emulator before starting or stopping the proxy, then relaunch it afterward.

Automatic Patching (Start Proxy) ​

When you press Start proxy in the action bar, the app imports credentials from each enabled supported emulator, patches the emulator config, then starts the proxy service. Do this only while the emulator is fully closed.

For RetroArch, the app patches retroarch.cfg.

  • It looks for the RetroArch config in common Android RetroArch paths
  • If you have previously granted folder access, it uses the saved permission to patch the file directly
  • If the file is directly writable, it patches it in place
  • On Android 12 and below, if folder access is needed, the app can prompt you to grant access to the RetroArch folder that contains retroarch.cfg
  • Before patching, it creates a one-time sibling backup named retroarch.raofflineproxy.cfg if that backup does not already exist

Automatic Reverting (Stop Proxy) ​

When you press Stop proxy, the app reverts any enabled emulator configs that were patched when the proxy started. Do this only while the emulator is fully closed, then relaunch it after the revert finishes.

The app reverts retroarch.cfg to clear the custom server setting so RetroArch connects directly to RetroAchievements again.

Why Hardcore Mode is Disabled ​

Hardcore mode is not supported by RAOfflineProxy. Any hardcore award request is rejected by the proxy, so leaving hardcore enabled while the proxy is running would result in silent unlock failures.

Which side turns it off depends on how the emulator is patched:

  • RetroArch, Dolphin, and PPSSPP when its config file is patched: RAOfflineProxy disables hardcore while patching, records the original value so it survives a process restart, and restores it when you stop the proxy
  • PPSSPP on the broadcast path, Flycast, and WatermelonDS: the emulator disables hardcore itself while the custom host is active and restores your setting once the override is cleared, so RAOfflineProxy never writes the setting
  • ARMSX2: hardcore is deliberately left under your own control, so turn it off in the emulator before starting the proxy
  • ARMSX1 and Mupen64Plus AE (fork): have no hardcore mode at all, so there is nothing to disable. ARMSX1 is softcore-only by construction: its achievements client is hardwired to softcore and the hardcore toggle was removed from its UI

If you are unsure how your emulator behaves, turn hardcore off in the emulator yourself before starting the proxy.