GDevelop extension · version 1.1.0

Achievements

Define achievements, unlock them or track their progress, save them on the device, and show a toast when one is unlocked.

The example game: a list of six achievements, and a toast at the bottom-right saying Achievement unlocked: First Step, with a footprint icon.
The example project: an achievements list built with events, and a toast with the achievement's own icon.

Get Started

  1. In GDevelop, open the extension store (Project Manager › Extensions), search Achievements and install it.
  2. At the beginning of your first scene, define each achievement once:
    Define achievement "coin_hunter": "Coin Hunter" (goal: 5)
    The identifier is how your events refer to it. Use a goal of 1 for an achievement that unlocks in one go.
  3. Unlock it in one go: Unlock achievement "first_step"
    or add progress, and it unlocks when the progress reaches the goal: Add 1 to the progress of achievement "coin_hunter"
  4. Optional: react to it with the condition Achievement "coin_hunter" was just unlocked: play a sound, give a reward. It is true for one frame only.

Use Set progress for numbers you already keep, like the best score or the level reached: Set the progress of achievement "high_score" to BestScore.

The Toast

A toast slides in when an achievement is unlocked. It needs no object in your scene: the extension draws it on its own layer, above everything else, in 2D and 3D games. When several achievements unlock together, their toasts are shown one after another.

A green toast with the label Pencapaian dibuka, which is Malay for Achievement unlocked.
The label translated to Malay, with custom colors.

Secret Achievements

Make achievement "curious" secret: yes hides its title and description until it is unlocked: the expressions Title and Description give “Secret achievement” and “???” instead (change these with Secret achievement text). The toast shows the real title when it unlocks.

An Achievements Screen

Build your own list with a Repeat event: repeat Achievements::Count() times, and for each position i (a variable from 0), Achievements::IdAt(i) gives the identifier. Use it with Title, Description, Progress, Goal, ProgressPercent for a progress bar, and the condition Achievement is unlocked. The example project has a complete one.

Saving

Progress is saved on the player's device as soon as it changes, in the browser's local storage, under a key with your game's name. It works in web, desktop and mobile exports. Definitions (titles, goals) are not saved: they come from your events every time the game starts, so you can change them in an update. If you make a goal smaller, players who already reached it get the achievement.

Achievements are local to the device: they are not linked to Steam, Game Jolt or another platform. Reset all achievements erases them, which is handy for a “reset progress” button and while testing.

Reference

Every action, condition and expression, as you find them in GDevelop. Highlighted parts are what you fill in.

Setup

Action
Define an achievement
Define achievement Achievement identifier: Title (goal: Goal)

Define an achievement: its title, description and goal. Do this at the start of the first scene, before unlocking anything. Use a goal of 1 for an achievement that unlocks in one go, or a bigger goal (like 10) for one that unlocks when its progress reaches it. Progress is saved on the player's device.

  • Achievement identifier (for example: "first_coin") text
  • Title text
  • Description text
  • Goal (1 to unlock in one go) number, default 1
Action
Make an achievement secret
Make achievement Achievement identifier secret: Secret

Make an achievement secret (or not): until it is unlocked, its title and description are hidden. The toast shows the real title when it is unlocked.

  • Achievement identifier (for example: "first_coin") text
  • Secret yes / no, default yes
Action
Achievement icon
Use image Image as the icon of achievement Achievement identifier

Use an image as the icon of an achievement. It is shown in the toast instead of the star. A square image works best.

  • Achievement identifier (for example: "first_coin") text
  • Image image
Action
Secret achievement text
Show Title and Description for locked secret achievements

Change the title and description shown for secret achievements that are still locked (“Secret achievement” and “???” by default).

  • Title text
  • Description text
Action
Reset an achievement
Reset achievement Achievement identifier

Lock an achievement again and set its progress back to 0.

  • Achievement identifier (for example: "first_coin") text
Action
Reset all achievements
Reset all achievements

Lock every achievement again and erase all saved progress. Useful for a “reset progress” button or while testing.

Unlock and Progress

Action
Unlock an achievement
Unlock achievement Achievement identifier

Unlock an achievement now. Nothing happens if it is already unlocked.

  • Achievement identifier (for example: "first_coin") text
Action
Add progress to an achievement
Add Amount to add to the progress of achievement Achievement identifier

