Skip to content

Achievements Overview

Upcoming SDK release

Achievements ship in an upcoming Scorbit SDK release. This section documents that release ahead of time, so details may still change before it ships.

Achievements are badges a player earns by playing. They are authored by creators in the Scorbit Creator Portal and delivered to your machine automatically. Your game code does not decide when an achievement is earned. It reports what is happening in the game, exactly as it already does for scores and modes, and the SDK evaluates every achievement for every claimed player on each commit().

What your game is responsible for:

  1. Feeding facts. Scores, balls, players, modes, completed modes and event counters, then commit(). See Feeding Achievements.
  2. Presenting results. Handling the AchievementUpdated event to celebrate an unlock, and withdrawing one the server refuses. See Definitions, Progress and Events.
  3. Optionally, drawing achievement lists, in attract mode or between balls, and claimed players' progress during a game. See Displaying Achievements.

Who Decides What

Achievements are evaluated in two places, and they work together rather than as alternatives.

The machine (SDK) The Scorbit server
Decides Every achievement it can measure from this game: all single-game achievements, lifetime achievements whose rules it can measure, and chains whose prerequisites it holds Trophies, cross-title chains, and anything only the completed game log reveals
When Immediately, on the commit() where the rules become true After the claim arrives, or after the game ends
Authority Proposes. Its verdict travels with a report to the server Adjudicates every claim and owns the player's profile

The server is not required to redo the machine's working. It checks that the achievement is published, that its scope allows it here, and that the player is claimed on this game. That is why the machine can celebrate an unlock as soon as it decides it. After the game, the server may also grant achievements the machine missed or never reported. It never takes back a granted achievement, except when a trophy passes to another player.

Key Concepts

The key

Every achievement has an immutable key such as game-cv-boom-balloon. Keys never change once created, so they are safe to store and compare. Game code refers to achievements only by key.

Keys are unique across every achievement, including archived ones. An archived achievement can't be republished, so re-creating it means a new achievement with a new key.

Evaluation class

Every achievement measures its rules over exactly one window:

Class Window
In-session The current game only. Every counter starts at zero when the game starts.
Unlimited Every game the player has played on this title (or venue, or event), including the one in progress, for life.

"Ten multiballs in one game" is in-session. "Ten thousand spinner spins" is unlimited: the SDK seeds the count with the player's lifetime total when they claim a slot, and adds the spins made from that point on. This applies whenever they claim, including partway through a game.

Scope

Scope Earned when
Game Playing the title. Tied to the title, not to one cabinet. The common case.
Venue Playing at a specific venue
Event Playing during a specific event or tournament
Global Holding a set of other achievements, usually across titles

Scope is a condition for earning, not just a delivery filter: the server refuses an unlock whose game took place outside the achievement's venue or event.

Permanent achievements and trophies

Most achievements are permanent: once earned, they stay on the player's profile. A trophy is held by exactly one player at a time, such as "highest score at this venue". When a new player takes it, the previous holder loses it. Only the server decides who holds a trophy. The machine never claims or announces one.

Visibility

  • Invisible achievements (visible is false) are ingredients of a chain. Don't list them or celebrate them by name.
  • Obscured achievements are listed, but their name, description and image are hidden behind a placeholder until the player earns them.
  • Archived achievements can no longer be earned, but players who already hold them keep them.

Groups

Related achievements, typically tier ladders such as 100, 1,000 and 10,000 spins, share a group. Members carry a display position (1, 2, 3, ...) for ordering. Groups only affect display, never evaluation.

The Life of an Achievement on a Machine

  1. Definitions arrive. Once the machine is authenticated and paired, the SDK downloads the published achievements for its title and caches them on disk. It revalidates the cache at boot and at the start of every game, so newly published achievements appear without a reboot.
  2. A player claims a slot. The SDK fetches that player's stored progress, so lifetime achievements start from their real totals. Only what happens after the claim counts: a player who claims partway through a game is not credited with anything that happened before they claimed, and a player who never claims a slot earns nothing.
  3. Your game code commits. On every commit() the SDK re-evaluates every achievement for every claimed player. There is no "check achievements" call.
  4. An unlock is decided. The SDK raises AchievementUpdated with status UnlockedLocally. Your game may celebrate it right away.
  5. The server answers. The SDK sends single-game unlocks to the server immediately, and lifetime unlocks with the end-of-ball report. A follow-up AchievementUpdated arrives with Confirmed, AlreadyHeld (the player already had it, so don't celebrate twice) or Retracted (your game withdraws anything it showed).
  6. Progress is reported between balls. For lifetime achievements whose values changed, the SDK reports the player's totals at the end of each ball and at the end of the game, and raises AchievementUpdated with status Progress. There can be many of these at once, one per changed achievement and player, so update displays quietly rather than interrupting play (see Rules for handling unlocks).

Trophies and cross-title chains are decided by the server, not in this flow. The SDK doesn't deliver those decisions to game code, including a player losing a trophy, so don't plan on-machine presentation for them.

Offline play

If the machine cannot reach Scorbit for an entire game, nothing from that game reaches the player's profile: neither the unlocks decided during it nor its lifetime progress. Reports are retried with backoff while the machine is running, so short outages during a game are recovered.

Next Steps