Achievements Interface

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.

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 define your achievements on the Developer Portal. When you retrieve data for achievement definitions, it will be contained in the struct EOS_Achievements_DefinitionV2, which has the following parameters:

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.

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:

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. If LocalUserId is set to null and you do not override the locale code, then the system will return default text for achievement definitions.

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:

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:

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:

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:

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:

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:

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:

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:

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:

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 achievements introduced in an update.

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

Please consult the Service Usage Limitations page for information about usage limits that you should observe to maintain performance and speed.