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.
Starting with EOS SDK version 1.8, we have updated how achievement icons are handled. While you should not experience any disruptions if you are moving from 1.7 to 1.8, there is a possibility that some of your icons will revert to a default state. If you see this, contact your Technical Account Manager for support.
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.
Video Introduction to Achievements
See the introduction video on youtube.com: Introduction to Achievements.
Video: Accessing the Achievements Interface
Accessing the Achievements Interface
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.
Epic Online Services achievement Definitions
We no longer support the LATEST aggregation type in Epic Online Services achievement definitions. How this affects you:
- You can still create a stat that uses the aggregation type LATEST
- However, you cannot create an Epic Online Services achievement that references a stat that uses the aggregation type LATEST
- If an Epic Online Services achievement already exists that references a stat that uses the LATEST aggregation type, editing is still allowed
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:
EOS_Achievements_DefinitionV2: | |
|---|---|
| Parameter | Description |
ApiVersion |
EOS_ACHIEVEMENTS_DEFINITIONV2_API_LATEST |
AchievementId |
Achievement ID that can be used to uniquely identify the achievement. |
UnlockedDisplayName |
Localized display name for the achievement when it has been unlocked. |
UnlockedDescription |
Localized description for the achievement when it has been unlocked. |
LockedDisplayName |
Localized display name for the achievement when it is locked. |
LockedDescription |
Localized description for the achievement when it is locked. |
FlavorText |
Localized flavor text that can be used by the game in an arbitrary manner. This may be null if there is no data configured in the dev portal. |
UnlockedIconURL |
URL of an icon to display for the achievement when it is unlocked. If there is no data configured in the developer portal, this value will be null, and the Social Overlay will use a default image. |
LockedIconURL |
URL of an icon to display for the achievement when it is locked or hidden. If there is no data configured in the developer portal, this value will be null, and the Social Overlay will use a default image. |
bIsHidden |
EOS_TRUE if achievement is hidden; EOS_FALSE if otherwise. When set to EOS_TRUE, the Social Overlay will use "Hidden Achievement" for the display name and an empty string for the description while the achievement is locked. The values of LockedDisplayName and LockedDescription within this structure will, however, remain unchanged. |
StatThresholdsCount |
The number of stat thresholds used to monitor progress towards this achievement. |
StatThresholds |
Array of EOS_Achievements_StatThresholds that need to be satisfied in order to unlock this Epic Online Services achievement. Consists of Name and Threshold Value. |
Querying Epic Online Services achievement Definitions
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:
EOS_Achievements_QueryDefinitions: | ||
|---|---|---|
| Parameter | Description | |
Handle |
A valid EOS_HAchievements handle. | |
Options |
An EOS_Achievements_QueryDefinitionsOptions structure containing data pertinent to retrieving localized text, as well as options for what kind of data should be returned. | |
ClientData |
Arbitrary data that is passed back to you in the CompletionDelegate. | |
CompletionDelegate |
A function called when the operation completes, using a signature consistent with EOS_Achievements_OnQueryDefinitionsCompleteCallback. | |
EOS_Achievements_QueryDefinitionsOptions: | ||
|---|---|---|
| Parameter | Description | |
ApiVersion |
Set to EOS_ACHIEVEMENTS_QUERYDEFINITIONS_API_LATEST. | |
LocalUserId |
Product User ID for user who is querying definitions. | |
EpicUserId |
Deprecated. Must be set to null. | |
HiddenAchievementIds |
Deprecated. Must be set to null. | |
HiddenAchievementsCount |
Deprecated. Must be set to zero. | |
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.
Query Definitions Complete Callback
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.
Copying Cached Epic Online Services achievement Definitions
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.
Getting the Number of Cached Epic Online Services achievements
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.
Copying Epic Online Services achievement Definitions by Index
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:
EOS_Achievements_CopyAchievementDefinitionV2ByIndex: | |
|---|---|
| Parameter | Description |
Handle |
A valid EOS_HAchievements handle. |
Options |
An EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions structure containing the requested index to copy from the cache. |
OutDefinition |
An out parameter containing a copy of the requested EOS_Achievements_DefinitionV2. If OutDefinition contains valid data, then you must call EOS_Achievements_DefinitionV2_Release on this data to release it from memory. |
EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions: | |
|---|---|
| Parameter | Description |
ApiVersion |
EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYINDEX_API_LATEST |
AchievementIndex |
The index of the achievement definition to retrieve from the cache. |
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.
Copying Achievement Definitions by ID
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:
EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId: | |
|---|---|
| Parameter | Description |
Handle |
A valid EOS_HAchievements handle. |
Options |
An EOS_Achievements_CopyAchievementDefinitionV2ByAchievementIdOptions structure containing the Achievement ID we want to search the cache for. |
OutDefinition |
An out parameter containing a copy of the requested EOS_Achievements_DefinitionV2. If OutDefinition contains valid data, then you must call EOS_Achievements_DefinitionV2_Release on this data to release it from memory. |
CopyAchievementDefinitionV2ByAchievementIdOptions: | |
|---|---|
| Parameter | Description |
ApiVersion |
Set to EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYACHIEVEMENTID_API_LATEST. |
AchievementId |
The achievement ID to look for when copying a definition from the cache. |
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.
Releasing Memory from Copied Achievement Definitions
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
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:
EOS_Achievements_PlayerAchievement: | |
|---|---|
| Parameter | Description |
ApiVersion |
Set to EOS_ACHIEVEMENTS_PLAYERACHIEVEMENT_API_LATEST. |
AchievementId |
Unique identifier used to identify the achievement. |
Progress |
Progress toward completing this achievement as a percentage. The current progress is updated when EOS_Achievements_QueryPlayerAchievements succeeds and when an achievement is unlocked. |
UnlockTime |
The POSIX timestamp that the achievement was unlocked. If the achievement has not been unlocked, this value will be EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED. |
StatInfoCount |
The number of player stat info entries associated with this achievement. |
StatInfo |
Array of EOS_Achievements_PlayerStatInfo structures containing information about stat thresholds used to unlock the achievement and the player's current values for those stats. |
DisplayName |
Localized display name for the achievement based on this specific player's current progress on the achievement. DisplayName is null in the SDK cache until EOS_Achievements_QueryDefinitions is successfully called. |
Description |
Localized description for the achievement based on this specific player's current progress on the achievement. The current progress is updated when EOS_Achievements_QueryPlayerAchievements succeeds and when an achievement is unlocked. |
IconURL |
URL of an icon to display for the achievement based on this specific player's current progress on the achievement. This may be null if there is no data configured in the dev portal. IconURL is null in the SDK cache until EOS_Achievements_QueryDefinitions is successfully called. |
FlavorText |
Localized flavor text that can be used by the game in an arbitrary manner. This may be null if there is no data configured in the dev portal.
FlavorText is null in the SDK cache until EOS_Achievements_QueryDefinitions is successfully called. |
EOS_Achievements_PlayerStatInfo: | |
|---|---|
| Parameter | Description |
ApiVersion |
Set to EOS_ACHIEVEMENTS_PLAYERSTATINFO_API_LATEST. |
Name |
The name of the stat. |
CurrentValue |
The current value of the stat. |
ThresholdValue |
The threshold value of the stat. |
For more information about player stats, refer to the Stats Interface page.
Querying Player Achievement Progress
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:
EOS_Achievements_QueryPlayerAchievements: | |
|---|---|
| Parameter | Description |
Handle |
A valid EOS_HAchievements handle. |
Options |
An EOS_Achievements_QueryPlayerAchievementsOptions structure containing the UserId of the player whose information we are querying. |
ClientData |
Arbitrary data that is passed back to you in the CompletionDelegate. |
CompletionDelegate |
A function called when the operation completes, using a signature consistent with EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback. |
EOS_Achievements_QueryPlayerAchievementsOptions | |
| Parameter | Description |
ApiVersion |
Set to EOS_ACHIEVEMENTS_QUERYPLAYERACHIEVEMENTS_API_LATEST. |
UserId |
The account ID for the user whose achievement progress data we are retrieving. |
Query Player Achievements Completed Callback
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.
Copying Player Achievement Progress
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.
Copying Player Achievements by Index
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:
EOS_Achievements_CopyPlayerAchievementByIndex: | |
|---|---|
| Parameter | Description |
Handle |
A valid EOS_HAchievements handle. |
Options |
An EOS_Achievements_CopyPlayerAchievementByIndexOptions structure containing the requested index to copy from the cache. |
OutAchievement |
An out parameter containing a copy of the requested EOS_Achievements_PlayerAchievement. If OutAchievement contains valid data, then you must call EOS_Achievements_PlayerAchievement_Release on this data to release it from memory. |
EOS_Achievements_CopyPlayerAchievementByIndexOptions: | |
|---|---|
| Parameter | Description |
ApiVersion |
Set to EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYINDEX_API_LATEST. |
UserId |
A valid EOS_ProductUserId representing the account ID for the user who is copying the achievement. |
AchievementIndex |
The index of the player achievement data to retrieve from the cache. |
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.
Copying Player Achievements by ID
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:
EOS_Achievements_CopyPlayerAchievementByAchievementId: | |
|---|---|
| Parameter | Description |
Handle |
A valid EOS_HAchievements handle. |
Options |
An EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions structure containing the Achievement ID we want to search the cache for. |
OutAchievement |
An out parameter containing a copy of the requested EOS_Achievements_PlayerAchievement. If OutAchievement contains valid data, then you must call EOS_Achievements_PlayerAchievement_Release on this data to release it from memory. |
EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions: | |
|---|---|
| Parameter | Description |
ApiVersion |
Set to EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYACHIEVEMENTID_API_LATEST. |
UserId |
A valid EOS_ProductUserId representing the account ID for the user who is copying the achievement. |
AchievementId |
The achievement ID to look for when copying a definition from the cache. |
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.
Releasing Memory from Copied Player Achievements
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.
Unlocking Epic Online Services achievements
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.
Unlocking Epic Online Services achievements via Stats
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.
Unlocking Epic Online Services achievements Manually
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:
EOS_Achievements_UnlockAchievements: | |
|---|---|
| Parameter | Description |
Handle |
A valid EOS_HAchievements handle. |
Options |
An EOS_Achievements_UnlockAchievementsOptions structure containing information about the player whose Epic Online Services achievements we are unlocking as well as the Epic Online Services achievements we wish to unlock. |
ClientData |
Arbitrary data that is passed back to you in the CompletionDelegate. |
CompletionDelegate |
A function called when the operation completes, using a signature consistent with EOS_Achievements_OnUnlockAchievementsCompleteCallback. |
EOS_Achievements_UnlockAchievementsOptions: | |
|---|---|
| Parameter | Description |
ApiVersion |
Set to EOS_ACHIEVEMENTS_UNLOCKACHIEVEMENTS_API_LATEST. |
UserId |
The EOS_ProductUserId representing the account ID of the user whose achievements we want to unlock. |
AchievementIds |
A list of achievement IDs that we want to unlock. |
AchievementsCount |
The number of achievements we want to unlock. |
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:
EOS_Achievements_OnUnlockAchievementsCompleteCallback: | |
|---|---|
| Parameter | Description |
ResultCode |
An EOS_EResult denoting the status of the operation. The result of EOS_Success means that the operation was completed successfully. Any other result denotes an error. |
ClientData |
Context that was passed into EOS_Achievements_UnlockAchievements. |
UserId |
The EOS_ProductUserId representing the account ID of the user who initiated this request. |
AchievementsCount |
The number of achievements to unlock. |
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:
-
Always download user achievement status on login.
-
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.
It is okay to call EOS_Achievements_UnlockAchievements more than once, even on every launch, as long as it respects proper retry rates and waits for completion status to return before trying.
Epic Online Services achievement Notifications
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.
Usage Limitations
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:
| Feature | Limitation |
|---|---|
| Total number of achievements | 1000 |
| Stats per achievement | 3 |
| Achievement ID length | 256 characters |
| Localized text variations per achievement | 22. Overlay supports 16 languages. |
| Localized text length | 256 characters |
| Achievement icon file size | 1.02 MB |
| Achievement icon resolution | 1024x1024 pixels |
| Achievement icon file types | PNG, JPG, BMP, and GIF (not animated) |
When you define an Epic Online Services achievement you must not use the following symbols in the AchievementId parameter of EOS_Achievements_DefinitionV2:
, { ^ } % ` ] > [ ~ < # | & $ @ = ; : + ? ! \ ( ) * /
These symbols might create issues when you import or export the definition.
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.
| Feature | Per-User Limitation | Per-Deployment Limitation |
|---|---|---|
| Get all achievement definitions | 10 requests per minute | - |
| Get one achievement definition | 100 requests per minute | - |
| Get a player's achievements | 100 requests per minute | - |
| Unlock achievement | 100 requests per minute | - |
| Create achievement | - | 100 requests per minute |
| Delete achievement | - | 100 requests per minute |
Test your Epic Online Services achievements
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.