retroachievements 0.1.0

A typed Dart client library for the RetroAchievements.org API.

retroachievements

A strongly-typed, comprehensive Dart and Flutter client library for the RetroAchievements.org API.

Migrated to Dart with 100% 1:1 API feature parity with @retroachievements/api (v2.10.0).

---

Features

• 🎮 Complete API Coverage: Support for all RetroAchievements endpoints across Console, Game, Achievement, User, Feed, Leaderboard, Comment, and Ticket modules.
• 🔒 Type-Safe: Strongly-typed models for all requests and responses with null-safety and strict analysis.
• ⚡ Zero Unnecessary Dependencies: Lightweight, built on Dart 3 and package:http.
• 🧼 Clean Data Transformations: Automatically transforms raw API payload inconsistencies into idiomatic camelCase objects, numeric types, and typed enums.
• 🧪 Fully Tested: 106+ unit test suites covering every API function with mock HTTP responses.

---

Installation

Add retroachievements to your pubspec.yaml:

dependencies:
  retroachievements: ^0.1.0

Or via terminal:

dart pub add retroachievements

---

Authentication

Every API call requires an AuthObject containing your RetroAchievements username and webApiKey. You can find your Web API key in your RetroAchievements Settings page under Keys.

import 'package:retroachievements/retroachievements.dart';

final auth = buildAuthorization(
  username: 'your_username',
  webApiKey: 'your_web_api_key',
);

---

Quickstart & Examples

1. Fetching Consoles & Games

import 'package:retroachievements/retroachievements.dart';

// Get list of active console systems
final consoles = await getConsoleIds(
  auth,
  shouldOnlyRetrieveActiveSystems: true,
);

// Get list of games for Genesis (Console ID: 1)
final games = await getGameList(
  auth,
  consoleId: 1,
  shouldRetrieveHashes: true,
);

2. Game Metadata & Achievements

// Get game details
final game = await getGame(auth, gameId: 14402);
print('${game.title} - Developer: ${game.developer}');

// Get extended game details with achievements and claims
final extended = await getGameExtended(auth, gameId: 14402);
print('Achievements count: ${extended.achievements.length}');

3. User Profiles & Progress

// Get user summary
final summary = await getUserSummary(auth, username: 'xelnia');
print('Total points: ${summary.totalPoints}');

// Get game info combined with user completion progress
final userProgress = await getGameInfoAndUserProgress(
  auth,
  gameId: 14402,
  username: 'xelnia',
);
print('Completion: ${userProgress.userCompletionHardcore}');

// Get user recent achievements
final recentAchievements = await getUserRecentAchievements(
  auth,
  username: 'xelnia',
  recentMinutes: 120,
);

4. Feed & Community

// Achievement of the Week
final aotw = await getAchievementOfTheWeek(auth);
print('Current AOTW: ${aotw.achievement.title} (${aotw.game.title})');

// Top Ten Users
final topTen = await getTopTenUsers(auth);

// Active Developer Claims
final claims = await getActiveClaims(auth);

5. Leaderboards

// Get leaderboards for a game
final leaderboards = await getGameLeaderboards(auth, gameId: 14402);

// Get leaderboard entries
final entries = await getLeaderboardEntries(auth, leaderboardId: 1234);

---

Offline Embedded Data Cache

The library embeds an offline snapshot of the complete RetroAchievements catalog (85 systems, 12,130 games, and 18,247 ROM hashes) compiled directly into native const Dart data structures.

• ⚡ Zero Network Requests: Instantaneous, offline lookups without hitting the API.
• 🚀 Zero JSON Parsing Overhead: Native const instances evaluated at compile-time.
• 🌲 Tree-Shakeable: Adds 0 KB overhead if your app only uses the online API. Full offline matching adds ~1.5 MB to a compressed release bundle.
• 🌐 Platform-Agnostic: Works seamlessly in Flutter, Web, Mobile, Desktop, and Server.

Offline Examples

import 'package:retroachievements/cache.dart';

