RetroAchievements Tools Suite

A collection of Python-based utilities to scan, verify, list, and enhance your local ROM library using the RetroAchievements (RA) API.

Features

This suite includes an interactive menu (Run-Menu.bat) providing access to three distinct tools:

1. ROM Hash Checker (Check-RetroAchievements.py)

   • Recursively scans your ROM directories, hashes each file using RAHasher (and DolphinTool for GC/Wii), and checks them against the RetroAchievements database.
   • Outputs a detailed CSV report (reports/RA_HashMapReport.csv) showing exactly which ROMs are linked to RA and which ones are unrecognized (bad dumps, unsupported versions, etc.).

2. ROM Library Lister (list_roms.py)

   • Generates a clean, alphabetically sorted text file (reports/rom_list.txt) of your entire ROM collection.
   • Intelligently filters out junk folders (like updates, temp, or BIOS) by checking against official RetroAchievements system names and your configured aliases.

3. Game Patch Checker (game-patch-checker.py)

   • Cross-references your verified games against RetroAchievements' patch database.
   • Specifically hunts for Quality of Life (QoL), Color Restorations, Widescreen hacks, and DX enhancements (while intelligently filtering out redundant language translations and MSU-1 audio hacks).
   • Tracks which patches you've already applied vs. which ones are still available to download, splitting them into two separate reports (reports/RA_PatchesApplied.txt and reports/RA_PatchesAvailable.txt).

Requirements

• Python 3.x installed and added to your system PATH. (No pip packages required! The entire suite runs purely on Python's built-in standard libraries).
• RAHasher.exe (Place inside the tools/ folder).
• DolphinTool.exe (Optional, for GameCube/Wii checking. Place inside the tools/ folder).
• A RetroAchievements Account (Username and Web API Key).

Setup & Configuration

1. Configure the Suite: Open config/config.json in any text editor.

   • rom_base_path: The absolute path to the root directory containing your system ROM folders (e.g., D:\\EmulationLibrary).
   • ra_username: Your RetroAchievements username.
   • ra_api_key: Your Web API Key (Generated from your RetroAchievements settings panel).
   • Paths for RAHasher, DolphinTool, and reports are pre-configured to relative paths inside the project.

2. System Folders & Aliases:

   • The tools automatically map your local folders (e.g., snes, gba, genesis) to the official RA system lists using fuzzy-matching and a predefined list of aliases located in config/system_aliases.json.
   • If a folder isn't being recognized, you can either add its name to the system_aliases.json file, or explicitly define it inside "manual_system_map" within config.json.

Usage

Simply double-click Run-Menu.bat to launch the interactive dashboard!

The script will automatically verify your Python installation and let you choose which tool you want to run. All outputs will be neatly saved into the reports/ directory.