Achievements

Last updated on 26 January, 2023 4:13 AM

Overview

Achievements are a tool developers can use to increase player engagement with their game. Recognizing players’ progress in your game and rewarding them with items or new characters not only fosters deeper enjoyment of your game but brand loyalty as well. There are two main types of achievements: incremental and non-incremental. Both of these types are explained belowAccelByte Foundations’ Achievements service enables developers to increase player engagement with their games. Recognizing players’ progress in your game and rewarding them with items or new characters not only fosters deeper enjoyment of your game, but brand loyalty as well. There are two main types of achievements: incremental and non-incremental. Both of these types are explained below.

Incremental Achievements

Incremental achievements work in conjunction with our AccelByte Foundations’ Statistics service. When a player’s stats are updated, the Achievement service checks if the conditions for any incremental achievements have been met. If the conditions for an achievement have been met the achievement will be unlocked. Here are a couple of examples of incremental achievements:

• Collect 10,000 gold In order to unlock bullets, a player must collect 10,000 gold.
• Collect 100 items To unlock the Collector trait, a player must collect 100 items.

Non-Incremental Achievements

Non-incremental achievements don’t require a goal value to be hit, and as such do not need to be integrated with the Statistics service. Here are some examples of non-incremental achievements:

• Play your first game To unlock a bundle of weapons, a player must play the game for the first time.
• Kill 25 thieves in a single game To earn their first medal, players must kill 25 thieves in a single game.

Prerequisites

You have created the relevant StatCodes in the Foundations Statistics service.

Managing Achievements in the Admin Portal

Create a New Achievement Configuration

1. In the desired game title, click the Achievements on the left sidebar and select Add Achievements.

   

2. The Add New Achievements form will appear. Fill in the required fields.

   

   • Code: Type the Code of the achievement with an appropriate format e.g., kill-enemies-achievement.
   • Name: Type the default name of the achievement with a readable string. This will be visible to your players.
   • Description: Type the description of the achievement. This will be visible to your players.
   • Hidden: Select this if you want the achievement to remain hidden to players until it is unlocked.
   • Incremental: If selected, the achievement will automatically be unlocked once the goal value is met. The Achievement service relies on the player’s statistics updates provided by the Statistics service and uses the latest value to determine whether the goal is met.

   If Incremental is selected, two more fields will appear:

   

   • Statcode: Type the relevant StatCode you’ve configured in the Statistics service.

   • Goal Value: Set the goal value to be met in order to unlock the achievement. This value should not exceed the Max Value as defined in the Statistics configuration.

   • Tag: Input contextual information related to the achievement. This field is optional.

   • Locked Icon: Select an image to display for players who have yet to unlock this achievement.

   • Unlocked Icon: Select an image to be displayed when the achievement is Unlocked.

3. Click Add. Your new configuration will be added to the list.

Import or Export Achievement Configurations

1. Expand the Game Management menu and select Achievements.

2. Click the arrow icon next to the Add Achievement button. Two options will appear: Export Achievements and Import Achievements.

   

   a. Export Achievements: All of your achievement configurations will be downloaded in JSON format.

   b. Import Achievements: The Import Configuration form will appear. Select the correct JSON file to import and then choose the import method:

   

• Replace Choose this if you want to replace an old configuration with a new one. The new configuration must have the same key as the oneyou want to replace. If you have multiple configurations in your file, any one with unique keys will also be imported.
• Leave Out Choose this if you want to add a new configuration without replacing any old ones. Using this method, any configurations in your JSON file whose keys match existing ones will not be imported. Only configurations with unique keys will be imported.

A confirmation window will appear. To confirm your selection, type IMPORT in the text box and then click the Import button.

Implementing Achievements using the SDKs

Unlock an Achievement

There are two ways to unlock a player’s achievement: either from Game Client or from the Game Dedicated Server.

Unlock an Achievement from the Game Client

NOTE

This function can only be used for non-incremental achievements that do not affect gameplay, such as the player’s first time entering the lobby, their first time inviting a friend, etc.

Unreal Engine

FString AchievementCode = FString("MyAchievementCode");

