Achievements Interface

Use the Achievements Interface to do the following actions:

• Retrieve data about the state of a specific player's achievements.
• Unlock achievements manually via calls.
• Retrieve data about all of the achievements belonging to an application.

See the API reference documentation for full details: EOS Achievements Interface API Reference.

Achievements that you define with the Achievements Interface are called "Epic Online Services achievements". You can add them to your product regardless of the platforms or storefronts that your product uses.

If you publish your product on the Epic Games Store, you can enhance your product's user experience further with Epic Games Store achievements. Epic Games Store achievements extend Epic Online Services achievements. They reward your users with experience points (XP) and other benefits in their Epic player accounts. For more information, see the documentation on Epic Games Store achievements.

See the introduction video on youtube.com: Introduction to Achievements.

To access the Achievements Interface, you need to acquire an EOS_HAchievements handle by calling the EOS_Platform_GetAchievementsInterface function. Similarly to all other interfaces, it is important that the EOS_HPlatform handle is ticking to ensure that the appropriate callbacks are triggered when requests are completed.

When you retrieve data for Epic Online Services achievement definitions, it will be contained in the struct EOS_Achievements_DefinitionV2, which has the following parameters:

The function EOS_Achievements_QueryDefinitions can be used to retrieve an array of all Epic Online Services achievement definitions that you have created on the Developer Portal for your application.

Once the query is complete, the Epic Online Services achievement definitions are cached locally rather than being returned through the function. They can then be accessed using EOS_Achievements_CopyAchievementDefinitionV2ByIndex or EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId to obtain a copy of an EOS_Achievements_DefinitionV2. You must release the memory for storing these copied definitions using EOS_Achievements_DefinitionV2_Release. For more information on copying Epic Online Services achievements, refer to the section below on Copying Cached Achievement Definitions.

EOS_Achievements_QueryDefinitions takes the following parameters:

The query uses LocalUserId to determine the user's locale, which is used to return localized text if the user has a linked Epic Online Services Account ID. You can also call EOS_Platform_SetOverrideLocaleCode to force the system to use a locale of your choice to retrieve Epic Online Services achievement info.

The callback function EOS_Achievements_OnQueryDefinitionsCompleteCallback will be called when the Query Definitions operation has completed and it returns a EOS_Achievements_OnQueryDefinitionsCompleteCallbackInfo structure. The callback info will contain a ResultCode and any client data that was set in EOS_Achievements_QueryDefinitionsOptions using the ClientData parameter.

Once an EOS_Achievements_QueryDefinitions operation has finished, Epic Online Services achievement Definitions are cached locally. You can retrieve a copy of an EOS_Achievements_DefinitionV2 using either EOS_Achievements_CopyAchievementDefinitionV2ByIndex or EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId.

You can use the function GetAchievementDefinitionCount to obtain the number of cached Epic Online Services achievements available. This function returns the count as an integer, and takes an EOS_Achievements_GetAchievementDefinitionCountOptions struct as a parameter.

The EOS_Achievements_GetAchievementDefinitionCountOptions struct itself only takes an ApiVersion parameter, which should be set to a value of EOS_ACHIEVEMENTS_GETACHIEVEMENTDEFINITIONCOUNT_API_LATEST.

The function EOS_Achievements_CopyAchievementDefinitionV2ByIndex retrieves a copy of an EOS_Achievements_DefinitionV2 using an index value within the cached Epic Online Services achievement list, then outputs the copy through the out parameter OutDefinition. This function takes the following parameters:

The function returns an EOS_EResult with a value of EOS_Success if the information is available and passed out in OutDefinition. If you pass a null pointer for the out parameter, then it will return EOS_InvalidParameters. If the requested Achievement Definition isn't found, it will return EOS_NotFound.

The function EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId searches the achievement cache for an achievement matching a given AchievementId, then outputs a copy of its data through the out parameter OutDefinition. This function takes the following parameters:

The function returns an EOS_EResult with a value of EOS_Success if the information is available and passed out in OutDefinition. If you pass a null pointer for the out parameter, then it will return EOS_InvalidParameters. If the requested Achievement Definition isn't found, it will return EOS_NotFound.

Information copied with the OutDefinition of either EOS_Achievements_CopyAchievementDefinitionV2ByIndex or EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId must be released from memory using the function EOS_Achievements_DefinitionV2_Release. This function takes a pointer to a single EOS_Achievements_DefinitionV2 called AchievementDefinition.

Player achievement progress data is contained in a structure called EOS_Achievements_PlayerAchievement. While EOS_Achievements_AchievementDefinition contains general information about an Epic Online Services achievement in the backend, EOS_Achievements_PlayerAchievement tracks a specific player's progress toward unlocking an Epic Online Services achievement, the time they unlocked it (if already unlocked), and relevant stat information toward unlocking it.

The parameters of EOS_Achievements_PlayerAchievement are as follows:

The asynchronous function EOS_Achievements_QueryPlayerAchievements can be used to retrieve a player's achievement progress data. Once the query is complete, it stores the requested data in a list that is cached locally. They can then be accessed using EOS_Achievements_CopyPlayerAchievementByIndex or EOS_Achievements_CopyPlayerAchievementByAchievementId to obtain copies of the desired data. After this is done, you must call EOS_Achievements_PlayerAchievement_Release to release the copied information from memory.

The parameters for EOS_Achievements_QueryPlayerAchievements are as follows:

