Achievements #

Progressive achievements used in Mr. Autofire by Lightheart Entertainment
Progressive achievements used in Mr. Autofire by Lightheart Entertainment

Achievement systems are a great tool for game designers to use to create a sense of progression and reward for players. It can be used to unlock new content, provide a sense of accomplishment, and reward players for their progress.

An “achievement” represents a player task which can be completed and, on completion, can unlock a reward. The reward can be in-game currency, collectables, energy, energy modifiers, or consumables.

Achievements can be configured to repeat on a schedule, or to repeat automatically when the player completes the task. They can also be one-off achievements which are only completed once.

For increased player engagement and larger sense of progression, achievements can be configured to have a precondition. This means that the achievement cannot be completed until one or more other achievements have been completed.

Achievements can also be configured to have any number of sub achievements. Sub achievements are nested, hierarchical achievements that can be used for progressive rewards.

Customization parameters #

The following JSON represents the customization parameters you can use to configure the default user experience for the achievements system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

{
    "achievements": {
        "<achievementId1>": {
            "auto_claim": false,
            "auto_reset": false,
            "name": "",
            "category": "",
            "description": "",
            "reset_cronexpr": "* * * * *",
            "duration_sec": 86400,
            "count": 0,
            "max_count": 10,
            "reward": {
                "guaranteed": {
                "currencies": {
                    "gold": {
                        "min": 100
                    }
                },
                "items": {
                    "hero_card": {
                        "min": 1,
                        "max": 5
                    }
                }
            },
            "additional_properties": {
                "<propertyName>": "value"
            }
        },
        "<achievementId2>": {
            "auto_claim": false,
            "auto_claim_total": false,
            "auto_reset": false,
            "name": "",
            "category": "",
            "description": "",
            "reset_cronexpr": "* * * * *",
            "duration_sec": 86400,
            "count": 0,
            "max_count": 10,
            "precondition_ids": [
                "<achievementId1>"
            ],
            "reward": {
                "guaranteed": {
                "currencies": {
                    "gold": {
                        "min": 100
                    }
                },
                "items": {
                    "hero_card": {
                        "min": 1,
                        "max": 5
                    }
                }
            },
            "sub_achievements": {
                "<subAchievementId1>": {
                    // Same as a standard achievement schema
                }
            },
            "total_reward": {
                "guaranteed": {
                "currencies": {
                    "gold": {
                        "min": 100
                    }
                },
                "items": {
                    "hero_card": {
                        "min": 1,
                        "max": 5
                    }
                }
            },
            "additional_properties": {
                "<propertyName>": "value"
            }
        }
    }
}

The JSON schema defines an achievements object which must contain an individual object for each achievement you wish to define in the system. You can configure as few or as many achievements and sub-achievements as needed for your desired gameplay.

Each achievement is keyed by id and may define the following:

PropertySubpropertyDescription
auto_claimWhether the achievement reward should be given automatically upon completion.
auto_claim_totalWhether the achievement total reward should be given automatically upon completing this and all sub-achievements.
auto_resetWhether the achievement should reset after completion.
nameThe display friendly name of this achievement.
categoryThe category name for this achievement.
descriptionThe description for this achievement.
countThe initial count towards progress for this achievement.
max_countThe number of times this achievement can be progressed before it can be claimed.
duration_secHow long (in seconds) this achievement is available for progression after creation. Used for limited time achievements.
reset_cronexprThe reset interval in CRON format.
precondition_idsAn array of achievement ids the user must have completed to qualify for starting this achievement.
rewardAn object that defines what rewards a player should receive once they complete this achievement.
sub_achievementsAn object with the same Schema as the root achievements object, used to define nested achievements.
total_rewardAn object that defines what rewards a player should receive once they have completed this achievement and all sub achievements.
additional_propertiesA string:string dictionary of key value pairs that can contain additional context.

Initializing the achievements system #

The achievements system relies on the Nakama System and the Economy System, both must be passed in as dependencies via the constructor.

1
2

var achievementsSystem = new AchievementsSystem(nakamaSystem, economySystem)
systems.Add(achievementsSystem);

Subscribing to changes in the achievements system #

You can listen for changes in the achievements system so that you can respond appropriately, such as updating the UI, by implementing the appropriate interface.

1
2
3
4
5

var disposer = SystemObserver<AchievementsSystem>.Create(leaderboardsSystem, system => {
  Instance.Logger.Info($"System updated.");

  // Update UI elements etc as necessary here...
});

Refreshing the achievements system #

To ensure the achievements system has the latest information from Nakama you can refresh it.

1

await achievementsSystem.RefreshAsync();

Listing achievements #

You can list all achievements for the user.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

foreach (var achievementKvp in achievementsSystem.Achievements)
{
    var id = achievementKvp.Key;
    var achievement = achievementKvp.Value;
    
    Debug.Log($"Achievement {achievement.Name} ({achievement.Category})");
    Debug.Log(achievement.Description);

    if (achievement.HasReward())
    {
        Debug.Log("Reward available on completion");
    }

    if (achievement.SubAchievements.Any())
    {
        Debug.Log($"{achievement.SubAchievements.Count} sub-achievements.");
    }
}

You can also list all repeatable achievements for the user.

1
2
3
4

foreach (var achievementKvp in achievementsSystem.RepeatAchievements)
{
  // ...
}

As well as list achievements by category for the user.

1
2
3
4

foreach (var achievement in achievementsSystem.GetCategory("<categoryName>"))
{
  // ...
}

Listing available achievements by category #

Similarly to above, you can list achievements by category for the user, including only achievements the user is currently able to complete.

1
2
3
4

foreach (var achievement in achievementsSystem.GetAvailableAchievements("<categoryName">))
{
  // ...
}

Updating achievement progress #

You can update the user’s progress for achievements.

1
2

var timesCompleted = 1;
await achievementsSystem.UpdateAchievementsAsync(new[] {"<achievementId1>", "<achievementId2>"}, timesCompleted);

Claiming achievement rewards #

You can claim rewards for an achievement. You can also specify whether you would like to claim any available total rewards (e.g. if the user has completed all sub-achievements) as well as whether or not to refresh the Economy System.

1
2
3
4

var claimTotalReward = true;
var refreshEconomy = true;

await achievementsSystem.ClaimAchievementsAsync(new[] {"<achievementId1>", "<achievementId2>}", claimTotalReward, refreshEconomy);