Achievements

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.

Use Cases #

• Daily/weekly quests: Recurring goals that reset on a schedule.
• Battle pass tracks: A parent achievement with sub‑achievements for each tier; rewards per tier plus an optional completion reward.
• Limited‑time events: Achievements that are only active during an event window.
• Milestones: One‑off goals that don’t repeat.

Key Terms #

• Achievement: A top‑level goal that can award a reward and may contain sub‑achievements.
• Sub‑achievement: A child goal used for progressive tracks or stepwise rewards.
• Active phase: The time window during which progress counts for an achievement before it completes or resets.
• reward vs total_reward:
  • reward applies to the achievement (or a sub‑achievement) itself.
  • total_reward applies when a parent achievement with sub‑achievements is fully complete.
• Auto-claim:
  • auto_claim: Automatically claims the reward defined on that achievement/sub‑achievement.
  • auto_claim_total: Automatically claims the total_reward on the parent achievement when all sub‑achievements are complete.
• Preconditions (precondition_ids): Other achievement or sub‑achievement IDs that must be complete before this one becomes available.

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.

Achievements can be always‑available, time‑boxed, or recurring. Four fields govern timing:

• reset_cronexpr: A cron expression that creates recurring active phases (for example, every day at 00:00).
• duration_sec: The length of each active phase. When the duration elapses, the phase ends and the achievement resets if it is recurring.
• start_time_sec: The first moment a phase is allowed to begin (Unix timestamp). If set, the initial phase won’t start before this time.
• end_time_sec: A cutoff in the future (Unix timestamp). After this time, new phases don’t start. An in‑progress phase may still finish if it started before the cutoff.

Scheduling configuration examples #

• Nothing configured -> Always available until completed.
• reset_cronexpr only -> Recurring achievement that resets on schedule.
• duration_sec only -> A one‑time achievement with a limited active window from creation time.
• reset_cronexpr + duration_sec -> Recurring windows (for example, weekly challenges open for 72 hours).
• Add start_time_sec-> Delay the first eligible phase until the start time.
• Add end_time_sec -> Stop scheduling new phases after the end time.

Example: With reset_cronexpr set to weekly and duration_sec set to 3 days, phases open every Monday and last 72 hours. If start_time_sec is next Monday 00:00, nothing opens before then. If end_time_sec is one month later, weeks after that date won’t create new phases.

Rewards model and claiming #

• Use reward for per‑step or per‑achievement payouts.
• Use total_reward to grant an additional payout when a parent achievement with sub‑achievements is fully complete.
• You may define both on the same parent. This supports battle passes that grant a reward for the final step and a completion bonus.
• Auto‑claim controls are scoped:
  • auto_claim applies only to the reward on that achievement (or sub‑achievement).
  • auto_claim_total applies only to the parent’s total_reward.

Preconditions #

Use precondition_ids to gate availability or sequence content. You can reference achievement IDs and sub‑achievement IDs. Typical patterns include:

• Linear track: Each sub‑achievement requires the previous one.
• Branching: A parent unlocks multiple children after completion.
• Event gating: A limited‑time parent requires a permanent milestone first.

Sub‑achievements #

Sub‑achievements let you build progressive tracks:

• Define as many steps as you need.
• Attach reward to each step for granular payouts.
• Optionally add a parent total_reward for finishing the whole track.
• Combine with preconditions to enforce order.

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

{
  "achievements": {
    "achievementId1": {
      "auto_claim": false,
      "auto_reset": false,
      "category": "category1",
      "count": 0,
      "reset_cronexpr": "* * * * *",
      "duration_sec": 86400,
      "max_count": 10,
      "name": "name1",
      "reward": {
        "guaranteed": {
          "currencies": {
            "gold": {
              "min": 100
            }
          },
          "items": {
            "hero_card": {
              "min": 1,
              "max": 5
            }
          }
        }
      },
      "additional_properties": {
        "propertyName": "value"
      },
      "sub_achievements": {}
    },
    "achievementId2": {
      "auto_claim": false,
      "auto_claim_total": false,
      "auto_reset": false,
      "category": "category2",
      "count": 0,
      "reset_cronexpr": "* * * * *",
      "duration_sec": 86400,
      "max_count": 10,
      "name": "name2",
      "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
            }
          }
        }
      },
      "precondition_ids": [
        "achievementId1"
      ],
      "additional_properties": {
        "propertyName": "value"
      },
      "sub_achievements": {}
    }
  }
}

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 individual achievement is keyed by id and may define the following:

Achievement #

Additional Information #

How-to Guides

• How to implement a Battle Pass
• How to implement Quests

Reference Docs

• Server-side implementation of achievements
• Achievements in Unity
• Achievements in Unreal