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 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
In the desired game title, click the Achievements on the left sidebar and select Add Achievements.
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.
Click Add. Your new configuration will be added to the list.
Import or Export Achievement Configurations
Expand the Game Management menu and select Achievements.
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
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
- Unity
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);
}));
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
- Unity
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);
}));
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
- Unity
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);
}));
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
- Unity
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);
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
- Unity
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);
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);