Achievements #

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

The Achievement system is a great tool that game designers can use to create a sense of progression by unlocking new content and rewarding players for completing tasks.

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.

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.

Scheduling #

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. If an achievement has been completed, but hasn’t been claimed yet, and the schedule causes it to reset, the player is still able claim their rewards. Alternatively, you could set the achievement to be auto claimed upon completion. If the achievement is set to reset upon completion, rather than using an interval, it will reset immediately, even if there are rewards to claim (they can still be claimed later).

An achievement’s active phase and reset schedule is calculated as soon as the configuration is loaded by the server, this means that you can’t currently create an achievement to be available at a future point in time, instead, it would have to be created/added at that future point in time. An easy way to do this is to use Satori Feature Flags to add new achievements to the remote configuration when you want them to become available.

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,
            "category": "",
            "count": 0,
            "description": "",
            "reset_cronexpr": "* * * * *",
            "duration_sec": 86400,
            "max_count": 10,
            "name": "",        
            "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,
            "category": "",
            "count": 0,
            "description": "",
            "reset_cronexpr": "* * * * *",
            "duration_sec": 86400,
            "max_count": 10,
            "name": "",          
            "precondition_ids": [
                "<achievementId1>"
            ],
            "reward": {
                "guaranteed": {
                "currencies": {
                    "gold": {
                        "min": 100
                    }
                },
                "items": {
                    "hero_card": {
                        "min": 1,
                        "max": 5
                    }
                }
            },
            "total_reward": {
                "guaranteed": {
                "currencies": {
                    "gold": {
                        "min": 100
                    }
                },
                "items": {
                    "hero_card": {
                        "min": 1,
                        "max": 5
                    }
                }
            },
            "sub_achievements": {
                "<subAchievementId1>": {
                    // Similar to the standard achievement schema
                }
            },
            "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.

PropertyTypeDescription
achievementsstring:AchievementA map of all achievements.

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

Achievement #

PropertyTypeDescription
auto_claimboolWhether the achievement reward should be given automatically upon completion.
auto_claim_totalboolWhether the achievement total reward should be given automatically upon completing this and all sub-achievements.
auto_resetboolWhether the achievement should reset after completion.
categorystringThe category name for this achievement.
countint64The initial count towards progress for this achievement.
descriptionstringThe description for this achievement.
reset_cronexprstringThe reset interval in CRON format.
duration_secint64How long (in seconds) this achievement is available for progression after creation. Used for limited time achievements.
max_countint64The number of times this achievement must be progressed before it can be claimed. Set this to 0 (zero) to allow for immediate claiming, so long as all preconditions are met.
namestringThe display friendly name of this achievement.
precondition_ids[]stringAchievement IDs the user must have completed to qualify for starting this achievement.
rewardRewardThe rewards a user should receive once they complete this achievement.
total_rewardRewardThe rewards a user should receive once they have completed this achievement and all sub achievements.
sub_achievementsstring:SubAchievementA map of nested achievements.
additional_propertiesstring:stringA map of key value pairs that can contain additional context.