The callback function EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback will be called when the Query Player Achievements operation has completed and will return a EOS_Achievements_OnQueryPlayerAchievementsCompleteCallbackInfo structure. The callback info will contain a ResultCode, any client data that was set in EOS_Achievements_QueryPlayerAchievementsOptions and the user ID of the player who owns the data.

Player achievement data is cached locally. You can use EOS_Achievements_GetPlayerAchievementCount to retrieve the number of Epic Online Services achievements that are cached.

The functions EOS_Achievements_CopyPlayerAchievementByIndex and EOS_Achievements_CopyPlayerAchievementByAchievementId can be used to obtain a copy of an EOS_Achievements_PlayerAchievement. You must release the memory associated with this copied data using EOS_Achievements_PlayerAchievement_Release.

The function EOS_Achievements_CopyPlayerAchievementByIndex retrieves a copy of an EOS_Achievements_PlayerAchievement structure from the local cache using an index value within the cached achievement list, then outputs the copy through the out parameter OutAchievement. This function takes the following parameters:

The function returns an EOS_EResult with a value of EOS_Success if the requested information is available and passed out in OutAchievement. If you pass a null pointer through the out parameter then it will return EOS_InvalidParameters. If the requested Player Achievement isn't found, it will return EOS_NotFound.

The function EOS_Achievements_CopyPlayerAchievementByAchievementId searches the local player achievement cache for an achievement matching a given AchievementId, then outputs a copy of its data through the out parameter OutAchievement. This function takes the following parameters:

The function returns an EOS_EResult with a value of EOS_Success if the requested information is available and passed out in OutAchievement. If you pass a null pointer through the out parameter then it will return EOS_InvalidParameters. If the requested Player Achievement isn't found, it will return EOS_NotFound.

Information copied with the OutAchievement of either EOS_Achievements_CopyPlayerAchievementByIndex or EOS_Achievements_CopyPlayerAchievementByAchievementId must be released from memory using the function EOS_Achievements_PlayerAchievement_Release. This function takes a pointer to a single EOS_Achievements_PlayerAchievement called Achievement.

Epic Online Services achievements can be unlocked automatically when stats linked to an Epic Online Services achievement are ingested, or they can be unlocked manually with a call to the EOS_Achievements_UnlockAchievements function.

Epic Online Services achievements are defined with a set of stat thresholds, composed of stats' names and amounts for stats to reach to unlock the Epic Online Services achievement. Once all necessary thresholds are met the achievement will be unlocked and the Progress will be set to 1.0.

Refer to the Stats Interface page for more information about how to update stats with the stats ingest operation.

The function EOS_Achievements_UnlockAchievements can unlock one or more Epic Online Services achievements for a user. The parameters for this function are as follows:

The callback function EOS_Achievements_OnUnlockAchievementsCompleteCallback will run when the EOS_Achievements_UnlockAchievements operation completes. This function is responsible for returning data from the operation. Its parameters are as follows:

Note that the SDK does not store achievement state locally or offline. To mitigate issues unlocking Epic Online Services achievements not backed by the stats service during a service outage, consider the following:

1. Always download user achievement status on login.

2. Compare the unlock state against your backing stats/data and unlock the achievement if the conditions are met

This process also covers users who may have completed new Epic Online Services achievements introduced in an update.

Notifications are available to inform you when Epic Online Services achievements have been unlocked. Achievement notifications can be triggered either from ingesting stats or unlocking an achievement manually.

The function EOS_Achievements_AddNotifyAchievementsUnlockedV2 can subscribe to notifications when Epic Online Services achievements are successfully unlocked. It takes in an Options parameter using the structure EOS_Achievements_AddNotifyAchievementsUnlockedV2Options, as well as a reference to a function whose signature is consistent with EOS_Achievements_OnAchievementsUnlockedCallbackV2. That callback function will then be called whenever an achievement is unlocked. ClientData can be used to pass arbitrary context data through to the callback when it occurs.

The structure EOS_Achievements_AddNotifyAchievementsUnlockedV2Options includes ApiVersion which should be set to EOS_ACHIEVEMENTS_ADDNOTIFYACHIEVEMENTSUNLOCKEDV2_API_LATEST.

The callback function EOS_Achievements_OnAchievementsUnlockedCallbackV2 returns an EOS_Achievements_OnAchievementsUnlockedCallbackV2Info structure. The callback info will contain the AchievementId and UnlockTime of the achievement that has been unlocked. It will also contain the ClientData passed in through EOS_Achievements_AddNotifyAchievementsUnlockedV2 and the UserId for the user the Epic Online Services achievements belong to.

RemoveNotifyAchievementsUnlocked can be used to unsubscribe from notifications.

The Achievements Interface provides a way for developers to retrieve data about a player's Epic Online Services achievements, unlock Epic Online Services achievements for that player, and retrieve data about all of the Epic Online Services achievements belonging to an application. For general information about throttling, usage quotas, and best practices, see Service Usage Limitations.

The following limits apply to a deployment's overall use of Epic Online Services achievements:

There are also usage-rate limitations that apply on a per-user or per-deployment basis. Per-user limitations apply to individual users playing games and interacting with existing achievements, while per-deployment limitations apply to calls that set up the achievements that players can see and unlock.

You can test your Epic Online Services achievements in a deployment to one of your test sandboxes. You should do this before you deploy to your live environment, so that you can check for errors in the achievement definition and make sure that players can unlock Epic Online Services achievements successfully. For more information on creating a test sandbox for your product, see Product, Sandbox, and Deployment IDs.