RetroAchievements Integration

TruchiEmu integrates with RetroAchievements.org to track and unlock achievements in classic games.

Overview

RetroAchievements turns classic games into a completion challenge. Log into your RetroAchievements.org account and TruchiEmu will track your progress, unlock achievements as you earn them, and share what you're playing with the community. A Hardcore Mode is available for purists who want the leaderboard-eligible run.

What You Get

Achievement Tracking: Unlock trophies for in-game feats beat the boss without dying, find the secret, max the combo, and so on
Rich Presence: Your current game and activity are shared with the RetroAchievements community automatically
Hardcore Mode: Earn achievements the way the leaderboard counts them no save states, no rewinds, no slow motion, no cheats. Off by default; opt in from the Achievements panel
In-Game Notifications: Achievement unlocks pop up as a pill on the game window so you don't miss them
Profile & Game List: Your unlocked achievements sync to your RetroAchievements.org profile

Step-by-Step Configuration Guide

Initial Setup

Create RetroAchievements Account
Visit RetroAchievements.org and create a free account. Verify your email address to unlock full functionality.
Configure TruchiEmu Credentials
In TruchiEmu, go to Settings → Achievements → Account and enter your RetroAchievements username, password, and Web API key. Generate your Web API key from the RetroAchievements website under Settings (Control Panel).
Connect
Click "Connect" to log in. After successful authentication, you'll see a green "Connected" indicator with your user stats.
Enable RetroAchievements
Toggle "RetroAchievements" in the main Achievements settings panel to enable or disable the integration.
Rich Presence
Rich presence is displayed automatically during gameplay when RetroAchievements is enabled. The current activity message is shown in the Rich Presence section of the Achievements settings. Messages are generated automatically from the game's rich presence script — no manual configuration needed.

Game-Specific Setup

Load Supported Game
Open a ROM for a supported system. TruchiEmu automatically detects if the game has achievements available.
View Achievement List
Open the achievement list from the game menu to see all available achievements for the current game.
Track Achievement Progress
Achievement progress is displayed during gameplay with on-screen notifications when conditions are met.

Troubleshooting

Achievements Not Unlocking

Symptom: Playing a supported game but achievements aren't being detected.

Solution: Verify your ROM is the correct version (usually USA/World). Check ROM hash against RetroAchievements database. Ensure achievement detection is enabled in settings.

Connection Errors

Symptom: "Failed to connect to RetroAchievements.org" error message.

Solution: Check your internet connection and firewall settings. Verify API key is correct and hasn't expired. Try generating a new API key from the RA website.

Rich Presence Not Working

Symptom: RA profile not showing current game status.

Solution: Ensure you are logged in with valid credentials and that RetroAchievements is enabled. Rich presence requires an active game session and is sent automatically to the RA website.

Hardcore Mode Restrictions

Symptom: Can't use save states, rewind, or slow motion after enabling Hardcore mode.

Solution: This is intended behavior. Hardcore mode blocks save states, rewind, slow motion, and cheats for competitive fairness. Disable Hardcore mode to restore functionality.