RetroAchievements Integration

Service Overview

The RetroAchievements service in TruchiEmu provides seamless integration with the RetroAchievements.org platform, allowing you to earn achievements in thousands of supported classic games. Our implementation includes real-time achievement tracking, rich presence integration, and automatic save state management when achievements are earned.

Achievement detection pipeline from game memory to RetroAchievements.org synchronization

Core Features

• Real-time Memory Monitoring: Continuous scanning of game memory for achievement conditions
• Rich Presence: Share your current game and activity with the RetroAchievements community
• Hardcore Mode: Earn achievements without save states, rewinds, or cheats for maximum prestige
• Leaderboard Integration: Compete in time trials, high scores, and challenge leaderboards
• Automatic Backups: Save state created automatically when earning achievements for proof

Technical Architecture

The achievement system consists of several integrated components:

• Memory Scanner: Efficient pattern matching engine that monitors game RAM for achievement triggers
• Achievement Engine: Core logic that evaluates achievement conditions and manages state
• API Client: Secure HTTPS client for communicating with RetroAchievements.org API
• Rich Presence Manager: Updates your Discord and RA profile with current game status
• Authentication Service: Secure token-based authentication with encrypted credential storage

Supported Systems

TruchiEmu supports achievements on the following platforms: NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Sega Genesis, Sega CD, Sega 32X, TurboGrafx-16, and Neo Geo Pocket. Achievement support is automatically detected when loading compatible ROMs.

Step-by-Step Configuration Guide

Initial Setup

1. Create RetroAchievements Account

   Visit RetroAchievements.org and create a free account. Verify your email address to unlock full functionality.

   
2. Configure TruchiEmu Credentials

   In TruchiEmu, go to Settings → Achievements → Account and enter your RetroAchievements username and API key. Generate your API key from the RetroAchievements website under Account Settings.

   
3. Test Connection

   Click "Test Connection" to verify your credentials work correctly. You should see a success message with your current stats.

4. Enable Achievement Detection

   Toggle "Enable Achievement Detection" in the main Achievements settings panel. This activates the memory scanner for supported games.

5. Configure Rich Presence

   Enable "Show Rich Presence" to share your gaming activity with Discord and the RA community. Customize the message format in the text field provided.

Advanced Configuration

1. Hardcore Mode Setup

   Enable "Hardcore Mode" for competitive achievement hunting. This disables save states, rewind, slow motion, and cheat codes. A confirmation dialog will appear warning about these restrictions.

2. Leaderboard Notifications

   Configure leaderboard notification settings under Settings → Achievements → Leaderboards. Set audio alerts, popup duration, and notification position on screen.

3. Notification Positioning

   Adjust where achievement notifications appear on screen. Choose from corner positions or set custom coordinates. Test positioning with the preview button.

Game-Specific Setup

1. Load Supported Game

   Open a ROM for a supported system (NES, SNES, Genesis, etc.). TruchiEmu automatically detects if the game has achievements available.

2. View Achievement List

   Press Cmd+A or select View → Achievement List to see all available achievements for the current game. The list shows progress, difficulty, and completion status.

   
3. Track Achievement Progress

   Enable "Show Progress in OSD" to display achievement progress directly in the game view. Progress bars appear for achievements with measurable progress.

4. Challenge Filtering

   Filter achievements by difficulty, type (progression, missable, etc.), or completion status to focus on specific goals during gameplay.

Configuration Examples

Example 1: Competitive Hardcore Setup

// Achievements Configuration
domain = "retroachievements.org"
username = "YourUsername"
api_key = "YourAPIKey"

// Gameplay Restrictions
hardcore_mode = true
disable_save_states = true
disable_rewind = true
disable_cheats = true

// Notifications
notification_duration = 5.0
sound_enabled = true
sound_volume = 0.7
screenshot_enabled = true

// Rich Presence
rich_presence_enabled = true
rich_presence_format = "Playing %g - %m achievements earned"

// Performance
memory_scan_interval = 1          // In frames
scan_efficiency_mode = "balanced"

Example 2: Casual Achievement Hunting

// Achievements Configuration
domain = "retroachievements.org"
username = "YourUsername"
api_key = "YourAPIKey"

// Gameplay Restrictions
hardcore_mode = false
allow_save_states = true
allow_rewind = true
cheats_block_achievements = true    // Cheats disable achievements

// Notifications
notification_duration = 3.0
sound_enabled = true
sound_file = "custom_unlock.wav"
notification_position = "top_right"
progress_in_osd = true

// Quality of Life
auto_screenshot = true
screenshot_delay = 100              // Milliseconds after unlock
achievement_list_hotkey = "Cmd+A"

// Social Features
rich_presence_enabled = true
discord_integration = true
leaderboard_notifications = true

Example 3: Offline Achievement Queue

// Achievements Configuration
offline_mode = false              // Set to true for pure offline play
queue_achievements = true         // Queue when offline
auto_sync = true                  // Sync when connection restored
sync_interval = 300               // Sync every 5 minutes

// Network Settings
api_timeout = 30
retry_attempts = 3
offline_cache_size = 50           // Max achievements in queue

// Achievement Detection
enable_detection = true
validate_hashes = true            // Verify ROM is correct version
detect_unofficial = false         // Ignore unofficial achievements

// Notification Settings
queue_notification = true         // Notify when achievements queued
sync_notification = true            // Notify when sync completes
show_offline_indicator = true     // Show offline status in UI

Troubleshooting