FRegistry::Achievement.UnlockAchievement(AchievementCode, FVoidHandler::CreateLambda([]()
{
    // Do something if UnlocKAchievement has been successful
}), FErrorHandler:: CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if UnlockAchievement has an error
    UE_LOG(LogTemp, Log, TEXT("Error UnlockAchievement, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string achievementCode = "MyAchievementCode";

        AccelBytePlugin.GetAchievement().UnlockAchievement(achievementCode, result =>
        {
            if (result.IsError)
            {
                // Do something if UnlockAchievement has an error
                Debug.Log($"Error UnlockAchievement, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if UnlockAchievement has been successful
            }
        });

Unlock an Achievement from the Dedicated Server

Unlocking an achievement from the server is usually done after a match is completed.

Unreal Engine

FString AchievementCode = FString("MyAchievementCode");
FString UserId = FString("SomeUserId");
    
FRegistry::ServerAchievement.UnlockAchievement(UserId, AchievementCode, FVoidHandler::CreateLambda([]()
{
    // Do something if UnlockAchievement has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if UnlockAchievement has an error
    UE_LOG(LogTemp, Log, TEXT("Error UnlockAchievement, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string achievementCode = "MyAchievementCode";
        string userId = "SomeUserId";

        AccelByteServerPlugin.GetAchievement().UnlockAchievement(userId, achievementCode, result =>
        {
            if (result.IsError)
            {
                // Do something if UnlockAchievement has an error
                Debug.Log($"Error UnlockAchievement, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if UnlockAchievement has been successful
            }
        });

Achievements Query

Get a Single Achievement

Use this function to retrieve achievement info, such as the achievement name, description, goalValue, etc.

Unreal Engine

FString AchievementCode = FString("MyAchievementCode");

FRegistry::Achievement.GetAchievement(AchievementCode, THandler<FAccelByteModelsMultiLanguageAchievement>::CreateLambda([](const FAccelByteModelsMultiLanguageAchievement& Result)
{
    // Do something if GetAchievement has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetAchievement has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetAchievement, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string achievementCode = "MyAchievementCode";

        AccelBytePlugin.GetAchievement().GetAchievement(achievementCode, result =>
        {
            if (result.IsError)
            {
                // Do something if GetAchievement has an error
                Debug.Log($"Error GetAchievement, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if GetAchievement has been successful
            }
        });

Query All Achievements

Use this function to retrieve a list of all achievements in the related namespace.

Unreal Engine

FString Language = FString("en");
EAccelByteAchievementListSortBy SortBy = EAccelByteAchievementListSortBy::LISTORDER;
int32 Offset = 0;
int32 Limit = 50;

FRegistry::Achievement.QueryAchievements(Language, SortBy, THandler<FAccelByteModelsPaginatedPublicAchievement>::CreateLambda([](const FAccelByteModelsPaginatedPublicAchievement& Result)
{
    // Do something if QueryAchievements has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if QueryAchievements has an error
    UE_LOG(LogTemp, Log, TEXT("Error QueryAchievements, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}), Offset, Limit);

Unity

string language = "en";
        AchievementSortBy sortBy = AchievementSortBy.LISTORDER;
        int offset = 0;
        int limit = 50;

        AccelBytePlugin.GetAchievement().QueryAchievements(language, sortBy, result =>
        {
            if (result.IsError)
            {
                // Do something if QueryAchievements has an error
                Debug.Log($"Error QueryAchievements, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if QueryAchievements has been successful
            }
        }, offset, limit);

Query a Player’s Achievement

Use this function to query a player’s unlocked and in-progress achievements.

Unreal Engine

EAccelByteAchievementListSortBy SortBy = EAccelByteAchievementListSortBy::LISTORDER;
int32 Offset = 0;
int32 Limit = 50;

FRegistry::Achievement.QueryUserAchievements(SortBy, THandler<FAccelByteModelsPaginatedUserAchievement>::CreateLambda([](const FAccelByteModelsPaginatedUserAchievement& Result)
{
    // Do something if QueryUserAchievements has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if QueryUserAchievements has an error
    UE_LOG(LogTemp, Log, TEXT("Error QueryUserAchievements, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}), Offset, Limit);

Unity

AchievementSortBy sortBy = AchievementSortBy.LISTORDER;
        int offset = 0;
        int limit = 50;

        AccelBytePlugin.GetAchievement().QueryUserAchievements(sortBy, result =>
        {
            if (result.IsError)
            {
                // Do something if QueryUserAchievements has an error
                Debug.Log($"Error QueryUserAchievements, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if QueryUserAchievements has been successful
            }
        }, offset, limit);