Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rommapp/romm/llms.txt

Use this file to discover all available pages before exploring further.

RomM integrates with RetroAchievements.org to display achievement lists alongside your ROMs and to track unlock progress per user. When you open a game’s detail page, RomM fetches the achievement set for that ROM — identified by matching its hash against the RetroAchievements database — and shows each achievement’s title, description, point value, and badge image.

​
Prerequisites

  • A free account at retroachievements.org
  • A RetroAchievements Web API key (found under Settings → Keys on the website)

​
Setup

1

Generate your API key

Log in to RetroAchievements.org, navigate to Settings → Keys, and copy your Web API Key.
2

Add the API key to RomM

Set the RETROACHIEVEMENTS_API_KEY environment variable in your Docker Compose file:
environment:
  - RETROACHIEVEMENTS_API_KEY=your_api_key_here
Restart the container for the change to take effect.
3

Scan your library

Run a full library scan (or wait for the scheduled rescan) so RomM can calculate ROM hashes and look up matching achievement sets.
4

View achievements

Open any game that has an achievement set on RetroAchievements. The Achievements tab on the game detail page shows each achievement’s badge, title, description, point value, and unlock counts.

​
Configuration

VariableDefaultDescription
RETROACHIEVEMENTS_API_KEY(empty)Your RetroAchievements Web API key. The integration is disabled when this is not set.
REFRESH_RETROACHIEVEMENTS_CACHE_DAYS30Number of days before the local hash-to-game-ID cache is refreshed from the RetroAchievements API.
ENABLE_SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNCfalseEnable the scheduled progress sync task.
SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRON0 4 * * *Cron expression controlling when the progress sync runs (default: 4 AM daily).

​
How ROM identification works

RetroAchievements identifies games by hashing ROM files using its own hashing algorithm. RomM calculates a hash for each ROM during a scan, then looks it up in a platform-specific hash index downloaded from the RetroAchievements API. The hash index is stored locally as ra_hashes_v2.json inside the platform’s resource directory. RomM refreshes this file automatically once the age exceeds REFRESH_RETROACHIEVEMENTS_CACHE_DAYS.
You can force RomM to use a specific RetroAchievements game entry for a ROM by adding an (ra-XXXXX) tag to the filename, where XXXXX is the RetroAchievements game ID. For example: Sonic the Hedgehog (USA) (ra-1).md. This bypasses hash-based lookup and pins the achievement set directly.

​
Supported platforms

RomM maps the following platform slugs to RetroAchievements system IDs:
PlatformRA System ID
NES / Famicom7
SNES / Super Famicom3
Nintendo 642
Game Boy4
Game Boy Color6
Game Boy Advance5
Nintendo DS18
GameCube16
Wii19
Sega Genesis / Mega Drive1
Sega Master System11
Sega CD9
SEGA 32X10
Sega Saturn39
Dreamcast40
Game Gear15
PlayStation12
PlayStation 221
PSP41
TurboGrafx-168
Atari 260025
Atari 780051
Lynx13
Jaguar17
Neo Geo Pocket / Color14
MSX / MSX229
Arcade27
PC-FX49
Virtual Boy28
WonderSwan / Color53
Pokémon Mini24
Famicom Disk System81
Windows102
Platforms not in this list will not have RetroAchievements data, but will still appear in your library normally.

​
What data RomM fetches

For each matched ROM, RomM retrieves the following from the RetroAchievements API:
  • Game details: title, cover image, in-game screenshot, release date, genre, publisher, and developer
  • Achievement list: for every achievement in the set — RA ID, title, description, point value, badge image URLs (locked and unlocked variants), total unlock counts, display order, and type (progression, win condition, missable, etc.)
User progression data (per-game) includes:
  • Total achievements possible
  • Number unlocked (normal and hardcore)
  • Most recent unlock date
  • Highest award kind (e.g. beaten, mastered)
  • Per-achievement unlock date (normal and hardcore)

​
Scheduled progress sync

When ENABLE_SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC=true, RomM periodically fetches updated progress for all users who have linked their RetroAchievements username. The sync is incremental: if the unlock count and most recent unlock date for a game haven’t changed since the last run, RomM skips the per-game API call and reuses cached data, minimising API usage. 
environment:
  - ENABLE_SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC=true
  - SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRON=0 4 * * *  # 4 AM daily
The progress sync runs automatically on the configured cron schedule. You can monitor its status from the Administration → Tasks page.

​
Linking a RetroAchievements username

Each RomM user can link their RetroAchievements username in their profile settings. Once linked, the achievements tab shows their personal unlock status (locked/unlocked badge overlay) on top of the global achievement data.

Build docs developers (and LLMs) love

Get started for freeTalk to us