Skip to content

Achievements

Jump to bottom
Francisco Dias edited this page Jun 20, 2024 · 5 revisions

Achievements

Epic Online Services Interface: Achievements Interface

The Achievements Interface provides a way for developers to retrieve data about a player's Epic Online Services achievements, unlock achievements for that player, and retrieve data about all of the Epic Online Services achievements belonging to an application.

Functions

These functions are provided for handling achievements:

Structs

These are the structures used by this API:


Back To Top

EpicGames_Achievements_AddNotifyAchievementsUnlockedV2

Epic Online Services Function: EOS_Achievements_AddNotifyAchievementsUnlockedV2

This function registers to receive achievement unlocked notifications.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_Achievements_AddNotifyAchievementsUnlockedV2()



Returns:

Int64


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_Achievements_AddNotifyAchievementsUnlockedV2"
UnlockTime Int64 POSIX timestamp when the achievement was unlocked
AchievementId String The Achievement ID for the achievement that was unlocked. Pass this to EpicGames_Achievements_CopyPlayerAchievementByAchievementId to get the full achievement information.
UserId String The Product User ID for the user who received the unlocked achievements notification

Example:

identifier = EpicGames_Achievements_AddNotifyAchievementsUnlockedV2();

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Achievements_AddNotifyAchievementsUnlockedV2")
if(async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_Achievements_CopyAchievementDefinitionV2ByAchievementId

Epic Online Services Function: EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId

This function fetches an AchievementDefinition from a given achievement ID.

Note

Requires a previous call to EpicGames_Achievements_QueryDefinitions to store values in cache.


Syntax:

EpicGames_Achievements_CopyAchievementDefinitionV2ByAchievementId(AchievementId)
Argument Type Description
AchievementId String Achievement ID to look for when copying the definition from the cache



Returns:

AchievementDefinition


Example:

var _struct = EpicGames_Achievements_CopyAchievementDefinitionV2ByAchievementId("MyAchievement1");
if(_struct.status == EpicGames_Success)
{
    var _achievement_id = _struct.AchievementId;
}

The above code will show an example of how the function should be used. The achievement definition data is returned providing an achievement ID.



Back To Top

EpicGames_Achievements_CopyAchievementDefinitionV2ByIndex

Epic Online Services Function: EOS_Achievements_CopyAchievementDefinitionV2ByIndex

This function fetches an AchievementDefinition from a given index.

Note

Requires a previous call to EpicGames_Achievements_QueryDefinitions to store values in cache.


Syntax:

EpicGames_Achievements_CopyAchievementDefinitionV2ByIndex(index)
Argument Type Description
index Real Index of the achievement definition to retrieve from the cache



Returns:

AchievementDefinition


Example:

for(var i = 0 ; i < EpicGames_Achievements_GetAchievementDefinitionCount() ; i ++)
{
    var _struct = EpicGames_Achievements_CopyAchievementDefinitionV2ByIndex(i);
    if(_struct.status == EpicGames_Success)
    {
         var _achievement_id = _struct.AchievementId;
    }
}

The above code shows an example of how the function should be used. The achievement definition data is returned providing an achievement index.



Back To Top

EpicGames_Achievements_CopyPlayerAchievementByAchievementId

Epic Online Services Function: EOS_Achievements_CopyPlayerAchievementByAchievementId

This function fetches a player achievement from a given achievement ID.

Note

Requires a previous call to EpicGames_Achievements_QueryPlayerAchievements to store values in cache.


Syntax:

EpicGames_Achievements_CopyPlayerAchievementByAchievementId(userID, userID_target, achievementID)
Argument Type Description
userID String The Product User ID for the user who is querying for a player achievement. For a Dedicated Server this should be null.
userID_target String The Product User ID for the user whose achievement is to be retrieved.
achievementID String Achievement ID to search for when retrieving player achievement data from the cache.



Returns:

PlayerAchievement


Example:

var _struct = EpicGames_Achievements_CopyPlayerAchievementByAchievementId(userID, userID_target, achievementID);
if(struct.status == EpicGames_Success)
{
    var _achievementd = _struct.AchievementId;
}

The above code will show an example of how the function should be used. The player achievement data is returned providing an achievement ID.



Back To Top

EpicGames_Achievements_CopyPlayerAchievementByIndex

Epic Online Services Function: EOS_Achievements_CopyPlayerAchievementByIndex

This function fetches a player achievement from a given index.

Note

Requires a previous call to EpicGames_Achievements_QueryPlayerAchievements to store values in cache.


Syntax:

EpicGames_Achievements_CopyPlayerAchievementByIndex(userID, userID_target, index)
Argument Type Description
userID String The Product User ID for the user who is querying for a player achievement. For a Dedicated Server this should be null.
userID_target String The Product User ID for the user whose achievement is to be retrieved.
index Real The index of the player achievement data to retrieve from the cache.



Returns:

PlayerAchievement


Example:

for(var i = 0 ; i < EpicGames_Achievements_GetPlayerAchievementCount(userID) ; i ++)
{
    var _struct = EpicGames_Achievements_CopyPlayerAchievementByIndex(i);
    if(_struct.status == EpicGames_Success)
    {
         var _achievement_id = _struct.AchievementId;
    }
}

The above code will show an example of how the function should be used. The player achievement data is returned providing an achievement index.



Back To Top

EpicGames_Achievements_GetAchievementDefinitionCount

Epic Online Services Function: EOS_Achievements_GetAchievementDefinitionCount

This function fetches the number of achievement definitions that are cached locally.

Note

Requires a previous call to EpicGames_Achievements_QueryDefinitions to store values in cache.


Syntax:

EpicGames_Achievements_GetAchievementDefinitionCount()



Returns:

Real


Example:

for(var i = 0 ; i < EpicGames_Achievements_GetAchievementDefinitionCount() ; i ++)
{
    var _struct = EpicGames_Achievements_CopyAchievementDefinitionV2ByIndex(i);
    if(_struct.status == EpicGames_Success)
    {
         var _achievement_id = _struct.AchievementId;
    }
}

The above code will show an example of how the function should be used. After a successful call to EpicGames_Achievements_QueryDefinitions, the function EpicGames_Achievements_GetAchievementDefinitionCount will return the number of entries in the query array which can then be accessed using the EpicGames_Achievements_CopyAchievementDefinitionV2ByIndex function.



Back To Top

EpicGames_Achievements_GetPlayerAchievementCount

Epic Online Services Function: EOS_Achievements_GetPlayerAchievementCount

This function fetches the number of player achievements that are cached locally.

Note

Requires a previous call to EpicGames_Achievements_QueryPlayerAchievements to store values in cache.


Syntax:

EpicGames_Achievements_GetPlayerAchievementCount(userID)
Argument Type Description
userID String The Product User ID for the user whose achievement count is being retrieved.



Returns:

Real


Example:

for(var i = 0 ; i < EpicGames_Achievements_GetPlayerAchievementCount(userID) ; i ++)
{
    var _struct = EpicGames_Achievements_CopyPlayerAchievementByIndex(i);
    if(_struct.status == EpicGames_Success)
    {
         var _achievement_id = _struct.AchievementId;
    }
}

The above code will show an example of how the function should be used. After a successful call to EpicGames_Achievements_QueryPlayerAchievements, the function EpicGames_Achievements_GetPlayerAchievementCount will return the number of entries in the query array which can then be accessed using the EpicGames_Achievements_CopyPlayerAchievementByIndex function.



Back To Top

EpicGames_Achievements_QueryDefinitions

Epic Online Services Function: EOS_Achievements_QueryDefinitions

This function queries for a list of definitions for all existing achievements, including localized text, icon IDs and whether an achievement is hidden. Once the callback has been fired with a successful EpicGames_Result, it is possible to call one of the following functions:

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_Achievements_QueryDefinitions(userId)
Argument Type Description
userId String Product User ID for user who is querying definitions.



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_Achievements_QueryDefinitions"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID

Example:

identifier = EpicGames_Achievements_QueryDefinitions(userId);

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Achievements_QueryDefinitions")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_Achievements_QueryPlayerAchievements

Epic Online Services Function: EOS_Achievements_QueryPlayerAchievements

This function queries for a list of achievements for a specific player, including progress towards completion for each achievement.

Once the callback has been fired with a successful EpicGames_Result, it is possible to call one of the following functions:

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_Achievements_QueryPlayerAchievements(userID, userID_target)
Argument Type Description
userID String The Product User ID for the user who is querying for player achievements. For a Dedicated Server this should be null.
userID_target String The Product User ID for the user whose achievements are to be retrieved.



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_Achievements_QueryPlayerAchievements"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID

Example:

identifier = EpicGames_Achievements_QueryPlayerAchievements(userID, userID);

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Achievements_QueryPlayerAchievements")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_Achievements_RemoveNotifyAchievementsUnlocked

Epic Online Services Function: EOS_Achievements_RemoveNotifyAchievementsUnlocked

This function unregisters from receiving achievement unlocked notifications, should be passed the identifier returned from the function:


Syntax:

EpicGames_Achievements_RemoveNotifyAchievementsUnlocked(id)
Argument Type Description
id Real The notification registration handle (returned by EpicGames_Achievements_AddNotifyAchievementsUnlockedV2)



Returns:

N/A


Example:

handle = EpicGames_Achievements_AddNotifyAchievementsUnlockedV2();
//...
//later...
//...
EpicGames_Achievements_RemoveNotifyAchievementsUnlocked(handle);

The code sample above enables the achievement unlock notifications (EpicGames_Achievements_AddNotifyAchievementsUnlockedV2) and later disables them by referring to the previous generated handle.



Back To Top

EpicGames_Achievements_UnlockAchievement

Epic Online Services Function: EOS_Achievements_UnlockAchievements

This function unlocks an achievement for a specific player.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_Achievements_UnlockAchievement(userID, AchievementID)
Argument Type Description
userID String The Product User ID for the user whose achievements we want to unlock.
AchievementID String Achievement ID to unlock.



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "EpicGames_Achievements_UnlockAchievement"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_Achievements_UnlockAchievement();

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Achievements_UnlockAchievement")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

PlayerAchievement

A player achievement is represented by a struct and contains information about a single player achievement.

The status member present in the struct can be represented by one of the following values:

  • EpicGames_Success if the information is available and was correctly returned;
  • EpicGames_InvalidParameters (extension internal error, should never be returned);
  • EpicGames_NotFound if the achievement definition is not found;
  • EpicGames_Invalid_ProductUserID if you pass an invalid user ID;

This struct is referenced by the following functions:


Member Type Description
status EpicGames_Result The result value of the task
status_message String Text representation of the status code
AchievementId String This achievement's unique identifier
Progress Real Progress towards completing this achievement (as a percentage)
UnlockTime String The POSIX timestamp when the achievement was unlocked. If the achievement has not been unlocked, this value will be EpicGames_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED.
StatInfoCount String The number of player stat info entries associated with this achievement.
StatInfo Array of PlayerStatInfo Array of PlayerStatInfo structures containing information about stat thresholds used to unlock the achievement and the player's current values for those stats
DisplayName String Localized display name for the achievement based on this specific player's current progress on the achievement
Description String Localized description for the achievement based on this specific player's current progress on the achievement
IconURL String 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 developer portal
FlavorText String 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 developer portal

Back To Top

PlayerStatInfo

Epic Online Services Struct: (EOS_Achievements_StatThresholds)[https://dev.epicgames.com/docs/en-US/api-ref/structs/eos-achievements-stat-thresholds]

This struct contains information about a collection of stat threshold data.

This struct is referenced by the following structs:


Member Type Description
Name String The name of the stat.
ApiVersion Real The API version.
CurrentValue Real The current value of the stat.
ThresholdValue Real The value that the stat must surpass to satisfy the requirement for unlocking an achievement.

Back To Top

AchievementDefinition

An achievement definition is represented by a struct and contains information about a single achievement definition with localised text.

The status member present in the struct can be represented by one of the following values:

  • EpicGames_Success if the information is available and was correctly returned;
  • EpicGames_InvalidParameters (extension internal error, should never be returned);
  • EpicGames_NotFound if the achievement definition is not found;
  • EpicGames_Invalid_ProductUserID if any of the userid options are incorrect;

This struct is referenced by the following functions:


Member Type Description
status EpicGames_Result The result value of the task
status_message String Text representation of the status code
AchievementId String Achievement ID that can be used to uniquely identify the achievement
UnlockedDisplayName String Localized display name for the achievement when it has been unlocked
UnlockedDescription String Localized description for the achievement when it has been unlocked
LockedDisplayName String Localized display name for the achievement when it is locked or hidden
LockedDescription String Localized description for the achievement when it is locked or hidden
FlavorText String 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 development portal
UnlockedIconURL String 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 development portal
LockedIconURL String 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 development portal
bIsHidden Boolean true if the achievement is hidden; false otherwise

YoYoGames 2024

Clone this wiki locally