Define an achievement
define_achievementCreate or update a game achievement by slug, defining its name, description, points, and badge. Idempotent on game and slug, so re-running a publish script never resets player unlocks.
Instructions
Adds one achievement to a game you own, or overwrites the one that already has this slug. Achievements are maker data: only the owner defines them, and the game itself can never mint one — a build calls Arcade.achievements.unlock("<slug>") and we refuse any slug that is not already defined here. This tool is idempotent on (game, slug), so a publish script can run twice without making a mess, and re-declaring a badge never resets how many players have earned it. Use define_achievements when you are declaring a whole set at once. Max 100 per game.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| game | Yes | The game, by slug (e.g. "orbital-drift") or by id (uuid). | |
| name | Yes | What players see on the badge, up to 60 characters. Name the deed, not the mechanic: "Untouchable" beats "damage_taken == 0". | |
| slug | Yes | The stable key your game code passes to Arcade.achievements.unlock(). Lowercase letters, digits and hyphens, up to 48 characters — e.g. "first-win", "no-damage-run". Pick it once and keep it: renaming the name or description never breaks a shipped build, changing the slug breaks every call site in it. | |
| emoji | No | One emoji, drawn as the badge face. Defaults to 🏆. | 🏆 |
| hidden | No | Secret until earned. A hidden achievement still shows on the game page as a locked mystery tile with its rarity count, but its name and description are redacted server-side until that player unlocks it. Use it for endings and easter eggs, not for everything. | |
| points | No | Weight, 0-100, defaults to 10. Spend it like a budget: a whole game worth 10 achievements at 10 points each says everything is equally hard, which is never true. | |
| iconUrl | No | https:// URL of a custom badge image, used instead of the emoji. Optional. | |
| sortOrder | No | Display position, ascending. Ties fall back to slug order. | |
| description | No | How it is earned, in one plain-text line, up to 240 characters. No markdown. For a hidden achievement this is only revealed once a player unlocks it. |