Achievements

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 below.

Incremental Achievements

Incremental achievements work in conjunction with our 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 examples of incremental achievements:

  • Collect 10,000 gold In order to unlock packs of 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.
  • Kill 25 thieves in a single game. To earn their first medal, players must kill 25 thieves in a single game.

Prerequisites

Before you can create achievements, you must have statistics for those achievements to be based on.

Create a New Statistic Configuration

  1. In the Statistics section of the Admin Portal, open the Configurations menu.

    achievement

  2. In the Statistic Configurations window, click the Add Configuration button.

    achievement

  3. Fill in the appropriate fields.

    achievement

    • Input the statistic code in the Code field, following the formatting rules given.
    • Input the Name of the configuration.
    • Input a Description of the configuration. This field is optional.
    • Define the minimum value of the statistic in the Min. Value field.
    • Define the maximum value of the statistic in Max. Value field.
    • Input the Default Value of the statistic.
    • Choose the Increment value. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.
    • Choose the Set As Global value. If set to true, every time the stat is updated the global stat value will also be updated.
    • Select the Set By value. You can select either the game client or game server. This determines which client will update the stat value.
    • Input the Tag with contextual information related to the statistic. This field is optional.

Tutorials

Create a New Achievement Configuration

Create a New Achievement Configuration

You’ll need the statistics code you created earlier when you fill in the configuration form.

  1. On the Achievements page of the Admin Portal, click the Add Configuration button.

    achievement

  2. Once the form appears, fill in the appropriate fields.

    achievement

    • Input the Code of the achievement with an appropriate format e.g. kill-enemies-achievement.
    • Input the Default Name of the achievement with a readable string. This will be the public facing name.
    • Input the Default Description of the achievement. This description is also public facing.
    • Choose if you want the achievement to be Hidden or not. Hidden achievements are not shown when they are still locked, but will appear once they’re unlocked.
    • Select Incremental for an incremental achievement, or leave the checkbox unselected for a non-incremental achievement..
    • For incremental achievements, input the StatCode with the statistics code for the relevant statistic. You can leave this field empty if you’re creating a non-incremental achievement.
    • For incremental achievements, input the Goal Value. Note that the goal value should not exceed the max value defined in the Statistic - Configuration. You can leave this field empty if you’re creating a non-incremental achievement.
    • Input the Tag field with contextual information related to the achievement.
    • Select an image for the Locked Icon. This image will display for players who do not have this achievement yet.
    • Select an image to be displayed when the achievement is Unlocked.
  3. Click Add. Your new configuration will be added to the list.

    achievement

Export Achievement Configurations

You can export your achievement configurations in JSON format by following the steps below.

  1. In the Achievements menu of the Admin Portal, open the dropdown menu next to the Add Configuration button and choose Export Configuration.

    achievement

  2. The download will be started. Once it’s finished, open the JSON file to see your achievement configs.

Import an Achievement Configuration

  1. In the Achievements menu of the Admin Portal, open the dropdown menu next to the Add Configuration button and choose Import Configuration.

    achievement

  2. The Import Configuration form will appear.

    achievement

    • Choose a File to Import. The file should be in JSON format.

    • Select the Import Method.

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

    Click Import.

  3. Confirm the import configuration by typing IMPORT in the pop-up form below.

    achievement

Integrate the Achievement Service with the SDK

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 that this function can only be used for non-incremental achievements that do not affect gameplay. For example, the first time going to the gallery, first time inviting a friend, etc.

FString AchievementCode = “YourAchievementCode”;
AccelByte::FRegistry::Achievement.UnlockAchievement(AchievementCode, FVoidHandler::CreateLambda([this]()
{
UE_LOG(LogTemp, Log, TEXT(“Achievement Unlocked”));
}),
FErrorHandler::CreateLambda([this](int32 code, FString message)
{
UE_LOG(LogTemp, Warning, TEXT("Failed to Unlock Achievement, Code : %i Message : %s"), code, *message);
}));
Unlock an Achievement from the Dedicated Server

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