// 1. Get all 85 console systems (or active/game systems only)
final activeSystems = getCachedConsoleIds(shouldOnlyRetrieveActiveSystems: true);

// 2. Get all games for Sega Genesis (ID: 1) or 32X (ID: 10)
final games32x = getCachedGameList(consoleId: 10);

// 3. Match a ROM file's MD5 hash to game metadata (case-insensitive)
final game = findCachedGameByHash('49134106e611839a28caf94a1ddd783d');
print(game?.title); // "~Hack~ Doom 32X: Resurrection"

// 4. Fast O(1) indexed lookup service
final gameById = RaCache.findById(18179);
final gameByHash = RaCache.findByHash('49134106e611839a28caf94a1ddd783d');

To refresh the embedded dataset with the latest games and hashes from RetroAchievements:

export RAUSER="your_username"
export RAKEY="your_web_api_key"
dart run tool/sync_embedded_data.dart

---

API Function Reference

Module	Function	Endpoint	Description
Console	getConsoleIds	API_GetConsoleIDs.php	List of supported console systems.
	getGameList	API_GetGameList.php	List of games for a console system.
Achievement	getAchievementUnlocks	API_GetAchievementUnlocks.php	Users who unlocked a given achievement.
Game	getAchievementCount	API_GetAchievementCount.php	List of achievement IDs for a game.
	getAchievementDistribution	API_GetAchievementDistribution.php	Unlock distribution for a game.
	getGame	API_GetGame.php	Basic game metadata.
	getGameExtended	API_GetGameExtended.php	Extended game metadata and achievements.
	getGameHashes	API_GetGameHashes.php	Supported ROM file hashes for a game.
	getGameProgression	API_GetGameProgression.php	Average time taken to unlock achievements.
	getGameRankAndScore	API_GetGameRankAndScore.php	Latest masteries and high scores for a game.
	getGameRating	API_GetGameRating.php	User ratings and community score for a game.
User	getAchievementsEarnedBetween	API_GetAchievementsEarnedBetween.php	Achievements earned in a date range.
	getAchievementsEarnedOnDay	API_GetAchievementsEarnedOnDay.php	Achievements earned on a given date.
	getGameInfoAndUserProgress	API_GetGameInfoAndUserProgress.php	Game info with user progress.
	getUserAwards	API_GetUserAwards.php	User site badges, masteries, and completions.
	getUserClaims	API_GetUserClaims.php	Historical set claims made by a user.
	getUserCompletedGames	API_GetUserCompletedGames.php	Completed and beaten games list for a user.
	getUserCompletionProgress	API_GetUserCompletionProgress.php	Paginated completion progress overview.
	getUserGameRankAndScore	API_GetUserGameRankAndScore.php	User rank and points for a specific game.
	getUserPoints	API_GetUserPoints.php	User points and softcore points.
	getUserProfile	API_GetUserProfile.php	User profile statistics and motto.
	getUserProgress	API_GetUserProgress.php	Multi-game progress summary for a user.
	getUserRecentAchievements	API_GetUserRecentAchievements.php	Recently unlocked achievements.
	getUserRecentlyPlayedGames	API_GetUserRecentlyPlayedGames.php	Recently played games list.
	getUserSetRequests	API_GetUserSetRequests.php	User's set requests and points needed.
	getUsersFollowingMe	API_GetUsersFollowingMe.php	List of followers.
	getUsersIFollow	API_GetUsersIFollow.php	List of followed users.
	getUserSummary	API_GetUserSummary.php	Comprehensive user profile summary.
	getUserWantToPlayList	API_GetUserWantToPlayList.php	User's backlog / want to play list.
Feed	getAchievementOfTheWeek	API_GetAchievementOfTheWeek.php	Achievement of the week metadata and unlocks.
	getActiveClaims	API_GetActiveClaims.php	Active developer set claims.
	getClaims	API_GetClaims.php	Completed, dropped, or expired set claims.
	getRecentGameAwards	API_GetRecentGameAwards.php	Recent masteries and completions site-wide.
	getTopTenUsers	API_GetTopTenUsers.php	Top ten users by points.
