Achievement Rules¶

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.

Creators author achievements in the Creator Portal; game code never defines them. You still need to understand rules, because they decide which names and calls in your game an achievement can observe, and they explain the values you see when you read a player's progress.

An achievement holds one or more rules. All of them must be true at the same time: rules combine with AND, and there is no OR. Each rule has four fields:

Field	Meaning
`type`	What is measured: one of the twelve types below
`comparison`	`EQ` (=), `LE` (≤), `GE` (≥) or `NE` (≠). All inclusive.
`target`	A signed 64-bit integer
`reference`	The mode name, event name, list of modes or prerequisite key the rule refers to; empty for types that don't need one

The Twelve Rule Types¶

Type	Measures	`reference`	Family
`MODE`	Times the mode was activated	Mode name	Accumulator
`MODE_COMPLETED`	Times the mode was completed (`set_mode_completed`)	Mode name	Accumulator
`MODE_STACK`	Times the listed modes were active together	Two or more mode names, comma-separated	Accumulator
`EVENT`	The value of an event counter (`add_event`)	Event name	Accumulator
`SESSION`	Games played. The game in progress counts, so a player's first game is 1. Lifetime achievements only.	Empty	Accumulator
`ACHIEVEMENT`	Whether another achievement is held	Prerequisite key	Accumulator
`SCORE`	The player's score	Empty	Observation
`TIMER_SESSION`	Milliseconds the player spent at the machine in one game (their own turns only)	Empty	Observation
`TIMER_BALL`	Milliseconds one ball lasted	Empty	Observation
`TIMER_MODE`	Milliseconds one activation of the mode lasted	Mode name	Observation
`TIMER_BETWEEN`	Milliseconds needed to bring the other rules' facts together, within one ball	Empty	Observation (qualifier)
`BALL`	The ball number on which the other rules' facts happened	Empty	Observation (qualifier)

Mode and event references are compared byte-for-byte with the names your game reports, including any prefix such as MB: (see Mode Names Must Match Exactly).

Accumulators and observations¶

An accumulator resolves to one number counted over the window, such as the number of times a mode started or an event counter's total. The comparison is applied to that number.
An observation resolves to every value seen in the window, such as each ball's duration. It is satisfied when any one observed value satisfies the comparison. In a single-game achievement SCORE observes every score the player reached during the game. In a lifetime achievement it observes each previous game's final score plus the current score of the game in progress, so a lifetime score achievement can unlock mid-game.

Never happened means zero¶

A rule whose fact never occurred resolves to 0. A mode the player never started has an activation count of 0 and an activation duration of 0. This is why creators must pair "at most" and "not equal" rules with a rule requiring that the thing happened (see Constraints Creators Must Follow).

Qualifiers: `BALL` and `TIMER_BETWEEN`¶

These two rules measure nothing on their own. They constrain when the achievement's other rules had to happen, and they can only qualify facts that happen at a specific instant: MODE, MODE_COMPLETED, MODE_STACK and EVENT.

BALL limits the other facts to particular balls. MODE GE 1 "MB:Multiball" with BALL EQ 1 means "start a multiball on ball one".
TIMER_BETWEEN is the shortest span, inside one ball, containing an occurrence of every other rule's fact, in any order. With one other rule it is the gap between two consecutive occurrences: "two multiballs within thirty seconds".

TIMER_BALL, TIMER_MODE, TIMER_BETWEEN and BALL are confined to a single ball: facts on different balls never combine for them. Counting rules such as MODE and EVENT count across the whole window.

Chains: `ACHIEVEMENT` Rules¶

An ACHIEVEMENT rule requires another achievement, named by key. Chains let creators combine conditions from different titles (a global achievement) or different windows (one single-game ingredient and one lifetime ingredient). Ingredients are usually invisible, so only the final step appears in a player's list.

Chains are yes/no. A rule asks whether the prerequisite is held, never how many times.
The machine decides a chain only when it holds a definition for every prerequisite, which in practice means same-title chains. Cross-title chains are decided by the server and are not delivered to game code as events.
An archived prerequisite counts as held for everyone, so archiving one achievement never strands the achievements built on it. The machine leaves those to the server.

Constraints Creators Must Follow¶

The Creator Portal and the server refuse to publish an achievement that breaks any of these. They are listed here so you know what a delivered definition can and can't contain.

Not satisfiable by doing nothing. If every rule is true when nothing happened (all values 0), the achievement can't be published.
"At most" and "not equal" rules are paired. An LE or NE rule needs a GE 1 rule on the same mode, event or achievement, so that it can't pass for a player who never triggered it. Qualifiers are covered by their sibling rules.
MODE_STACK names at least two modes.
Qualifiers have siblings. BALL and TIMER_BETWEEN need at least one other rule, and every other rule must be MODE, MODE_COMPLETED, MODE_STACK or EVENT.
Lifetime-only rules. An achievement with a SESSION or ACHIEVEMENT rule must be lifetime (unlimited).
Global achievements are lifetime, and contain only ACHIEVEMENT rules.
Trophies are lifetime, and their first SCORE or timer rule (GE or LE) is the metric players are ranked by.
Rules are frozen once published. Rules are never added, removed or reordered after publishing, so a rule's index is stable for the life of the achievement. Changing what an achievement requires means a new achievement with a new key. A rule's target or comparison may still be adjusted in place, so don't hard-code targets; read them from the definitions.

Worked Examples¶

Billionaire: score over one billion, ever.

lifetime   SCORE GE 1000000000

Grand Finale: complete the wizard mode in one game.

single-game   MODE_COMPLETED GE 1 "WM:Grand Finale"

Marathon Multiball: keep one multiball running for sixty seconds.

single-game   TIMER_MODE GE 60000 "MB:Multiball"

Double Trouble: two multiballs within thirty seconds of each other.

single-game   MODE          GE 2 "MB:Multiball"
              TIMER_BETWEEN LE 30000

Ball One Hero: start a multiball on the first ball.

single-game   MODE GE 1 "MB:Multiball"
              BALL EQ 1

Quick Quest: play a quest that ends within a minute, in a game lasting over three minutes.

single-game   MODE          GE 1      "NA:Gem X"
              TIMER_MODE    LE 60000  "NA:Gem X"
              TIMER_SESSION GE 180000

The first rule is what makes this valid: without it, a long game in which the quest never started would pass, because a quest that never ran measures 0 ms. The quest only has to end quickly, not be won. MODE_COMPLETED GE 1 instead of MODE would not change that: TIMER_MODE is satisfied by any one activation, so a quick failed attempt plus a slow win would still pass.

Centurion: play one hundred games on this title.

lifetime   SESSION GE 100

Spinner Master: ten thousand spins, for life. Game code calls add_event("spins", n).

lifetime   EVENT GE 10000 "spins"

Stack Attack: multiball and wizard running together, three times in one game.

single-game   MODE_STACK GE 3 "MB:Multiball,WM:Grand Finale"

Known issue in the pre-release SDK

TIMER_BALL, TIMER_MODE and TIMER_SESSION durations are currently measured while still in progress, not only once they end. LE and NE rules can therefore be satisfied as soon as the ball, mode or game starts, and EQ rules as the running duration passes the target. Avoid relying on "at most", "exactly" or "not" timer achievements until this is fixed.