Achievements Interface

Interface for checking and unlocking achievements on a user-by-user basis.

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:

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 or hidden.

LockedDescription

Localized description for the achievement when it is locked or hidden.

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. This may be null if there is no data configured in the dev portal.

LockedIconURL

URL of an icon to display for the achievement when it is locked or hidden. This may be null if there is no data configured in the dev portal.

bIsHidden

EOS_TRUE if achievement is hidden; EOS_FALSE if otherwise.

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 achievement. Consists of Name and Threshold Value.

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:

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

ApiVersion

Set to EOS_ACHIEVEMENTS_QUERYDEFINITIONS_API_LATEST.

UserId

The user ID for the user who we are querying definitions for.

EpicUserId

Epic account ID for the user who we are querying definitions for.

HiddenAchievementIds

  1. Must be set to null.

HiddenAchievementsCount

  1. Must be set to zero.

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 UserId and EpicUserId to determine the user's locale, which is used to return localized text. You can also call EOS_Platform_SetOverrideLocaleCode to force the system to use a locale of your choice to retrieve achievement info. If either of these are 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:

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

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

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 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:

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.

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.

The current progress is updated when EOS_Achievements_QueryPlayerAchievements succeeds and when an achievement is unlocked.

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.

The current progress is updated when EOS_Achievements_QueryPlayerAchievements succeeds and when an achievement is unlocked.

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.

EOS_Achievements_PlayerStatInfo

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

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_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:

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

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

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 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:

EOS_Achievements_UnlockAchievements

Parameter

Description

Handle

A valid EOS_HAchievements handle.

Options

An EOS_Achievements_UnlockAchievementsOptions structure containing information about the player whose achievements we are unlocking as well as the 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

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.

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.