Achievements

Achievements are goals that unlock exactly once, when a counter the game keeps reaches a target or a group of other goals is done. Counters only go up. A pop-up tells the player, one at a time. When too many unlock together, the rest fold into one pop-up, and no unlock is ever lost.

Also called: Trophies, Badges, Milestones, Unlockable goals.

A fennec-like pilot in goggles cheers on a floating launch pad as a golden leaf-shaped medal leaps from a glowing counter tube, while a row of picture plaques waits in a stack at the edge of the sky. — Zephyrcrumb Skyport, an invented retro cloud-pilot game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Achievements" to my game.

What it should do: Achievements give the player extra goals beside the main one and a reason to try things the story never asks for. The pop-up makes a small win feel seen, and the list of goals shows what is still left to do.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> quiet
  quiet: Quiet
  showing: Pop-up showing
  backlog: Pop-ups waiting
  complete: All done
  quiet --> showing: a goal unlocks
  quiet --> backlog: several unlock at once
  showing --> backlog: another unlocks
  showing --> quiet: pop-up ends
  showing --> complete: last pop-up ends
  backlog --> showing: pop-up ends, next shows
  complete --> [*]
```

Use these starting values:
- toastTime: 3 s
- queueLimit: 5 items

Watch out for these common mistakes:
- It unlocks every time the goal is true: Tell your AI: only unlock goals that are not in the unlocked list yet, and add a goal to the list in the same step.
- A negative or broken count takes progress away: Tell your AI: counters only go up. Ignore any count that is zero, below zero, or not a real number.
- An old save floods the screen: Tell your AI: when the game loads, check all goals once, show a few pop-ups, and fold the rest into one 'and more' pop-up.
- A dropped pop-up loses the unlock: Tell your AI: the list of unlocked goals is the truth. Write it first and treat the pop-up as decoration that may be left out.
- A secret goal shows its progress: Tell your AI: for a hidden goal that is still locked, send no counter value, no target and no progress to the screen.
- A best-of counter is added up: Tell your AI: say for each counter whether it adds up or keeps the best value, and keep the higher one for best-of counters.
- A goal with a target of zero or less: Tell your AI: a goal with a target of zero or less counts as already met, and its progress is shown as full.
- A collect-them-all goal names a goal that does not exist: Tell your AI: when the game starts, check that every goal named in a collect-them-all goal exists, and report any that does not.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

Achievements give the player extra goals beside the main one and a reason to try things the story never asks for. The pop-up makes a small win feel seen, and the list of goals shows what is still left to do.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Quiet → Pop-up showing: a goal unlocks
Quiet → Pop-ups waiting: several unlock at once
Pop-up showing → Pop-ups waiting: another unlocks
Pop-up showing → Quiet: pop-up ends
Pop-up showing → All done: last pop-up ends
Pop-ups waiting → Pop-up showing: pop-up ends, next shows

Good starting values

Value	Start with	What it changes
toastTime	3 s	How long each pop-up stays on screen. Under a second is too quick to read, and over five the screen fills with old news.
queueLimit	5 items	How many pop-ups may wait behind the one on screen. More than this fold into a single 'and more' pop-up. Five is about the most a player will sit through before losing patience.

What usually goes wrong

It unlocks every time the goal is true

The check runs after every jump, and each time the counter is above the target the achievement unlocks again. The pop-up appears over and over.

Fix: Tell your AI: only unlock goals that are not in the unlocked list yet, and add a goal to the list in the same step.

A negative or broken count takes progress away

A bug or a refund sends a count of minus four, or a number that is not a number. The counter drops, or turns into nothing, and the goal can never be reached.

Fix: Tell your AI: counters only go up. Ignore any count that is zero, below zero, or not a real number.

An old save floods the screen

A new version adds twenty goals, the player's old save already meets most of them, and twenty pop-ups roll across the screen one after another.

Fix: Tell your AI: when the game loads, check all goals once, show a few pop-ups, and fold the rest into one 'and more' pop-up.

A dropped pop-up loses the unlock

The line is full, so the game throws the new pop-up away, and the achievement with it. It never shows up in the list.

Fix: Tell your AI: the list of unlocked goals is the truth. Write it first and treat the pop-up as decoration that may be left out.

A secret goal shows its progress

A hidden goal is drawn as a question mark, but its progress bar still fills. The player can read off what it is about from the numbers.

Fix: Tell your AI: for a hidden goal that is still locked, send no counter value, no target and no progress to the screen.

A best-of counter is added up

A counter for the longest combo is added to each time instead of keeping the highest. Two combos of 3 add up to 6 and unlock a goal that needs 5.

Fix: Tell your AI: say for each counter whether it adds up or keeps the best value, and keep the higher one for best-of counters.

A goal with a target of zero or less

A goal asks for zero of something. The progress bar divides by zero and shows nothing, or the goal never unlocks.

Fix: Tell your AI: a goal with a target of zero or less counts as already met, and its progress is shown as full.

A collect-them-all goal names a goal that does not exist

A goal that waits for 'all the others' includes a misspelled name. It sits at 4 of 5 for ever and the player cannot finish the list.

Fix: Tell your AI: when the game starts, check that every goal named in a collect-them-all goal exists, and report any that does not.

How to check it works

A new game with a goal for 1 jump. the player jumps three times: the goal unlocks on the first jump and is in the list exactly once.
A goal for 100 jumps, and the player has jumped 99 times. the player jumps once more: the goal unlocks at exactly 100.
A coin counter that adds up and a combo counter that keeps the best. the player collects 30 and 20 coins, and makes combos of 4, 3 and 6: the coins read 50 and the combo reads 6.
A counter at 40. the game sends minus 5, zero, or a number that is not a number: the counter stays at 40 and the game notes that nothing changed.
A new game with goals for 1 jump and for 100 jumps. the player's count jumps straight to 100: both unlock, the first pop-up is on screen and the second waits in line.
A pop-up is on screen for 3 seconds and another is waiting. 2.9 seconds pass, then 0.1 more, then 3 more: the first stays, the second takes over with its full 3 seconds, and then the screen is clear.
A line that holds only 1 and a save that meets five goals at once. the game checks the goals: all five unlock, two pop-ups come as they are, and the other three come folded into one 'and more' pop-up.
A collect-them-all goal that waits for four others, and three of them are done. the player finishes the fourth: the fourth and the collect-them-all goal unlock in the same moment.
A hidden goal that needs a combo of 5, and the player has made one of 3. the achievements screen is drawn: it shows a mystery with no number and no target, and shows the real goal once it unlocks.
A goal for 100 jumps. the player has jumped 25 times, and in another game 250 times: the screen shows 25 of 100 and a quarter full, and 100 of 100 and full.
A loaded save with 500 coins and a goal for 500 coins that is not unlocked yet. the game checks all goals: the goal unlocks and its pop-up appears.
A counter name that no goal and no counter list knows. the game records it: nothing changes.

Works well with

Combo System: A longest-combo goal wants a counter that keeps the best, not one that adds up. Record the value when a combo ends, not on every hit. Update the combo first, then record its best value as a counter.
Currency Wallet: A goal for 500 coins collected should not go away when the player spends the coins. Keep a separate counter that only goes up, next to the wallet balance. Count coins when they are earned, not when the wallet changes.

Common questions

how do i add achievements to my game

Keep a few counters that only go up, such as jumps or coins collected. Give each achievement a counter and a target, and unlock it once when the counter reaches the target. Tell your AI to keep a list of what is unlocked, so nothing unlocks twice.

why does my achievement pop up again and again

The game checks the goal after every action and does not remember that it already unlocked. Keep a list of unlocked achievements and skip anything on it.

what should happen when many achievements unlock at once

Show them one at a time for about three seconds each. If more than five are waiting, fold the rest into one pop-up that says how many more there were. They all still unlock, only the pop-up is shortened.

what do i tell my ai to make an achievement system

Paste this: Add achievements. Keep counters that only go up, ignore zero, negative or broken counts, and keep the highest value for best-of counters. Each achievement unlocks once at its target, and one can wait for a group of others. Show pop-ups one at a time for about three seconds, and fold more than five waiting into one summary without losing any unlock.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

24 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it