Skip to main content

Achievements

Last updated on

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 AccelByte Gaming Services (AGS) Starter 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 Gaming Services (AGS) Starter 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 AGS Starter Statistics service.

Managing Achievements in the Admin Portal​

Create a New Achievement Configuration​

To create a new achievement configuration, follow the steps below:

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

    achievement

  2. On the Achievements page, click the Add Achievements button.

    achievement

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

    achievement

    • Input the Code of the achievement, e.g., kill-enemies-achievement.
    • Input the Name of the achievement with a readable string. This will be a public facing name.
    • Input the Description of the achievement. This description is also public facing.
    • Choose if you want the achievement to be Hidden. Hidden achievements are not shown to player when they are still locked, but will appear once unlocked.
    • Select Incremental for an incremental achievement, or leave the checkbox unselected for a non-incremental achievement. If you’re creating an incremental achievement, input the Goal Value and a StatCode of the statistic associated with this achievement.
    • Select Incremental for an incremental achievement, or leave the checkbox unselected for a non-incremental achievement. In this case, we’re creating an incremental achievement so, we need to input the Goal Value and a StatCode of a statistics configuration associated with this achievement.
NOTE

The Goal Value should not exceed the Max. Value defined in the Statistic configuration.

- Input the **Tag** field with contextual information related to the achievement. You can input up to five tags. This field is optional.
- Select an image for the **Locked Icon**. This image will be displayed for players who do not have this achievement yet.
- Select an image for the **Unlocked Icon**. This image will display when the achievement is unlocked.
  1. Click Add. Your new configuration will be added to the list.

Edit achievement configurations​

To edit an existing achievement configuration, follow the steps below:

  1. In the Game Management section of the Admin Portal, select Achievements.

    achievement

  2. On the Achievements page, you can see the list of existing achievements. You can Filter by Code or Filter by Tag to narrow down the list.

    achievement

  3. To see the achievement details, click View next to the selected achievements.

    achievement

  4. The Achievement Detail page appears. You can edit the achievement configuration here.

    achievement

Export Achievement Configurations​

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

  1. In the Game Management section of the Admin Portal, select Achievements.

    achievement

  2. On the Achievements page, open the dropdown menu next to the Add Achievements button and choose Export Achievements.

    achievement

  3. The download will start. Once it’s finished, open the JSON file to see - achievement configs. 

    [
        {
            "Hidden": false,
            "Incremental": false,
            "ID": "5ec4b6ee296bxxde03cdeee1",
            "ListOrder": 1,
            "GoalValue": 0,
            "UnlockedIcons": [
            {
                "url": "https://cdn.demo.accelbyte.io/files/accelbyte/achievements/54a4c4485ac34a63a0ece0e849b488e0.png",
                "slug": "rectangle-1png"
            }
            ],
            "LockedIcons": [
            {
                "url": "https://cdn.demo.accelbyte.io/files/accelbyte/achievements/53351a0b28134d008600bb5fb6cf23c3.png",
                "slug": "rectanglepng"
            }
            ],
            "CreatedAt": "2020-05-20T04:49:50.825Z",
            "UpdatedAt": "2020-05-20T04:49:50.825Z",
            "Namespace": "accelbyte",
            "AchievementCode": "penta-kill",
            "StatCode": "",
            "DefaultLanguage": "en",
            "Tags": [
            "kills"
            ],
            "Name": {
            "en": "Penta Kill"
            },
            "Description": {
            "en": "Penta Kill description"
            }
        }
    ]

Import an Achievement Configuration​

You can import an achievement configuration in JSON format into the admin Portal. To do so, follow the steps below.

  1. In the Game Management section of the Admin Portal, select Achievements.

    achievement

  2. On the Achievements page, open the dropdown menu next to the Add Achievement button and choose Import Achievements.

    achievement

  3. The Import Configuration form will appear. Fill in the required fields.

    achievement

    • Choose a File to Import. The file must 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.

  4. Click Import.

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

    achievement

  6. Click Import.

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.

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);
}));

Unlock an Achievement from the Dedicated Server​

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

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);
}));

Achievements Query​

Get a Single Achievement​

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

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);
}));

Query All Achievements​

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

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);

Query a Player’s Achievement​

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

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);