Leaderboard	getGameLeaderboards	API_GetGameLeaderboards.php	Leaderboards configured for a game.
	getLeaderboardEntries	API_GetLeaderboardEntries.php	Entries and rankings on a leaderboard.
	getUserGameLeaderboards	API_GetUserGameLeaderboards.php	User's scores across game leaderboards.
Comment	getComments	API_GetComments.php	Comments on user walls, games, or achievements.
Ticket	getTicketData	API_GetTicketData.php	Polymorphic ticket info and stats.
	getTicketById	API_GetTicketData.php	Single ticket by ID.
	getRecentTickets	API_GetTicketData.php	Recently opened tickets site-wide.
	getMostTicketedGames	API_GetTicketData.php	Games with most open tickets.
	getUserTicketStats	API_GetTicketData.php	Ticket breakdown for a developer.
	getGameTicketStats	API_GetTicketData.php	Ticket count and details for a game.
	getAchievementTicketStats	API_GetTicketData.php	Ticket count for an achievement.
Cache (Offline)	getCachedConsoleIds	Offline Embedded	Synchronous offline list of all systems.
	getCachedGameList	Offline Embedded	Synchronous offline list of games for a console.
	getCachedAllGames	Offline Embedded	All 12,130 cached games across systems.
	findCachedGameByHash	Offline Embedded	Case-insensitive ROM MD5 hash lookup.
	findCachedGameById	Offline Embedded	Fast game ID lookup.
	RaCache	Offline Embedded	In-memory indexing service for fast lookups.
Hashing (rhash)	rcHashGenerate	Offline Hashing	Primary RetroAchievements ROM/disc MD5 hash generator.
	rcHashCompute	Offline Hashing	Full hash result with primary and alternate hashes.
	RcHashIterator	Offline Hashing	Multi-hash iterator (rc_hash_iterator_t equivalent).

---

ROM & Disc Hashing (rhash)

The ROM and optical media hashing implementation is migrated from RetroAchievements/rcheevos (rc_hash). It handles platform-specific container parsing and header stripping so game hashes match the RetroAchievements database.

Features

• Platform Specific:
  • PlayStation Portable (PSP): ISO 9660 directory parser (PSP_GAME/PARAM.SFO + PSP_GAME/SYSDIR/EBOOT.BIN) and EBOOT.PBP container parser.
  • NES / Famicom: Automatic 16-byte iNES header stripping.
  • SNES / Super Famicom: Automatic 512-byte copier header stripping.
  • ZIP Archives: Automatically inspects .zip containers, finds the primary ROM file, and applies platform hashing rules.
• Custom I/O: RcFileReader and RcCdReader interfaces allow plugging in custom file readers (e.g. virtual file systems, CHD, in-memory buffers).
• Iterator: RcHashIterator cycles through primary and fallback/alternate hashes.

import 'package:retroachievements/hash.dart';

// 1. Generate primary hash from a ROM file path
final hash = await rcHashGenerate(path: '/path/to/game.iso', consoleId: 41);

// 2. Compute full result with alternate hashes
final result = await rcHashCompute(path: '/path/to/game.nes', consoleId: 7);
print('Primary: ${result?.primaryHash}');
print('Alternates: ${result?.alternateHashes}');

// 3. Or pass in-memory buffer directly
final bufferHash = await rcHashGenerate(buffer: romBytes, consoleId: 3);

---

Error Handling

Failed requests throw a RetroAchievementsApiException containing the HTTP status code, status message, endpoint URL, and raw response body.

try {
  final game = await getGame(auth, gameId: 9999999);
} on RetroAchievementsApiException catch (e) {
  print('API Exception (${e.statusCode}): ${e.statusText}');
  print('Endpoint: ${e.endpointUrl}');
}

---

License

MIT License. See LICENSE for details.