FString AchievementCode = "YourAchievementCode";
FString UserId = "YourUserId";
FRegistry::ServerAchievement.UnlockAchievement(UserId, AchievementCode, FVoidHandler::CreateLambda([this]() {
UE_LOG(LogTemp, Log, TEXT("Achievement Unlocked"));
}), FErrorHandler::CreateLambda([](int32 code, FString message)
{
UE_LOG(LogTemp, Warning, TEXT("[Server] Failed to Unlock Achievement, Code : %i Message : %s"), code, *message);
}));

Achievements Query

Get a Single Achievement

You can use this function to retrieve achievement info, such as the achievement name, description, goalValue, etc.

FString AchievementCode = “YourAchievementCode”;
AccelByte::FRegistry::Achievement.GetAchievement(AchievementCode, THandler<FAccelByteModelsMultiLanguageAchievement>::CreateLambda([this](const FAccelByteModelsMultiLanguageAchievement& Result)
{
UE_LOG(LogTemp, Log, TEXT("Get Achievement Success!"));
TArray<FString> AchievementNames;
Result.Name.GenerateValueArray(AchievementNames);
TArray<FString> AchievementDescriptions;
Result.Description.GenerateValueArray(AchievementDescriptions);
UE_LOG(LogTemp, Log, TEXT("Achievement Name: %s | Achievement Description: %s"), *AchievementNames[0], *AchievementDescriptions[0]);
}),
FErrorHandler::CreateLambda([this](int32 code, FString message)
{
UE_LOG(LogTemp, Warning, TEXT("Failed to Get Achievement, Code : %i Message : %s"), code, *message);
}));
Query All Achievements

You can use this function to retrieve a list of all achievements in the related namespace.

FString language = TEXT(“en”);
AccelByte::FRegistry::Achievement.QueryAchievements(language, EAccelByteAchievementListSortBy::LISTORDER,
THandler<FAccelByteModelsPaginatedPublicAchievement>::CreateLambda([this](const FAccelByteModelsPaginatedPublicAchievement& Result)
{
UE_LOG(LogTemp, Log, TEXT("Query Achievements Success!"));
for (FAccelByteModelsPublicAchievement QueryAchievements : Result.Data)
{
UE_LOG(LogTemp, Log, TEXT("Achievement Name: %s | Achievement Description: %s"), *QueryAchievements.Name, *QueryAchievements.Description);
}
}),
FErrorHandler::CreateLambda([this](int32 code, FString message)
{
UE_LOG(LogTemp, Warning, TEXT("Error: %s | Message: %s"), code, *message);
}));

Query a Player’s Achievement

You can use this function to query a player’s unlocked and in-progress achievements.

AccelByte::FRegistry::Achievement.QueryUserAchievements(EAccelByteAchievementListSortBy::LISTORDER, THandler<FAccelByteModelsPaginatedUserAchievement>::CreateLambda([this](const FAccelByteModelsPaginatedUserAchievement& Result)
{
UE_LOG(LogTemp, Log, TEXT("Query Achievements Success!"))
UE_LOG(LogTemp, Log, TEXT("Achievement Count: %i"), Result.CountInfo.NumberOfAchievements);
for (FAccelByteModelsUserAchievement QueryUserAchievements : Result.Data)
{
//1 in-progress | 2 unlocked
UE_LOG(LogTemp, Log, TEXT("Achievement Code: %s | Status: %i"), *QueryUserAchievements.AchievementCode, QueryUserAchievements.Status);
}
}),
FErrorHandler::CreateLambda([this](int32 code, FString message)
{
UE_LOG(LogTemp, Log, TEXT("Error: %i | Message: %s"), code, *message);
}));

What’s Next?

  • Check out the API Reference to learn more about achievements.
  • Once you have achievements in place, you can create leaderboards.