@indiegems/gem-web-sdk 23.3.0 → 24.0.1

package/docs/inventory-and-catalogs.md

@@ -141,7 +141,7 @@ gem.me.inventory.onChanged(async () => {
 
 It is a cue to re-read, not a receipt, and it arrives a moment after the change commits. It is
 only ever about **this** game, on the channel you are playing: the Arcade never relays another
-game's changes or the platform wallet's (Gems and Coins have their own hint,
+game's changes or the platform wallet's (Coins have their own hint,
 `gem.platform.earnAllowance.on('changed')`). A burst — a function granting in a loop — reaches
 you as one call now and at most one more every two seconds, and the hint itself makes no request.
 
@@ -334,6 +334,77 @@ fails. The platform checks prerequisites **before it charges anything**: a recip
 currency (§16) that the player is locked out of is refused with the code `recipe_locked`, and no
 currency moves.
 
+### Requirements: `requires`
+
+New config states what a player must hold or have done with one vocabulary, `requires`: a list
+of requirements that must **all** hold. Items, recipes and progression tracks may carry one, and so
+may each bonus (below).
+
+| `kind`                 | Holds when the player…                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| `holds_pass`           | holds the pass `pass` now, e.g. `{ kind: 'holds_pass', pass: 'vip' }`               |
+| `owns_platform_item`   | owns the platform item `item_definition_id`; only one this game grants or sells      |
+| `owns_item`            | holds at least `min` of the game item `item_definition_id`                           |
+| `has_currency`         | holds at least `min` of the **game** currency `currency_id`; a platform currency is refused |
+| `progression_complete` | has completed the progression `progression_definition_id`                            |
+| `progression_level`    | is at or above `min` on the progression `progression_definition_id`: its track level, or its value when it has no tracks |
+
+- **The platform judges it, when the recipe runs.** Not the browser: a requirement is the one place
+  a gate on a pass is enforced.
+- **A refusal or a receipt names an unmet requirement by its index and kind**, never by the pass or
+  item it names.
+- **The older shapes still work.** A recipe's `prerequisites`, a loot entry's exclusion conditions
+  and a track's `requires_item_id` are read as they always were; `gemctl` warns on `prerequisites`
+  in a new upload. Write `requires` in new config.
+
+### Bonuses: more for a player who meets a requirement
+
+A recipe or a loot table may carry `bonuses`: extra grants for a player who meets each bonus's own
+`requires`. VIP is just `holds_pass: vip`; owning a charm, or reaching a level, works the same way.
+
+```jsonc
+// a recipe
+{
+  "id": "open_chest",
+  "costs": [{ "type": "item_remove", "item_definition_id": "<chest_key>", "quantity": 1 }],
+  "loot_table_id": "<chest_common>",
+  "bonuses": [
+    {
+      "id": "vip_roll",
+      "requires": [{ "kind": "holds_pass", "pass": "vip" }],
+      "grants": [{ "type": "roll", "loot_table_id": "<chest_common>", "count": 1 }]
+    },
+    {
+      "id": "lucky_charm",
+      "requires": [{ "kind": "owns_item", "item_definition_id": "<lucky_charm>", "min": 1 }],
+      "grants": [{ "type": "item_grant", "item_definition_id": "<rare_shard>", "quantity": 1, "account_bound": true }]
+    }
+  ]
+}
+```
+
+- **A bonus never fails the base.** The recipe runs exactly as it would without bonuses; each bonus
+  is then judged on the player's state from before the recipe ran, applied or skipped on its own,
+  and a skipped bonus changes nothing else. The order's `changes` carry one `bonus` entry per
+  bonus: `{ bonus_id, outcome: 'applied' | 'skipped', reason?, unmet: [{ index, kind }] }`, so the
+  game can say "VIP bonus: +1 roll".
+- **What a bonus may grant:** game items, game currencies, and `roll`, which rolls a loot table
+  `count` times. Never a platform currency, and never a write to a progression.
+- **A loot table's bonuses grant extra rolls only**, never extra entries, so the base roll's odds
+  never move. A `roll`'s table may not carry bonuses of its own: one level deep.
+- **Limits:** at most 8 bonuses on a recipe or a table, and 10 rolls per bonus. A bonus that grants
+  what a bonus requires is refused, and a VIP bonus that grants a transferable item is warned about:
+  mark it `account_bound`.
+- **Rolls are their own.** Each bonus rolls from its own random stream, after every base draw, and
+  never reads or moves pity, so adding, removing or skipping a bonus never changes the base's
+  outcome or another bonus's.
+- **The platform holds nothing.** A bonus is judged when the recipe runs and never later: there is
+  no pending or missed bonus and no voucher. To sell VIP at that moment, offer it **before** the
+  recipe runs ([the upsell](#offering-vip-before-a-reward-the-upsell)).
+- **A paid roll is gated.** On a recipe priced in Coins, a bonus that rolls is skipped with
+  `paid_chance_restricted` for a known minor and in restricted regions; the base of a free recipe is
+  never affected.
+
 ## 10. Orders — the record that something happened
 
 Every change to a player's holdings produces an **order**. Order history is read-only and answers
@@ -410,6 +481,12 @@ because the config does not re-poll — `gem.gameConfig.refresh()` is the only t
 it. Show this number as a "base chance," or not as a number at
 all. The only authority on what a player actually receives is the result of executing the recipe.
 
+**Show the odds before a player pays for a roll.** A recipe priced in Coins that rolls a table, or
+carries a bonus that rolls one, is a paid random item: the arcade's purchase sheet shows the odds
+from the published weights before the player pays, and your shop and any upsell show them too. The
+platform refuses a paid roll with `paid_chance_restricted` for a known minor and in restricted
+regions (a bonus roll is skipped instead), so hide such an offer rather than drawing a dead button.
+
 ## 13. Progressions
 
 A **progression** is a track a player advances along — a battle pass, a level, a mastery. You read
@@ -469,7 +546,7 @@ is `gemctl platform config`'s answer.
 so this page does not list them. Name one that is not permitted and the config upload is refused
 with an error that enumerates the ones that are.
 
-Gems can be your game's soft currency, awarded through a mapping. A game currency of your own suits
+Coins can be your game's soft currency, awarded through a mapping. A game currency of your own suits
 what lives inside one play loop — gold picked up and spent within a run, energy, crafting
 materials: you control it completely, no other game can spend it, and none of the constraints below
 apply to it.
@@ -496,7 +573,7 @@ What that means for game code:
   happens to add to the source.
 - **The channel does not change where a grant lands.** A mapping fires on `dev`, `test` and
   `release` alike, into the player's real platform balance, against the real per-game cap — so
-  Gems paid while you test are real, and the allowance they spend is not given back.
+  Coins paid while you test are real, and the allowance they spend is not given back.
 - The order your server gets back carries one `platform_grant` entry in `changes` per mapping:
   `fired`, `clamped` (and which ceiling bit — the per-firing ceiling, the platform's per-game
   ceiling or its daily maximum across all games, or the player's holdings cap), or `suppressed`
@@ -526,13 +603,66 @@ What that means for game code:
   hold** — within a window it only rises, resetting or lowering the source progression never takes
   it back, and a player spending a granted currency does not refill your game's allowance.
 
+### Showing a payout before and after: `preview` and `fromReceipt`
+
+**These two are the only way to show a platform payout.** Never multiply by `gem.player.boost`, and
+never copy a config amount into your game's code: the platform retunes amounts and multipliers
+without a release of your game, and both go stale the moment it does. The release review flags
+hand-written multiplier code.
+
+Before the claim, give the preview a **config id** — never an amount, never a pass:
+
+```js
+const preview = await gem.gameConfig.preview({ recipe: 'open_chest' });
+// or { progression: 'run_complete' }            — an `on_complete` mapping
+// or { progression: 'puzzles_cleared', add: 3 } — an `on_add` mapping, with the delta you will apply
+
+for (const p of preview.platformGrants) {
+  // { currencySlug: 'ARCADE_TICKETS', base: 30, total: 45,
+  //   breakdown: [{ source: 'pass', pass: 'vip', amount: 15 }], ifComplete?: true }
+  rewardRow.show(p.total, p.breakdown.map((b) => (b.source === 'pass' ? 'VIP' : 'Boost')));
+}
+for (const b of preview.bonuses) {
+  // { id, grants, eligible: true | false | 'unknown', unmet: [{ index, kind }] }
+}
+```
+
+- **`grants`**: the items and game currencies the recipe gives, and `{ kind: 'roll', lootTableId,
+  count }` for each roll — "1 roll from Common Chest", never what it will land on.
+- **`platformGrants`**: each `platform_grants` mapping that fires, with `base` (no pass, no Boost),
+  `total` (this player) and the `breakdown` of the difference. `ifComplete: true` marks an
+  `on_complete` payout: it pays only if this claim completes the progression.
+- **`bonuses`**: each bonus with `eligible` `true`, `false` or `'unknown'` — unknown when the SDK
+  cannot see what the requirement names. Draw unknown as neither won nor lost.
+- **`upsells`**: what each pass on sale here would add. Empty means show no upsell
+  ([below](#offering-vip-before-a-reward-the-upsell)).
+- **It is advisory.** The run decides: state can change between the preview and the claim, and the
+  platform's daily limits are not in it, because they are private.
+- **Browser only.** It rejects a `PreviewError` with `not_found` for an id the config does not have,
+  `invalid_argument` for a target that is not one of the three shapes, and `unsupported` outside a
+  browser game.
+
+After the claim, the order's `platform_grant` change is the receipt. `gem.earnings.fromReceipt`
+turns it into the same shape, so one component draws "you will earn" and "you earned":
+
+```js
+for (const change of order.changes) {
+  const paid = await gem.earnings.fromReceipt(change); // null for any other kind of change
+  if (paid) rewardRow.show(paid.total, paid.breakdown);
+}
+```
+
+`base` there is what a player with no pass and no Boost would have got under the same limits, so
+the breakdown is exact even when a limit trimmed the payout. A function's `gem.earnings` and a
+dedicated server's `gem.earnings` read receipts the same way.
+
 ### Achievements: the other kind of platform grant
 
 A `platform_grants` entry can also be an **achievement** — a platform-wide recognition with points,
 on the progression's completion or on one level of a track, that unlocks once per player when your
 server, or a serverless function that player called, moves the progression past it. Everything
 above about server-only writes applies — an achievement that awards points or rewards may not sit
-on a progression any operation in your config can raise, so a recipe priced in Gems can never sell
+on a progression any operation in your config can raise, so a recipe priced in Coins can never sell
 one — and more: an achievement unlocks only on `release`, it never re-fires, and what it credits is
 fixed once released. Its points are never boosted. [achievements.md](achievements.md) is the whole of it.
 
@@ -581,9 +711,10 @@ nobody else can touch them. The arcade also has currencies that span every game,
 
 That changes what a shop can be. A player earns in someone else's game and spends in yours.
 
-There are two such currencies, and they are not interchangeable: **Gems** (`GEMS`) buy progress and
-**Coins** (`ARCADE_TICKETS`) buy cosmetics, and play items too where Coins' spend scope allows.
-[arcade-economy.md](arcade-economy.md) says which to use for what.
+That currency is **Coins** (`ARCADE_TICKETS`): play earns them, the Arcade sells them, and games
+price in them. **Gems are retiring** — reprice any `GEMS` price in Coins at 5 Coins per Gem and move
+any Gem grant to Coins; [arcade-economy.md](arcade-economy.md) has the date's consequences and the
+rest of the rules.
 
 ### Awarding one
 
@@ -613,13 +744,12 @@ A browser-only game cannot award a platform currency without a server **or a ser
 That is the price of the platform never trusting a client. A game with no dedicated server writes
 the source progression from a function the player calls, on a progression that opts in with
 `function_may_grant`, and the platform then pays that player only, in any listed platform currency
-— Gems (`GEMS`) and Coins (`ARCADE_TICKETS`) alike
+— Coins (`ARCADE_TICKETS`)
 ([serverless-functions.md](serverless-functions.md#paying-the-player-who-called)).
 
 ### Showing the reward land in the arcade's wallet
 
-**Platform-currency display belongs to the arcade** (the creator's ruling, 2026-09-24) — Gems and
-Coins alike. The arcade shows the player's platform currencies in its own chrome — in the Gem
+**Platform-currency display belongs to the arcade** (the creator's ruling, 2026-09-24). The arcade shows the player's platform currencies in its own chrome — in the Gem
 Arcade, the Gem menu the player opens from the Gem button over your frame; no wallet
 is drawn over your game — and moves a total when the platform confirms a grant. Your game keeps no counter or balance
 of a platform currency of its own, draws no flight or celebration of its own, and shows no
@@ -627,20 +757,19 @@ platform-currency amount at all when it is not connected to the arcade.
 
 What your game does is ask for the payout to start on **your** screen, from the currency's icon (or
 hero) beside the reward, so the currency flies from there into the arcade — in the Gem Arcade,
-into the Gem button, which pops as each mark lands. A Gems payout is cued from the gem:
+into the Gem button, which pops as each mark lands. A Coins payout is cued from the coin:
 
 ```js
-const { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem element's own box
+const { x, y, width, height } = rewardCoin.getBoundingClientRect(); // the coin element's own box
 gem.cueReward({
-  currencySlug: 'GEMS',
+  currencySlug: 'ARCADE_TICKETS',
   expected: 15, // if you know it; drawn as provisional until the platform confirms
   origin: { x: x + width / 2, y: y + height / 2 }, // CSS px of your own viewport
 });
 ```
 
-`origin` is the **centre of the gem on screen** — measure the gem element itself, not the row or
-panel around it. A Coins payout is the same call with `currencySlug: 'ARCADE_TICKETS'`, from the
-coin: the slug decides what flies and which total moves. **A payout you do not cue still flies**
+`origin` is the **centre of the coin on screen** — measure the coin element itself, not the row
+or panel around it. The slug decides what flies and which total moves. **A payout you do not cue still flies**
 in the Gem Arcade, from the middle of your frame, once the platform confirms it — cue it so the
 flight starts where the player is looking. **If `cueReward` returns `false`, do nothing**: there is
 no fallback celebration.
@@ -658,10 +787,10 @@ reward once, whichever reaches it first, so you may cue before the call or after
 ```js
 const cueId = crypto.randomUUID(); // one per award, never reused
 const result = await gem.functions.invoke({ claim: 'daily' }, { cueId });
-gem.cueReward({ currencySlug: 'GEMS', expected: 15, origin, cueId });
+gem.cueReward({ currencySlug: 'ARCADE_TICKETS', expected: 45, origin, cueId });
 ```
 
-A payout that pays Gems and Coins in one call cues each currency with the same `cueId`. The id is
+A payout that pays more than one platform currency in one call cues each with the same `cueId`. The id is
 yours and opaque: 1 to 64 letters, digits, `_` or `-`, and the SDK leaves out anything else with a
 console warning rather than fail the cue or the call. It is for the animation only. It moves no
 balance, your function never sees it, and no receipt or order carries it.
@@ -721,14 +850,14 @@ gem.cueReward({ currencySlug: 'ARCADE_TICKETS', expected: 20, origin: claimCoinC
   the bridge is up (held and sent on connect) and under an embedder that presents every payout its
   own way; there, keep cueing as usual and nothing else changes.
 
-To draw the Gem on your own screen, use the platform's art, which ships in the package — the Gems
-**icon** beside an amount or price, the **hero** only on a reward presentation where the gem is the
-subject. [brand-art.md](brand-art.md) has both, how to draw them, and the rest of the rules.
+To draw a Coin on your own screen, use the platform's art, which ships in the package — the Coins
+**icon** beside an amount or price, the **hero** only on a reward presentation where the coin is
+the subject. [brand-art.md](brand-art.md) has both, how to draw them, and the rest of the rules.
 
 ### Being paid in one
 
-**Spend platform currency with `gem.purchases.request`.** Every game sells for Gems, Coins or any
-other platform currency through the arcade's buy sheet: the platform confirms the purchase with the
+**Spend platform currency with `gem.purchases.request`.** Every game sells for Coins, or any
+other platform currency, through the arcade's buy sheet: the platform confirms the purchase with the
 player, offers a guest an account, and processes the order. Build your shop's Buy button on it.
 
 | Call                             | Who owns confirmation | Transport                                                      | Use it for                                                                          |
@@ -754,7 +883,7 @@ const item = config.item('extra-life');
 const res = await gem.purchases.request({
   kind: 'item', // or 'recipe'
   targetId: item.id, // UUID, never the slug
-  currencySlug: 'GEMS',
+  currencySlug: 'ARCADE_TICKETS',
   quantity: 1,
 });
 
@@ -768,11 +897,12 @@ The platform re-fetches the target and price, submits the order with the player'
 and verifies an `ok` before returning it to the game. Whether the player sees a sheet first depends
 on the currency:
 
-- **Gems and other platform currencies:** the arcade opens its purchase sheet, and nothing is spent
-  until the player presses Buy.
+- **Any other platform currency:** the arcade opens its purchase sheet, and nothing is spent until
+  the player presses Buy.
 - **Coins (`ARCADE_TICKETS`) the player can afford:** no sheet. The arcade spends them at once, does
   not pause your game, and says so over it ("Lantern purchased · 180 Coins left"). Coins are earned
-  by playing, never bought, so the arcade does not ask.
+  by playing as well as bought, and a game's Coin spend needs no confirmation: the platform's
+  decision, unchanged since Coins went on sale.
 - **Coins the player cannot afford:** the arcade opens its sheet to say so, and answers `declined`
   with reason `insufficient_funds`.
 
@@ -824,7 +954,7 @@ backend it answers `undefined` by design: there, your placeholder is what you se
 The direct path submits an order from your game with no platform sheet. Its job is recipes paid in
 your own game currency or items (`payment: { kind: 'configured' }`, below). It also accepts a
 `platform_currency` payment, but **do not spend platform currency this way on gemarcade.com**: a
-web guest is refused (below), and every game spends Gems and Coins through
+web guest is refused (below), and every game spends Coins through
 [the sheet](#platform-owned-purchase-sheet). The form is documented for games that have not moved
 yet:
 
@@ -835,7 +965,7 @@ const result = await gem.me.mutations.purchase({
   quantity: 1,
   payment: {
     kind: 'platform_currency',
-    currencySlug: 'GEMS',
+    currencySlug: 'ARCADE_TICKETS',
   },
 });
 
@@ -905,7 +1035,7 @@ Do not retry an unsafe write after a timeout; re-read inventory or use the retur
 ids for support.
 
 **A guest is refused `guest_upgrade_required`, and you draw nothing.** The platform lets only a
-player with an account spend Gems or Coins — which is why platform currency is spent through
+player with an account spend Coins — which is why platform currency is spent through
 [the sheet](#platform-owned-purchase-sheet), where the arcade handles a guest itself. This is the
 safety net for a game that still spends directly. When a guest's direct purchase is refused, the SDK
 hands the attempt to the arcade, which offers the player an account over your game, and your call
@@ -943,7 +1073,7 @@ the same strings.
 
 | Code                                                                                                                  | What happened                                                                          | What to do                                                                       |
 | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `unknown_currency`                                                                                                    | the slug is not an active platform currency                                            | write `ARCADE_TICKETS` or `GEMS`; the direct path's message lists what is active |
+| `unknown_currency`                                                                                                    | the slug is not an active platform currency                                            | write `ARCADE_TICKETS`; the direct path's message lists what is active |
 | `currency_not_in_game_payable`                                                                                        | the currency exists but cannot pay for game items                                      | price in a currency `gemctl platform config` lists under `platform_prices`       |
 | `not_purchasable`                                                                                                     | the target is not in the purchase catalog on this channel, or cannot be bought         | send the id (not the slug); promote the config version that prices it            |
 | `no_price_in_currency`                                                                                                | the target has no price in that currency                                               | ask in the currency it is priced in, or add the price                            |
@@ -964,24 +1094,21 @@ inventory, never on a reason, and do not retry because of one.
 ⚠️ **Never draw a top-up or payment screen of your own** — no checkout, no wallet top-up, nothing
 that looks like the arcade's purchase sheet or wallet. A game screen shaped like platform payment
 chrome is an imitation of it. Your Buy button is yours, and taking a player's money is the
-arcade's alone: a "Get Gems" button of yours calls `gem.store.purchase` from the player's press, a
-"Get VIP" button calls `gem.store.showOffer`, and the arcade store's own checkout does the rest
+arcade's alone: a "Get Coins" button of yours calls `gem.store.purchase` with a Coin pack from the
+player's press, a "Get VIP" button calls `gem.store.showPass('vip')`, and the arcade store's own checkout does the rest
 ([arcade-and-store.md](arcade-and-store.md)). An
 `insufficient_funds` refusal never opens it by itself.
 
-### What Coins and Gems may buy: the spend scope
+### What Coins may buy: the spend scope
 
-The arcade has two currencies a player spends: **Gems**, for progress, and **Coins**
-(`ARCADE_TICKETS`), earned by play, for cosmetics and, since 25 Oct 2026, play items too. What
-each may price is decided by two settings: each platform currency's **spend scope**, which the
-platform sets, and each of your items' **category**, which you set.
+What a platform currency may price is decided by two settings: the currency's **spend scope**, which
+the platform sets, and each of your items' **category**, which you set.
 
-- A currency whose spend scope is **`cosmetic_only`** may price cosmetics only. Coins' is, until
-  the platform moves it to `any` to let Coins price play items.
-- A currency whose spend scope is **`any`** may price anything. Gems' is.
+- A currency whose spend scope is **`any`** may price anything. Coins' is.
+- A currency whose spend scope is **`cosmetic_only`** may price cosmetics only.
 
-The platform owns each currency's scope and can change it, so do not hard-code which is which: a
-refusal always names the scope that applied.
+The platform owns each currency's scope and can change it, so do not hard-code it: a refusal always
+names the scope that applied.
 
 ```yaml
 items:
@@ -990,27 +1117,28 @@ items:
     category: cosmetic # changes only how the player looks
     platform_prices:
       - currency: ARCADE_TICKETS
-        price: 120
+        price: 1500
   - id: '…'
     slug: extra-life
     # category omitted: `progression`, the default
     platform_prices:
-      - currency: GEMS
-        price: 25
+      - currency: ARCADE_TICKETS
+        price: 125
 ```
 
 - **`category`** is `cosmetic` — skins, outfits, visual effects, decorations, emotes, profile
   cosmetics: anything that changes how the player looks and never what they can do — or
   `progression`, anything that affects play. It defaults to `progression`, so an item is only ever a
   cosmetic because you said so.
-- **A price in a `cosmetic_only` currency, such as Coins, is accepted only on a cosmetic.** On an
-  item, that item must be `category: cosmetic` and a plain `item_type: item` — a `bundle` or
-  `loot_box` opens into things its own row does not describe, so it cannot be sold for Coins.
-- **A recipe priced in a `cosmetic_only` currency must grant at least one cosmetic item and nothing
-  else.** It is refused if it grants any currency, moves any progression, grants a non-cosmetic item,
-  or rolls a loot table — a loot table is refused for now even when every entry is cosmetic. Taking
-  from the player as part of the recipe (`currency_consume`, `item_remove`) is fine.
-- **A currency whose scope is `any`, such as Gems, may price anything**, cosmetic or not.
+- **Under a `cosmetic_only` scope, a price is accepted only on a cosmetic.** On an item, that item
+  must be `category: cosmetic` and a plain `item_type: item`; a recipe must grant at least one
+  cosmetic item and nothing else — no currency, no progression, no non-cosmetic item, no loot table.
+  Taking from the player as part of the recipe (`currency_consume`, `item_remove`) is fine.
+- **Under `any`, a price may go on anything**, cosmetic or not.
+- **A paid roll is gated.** A recipe priced in Coins that rolls a loot table, or has a bonus that
+  rolls one, is a paid random item: the arcade's sheet shows the odds before the player pays, and
+  the platform refuses it with `paid_chance_restricted` for a known minor and in restricted regions
+  (§12).
 
 The upload refuses a config that breaks the rule. The refusal names the currency and its scope, and
 the offending item or operation, so you know what to change:
@@ -1025,8 +1153,8 @@ purchase catalog stops listing that currency's price on anything the scope does
 purchase naming such a price is refused `not_purchasable` before anything is charged.
 
 The category is a declaration the platform takes at your word, and the release review checks it.
-Labelling something that affects play `cosmetic` so it can be sold for Coins breaks platform policy,
-whatever the scope: a play item sold for Coins keeps `category: progression`.
+Labelling something that affects play `cosmetic` breaks platform policy, whatever the scope: a play
+item sold for Coins keeps `category: progression`.
 
 **To sell a cosmetic that needs game progress first, sell it through a recipe.** An item's own
 `platform_prices` cannot carry prerequisites; a recipe's can. Grant the cosmetic from a recipe that
@@ -1048,27 +1176,70 @@ catalogs:
             item_definition_slug: dragon-skin
         platform_prices:
           - currency: ARCADE_TICKETS
-            price: 120
+            price: 1500
 ```
 
 A player below level 10 is refused `recipe_locked` before any Coins are taken, and
 `recipeAvailability` tells your shop the recipe is locked and what it needs (§9) — so show the lock
 ("Reach level 10 to unlock") instead of offering the purchase.
 
+### Offering VIP before a reward: the upsell
+
+The platform holds nothing back for later, so a game that wants to sell VIP does it **before** it
+grants: it holds the reward, shows what VIP would add, offers it, then runs the recipe.
+
+```js
+async function openChest() {
+  const preview = await gem.gameConfig.preview({ recipe: 'open_chest' });
+  const upsell = preview.upsells[0]; // empty: no pass on sale here would add anything
+  if (upsell && (await vipCard.ask(upsell)) === 'get') {
+    // The card shows upsell.name and its locked extras: "+1 roll · 45 Coins".
+    const { outcome, reason } = await gem.store.showPass(upsell.pass);
+    if (outcome === 'ok' && reason === 'pending') note('VIP will apply once it is confirmed');
+  }
+  vipCard.focusReturnsTo(openButton);
+  await runRecipe(); // the bonus applies if VIP is now held, and the base runs either way
+}
+```
+
+`showPass` answers `ok` only once a re-read shows the pass held, so a recipe run after it gets the
+bonus the player just paid for. `pending` (Ask to Buy, or a payment not yet settled) means run it
+now without the bonus. `declined` or `unavailable` means run it as it is — and `unavailable` or
+`error` may still mean the player paid, so read `gem.me.passes` again rather than telling them
+they did not.
+
+`upsells` is empty for a minor, a store that is off, a pass the player declined twice today or
+already holds, and anywhere the store sells no pass: draw nothing then. A guest **does** get
+upsells, and buying takes them through sign-up first.
+
+**The rules, every one a must:**
+
+- **Upsell only before granting**, and at most once per reward moment. Never after.
+- **Give Get VIP and Continue equal weight.** Neither is the default, the larger or the brighter.
+- **Never show the outcome of a locked roll.** Show "+1 roll", never what it would land on.
+- **Disclose the odds** for a bonus roll, as for any roll ([§12](#12-loot-tables-and-odds)).
+- **No countdowns, no "expires" pressure, and no price** in your game. The Arcade's sheet shows the
+  price.
+- **Show a lock as an icon plus text**, never colour alone.
+- **Return focus to the button** that opened the sheet when it closes.
+- **Announce an applied bonus in a polite live region** (`aria-live="polite"`).
+- **Use the preview's numbers and `upsell.name`**, never your own copy of them, and never a
+  literal `'vip'`: pass `upsell.pass` straight to `showPass`.
+
 ### Reading the player's balance
 
 ```js
 const currencies = await gem.platform.currencies.get();
-const gems = currencies.find((currency) => currency.slug === 'GEMS');
-buyButton.disabled = !gems || gems.balance < price; // can the player afford it?
+const coins = currencies.find((currency) => currency.slug === 'ARCADE_TICKETS');
+buyButton.disabled = !coins || coins.balance < price; // can the player afford it?
 ```
 
 **Read it to decide, never to display.** Platform-currency display belongs to the arcade: its
 wallet — the Gem menu, in the Gem Arcade, and beside the Gem for a game that asks with
 `gem.setWalletVisible(true)` ([the Arcade's wallet](what-a-game-must-do.md#the-arcades-wallet-in-the-gem-menu-and-beside-the-gem-when-you-ask))
-— shows the player's Gems and Coins totals while your game runs, and your game keeps no
-counter, balance or wallet total of either of its own ([brand-art.md](brand-art.md) §5). Use the
-balance to enable a purchase or to say "not enough Gems" — not to draw a number.
+— shows the player's Coins total while your game runs, and your game keeps no counter, balance or
+wallet total of its own ([brand-art.md](brand-art.md) §5). Use the balance to enable a purchase or
+to say "not enough Coins" — not to draw a number.
 
 Every game receives every active platform currency. Each row has `access: 'spend'`; the field stays
 in the response shape for existing consumers.
@@ -1084,27 +1255,27 @@ in the response shape for existing consumers.
 
 ```js
 const allowances = await gem.platform.earnAllowance.get();
-const gems = allowances.find((a) => a.currencySlug === 'GEMS');
+const coins = allowances.find((a) => a.currencySlug === 'ARCADE_TICKETS');
 // 0 or less once `resetsAt` has passed: the read is stale, so say nothing about when.
-const hours = gems?.resetsAt ? Math.ceil((gems.resetsAt - Date.now()) / 3_600_000) : 0;
-if (gems && gems.remaining > 0) {
+const hours = coins?.resetsAt ? Math.ceil((coins.resetsAt - Date.now()) / 3_600_000) : 0;
+if (coins && coins.remaining > 0) {
   hud.setText(
-    `You can still earn ${gems.remaining} Gems` + (hours > 0 ? `, more in ${hours}h` : ''),
+    `You can still earn ${coins.remaining} Coins` + (hours > 0 ? `, more in ${hours}h` : ''),
   );
-} else if (gems?.resetsAt) {
+} else if (coins?.resetsAt) {
   // Spent for now: say when more arrives, never "0 left".
-  hud.setText(hours > 0 ? `More Gems in ${hours}h` : 'More Gems soon');
+  hud.setText(hours > 0 ? `More Coins in ${hours}h` : 'More Coins soon');
 }
 ```
 
-One entry per earned platform currency (Gems and Coins today), for **this game and this player**:
+One entry per earned platform currency (Coins, today), for **this game and this player**:
 how much more your game can still grant before the platform's ceilings trim the grant. It is the
 lower of what is left of your game's own cap and what is left of the player's daily maximum across
 all games, with the player's Boost applied — one figure, never a breakdown.
 
 | Field          | What it is                                                                                        |
 | -------------- | ------------------------------------------------------------------------------------------------- |
-| `currencySlug` | `GEMS`, `ARCADE_TICKETS`, … (`''` if the platform sent none)                                      |
+| `currencySlug` | `ARCADE_TICKETS`, … (`''` if the platform sent none)                                                  |
 | `currencyId`   | The permanent id; joins to `gem.platform.currencies` and `platform_prices[].platform_currency_id` |
 | `limit`        | The binding ceiling: your game's own allowance, or the daily maximum across every game            |
 | `earned`       | How much of that ceiling has been paid, which may include other games' payouts                    |
@@ -1127,8 +1298,8 @@ end of the reported period when both of the platform's ceilings are spent.
 
 **Display only. Never gate gameplay or a grant on it.**
 
-- ✅ ``hud.setText(`${gems.remaining} Gems left to earn today`)``
-- ❌ `if (gems.remaining > 0) awardDailyBonus()`
+- ✅ ``hud.setText(`${coins.remaining} Coins left to earn today`)``
+- ❌ `if (coins.remaining > 0) awardDailyBonus()`
 
 Grant anyway: the platform trims every grant to what is left, and the receipt is the authority on
 what landed. The figure can be stale the moment after you read it — another game may pay the player
@@ -1182,8 +1353,8 @@ remove it. A player spends it through the platform, by choosing to.
 
 **You cannot sell for real money here.** A platform currency a player _earns_ is what this surface
 reaches. Charging actual money is a separate platform capability and is not something a game config
-grants itself. What a game _can_ do is offer the arcade store's own Gem packs, Boosts, passes and
-bundles from a button of its own, through `gem.store`
+grants itself. What a game _can_ do is offer the arcade store's own Coin packs, passes such as VIP
+and bundles from a button of its own, through `gem.store`
 ([arcade-and-store.md](arcade-and-store.md)): the arcade prices them and takes the money.
 
 ## Errors
@@ -1201,8 +1372,8 @@ bundles from a button of its own, through `gem.store`
 
 ## What to read next
 
-- [`arcade-economy.md`](arcade-economy.md) — Gems, Coins and achievement points: which to use for
-  what, and the rules each carries.
+- [`arcade-economy.md`](arcade-economy.md) — Coins and achievement points: which to use for what,
+  the rules each carries, and Gems' retirement.
 - [`achievements.md`](achievements.md) — platform achievements on your progressions' thresholds.
 - [`game-economy-tutorial.md`](game-economy-tutorial.md) — build a shop, step by step, the safe way.
 - [`trading-and-gifting.md`](trading-and-gifting.md) — move items and currency between players.