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.

These functions are provided for handling achievements:

• eos_achievements_add_notify_achievements_unlocked_v2
• eos_achievements_copy_achievement_definition_v2_by_achievement_id
• eos_achievements_copy_achievement_definition_v2_by_index
• eos_achievements_copy_player_achievement_by_achievement_id
• eos_achievements_copy_player_achievement_by_index
• eos_achievements_get_achievement_definition_count
• eos_achievements_get_player_achievement_count
• eos_achievements_query_definitions
• eos_achievements_query_player_achievements
• eos_achievements_remove_notify_achievements_unlocked
• eos_achievements_unlock_achievement

These are the structures used by this API:

• AchievementDefinition
• PlayerAchievement
• PlayerStatInfo

Back To Top

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:

eos_achievements_add_notify_achievements_unlocked_v2()

Returns:

Int64

Triggers:

Social Async Event

Example:

identifier = eos_achievements_add_notify_achievements_unlocked_v2();

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

if (async_load[? "type"] == "eos_achievements_add_notify_achievements_unlocked_v2")
if(async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

Epic Online Services Function: EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId

This function fetches an AchievementDefinition from a given achievement ID.

Syntax:

eos_achievements_copy_achievement_definition_v2_by_achievement_id(achievement_id)

Returns:

AchievementDefinition

Example:

var _struct = eos_achievements_copy_achievement_definition_v2_by_achievement_id("MyAchievement1");
if(_struct.status == EOS_RESULT.SUCCESS)
{
    var _achievement_id = _struct.achievement_id;
}

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

Epic Online Services Function: EOS_Achievements_CopyAchievementDefinitionV2ByIndex

This function fetches an AchievementDefinition from a given index.

Syntax:

eos_achievements_copy_achievement_definition_v2_by_index(index)

Returns:

AchievementDefinition

Example:

for(var i = 0 ; i < eos_achievements_get_achievement_definition_count() ; i ++)
{
    var _struct = eos_achievements_copy_achievement_definition_v2_by_index(i);
    if(_struct.status == EOS_RESULT.SUCCESS)
    {
        var _achievement_id = _struct.achievement_id;
    }
}

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

Epic Online Services Function: EOS_Achievements_CopyPlayerAchievementByAchievementId

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

Syntax:

eos_achievements_copy_player_achievement_by_achievement_id(user_id, user_id_target, achievement_id)

Returns:

PlayerAchievement

Example:

var _struct = eos_achievements_copy_player_achievement_by_achievement_id(user_id, user_id_target, achievement_id);
if(_struct.status == EOS_RESULT.SUCCESS)
{
    var _achievement_id = _struct.achievement_id;
}

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

Epic Online Services Function: EOS_Achievements_CopyPlayerAchievementByIndex

This function fetches a player achievement from a given index.

Syntax:

eos_achievements_copy_player_achievement_by_index(user_id, user_id_target, index)

Returns:

PlayerAchievement

Example:

for(var i = 0 ; i < eos_achievements_get_player_achievement_count(userID) ; i ++)
{
    var _struct = eos_achievements_copy_player_achievement_by_index(i);
    if(_struct.status == EOS_RESULT.SUCCESS)
    {
        var _achievement_id = _struct.achievement_id;
    }
}

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

Epic Online Services Function: EOS_Achievements_GetAchievementDefinitionCount

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

Syntax:

eos_achievements_get_achievement_definition_count()

Returns:

Real

Example:

for(var i = 0 ; i < eos_achievements_get_achievement_definition_count() ; i ++)
{
    var _struct = eos_achievements_copy_achievement_definition_v2_by_index(i);
    if(_struct.status == EOS_RESULT.SUCCESS)
    {
        var _achievement_id = _struct.achievement_id;
    }
}

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

Back To Top

Epic Online Services Function: EOS_Achievements_GetPlayerAchievementCount

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

Syntax:

eos_achievements_get_player_achievement_count(user_id)

Returns:

Real

Example:

for(var i = 0 ; i < eos_achievements_get_player_achievement_count(userID) ; i ++)
{
    var _struct = eos_achievements_copy_player_achievement_by_index(i);
    if(_struct.status == EOS_RESULT.SUCCESS)
    {
        var _achievement_id = _struct.achievement_id;
    }
}

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

Back To Top

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 EOS_RESULT, it is possible to call one of the following functions:

• eos_achievements_copy_achievement_definition_v2_by_achievement_id
• eos_achievements_copy_achievement_definition_v2_by_index
• eos_achievements_get_achievement_definition_count

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:

eos_achievements_query_definitions(user_id)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_achievements_query_definitions(user_id);

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

if (async_load[? "type"] == "eos_achievements_query_definitions")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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 EOS_RESULT, it is possible to call one of the following functions:

• eos_achievements_copy_player_achievement_by_achievement_id
• eos_achievements_copy_player_achievement_by_index
• eos_achievements_get_player_achievement_count

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:

eos_achievements_query_player_achievements(user_id, user_id_target)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_achievements_query_player_achievements(user_id, user_id);

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

if (async_load[? "type"] == "eos_achievements_query_player_achievements")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

Epic Online Services Function: EOS_Achievements_RemoveNotifyAchievementsUnlocked

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

• eos_achievements_add_notify_achievements_unlocked_v2

Syntax:

eos_achievements_remove_notify_achievements_unlocked(id)

Returns:

N/A

Example:

handle = eos_achievements_add_notify_achievements_unlocked_v2();
//...
//later...
//...
eos_achievements_remove_notify_achievements_unlocked(handle);

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

Back To Top

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:

eos_achievements_unlock_achievement(user_id, achievement_id)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_achievements_unlock_achievement();

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

if (async_load[? "type"] == "eos_achievements_unlock_achievement")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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:

• EOS_RESULT.SUCCESS if the information is available and was correctly returned;
• EOS_RESULT.INVALID_PARAMETERS (extension internal error, should never be returned);
• EOS_RESULT.NOT_FOUND if the achievement definition is not found;
• EOS_RESULT.INVALID_PRODUCT_USER_ID if you pass an invalid user ID;

This struct is referenced by the following functions:

• eos_achievements_copy_player_achievement_by_achievement_id
• eos_achievements_copy_player_achievement_by_index

Back To Top

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:

• PlayerAchievement

Back To Top

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:

• EOS_RESULT.SUCCESS if the information is available and was correctly returned;
• EOS_RESULT.INVALID_PARAMETERS (extension internal error, should never be returned);
• EOS_RESULT.NOT_FOUND if the achievement definition is not found;
• EOS_RESULT.INVALID_PRODUCT_USER_ID if any of the user_id options are incorrect;

This struct is referenced by the following functions:

• eos_achievements_copy_achievement_definition_v2_by_achievement_id
• eos_achievements_copy_achievement_definition_v2_by_index