@indiegems/gem-web-sdk 7.9.1 → 8.1.0

package/docs/achievements.md

@@ -49,9 +49,20 @@ one progression, not three progressions.
 
 What the upload enforces, so you are not surprised by it:
 
-- **A budget.** Your game's achievements may be worth at most **1,000 points** in total, and your
-  game may have at most **200 achievements** over its life — both counting ones you have since
-  removed, so retiring an achievement never frees room for another. Points are identity, not
+- **A budget, set by the platform.** The platform limits the points your game's achievements may
+  award in total, how many achievements it may release, how many of them may award an icon and how
+  many distinct icons, how many one upload may declare, and how many items your game may own. It
+  can change any of those numbers, so none is written here: read your game's current limits, and
+  what it has used of each, with `gemctl achievement limits`, or from
+  `GET /v1/games/{game_id}/achievements/limits`. That endpoint answers an open map,
+  `{ game_id, limits: { <name>: { limit, used?, description } } }` — show every limit it returns,
+  not only the names you know, and read `description` for what each bounds. `used` can exceed
+  `limit` when the platform lowers one: nothing released is taken back, and nothing new fits until
+  usage is under it again. The budgets on points, achievements and icons are **lifetime**: they
+  count every achievement your game has put on the `release` channel, including ones you have since
+  removed, so retiring an achievement never frees room for another, and a config on `dev` or `test`
+  uses nothing. The item limit counts the items your game has now, and deleting a `failed` one frees
+  its slot. Points are identity, not
   currency — a player cannot spend them, and a game cannot mint them freely.
 - **Nothing in your config may put value into its progression.** An achievement that awards
   points or rewards may not sit on a progression that a recipe's cost or grant, a loot-table
@@ -73,10 +84,66 @@ What the upload enforces, so you are not surprised by it:
 
 - **Released achievements are fixed.** Once a release carries an achievement, its `points`,
   `rewards`, `visibility` and _where it sits_ — which progression, which level, and that threshold —
-  cannot change. Its copy can. Removing it retires it: players who hold it keep it, and its points
-  still count against your budget.
+  cannot change. Its copy can. Removing it retires it: players who hold it keep it, and it still
+  counts against every budget.
 - **The text is screened.** Copy that impersonates the platform or its staff is refused, and the
   refusal names the rule it broke.
+- **`icon_url` is refused.** The platform does not host list art for achievements, so leave the
+  field out. An achievement awards an icon through `rewards`, below.
+
+### Awarding items (rewards)
+
+An achievement can award items when it unlocks, listed in its `rewards` by slug. These are platform
+items the player wears across the arcade, not your game's currency or inventory — those belong in
+the threshold's own payout — a level's `rewards` or the progression's `rewards_on_complete` — which
+is a different list (§3). Each `rewards[].item` names exactly one of:
+
+- **One of your game's own items, whose art is `ready`.** Usually an avatar icon: the player earns
+  it in your game and can wear it anywhere on the arcade, as their portrait or as one of their
+  badges. You upload it with `gemctl item upload`; it is never written in the config file. A game
+  item can also be a text-only title — gemctl does not create one, but one your game already has
+  (see `gemctl item list`) is named the same way.
+- **A platform name-style preset open to games** — a name colour (`preset-color-…`) or a name
+  animation (`preset-anim-…`). The platform owns these, so there is nothing to upload.
+
+The workflow for art of your own is **upload it → wait until it is `ready` → name its slug in
+`rewards` → upload and promote the config**:
+
+```bash
+gemctl achievement limits    # the item and icon limits, and what this game has used
+gemctl item upload icon.png --slug first-clear --name "First Clear"   # waits until ready
+gemctl config upload --wait  # the config that names first-clear in rewards
+```
+
+```yaml
+- achievement:
+    id: 91ac…
+    points: 20
+    display_name: Getting the Hang of It
+    description: Clear 10 boards.
+    rewards:
+      - item: first-clear # your game's own icon, uploaded above
+      - item: preset-color-ember # a platform name colour
+```
+
+- **What the upload refuses in `rewards`:** a slug that names no item your game may award — another
+  game's item and every platform item not open to games answer the same way, as unknown — one of
+  your own items still `processing`, `failed` or taken down, and the same slug twice. How many items
+  one achievement may award is in `gemctl config schema`.
+- **`preset-` is reserved.** Your own items can never take a slug starting with it — the platform
+  and `gemctl item upload` refuse one — so a slug can never name both your item and a preset.
+- **Rewards are fixed at release.** The slugs are resolved to items when the achievement first
+  reaches `release`, and its `rewards` cannot change afterwards. A later rename, takedown or new
+  preset never changes what it awards.
+- **Icons count against the icon budgets** — how many achievements may award an icon, and how many
+  distinct icons your game may award — and every item you upload counts against your game's item
+  limit, a `failed` one until you delete it. Titles and name styles cost nothing against the icon
+  budgets. `gemctl achievement limits` reports each limit and what your game has used.
+- **A hidden achievement withholds its rewards**, like its name and description, until the player
+  unlocks it.
+
+The image rules, who may upload and what to do about a `failed` item are in the gemctl `game-config`
+skill.
 
 ## 2. Who unlocks it