PolyhydraGames.RetroAchievements 1.0.2.93

PolyhydraGames.RetroAchievements

C# client library for the RetroAchievements web API.

This package wraps RetroAchievements endpoints for user profiles, game data, achievement progress, leaderboards, high scores, feeds, systems, comments, events, and tickets. It is intended for applications that need typed access to RetroAchievements data without hand-building REST URLs.

Status

• High-priority open-source cleanup candidate.
• Endpoint coverage is broad, but the public API is still being stabilized.
• Deterministic fixture-backed tests are being added so CI does not depend on live RetroAchievements API calls.
• Live API smoke tests should be opt-in only.

Target Frameworks

• netstandard2.0
• net8.0
• net10.0

Package

Current package ID in the project file:

PolyhydraGames.RetroAchievements

The package/repository naming is normalized in the current worktree. Keep the release checklist open until the package is packed and reviewed.

Installation

dotnet add package PolyhydraGames.RetroAchievements

Basic Usage

using PolyhydraGames.RetroAchievements;
using PolyhydraGames.RetroAchievements.Users;

var auth = new DefaultAuthConfig
{
    UserName = "your-retroachievements-user",
    ApiKey = "your-retroachievements-api-key"
};

using var httpClient = new HttpClient();
var users = new RetroAchievementUserApi(auth, httpClient);

var recentGames = await users.GetUserRecentlyPlayedGames("your-retroachievements-user");

Keep API keys in user secrets, environment variables, or your application secret store. Do not commit API keys.

API Families

• Achievements: unlock data
• Comments: achievement, game, and user comments
• Events: achievement of the week
• Feeds: recent awards, claims, and top users
• Games: game metadata, extended details, hashes, ranks, high scores, and progression data
• Leaderboards: game leaderboards, leaderboard entries, and user game leaderboard entries
• Systems: console IDs and game/hash lists
• Tickets: ticket data and ticket stats
• Users: profile, progress, points, awards, claims, recent games, completion, and recent achievements

Development

Build the solution:

dotnet build Cheevos.sln

Run deterministic tests:

dotnet test Cheevos.sln --no-restore

Live API tests are explicit and should be run intentionally:

dotnet test Cheevos.sln --filter "FullyQualifiedName~GameTests"

Avoid broad live runs during normal development because RetroAchievements can return auth or rate-limit responses.

Roadmap

• API opportunities
• Execution plan
• v1 roadmap
• Migration notes
• Release checklist

License

This project is licensed under the MIT License.