IAchievementManager14.1
Interface in Unbroken.LaunchBox.Plugins.Services.Achievements
public interface IAchievementManagerProvides host-managed achievement data from RetroAchievements, storefronts, and other installed sources.
Remarks
Request this service by declaring a public constructor with an IAchievementManager parameter. Providers implement the achievement capabilities; consumers use this service. Calls never expose provider instances or credentials. Invoke asynchronously after activation, not from a plugin constructor. Caller cancellation throws OperationCanceledException; retrieval problems are reported in results.Methods
GetCachedAsync(string, string, CancellationToken)Reads a cached source-local game without making network requests or creating a library association.GetCachedAsync(IGame, CancellationToken)Reads cached achievements for a library game's existing source associations without making network requests.GetContextsAsyncQueries the source's configured account and modes without exposing credentials.GetLibraryProgressAsyncQueries complete account-wide game summaries when supported, without changing the user's library.GetSourcesAsyncLists registered sources and sources retained in the game cache without making network requests.RefreshAsync(string, string, CancellationToken)Refreshes a source-local game through the host and updates its cache without creating a library association. Concurrent explicit requests for the same source/game and provider generation share work.RefreshAsync(IGame, CancellationToken)Refreshes a library game's achievements using the host's matching, account selection, scheduling, and cache merging.
GetCachedAsync(string, string, CancellationToken)
Task<AchievementGameSnapshot> GetCachedAsync(
string sourceId,
string gameId,
CancellationToken cancellationToken
)Reads a cached source-local game without making network requests or creating a library association.
sourceId- The achievement source identity.
gameId- The source-local game identity.
cancellationToken- Cancels the operation.
Returns
The cached snapshot, including explicit missing or unavailable state.GetCachedAsync(IGame, CancellationToken)
Task<IReadOnlyList<AchievementGameSnapshot>> GetCachedAsync(
IGame game,
CancellationToken cancellationToken
)Reads cached achievements for a library game's existing source associations without making network requests.
game- The host library game.
cancellationToken- Cancels the operation.
Returns
One snapshot per distinct source and source-local game; an empty list means no known associations.GetContextsAsync
Task<PluginServiceResult<IReadOnlyList<AchievementProgressContext>>> GetContextsAsync(
string sourceId,
CancellationToken cancellationToken
)Queries the source's configured account and modes without exposing credentials.
sourceId- The achievement source identity.
cancellationToken- Cancels retrieval.
Returns
Current contexts, or an explicit unconfigured, incomplete, unsupported, or unavailable result.GetLibraryProgressAsync
Task<PluginServiceResult<IReadOnlyList<AchievementProgress>>> GetLibraryProgressAsync(
string sourceId,
CancellationToken cancellationToken
)Queries complete account-wide game summaries when supported, without changing the user's library.
sourceId- The achievement source identity.
cancellationToken- Cancels retrieval.
Returns
Fresh summaries for the configured account and modes. Failed pagination never becomes a successful partial library.GetSourcesAsync
Task<IReadOnlyList<AchievementSourceInfo>> GetSourcesAsync(
CancellationToken cancellationToken
)Lists registered sources and sources retained in the game cache without making network requests.
cancellationToken- Cancels the operation.
Returns
Sources with their current availability and supported features. Features of an absent provider are unknown.RefreshAsync(string, string, CancellationToken)
Task<AchievementGameSnapshot> RefreshAsync(
string sourceId,
string gameId,
CancellationToken cancellationToken
)Refreshes a source-local game through the host and updates its cache without creating a library association. Concurrent explicit requests for the same source/game and provider generation share work.
Remarks
At most eight distinct explicit refresh requests per source may be outstanding. Further distinct requests return Failed with a localized busy message; callers may retry after pending work completes. Caller cancellation does not cancel other waiters. Consumer-only cache records are bounded to 128 entries across sources; library cache records are retained independently. Unknown-only first observations retain bounded diagnostics in memory without creating game files. Sequential requests still refresh.sourceId- The achievement source identity.
gameId- The source-local game identity.
cancellationToken- Cancels this caller's wait; already-started shared cache work may continue.
Returns
The resulting snapshot, retaining previous observations on retrieval failure.RefreshAsync(IGame, CancellationToken)
Task<IReadOnlyList<AchievementGameSnapshot>> RefreshAsync(
IGame game,
CancellationToken cancellationToken
)Refreshes a library game's achievements using the host's matching, account selection, scheduling, and cache merging.
game- The host library game.
cancellationToken- Cancels this caller's wait. Shared provider work may continue for other callers.