@indiegems/gem-web-sdk 23.2.0 → 24.0.0

package/docs/arcade-economy.md

@@ -1,32 +1,37 @@
-# Gems, Coins and Achievement Points
-
-The arcade runs three things across every game, and a player should be able to tell them apart at
-a glance:
-
-> **Gems = progress. Coins = what play earns: cosmetics, and play items too where the platform allows. Achievement Points = prestige.**
-
-You do not have to use any of them. A game with no platform currency and no achievements is a
-complete game, and the currencies your core loop runs on — gold, XP, energy, materials, cards — are
-yours to design however you like ([inventory-and-catalogs.md](inventory-and-catalogs.md)). Read this
-page before you design a reward a player carries out of your game, a price they pay with something
-earned elsewhere, or an achievement. The rules below decide which of the three a reward can be, and
-most of them are enforced at upload, so a design that ignores them is refused rather than shipped.
-
-## 1. The three, side by side
-
-|                    | **Gems** (`GEMS`)                                      | **Coins** (`ARCADE_TICKETS`)                  | **Achievement Points**                                    |
-| ------------------ | ------------------------------------------------------ | ----------------------------------------------- | --------------------------------------------------------- |
-| What it is         | the arcade's progression currency                      | the arcade's everyday currency, earned by play  | permanent prestige: the **Achievement Score**             |
-| Which games pay it | any game with a server or a serverless function        | any game with a server or a serverless function | an achievement, from any game with a server or a function |
-| What it buys       | anything a game prices in it                           | cosmetics; play items too, as its spend scope allows (§5) | nothing — it is never spent                               |
-| Sold for money     | by the arcade's own store only, never by a game        | never                                           | never                                                     |
-| A Boost raises it  | yes — the grants and the caps                          | yes — the grants and the caps                   | never                                                     |
-
-A player earns Gems across the arcade's games and spends them on progress anywhere: upgrades, unlocks,
-extra attempts, resources, characters, cards. A player earns Arcade Coins by playing almost anything and
-spends them on how they look: skins, outfits, visual effects, decorations, emotes, profile
-cosmetics, and since 25 Oct 2026 on play items too, wherever the platform's spend scope for Coins
-admits them (§5). Achievement points are what a player has done, summed across every game into the
+# Coins and Achievement Points
+
+The arcade runs two things across every game, and a player should be able to tell them apart at a
+glance:
+
+> **Coins = the arcade's one currency: play earns them, the Arcade sells them, games price in them. Achievement Points = prestige.**
+
+You do not have to use either. A game with no platform currency and no achievements is a complete
+game, and the currencies your core loop runs on — gold, XP, energy, materials, cards — are yours to
+design however you like ([inventory-and-catalogs.md](inventory-and-catalogs.md)). Read this page
+before you design a reward a player carries out of your game, a price they pay with something
+earned elsewhere, or an achievement. Most of the rules below are enforced at upload, so a design
+that ignores them is refused rather than shipped.
+
+⚠️ **Gems are retiring.** Every player's Gems become Coins on the date the platform announces, and
+nobody loses value. From then on a price in `GEMS` is refused (`422 platform_currency_unavailable`)
+and a Gem grant pays nothing; uploads already warn on `GEMS`. Move now: reprice every Gem price in
+Coins at **5 Coins per Gem**, move each Gem grant to a Coins grant at the rate in
+[§4](#4-earning-needs-server-authority), and take "Gems" out of your copy. Add no new Gem content.
+
+## 1. The two, side by side
+
+|                    | **Coins** (`ARCADE_TICKETS`)                                                    | **Achievement Points**                                    |
+| ------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| What it is         | the arcade's one currency                                                       | permanent prestige: the **Achievement Score**             |
+| Which games pay it | any game with a server or a serverless function                                 | an achievement, from any game with a server or a function |
+| What it buys       | anything a game prices in it, as its spend scope allows (§5)                    | nothing — it is never spent                               |
+| Sold for money     | **by the Arcade only**, in Coin packs; never by a game                          | never                                                     |
+| Raised by VIP      | yes — +50% on every grant, and the caps with it                                 | never                                                     |
+| Who may spend it   | a player with a full account; a guest earns and keeps, and spends after sign-up | —                                                         |
+
+A player earns Coins by playing almost anything, may buy more in the Arcade, and spends them in any
+game that prices in them: upgrades, unlocks, extra attempts, characters, cards, skins, outfits,
+effects, emotes. Achievement points are what a player has done, summed across every game into the
 Achievement Score; they are never bought, boosted or spent, and nothing takes them away except the
 platform, for fraud or moderation.
 
@@ -36,44 +41,38 @@ The arcade does not replace your economy. The currencies and resources your core
 gold, XP, wood, energy, lives, cards — stay your game's own: defined in your game config, minted and
 priced by you, invisible to every other game. Nothing on this page applies to them.
 
-What you map onto the three is the layer above that loop — the part that would otherwise become a
-platform-wide currency of your own:
+What you map onto Coins and achievements is the layer above that loop — the part that would
+otherwise become a platform-wide currency of your own:
 
 | If your design has…                                                                       | Use                                                       |
 | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| a premium or meta currency that speeds up or unlocks progress                             | **Gems**: price that progress in `GEMS`                   |
-| a cosmetics currency, or a shop of skins                                                  | **Coins**: price the cosmetics in `ARCADE_TICKETS`      |
+| a premium or meta currency that speeds up or unlocks progress, or buys cosmetics          | **Coins**: price it in `ARCADE_TICKETS`                   |
 | a trophy count, a mastery rank or a completion percentage that says "this player is good" | **achievements**, whose points join the Achievement Score |
 
-⚠️ **Do not build a second Gems or a second Coins.** A game-local premium or cosmetic
-meta-currency — "Crystals" that buy your upgrades, "Shards" that buy your skins, earned and hoarded
-the way a player would earn and hoard the arcade's — competes with the arcade's own, splits the
-player between two wallets that mean the same thing, and sidesteps every rule on this page: the Gem
-Source approval, the spend-scope line and the platform's caps. The release review checks for one.
-A currency that is part of play is fine: gold picked up in a level and spent in that run's shop,
-energy that paces a session, materials a crafting tree consumes.
+⚠️ **Do not build a second Coins.** A game-local premium or meta-currency — "Crystals" that buy your
+upgrades, "Shards" that buy your skins, earned and hoarded the way a player would earn and hoard the
+arcade's — competes with Coins, splits the player between two wallets that mean the same thing, and
+sidesteps every rule on this page: the spend-scope line and the platform's caps. The release review
+checks for one. A currency that is part of play is fine: gold picked up in a level and spent in that
+run's shop, energy that paces a session, materials a crafting tree consumes.
 
-## 3. Which kind of game is yours
+Which platform currencies **your** game may grant or price is the platform's answer, and it can
+change: `gemctl platform config --game <id>` lists them under `platform_grants` and
+`platform_prices`. A mapping onto a currency the platform will not let your game pay is refused at
+upload, and the refusal names the ones it will.
 
-There are four shapes:
+## 3. A game never sells currency for money
 
-| Shape          | Grants Gems | Prices in Gems | For example                                                                             |
-| -------------- | ----------- | -------------- | --------------------------------------------------------------------------------------- |
-| **Gem Source** | yes         | no             | a game with a controlled daily activity that feeds progress to the arcade               |
-| **Balanced**   | yes         | yes            | a Gem Source whose own progression also spends Gems                                     |
-| **Gem Sink**   | no          | yes            | a progression-heavy game: upgrades, characters, cards bought with Gems earned elsewhere |
-| **No-Gem**     | no          | no             | a game that stays out of Gems entirely                                                  |
+**Only the Arcade sells Coins.** A Coin pack is the Arcade Store's product, priced, sold and paid
+for in the Arcade's own checkout. Your game may put the Arcade's offers in front of a player from a
+button of its own, through `gem.store` ([arcade-and-store.md](arcade-and-store.md)), and that is
+the whole of its part:
 
-The shapes describe what a game does, not what it may do: a Gem Source that starts pricing its own
-progress in Gems is Balanced. Every shape may pay Coins, price its cosmetics in Coins and carry
-achievements. **Gems can be your game's soft currency** — award them for play and price your
-progression in them.
-
-Which platform currencies **your** game may grant or price is the platform's answer, and it can
-change: `gemctl platform config --game <id>` lists them under `platform_grants` and
-`platform_prices`, each with a note on what the arcade wants it used for. A mapping onto a currency
-the platform will not let your game pay is refused at upload, and the refusal names the ones it
-will.
+- **No currency for money.** Your game never sells Coins, a game currency or anything that grants
+  one for real money, alone or in a bundle.
+- **No top-up screen of your own** ([§8](#8-the-arcade-owns-the-display-of-every-platform-currency)).
+- **Bought and earned Coins spend the same.** Your game cannot tell them apart and prices nothing
+  differently for either.
 
 ## 4. Earning needs server authority
 
@@ -86,13 +85,13 @@ What may move it:
 - **Your game server** — a platform-allocated dedicated server, through the progression add and max
   routes.
 - **Your serverless function**, called by the player it pays, on a progression that sets
-  `function_may_grant: true`. It may pay Gems and Coins and unlock achievements for **that player
-  only**, and never for a guest. A function a player calls may also change only that player's own
-  state — any write it aims at another player is refused. Opting in makes the function's own checks
-  the only thing deciding a reward was earned, so read
+  `function_may_grant: true`. It may pay Coins and unlock achievements for **that player only**,
+  and never for a guest. A function a player calls may also change only that player's own state —
+  any write it aims at another player is refused. Opting in makes the function's own checks the
+  only thing deciding a reward was earned, so read
   [serverless-functions.md](serverless-functions.md) before you set it.
 - **Never the browser.** A mapped progression cannot be `client_writable`, and nothing else in your
-  config — a recipe, a loot-table entry, another progression's reward — may write it.
+  config — a recipe, a loot-table entry, another progression's reward, a bonus — may write it.
 
 So a browser-only game with neither a server nor a function pays nothing platform-wide. That is the
 rule read strictly, not a gap: a browser credential is public, and anything it could pay, a modified
@@ -104,156 +103,154 @@ to-dos. A one-time prize, such as finishing the tutorial or a first-time milesto
 stays modest. Work the rate out from what each firing pays and how often a player fires it, and keep
 it between 250 and 1,000 an hour: the release review estimates it, and a rate outside that band
 blocks release unless the creator has approved it for that game. The platform's ceilings
-([§6](#6-every-number-is-the-platforms-and-it-moves)) still trim each grant and each day, so at this
-rate a player reaches the daily maximum only after a long day of play; read the ceilings from
-`gemctl platform config`, never from here.
+([§6](#6-every-number-is-the-platforms-and-it-moves)) still trim each grant and each day; read them
+from `gemctl platform config`, never from here.
+
+**Configure the unboosted figure, and let the platform raise it.** A mapping's `amount` or
+`per_unit` is what a player with no VIP and no Boost earns. The platform applies VIP's +50%, or a
+Boost, itself when it pays ([§7](#7-vip-and-what-a-player-buys-with-money)).
+
+**Show a payout with the platform's answer, never your own arithmetic.** Before a claim,
+`gem.gameConfig.preview(target)` says what this player will get, what VIP would add, and which
+bonuses apply; after it, `gem.earnings.fromReceipt(change)` says what they got, in the same shape
+([inventory-and-catalogs.md](inventory-and-catalogs.md#showing-a-payout-before-and-after-preview-and-fromreceipt)).
+⚠️ **Never multiply by `gem.player.boost`, and never copy a config amount into your game's code.**
+Both go wrong the moment the platform retunes a number, and the release review flags hand-written
+multiplier code.
 
 **Achievements hold the same line, harder.** An achievement that awards points may not sit on a
-progression anything in your config writes: a recipe priced in Gems that adds to it would sell the
+progression anything in your config writes: a recipe priced in Coins that adds to it would sell the
 achievement. Points are never bought, boosted, spent, decayed or expired, and the platform removes
 them only for fraud or moderation ([achievements.md](achievements.md)).
 
-## 5. Spending: price each item in the currency it deserves
+## 5. Spending: pricing in Coins
 
-Any game may sell an item or a recipe for a platform currency, with no server and no approval: the
-item or recipe carries `platform_prices`, and the player pays through the arcade's purchase sheet,
+Any game may sell an item or a recipe for Coins, with no server and no approval: the item or recipe
+carries `platform_prices`, and the player pays through the arcade's purchase sheet,
 `gem.purchases.request`
-([inventory-and-catalogs.md](inventory-and-catalogs.md#16-selling-for-a-platform-currency)). What a
-currency may price is a platform setting on that currency, its **spend scope**:
-
-- **Gems — `any`.** Price progress in `GEMS`: an extra life, an upgrade, a character, a pack of
-  cards, another attempt.
-- **Coins — `cosmetic_only` today.** Since 25 Oct 2026 Coins may price play items as well as
-  cosmetics, and the platform moves Coins' scope to `any` to allow it; read the scope in
-  `gemctl platform config`. While it is `cosmetic_only`, a Coins price is accepted only on an item your config declares
-  `category: cosmetic`, or on a recipe that grants cosmetic items and nothing else. A Coins price
-  on anything that grants a currency, moves a progression, grants a non-cosmetic item, opens into
-  other items (a bundle or a loot box) or rolls a loot table is refused at upload — a loot table
-  even when every entry in it is cosmetic.
-
-So while the scope is `cosmetic_only`, a Coins price on an item is always the pair
-`currency: ARCADE_TICKETS` and `category: cosmetic`; on a recipe, every item it grants declares
-`category: cosmetic`. Once it is `any`, a play item may carry a Coins price and keeps
-`category: progression`.
+([inventory-and-catalogs.md](inventory-and-catalogs.md#16-selling-for-a-platform-currency)).
+
+- **What Coins may price is their spend scope**, a platform setting. Coins' is `any`, so they may
+  price play items and cosmetics alike. The platform owns the scope and can change it; read it in
+  `gemctl platform config`, and take it from a refusal rather than from this page.
+- **Spending needs a full account.** The platform refuses a guest's spend with
+  `403 guest_upgrade_required`, and the arcade takes the player through sign-up. A guest keeps
+  earning, and their Coins carry over when they sign up.
+- **A paid roll is gated.** A recipe priced in Coins that rolls a loot table, or carries a bonus
+  that rolls, is a paid random item: the arcade's purchase sheet shows the odds before the player
+  pays, and the platform refuses it for a known minor and in restricted regions
+  (`paid_chance_restricted`). Show the odds in your own shop too
+  ([inventory-and-catalogs.md](inventory-and-catalogs.md#12-loot-tables-and-odds)).
 
 **How much to charge: 500 Coins is worth about $1.** Price anything in Coins at what it would be
 worth in dollars, times 500: a $1 emote is 500 Coins, a $3 outfit 1,500, a $10 skin 5,000. A play
-item is worth what its counterpart costs in the hit games of its kind. At the
-earn rate in [§4](#4-earning-needs-server-authority), that is about an hour of play for each dollar.
-Coins are never sold for money, so the dollar is your yardstick only: never show a dollar figure
-beside a Coins price. The release review lists every Coins price with its dollar value and hours
-of play, and a price under 100 or over 10,000 Coins blocks release unless the creator has approved
-it for that game.
+item is worth what its counterpart costs in the hit games of its kind. At the earn rate in
+[§4](#4-earning-needs-server-authority), that is about an hour of play for each dollar. Never show a
+dollar figure beside a Coins price. The release review lists every Coins price with its dollar value
+and hours of play, and a price under 100 or over 10,000 Coins blocks release unless the creator has
+approved it for that game.
 
-**`category` defaults to `progression`**, so an item is a cosmetic only because you said so. The
-platform takes that at your word and the release review checks it: an item that changes what a
-player can do, labelled `cosmetic` so it can sell for Coins, breaks platform policy.
+**`category` still matters.** It defaults to `progression`; mark an item `category: cosmetic` only
+when it changes nothing but how the player looks. The release review checks the label, and the
+platform reads it whenever a currency's scope is `cosmetic_only`.
 
 **A cosmetic can still wait for progress.** "Reach level 10 to unlock the dragon skin" is a recipe
-with a prerequisite and a Coins price, and the platform refuses a locked player with
+with a requirement and a Coins price, and the platform refuses a locked player with
 `recipe_locked` before it takes anything ([game-economy-tutorial.md](game-economy-tutorial.md)).
 
-**Take the scope from the refusal, not from this page.** The platform owns each currency's scope and
-can change it. A refusal names the scope that applied, and `gemctl platform config` lists which
-currencies your game may price in at all. A scope changed after you published stops the prices it
-no longer admits: the purchase is refused and the price leaves the catalog, with nothing charged.
-
 **The arcade sells cosmetics of its own for Coins, and never sells prestige.** Besides your game's
 shop, the arcade has a Coins shop of its own profile cosmetics. Every arcade item is either a
 **shop** item — a cosmetic priced in Coins — or **earned**: a default, a free claim, an achievement
-or Achievement Score reward. An earned item can never be given a price, in Coins, Gems or anything
-else, so what a player shows off for what they did cannot be bought.
+or Achievement Score reward. An earned item can never be given a price, so what a player shows off
+for what they did cannot be bought.
 
 ## 6. Every number is the platform's, and it moves
 
-Each platform currency carries settings the arcade holds per currency and can change at any time,
-without a release of this SDK or of your game:
+Each platform currency carries settings the arcade holds and can change at any time, without a
+release of this SDK or of your game:
 
 - which games may grant it;
 - how much one grant may pay, how much one game may pay one player per window, and how much all
   games together may pay one player per day — the **daily maximum**;
 - the most a player may hold — the **holdings cap**;
 - whether games may price in it, and what it may price;
-- whether a Boost raises it;
+- whether VIP or a Boost raises it;
 - whether the arcade shows it in its header and wallet.
 
-**Author against `gemctl platform config`, never against a number you remember.** For your game it
-lists every currency a `platform_grants` mapping may target, with its current ceilings, every
-currency a price may name, and a note on when to reach for each. A currency it does not list for a
-site cannot be used there.
+**Author against `gemctl platform config`, never against a number you remember.**
 
 Your game declares no cap of its own. You choose only what each firing pays; the ceilings bound it,
 and the order's `platform_grant` entry — `fired`, `clamped` or `suppressed` — is the receipt for what
 landed:
 
-- **A ceiling trims; it does not refuse.** For every platform currency, a firing that would cross
-  the per-firing cap, the per-game cap or the daily maximum pays what is left of it and reads
-  `clamped`; once the day is spent it pays 0. When the player reaches the daily maximum, the arcade
-  tells them in its own chrome, and that notice is never relayed into your game
+- **A ceiling trims; it does not refuse.** A firing that would cross the per-firing cap, the
+  per-game cap or the daily maximum pays what is left of it and reads `clamped`; once the day is
+  spent it pays 0. When the player reaches the daily maximum, the arcade tells them in its own
+  chrome, and that notice is never relayed into your game
   ([daily-challenges.md](daily-challenges.md)), though it can read how much more it may pay
   ([the earn allowance](inventory-and-catalogs.md#showing-how-much-more-a-player-can-earn)).
 - **The holdings cap is all or nothing.** A grant that would take the player's balance past it pays
   nothing and reads `clamped` with `clamped_by: holdings_cap`. Nothing a player already holds is
   ever taken away.
 
-Your reward screen may say what the mapping pays; the receipt, never your screen, says what the
-player got.
-
-## 7. What a player buys with money: Gems and Boosts
-
-Nothing sells Coins or achievement points, alone or in a bundle. The arcade's own store sells
-Gems, and the Gems a player bought there spend in your game exactly as the ones they earned do: your
-game cannot tell the two apart and prices nothing differently for either. Your game never sells
-either itself. It may put the arcade store's own Gem packs, Boosts and passes in front of a player
-from a button of its own, through `gem.store`, and the arcade prices them, opens its own checkout
-and takes the money ([arcade-and-store.md](arcade-and-store.md)). The real-money product that changes
-what your game pays is a **Boost**, which a player always buys in the arcade's own checkout:
-
-- **It multiplies what Gems and Coins grants pay, and the ceilings with them.** A player on a 2×
-  Boost earns twice as much per grant, may earn twice as much per window and per day, and may hold
-  more. When it ends, what they earned stays theirs.
-- **It never touches achievement points.** An unlock credits the same points for every player.
-- **Your game does nothing to apply it.** The platform multiplies your mapping's payout itself.
-  Keep `amount` at the unboosted figure; the receipt reports what landed.
-- **None is on sale yet.** The first Boost, `booster_x2_30d`, is inactive until the arcade launches
-  it, so today every player earns at the unboosted rate. Design for both.
-
-⚠️ **Show a Boost; never gate on one.** Your game may tell a player they are boosted — "2× Coins"
-beside a reward, from `gem.player.boost`
-([what-a-game-must-do.md](what-a-game-must-do.md#the-signed-in-players-boost-show-it-never-gate-on-it))
-— and must never make content, difficulty, power, access, prices, matchmaking or odds depend on
-whether they are. A Boost buys a faster stream of the arcade's currencies and nothing else. A level,
-a character or an advantage behind it is paying to win, and the release review refuses it: the full
-rule is [platform-rules.md](platform-rules.md#8-a-players-boost-is-for-display-never-a-gate).
+A preview shows the uncapped figure, because the limits are private; the receipt says when a limit
+trimmed the payout, and `gem.earnings.fromReceipt` shows it.
+
+## 7. VIP, and what a player buys with money
+
+The Arcade Store sells **Coin packs** and **VIP**, a pass. Your game never sells either itself; it
+may open the Arcade's own sheet from a button of its own
+([arcade-and-store.md](arcade-and-store.md)).
+
+**VIP is a pass with +50% Coins.** While a player holds it:
+
+- **Every Coins grant pays +50%, and the ceilings scale with it**, so the extra stays real at the
+  cap. Your game does nothing to apply it: keep `amount` at the unboosted figure. The highest
+  multiplier in force wins — a player who also holds an older 2x Boost earns 2x, not 3x — and what
+  they earned stays theirs when VIP ends.
+- **It never touches achievement points.**
+- **It can unlock more in your game, through your config.** A recipe or loot table may carry
+  `bonuses`, each with a `requires`; `{ kind: 'holds_pass', pass: 'vip' }` is VIP. The platform
+  judges it when the recipe runs, and a bonus never fails the base grant
+  ([inventory-and-catalogs.md](inventory-and-catalogs.md#bonuses-more-for-a-player-who-meets-a-requirement)).
+- **A game can offer it at the moment it matters** — "VIP: +1 roll, 45 Coins" before a chest opens
+  — from `gem.gameConfig.preview`'s `upsells`, opened with `gem.store.showPass`. Upsell **before**
+  you grant, never after: the platform holds nothing back for later
+  ([inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell)).
+
+**The Boost is retired.** No Boost is on sale. A player who holds the 2x Boost keeps it until it
+ends, and `gem.player.boost` still reports it.
+
+⚠️ **Gate on the pass, never on the multiplier.** What VIP unlocks is decided by `holds_pass`,
+checked by the platform, or by a pass read on your server or function. `gem.player.boost` shows
+VIP's +50% too, and it is for display only: never make content, difficulty, power, access, prices,
+matchmaking or odds depend on it. The full rule is
+[platform-rules.md](platform-rules.md#8-a-players-boost-is-for-display-never-a-gate).
 
 ## 8. The arcade owns the display of every platform currency
 
-The arcade draws the player's platform currencies in its own chrome while your game runs, and
-animates every payout into the right total. Gems and Coins follow the same rules:
+The arcade draws the player's Coins in its own chrome while your game runs, and animates every
+payout into the right total:
 
 - **No counter.** Keep no balance, running total or wallet of a platform currency on any screen of
   yours. Read `gem.platform.currencies.get()` to decide whether a price is affordable, never to draw
   a number. A balance can change while your game is paused, so read it again on every
   `onPause(false)` if you keep anything worked out from it, such as a greyed-out Buy button.
-- **No celebration of your own.** At a payout, cue the arcade's wallet with `gem.cueReward`, naming
-  the currency that paid — `currencySlug: 'GEMS'` from the gem on your reward screen,
-  `'ARCADE_TICKETS'` from the coin. If it returns `false`, do nothing. When your serverless function
-  pays it, pass one `cueId` (a `crypto.randomUUID()`) to both the cue and the `gem.functions.invoke`
-  call, and the reward flies once
+- **No celebration of your own.** At a payout, cue the arcade's wallet with `gem.cueReward`,
+  `currencySlug: 'ARCADE_TICKETS'`, from the coin on your reward screen. If it returns `false`, do
+  nothing. When your serverless function pays it, pass one `cueId` (a `crypto.randomUUID()`) to
+  both the cue and the `gem.functions.invoke` call, and the reward flies once
   ([inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet)).
 - **No "daily max" of your own making.** Your game cannot see what every other game paid the player,
   and must not compute a maximum. To show how much more your game can pay, read
-  `gem.platform.earnAllowance.get()` (one consolidated figure, display only); the arcade still tells
-  the player when they reach the maximum.
-- **No top-up or payment screen of your own.** Never draw a "buy Coins" offer, a checkout, a
-  wallet top-up, or anything shaped like the arcade's purchase sheet: a game screen that looks like
-  platform payment chrome is an imitation of it, and players cannot tell the two apart. Your shop's
-  own Buy button is yours, and so is a "Get Gems" button that calls `gem.store.purchase`, or a "Get
-  VIP" button that calls `gem.store.showOffer`, from the player's press: the checkout each one
-  leads to is the arcade store's own
-  ([arcade-and-store.md](arcade-and-store.md)). When a purchase is refused for
-  `insufficient_funds`, say so in your shop's own words ("Not enough Coins") and stop there: a
-  refusal never opens the store by itself.
+  `gem.platform.earnAllowance.get()` (display only); the arcade still tells the player when they
+  reach the maximum.
+- **No top-up or payment screen of your own.** Never draw a "buy Coins" offer, a checkout, a wallet
+  top-up, or anything shaped like the arcade's purchase sheet. Your shop's own Buy button is yours,
+  and so is a "Get Coins" button that calls `gem.store.purchase` with a Coin pack, or a "Get VIP"
+  button that calls `gem.store.showPass('vip')`, from the player's press: the checkout each one
+  leads to is the Arcade's own. When a purchase is refused for `insufficient_funds`, say so in your
+  shop's own words ("Not enough Coins") and stop there: a refusal never opens the store by itself.
 - **No amount at all when you are not connected to the arcade.** Hide every platform price and
   reward unless `gem.awaitBridge()` settled `connected`.
 - **Draw a currency with the art the SDK ships**: the icon beside an amount, the hero only on a
@@ -264,37 +261,40 @@ never computes the score, restates it, or turns it into a currency of its own.
 
 ## 9. What the arcade does not have
 
-- **No Stars, Tokens or Supporter Seals, and not the old `COINS` currency** (retired; not today's
-  Coins, `ARCADE_TICKETS`). All four are retired. None of them can be
-  granted, priced in or bought: a config naming one is refused at upload, and a mapping onto one
-  that is still live reads `suppressed`. The Achievement Score is the arcade's measure of prestige.
-- **No Gems or Coins for money from a game**, alone or in a bundle. Only the arcade's own store
-  sells Gems, and nothing sells Coins.
+- **No Gems, once they retire**, and no Stars, Tokens, Supporter Seals or the old `COINS` currency
+  (retired; not today's Coins, `ARCADE_TICKETS`). None of them can be granted, priced in or bought:
+  a config naming one is refused at upload, and a mapping onto one reads `suppressed`.
+- **No currency for money from a game**, alone or in a bundle. Only the Arcade sells Coins.
 - **No achievement points or earned items for anything a player pays for.**
-- **No content behind a Boost.** A Boost is shown, never checked.
+- **No content behind a multiplier.** VIP's +50% and a Boost are shown, never checked; content goes
+  behind `holds_pass`.
+- **Nothing held for later.** The platform keeps no pending or missed bonus and no voucher: a bonus
+  is judged when the recipe runs.
 
 ## 10. When an upload or a grant is refused
 
-| What you get                                               | What happened                                                   | What to do                                                                                   |
-| ---------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| a mapping refused, naming the currencies your game may pay | the platform does not let your game grant that currency         | target one it lists — `gemctl platform config` has the current set                           |
-| a receipt `suppressed`, reason `not_allowlisted…`          | the platform stopped letting your game grant that currency      | target a currency `gemctl platform config` lists; paid balances stay                         |
-| a price refused, naming the spend scope `cosmetic_only`    | a Coins price on something that is not a cosmetic             | price it in `GEMS` while Coins' scope is `cosmetic_only`, or mark the item `category: cosmetic` only if it changes nothing but looks |
-| a receipt `suppressed`, reason `functions_not_opted_in`    | your function wrote a paying progression that has not opted in  | read [serverless-functions.md](serverless-functions.md), then set `function_may_grant: true` |
-| a receipt `suppressed`, reason `function_gems_not_enabled` | an older receipt, from before functions could pay Gems          | nothing — a function pays Gems now, so its next firing pays                                  |
-| `403 function_foreign_entity_write`                        | a function a player called wrote another player                 | take the player from the call's context, never its input                                     |
-| a receipt `clamped`                                        | a ceiling trimmed the payout, or the day was already spent      | nothing — show what landed; `gemctl platform config` has the ceilings                        |
-| a receipt `clamped`, `clamped_by: holdings_cap`            | the player already holds as much as they may                    | nothing — the player spends before they earn more                                            |
+| What you get                                                                       | What happened                                                  | What to do                                                                                                          |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| a mapping refused, naming the currencies your game may pay                         | the platform does not let your game grant that currency        | target one it lists — `gemctl platform config` has the current set                                                  |
+| an upload warning, or after the cut `422 platform_currency_unavailable`, on `GEMS` | Gems are retiring                                              | reprice in `ARCADE_TICKETS` at 5 Coins per Gem, and move Gem grants to Coins                                        |
+| a receipt `suppressed`, reason `not_allowlisted…`                                  | the platform stopped letting your game grant that currency     | target a currency `gemctl platform config` lists; paid balances stay                                                |
+| a price refused, naming a spend scope                                              | the currency's scope does not admit that item                  | price it in a currency whose scope does, or mark the item `category: cosmetic` only if it changes nothing but looks |
+| `403 guest_upgrade_required`                                                       | a guest tried to spend Coins                                   | nothing — the arcade takes them through sign-up                                                                     |
+| `paid_chance_restricted`                                                           | a paid roll for a known minor, or in a restricted region       | nothing for the base of a free recipe; a bonus roll is skipped, a paid roll refused                                 |
+| a receipt `suppressed`, reason `functions_not_opted_in`                            | your function wrote a paying progression that has not opted in | read [serverless-functions.md](serverless-functions.md), then set `function_may_grant: true`                        |
+| `403 function_foreign_entity_write`                                                | a function a player called wrote another player                | take the player from the call's context, never its input                                                            |
+| a receipt `clamped`                                                                | a ceiling trimmed the payout, or the day was already spent     | nothing — show what landed with `gem.earnings.fromReceipt`                                                          |
+| a receipt `clamped`, `clamped_by: holdings_cap`                                    | the player already holds as much as they may                   | nothing — the player spends before they earn more                                                                   |
 
 ## What to read next
 
-- [`inventory-and-catalogs.md`](inventory-and-catalogs.md) — platform grants (§13) and selling for a
-  platform currency (§16), in full.
-- [`game-economy-tutorial.md`](game-economy-tutorial.md) — a shop, step by step, including a
-  cosmetic sold for Coins.
+- [`inventory-and-catalogs.md`](inventory-and-catalogs.md) — platform grants (§13), requirements and
+  bonuses (§9), the payout preview and selling for a platform currency (§16), in full.
+- [`arcade-and-store.md`](arcade-and-store.md) — the Arcade Store, `showPass` and the VIP read.
+- [`game-economy-tutorial.md`](game-economy-tutorial.md) — a shop, step by step.
 - [`daily-challenges.md`](daily-challenges.md) — the commonest thing that pays a platform currency.
 - [`achievements.md`](achievements.md) — achievements, their points and the Achievement Score.
 - [`serverless-functions.md`](serverless-functions.md) — paying a player from a game with no
   dedicated server, and what a function a player calls may change.
-- [`platform-rules.md`](platform-rules.md) — the Boost rule, among the rest.
+- [`platform-rules.md`](platform-rules.md) — gate on the pass, never on the multiplier.
 - [`brand-art.md`](brand-art.md) — the art for every platform currency, and the rules for drawing it.

package/docs/changelog.md

@@ -16,6 +16,54 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 24.0.0
+
+Upgrading from 23.3.0. Impact: required.
+
+### Must change
+
+- Stop using the store offers call answering sign_in_required as a test for a guest. A current Arcade now answers a guest with ok, because a guest can buy. Use GemPlayer.isGuest instead. It is true only when the Arcade says the player is a guest who can sign up here, and false for a full account, for a surface with no sign-up, and for an older Arcade that does not say. It follows a guest who signs up in place.
+- Check any code that branches on the offer kind. ArcadeOffer.kind is now typed as ArcadeOfferKind, and a pack of a platform currency other than GEMS is reported as coin_pack rather than gem_pack. The gem_pack value is deprecated. Handle coin_pack wherever you handle gem_pack, or such packs will fall through your branches.
+- If your tests run the parent conformance kit against an Arcade host or a stand-in for one, update them for kit version 9. The version constant moved from 8 to 9, there is a new storeScenario member on the parent under test, and there are six new pass cases. Supply a store scenario so those cases can run.
+
+### Should change
+
+- GamePass.endsAt is deprecated on the browser, function and server halves. An exact end instant is a value two games could match to link one player's identities, so the platform will stop sending it and it will read null. Move to GamePass.daysLeft, which gives whole days remaining, capped at 7. A known guest is answered as not holding the pass. See [the deprecation policy](deprecation-policy.md#4-what-is-deprecated-today).
+
+### May stop
+
+- If your game works out expected rewards or the effect of a player's boost by hand, you can drop that arithmetic. The config preview now computes the multiplier, platform grants with their rounding, and bonus eligibility for you.
+
+### Rebuild
+
+- Types changed in two places. The store offers result now allows an optional pass and optional earn multipliers on each offer. The server match object gains playerPasses and playerBoost. Recompiling is enough, unless your code supplies its own stand-in for the match object, which then needs the two new members.
+
+### New capability
+
+- Offers now say which pass they sell and which earn multipliers they carry. Each ArcadeOffer has an optional pass and optional earnMultipliers, so a game can show what an offer raises before the player buys it.
+- A game can sell a pass by its slug. StoreApi.passOnSale tells you whether the pass is on sale here, and StoreApi.showPass opens its sheet. The ShowPassOutcome it returns is ok only once a fresh read of the player's passes shows the pass held, and otherwise ok or pending as that type describes.
+- A game can preview what a config change would grant before applying it. You pass a config id, never an amount or a pass. The preview works out the player's multiplier, holdings and local offers, and reports grants, platform grants with a breakdown crediting a held pass or Boost, bonuses with eligibility and unmet requirements, and upsells for passes the player could buy. Rolls are reported as a count from a table, never an outcome. Errors and targets have their own types.
+- Earnings can be read from a receipt. The new earnings API turns a receipt's platform grant change into the same platform grant shape the preview uses, from the base amount granted and the boost source. It is available on the browser, on the function half, and on the server and match server. The function half resolves the currency from the invoking player's currencies, while the server half takes a currency id only.
+- A dedicated game server can now read a player's passes and Boost in a match. Use the match player passes read to gate on a pass, using the same GamePass shape as the browser. The match player Boost read returns a MatchPlayerBoost with its multipliers, for display only. Both reads go through optional runtime hooks, host.passes and host.boost, and an image without a hook, or a listen host, is refused by name. A refusal surfaces as an API error that keeps its original code.
+
+## 23.3.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 23.2.0. Impact: required.
+
+### Must change
+
+- FrameCallbacks.onPlayer changed its signature.
+- FrameOptions.onPlayer changed its signature.
+
+### New capability
+
+- AccountApi.onSignInAvailableChange was added.
+- AccountApi.signInAvailable was added.
+- GemPlayer.signInAvailable was added.
+- SendPlayerInput.signInAvailable was added.
+
 ## 23.2.0
 
 *Written from the API facts alone; no summary was generated for this release.*

package/docs/deprecation-policy.md

@@ -100,6 +100,8 @@ deprecated.
 | `GemPlayer.displayHandle` | `PlayerIdentity.displayTag` — the same value | `7.0.0` | Package API surface |
 | `GemPlayer.avatarUrl` | `PlayerIdentity.avatarIconUrl` — the same value | `7.0.0` | Package API surface |
 | `AdRequest.format: 'interstitial'` | `gem.moments.signal` — a platform moment at the same break, from the press that leaves it | `14.0.0` | Package API surface |
+| `GamePass.endsAt` | `GamePass.daysLeft` — whole days, capped at 7 | `24.0.0`, for the member | Package API surface, plus runtime delivery |
+| `ArcadeOffer.kind: 'gem_pack'` | `'coin_pack'` — Gems are retired, and Coins are the one platform currency | `24.0.0` | Package API surface |
 | `profile(playerId)` | The room read's per-member display identity | Not a package release | Runtime delivery only |
 
 **"For the member" is the split from section 3**, and it is the row's real answer: `4.0.0` is

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "23.2.0"
+  "@indiegems/gem-web-sdk": "24.0.0"
 }
 ```