Add to an achievement's progress. It unlocks when the progress reaches its goal.

  • Achievement identifier (for example: "first_coin") text
  • Amount to add number, default 1
Action
Set the progress of an achievement
Set the progress of achievement Achievement identifier to Progress

Set an achievement's progress to a value (for example the best score or the level reached). It unlocks when the progress reaches its goal. Progress never goes down once the achievement is unlocked.

  • Achievement identifier (for example: "first_coin") text
  • Progress number
Condition
Achievement is unlocked
Achievement Achievement identifier is unlocked

Check if an achievement is unlocked.

  • Achievement identifier (for example: "first_coin") text
Condition
Achievement was just unlocked
Achievement Achievement identifier was just unlocked

Check if an achievement was just unlocked. This is true for one frame only: use it to play a sound or give a reward.

  • Achievement identifier (for example: "first_coin") text
Condition
Any achievement was just unlocked
Any achievement was just unlocked

Check if any achievement was just unlocked. This is true for one frame only. The expression LastUnlocked() tells which one.

Information

Expression
Progress
Achievements::Progress(Id)

The progress of an achievement (0 up to its goal).

  • Achievement identifier (for example: "first_coin") text
Expression
Goal
Achievements::Goal(Id)

The goal of an achievement.

  • Achievement identifier (for example: "first_coin") text
Expression
Progress in percent
Achievements::ProgressPercent(Id)

The progress of an achievement in percent (0 to 100). Handy for progress bars.

  • Achievement identifier (for example: "first_coin") text
Expression
Number of achievements
Achievements::Count()

The number of achievements defined.

Expression
Number of unlocked achievements
Achievements::UnlockedCount()

The number of defined achievements that are unlocked.

Text expression
Achievement identifier by position
Achievements::IdAt(Index)

The identifier of the achievement at a position (0 is the first one defined). Use it with a Repeat event to build an achievements screen.

  • Position (0 is the first achievement) number
Text expression
Title
Achievements::Title(Id)

The title of an achievement. A secret achievement that is still locked gives the secret title instead.

  • Achievement identifier (for example: "first_coin") text
Text expression
Description
Achievements::Description(Id)

The description of an achievement. A secret achievement that is still locked gives the secret description instead.

  • Achievement identifier (for example: "first_coin") text
Text expression
Icon
Achievements::Icon(Id)

The name of the image resource used as the icon of an achievement (empty if it has none).

  • Achievement identifier (for example: "first_coin") text
Condition
Achievement is secret
Achievement Achievement identifier is secret

Check if an achievement is secret.

  • Achievement identifier (for example: "first_coin") text
Text expression
Last unlocked achievement
Achievements::LastUnlocked()

The identifier of the achievement unlocked most recently in this game session.

Toast

Action
Show toasts
Show a toast when an achievement is unlocked: Show toasts

Show (or hide) the pop-up that slides in when an achievement is unlocked. It is shown by default.

  • Show toasts yes / no, default yes
Action
Toast position
Show toasts at the Position of the screen

Change where the toast appears on the screen.

  • Position choice, default "Top"
Action
Toast duration
Show toasts for Duration seconds

Change how long the toast stays on screen.

  • Duration (in seconds) number, default 3
Action
Toast colors
Toast colors: background Background color, text Text color, accent Accent color

Change the colors of the toast.

  • Background color color, default "30;34;51"
  • Text color color, default "255;255;255"
  • Accent color (border, star and label) color, default "255;200;61"
Action
Toast label
Toast label: Label

Change the small label above the title (“Achievement unlocked” by default). Use it to translate the toast, for example “Pencapaian dibuka”.

  • Label text
Condition
A toast just appeared
A toast just appeared

Check if a toast just appeared on screen. This is true for one frame only: use it with the action “Play a sound” to play a sound with every toast.

Text expression
Achievement shown in the toast
Achievements::ToastAchievement()

The identifier of the achievement shown in the toast (empty when no toast is shown).

Action
Show the toast of an achievement
Show the toast of achievement Achievement identifier

Show the toast of an achievement without unlocking it. Useful to preview the toast's look.

  • Achievement identifier (for example: "first_coin") text

Example and Source

Download the example project (open Achievements Example.json in GDevelop). The source, tests and issue tracker are on GitHub.