RetroAchievements Import

RetroAchievements Import

Import your retro gaming library from RetroAchievements into Tonkatsu Box. Games are matched against the IGDB database, with achievement progress and status tracking.

What gets imported

RA data	Tonkatsu Box
Played games	Games matched to IGDB
Achievement progress	Stored in tracker database with progress bars in game card
Highest award (mastered/beaten)	Status "Completed"
Games with achievements > 0	Status "In Progress" (or "Dropped" if inactive >90 days)
Games with 0 achievements	Status not changed
Award date (beaten/mastered)	Saved as Completed date
First earned achievement date	Saved as Started date
Last earned achievement date	Saved as Last Activity date
Unmatched games	Added to Wishlist (optional)
Console/platform	Mapped to IGDB platform (50+ consoles supported)

Requirements

• IGDB API key - needed to match RA games to the IGDB database. Set up IGDB
• RetroAchievements username - your RA profile name
• RetroAchievements Web API key - get one at retroachievements.org/controlpanel.php

Setting up RA credentials

1. Go to Settings → Import → RetroAchievements
2. Enter your RA Username
3. Enter your RA API Key
4. Tap Verify Connection to check credentials and preview your profile

Once credentials are saved, the RA badge will appear in the header of every game card whose platform is supported by RetroAchievements.

How to import

1. In Tonkatsu Box: go to Settings → Import → RetroAchievements
2. Enter credentials (if not already saved)
3. Configure options:
   • Add unmatched games to Wishlist - saves games that couldn't be found in IGDB
4. Choose target collection:
   • Create new collection - creates "RA Games"
   • Use existing collection - select from dropdown
5. Tap Start Import

Import progress

During import you'll see:

• Current stage (fetching RA library, matching games in IGDB)
• Progress bar with current / total count
• Name of the game being matched
• Live counters: added, updated, added to wishlist

How matching works

For each game in your RA library:

1. Manual links win first. If you've already linked the game to RA in its card (achievement section → "Link to RA") in a previous session, the importer reuses that IGDB id and skips the IGDB search entirely. The game won't be re-offered to the wishlist.
2. Otherwise, the app searches IGDB by the game's title, filtered by the mapped platform (e.g., SNES → IGDB platform 19)
3. It picks the best match: exact name > substring match > first result
4. If no results with platform filter - retries without the filter
5. If found - the game is added to the collection with the correct retro platform
6. If not found - the game is saved to your Wishlist with console name

Platform mapping

The importer maps 50+ RetroAchievements consoles to IGDB platforms, including:

NES, SNES, N64, Game Boy, GBA, Game Boy Color, Genesis/Mega Drive, Master System, Game Gear, Saturn, Dreamcast, Sega CD, 32X, PlayStation, PS2, PSP, Nintendo DS, 3DS, TurboGrafx-16, PC Engine, Neo Geo, Atari 2600/7800/Jaguar/Lynx, 3DO, ColecoVision, Virtual Boy, WonderSwan, Game & Watch, Arcade, and more.

Status sync rules

Status is always synced to match RA data - both during import and when opening a game card:

RA condition	Status	Notes
Award: mastered / beaten / completed	Completed	Any beaten/mastered variant
Achievements > 0, last activity > 90 days ago	Dropped	Only if current status is NOT Planned or Not Started
Achievements > 0, recent activity	In Progress
0 achievements	No change	RA has no data - existing status preserved

Dropped protection

If a game's current status is Planned or Not Started, it will NOT be changed to Dropped even if RA shows >90 days of inactivity. This prevents incorrectly marking games the user hasn't started yet. All other status transitions (→ Completed, → In Progress) are allowed from any status.

RA badge in game card header

When RA credentials are configured, a RetroAchievements logo appears in the game card header row (next to the IGDB source badge and platform label):

• Full-color logo - the game is linked to RA. Click to open the game's RA page in browser
• Pulsing semi-transparent logo - the game is NOT linked to RA but can be. Click to search and link
• No logo - RA credentials not set, or the game's platform is not supported by RA

Linking games manually

If a game was not matched during import (e.g., different name in IGDB vs RA), you can link it manually:

1. Open the game card
2. Click the pulsing RA logo in the header
3. The app loads all games for that console from RA and filters by name
4. Pick the correct game from the list
5. Achievement data loads automatically

To unlink a game: click the Unlink button (chain icon) in the RA achievements section header. This removes the tracker data and achievements for that game.

Achievement tracker in game card

When a game is linked to RA, the detail card shows a RetroAchievements section:

• Stats - total achievements, earned/total points, hardcore count
• Award badge - Mastered (gold), Beaten (silver), Hardcore (orange circle)
• Beaten progress - progression and win condition achievement bars
• Filter chips - All, Earned, Locked, Missable, Progression, Win Condition
• Achievement list - icons, titles, descriptions, points, earned dates
• Expand/Collapse - button above and below the list for easy navigation
• Refresh - manually update data from RA API
• Open on RA - opens the game page on retroachievements.org

Achievement details are loaded the first time you open the game card. The data is saved locally, so opening the same game again is instant.

Date sync on card open

When you open a game card with RA data, the following dates are automatically synced:

• Started - date of the earliest earned achievement
• Last Activity - date of the most recent earned achievement
• Completed - award date (if beaten/mastered)

This happens both on the first open and when you press Refresh.

Duplicate handling

When importing into an existing collection:

• Games already in the collection are updated (not skipped):
  • Status is always synced to match RA data (see Status sync rules above)
  • Activity dates are updated
  • Tracker data (achievements, awards) is updated in the tracker database
• Wishlist entries are deduplicated - existing unresolved items with the same name are not duplicated

Rate limiting

• RA API: 1 request per second between paginated calls
• IGDB: 300ms between search requests
• A library of 200 games takes about 2-3 minutes

Tips

• You can re-import to update achievement data - existing items will be updated, not duplicated
• Verify your credentials first with the Verify Connection button - it shows your profile with points and member date
• If IGDB connection is not set up, a warning appears at the top of the import screen
• The importer fetches both completion progress and award dates in parallel for faster loading
• Achievement details for each game load only when you open that card
• Tracker data is included in full backups and restored automatically
• Use the pulsing RA logo to manually link games that weren't matched during import