The Achievements Interface provides a way for developers to retrieve data about a player's achievements, unlock achievements for that player, and retrieve data about all of the achievements belonging to an application.
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, please contact your Technical Account Manager for support.
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.
Achievement Definitions
To retrieve data about achievements or manually unlock them, you must first define your achievements on the Developer Portal.
We no longer support the LATEST aggregation type in achievement definitions. How this affects you:
You can still create a stat that uses the aggregation type LATEST
However, you cannot create an achievement that references a stat that uses the aggregation type LATEST
If an achievement already exists that references a stat that uses the LATEST aggregation type, editing is still allowed
You cannot create new achievements that references a stat that uses the LATEST aggregation type
When you retrieve data for achievement definitions, it will be contained in the struct EOS_Achievements_DefinitionV2
, which has the following parameters:
|
|
---|---|
Parameter |
Description |
|
|
|
Achievement ID that can be used to uniquely identify the achievement. |
|
Localized display name for the achievement when it has been unlocked. |
|
Localized description for the achievement when it has been unlocked. |
|
Localized display name for the achievement when it is locked. |
|
Localized description for the achievement when it is locked. |
|
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. |
|
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](Overlay/Social/Overview) will use a default image.
|
|
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](Overlay/Social/Overview) will use a default image.
|
|
[Social Overlay](Overlay/Social/Overview) 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.
|
|
The number of stat thresholds used to monitor progress towards this achievement. |
|
Array of |
Querying Achievement Definitions
The function EOS_Achievements_QueryDefinitions
can be used to retrieve an array of all achievement definitions that you have created on the Developer Portal for your application.
To retrieve data about achievements or manually unlock them, you must first define your achievements on the Developer Portal.
Once the query is complete, the 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 achievements, refer to the section below on Copying Cached Achievement Definitions.
EOS_Achievements_QueryDefinitions
takes the following parameters:
|
||
---|---|---|
Parameter |
Description |
|
|
A valid |
|
|
An |
|
|
Arbitrary data that is passed back to you in the |
|
|
A function called when the operation completes, using a signature consistent with |
|
|
||
|
Set to |
|
|
Product User ID for user who is querying definitions. |
|
|
|
|
|
|
|
|
|
This function will return an EOS_EResult
value of EOS_Success
if the query was successful. Other results indicate an error or incorrect 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 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 Achievement Definitions
Once an EOS_Achievements_QueryDefinitions
operation has finished, 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 Achievements
You can use the function GetAchievementDefinitionCount
to obtain the number of cached 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 Achievement Definitions by Index
The function EOS_Achievements_CopyAchievementDefinitionV2ByIndex
retrieves a copy of an EOS_Achievements_DefinitionV2
using an index value within the cached achievement list, then outputs the copy through the out parameter OutDefinition
. This function takes the following parameters:
|
||
---|---|---|
Parameter |
Description |
|
|
A valid |
|
|
An |
|
|
An out parameter containing a copy of the requested |
|
|
||
|
|
|
|
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:
|
||
---|---|---|
Parameter |
Description |
|
|
A valid |
|
|
An |
|
|
An out parameter containing a copy of the requested |
|
|
||
|
Set to |
|
|
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 achievement in the backend, EOS_Achievements_PlayerAchievement
tracks a specific player's progress toward unlocking an 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:
|
||
---|---|---|
Parameter |
Description |
|
|
Set to |
|
|
Unique identifier used to identify the achievement. |
|
|
Progress toward completing this achievement as a percentage. |
|
|
The POSIX timestamp that the achievement was unlocked. If the achievement has not been unlocked, this value will be EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED. |
|
|
The number of player stat info entries associated with this achievement. |
|
|
Array of |
|
|
Localized display name for the achievement based on this specific player's current progress on the achievement. The current progress is updated when |
|
|
Localized description for the achievement based on this specific player's current progress on the achievement. The current progress is updated when |
|
|
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. The current progress is updated when |
|
|
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. |
|
|
||
|
Set to |
|
|
The name of the stat. |
|
|
The current value of the stat. |
|
|
The threshold value of the stat. |
For more information about player stats, refer to the Stats Interface page.
Querying Player Achievement Progress
To retrieve data about achievements or manually unlock them, you must first define your achievements on the Developer Portal.
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:
|
||
---|---|---|
Parameter |
Description |
|
|
A valid |
|
|
An |
|
|
Arbitrary data that is passed back to you in the |
|
|
A function called when the operation completes, using a signature consistent with |
|
|
||
|
Set to |
|
|
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_QueryDefinitionsOptions
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 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:
|
||
---|---|---|
Parameter |
Description |
|
|
A valid |
|
|
An |
|
|
An out parameter containing a copy of the requested |
|
|
||
|
Set to |
|
|
A valid |
|
|
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:
|
||
---|---|---|
Parameter |
Description |
|
|
A valid |
|
|
An |
|
|
An out parameter containing a copy of the requested |
|
|
||
|
Set to |
|
|
A valid |
|
|
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 Achievements
Achievements can be unlocked automatically when stats linked to an achievement are ingested, or they can be unlocked manually with a call to the EOS_Achievements_UnlockAchievements
function.
Unlocking Achievements via Stats
Achievements are defined with a set of stat thresholds, composed of stats' names and amounts for stats to reach to unlock the 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 Achievements Manually
The function EOS_Achievements_UnlockAchievements
can unlock one or more achievements for a user. The parameters for this function are as follows:
|
||
---|---|---|
Parameter |
Description |
|
|
A valid |
|
|
An |
|
|
Arbitrary data that is passed back to you in the |
|
|
A function called when the operation completes, using a signature consistent with |
|
|
||
|
Set to |
|
|
The |
|
|
A list of achievement IDs that we want to unlock. |
|
|
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:
|
|
---|---|
Parameter |
Description |
|
An |
|
Context that was passed into |
|
The |
|
The number of achievements to unlock. |
Please note that the SDK does not store achievement state locally or offline. To mitigate issues unlocking 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 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.
Achievement Notifications
Notifications are available to inform you when 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 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 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 achievements, unlock achievements for that player, and retrieve data about all of the 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 achievements:
Feature |
Limitation |
---|---|
Total number of achievements |
1000 |
Stats per achievement |
3 |
Achievement ID length |
256 characters |
Localized text variations per achievement |
19 |
Localized text length |
256 characters |
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 |