@indiegems/gem-web-sdk 23.3.0 → 24.0.1

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "5b880e515ce0d65ffff77b97c93844dbcc14d7ab55d89edabaa54f4858376216",
-      "updated": "2026-11-09T16:45:36Z"
+      "sha256": "73e77f3bd0124f69d53b42714fb24c7d128dd1be97e203fc3a353a8eb4e3c05a",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "108b3225a45dce776907344f8a3865b99b6e16598c6f70ddf0e8b923cf330a7e",
-      "updated": "2026-11-04T21:50:20Z"
+      "sha256": "6fadbb07d8a6ab44cb231b12a6ba89ce65a46bf42841bff932d3813aa4e0931a",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "async-opponents.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "85e888011b15aa2e9ebb56d938b9a8165489167bcebda236cba9e4f09937044f",
-      "updated": "2026-11-10T15:57:23Z"
+      "sha256": "1df1bb9edeb1db3a6e69f2625b091e3a06b6e3ca7accb7e6c22a392dbf95ba3c",
+      "updated": "2026-11-11T13:36:03Z"
     },
     {
       "file": "daily-challenges.md",
@@ -63,8 +63,8 @@
     },
     {
       "file": "deprecation-policy.md",
-      "sha256": "8134d5463e2737116ed23341bf177c51cede4bd86dabec54d76a82c5bfdfade1",
-      "updated": "2026-10-14T22:38:02Z"
+      "sha256": "4622fbf889603436d753013296e9aa8f9edd460ebdae91e4e8594698ea5a0500",
+      "updated": "2026-11-10T21:45:26Z"
     },
     {
       "file": "friends.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "bdadeee9b46529d4ef9543a2be61cd096e6b200c20dbe2ab1b361d23139d3e64",
-      "updated": "2026-11-10T15:57:23Z"
+      "sha256": "d740cfa7dd54f089399b3a83f29442f12337afa88309c997d598f583f5c9f113",
+      "updated": "2026-11-11T13:36:03Z"
     },
     {
       "file": "graphics-route.md",
@@ -88,8 +88,8 @@
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "f0445a3b56f7a31590acd9ef2874a7f51cc8d89b6fbfc7de9ea5861f1ef555ca",
-      "updated": "2026-11-08T20:08:14Z"
+      "sha256": "22998fb3ff26d4f9f29d2a73ce6db0ccf42ca2b635f171023a2e2214bbea4b1a",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "leaderboards.md",
@@ -113,18 +113,18 @@
     },
     {
       "file": "platform-rules.md",
-      "sha256": "ab5b971555490956ef50f6141b0f58a6a34335a7e4cc1ef0e4d339a259c9a062",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "e9cb3cf1945002d182d917b0f3f7cfdf26f41de9ec9cd34a47c487cb4c615152",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "player-sign-in.md",
-      "sha256": "f5066f2382bac9336c697d3646843f546295686a959726e877431ec7dc2daea3",
-      "updated": "2026-11-09T18:39:56Z"
+      "sha256": "ebdaa0a35815c72148bd72f529b5ecee264c2eeb703e73fdfc277066be63fab4",
+      "updated": "2026-11-11T01:30:40Z"
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "36394d5faee67f3907139b1fe8c8210a6074a6eac593bc070b567625e71c6129",
-      "updated": "2026-11-09T19:34:44Z"
+      "sha256": "505a6addbac54b9a154ca0b1afd727d319ba35f5f2a9b24d9835ac2a9104ded8",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "room-shapes.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "921591332e0a9fc52d36e3372af26a5ea808768e1bbd49826d765b7e4615ab53",
-      "updated": "2026-11-10T15:57:23Z"
+      "sha256": "8e18e0c918476d0bd4ca83a56fa8274dccb9c4f344c6eba566e3067104dc912d",
+      "updated": "2026-11-11T13:36:03Z"
     },
     {
       "file": "serverless-functions-js.md",

package/docs/platform-rules.md

@@ -326,41 +326,50 @@ longer one, are in [`server-bundles.md`](server-bundles.md#how-long-your-server-
 
 ## 8. A player's Boost is for display, never a gate
 
-Decided by the platform on **2026-09-26**, and a contract rather than an implementation fact.
+Decided by the platform on **2026-09-26**, restated for VIP on **2026-11-10**, and a contract
+rather than an implementation fact.
 
-The **Boost** is something the Arcade sells for real money, in its own store. While a player has
-one, they earn **Gems and Coins** faster — every grant is multiplied — and their earning limits
-and holdings cap are raised by the same tier. It **never** touches achievement points. The platform applies all of
-it on its own side, when it pays: a game does nothing to make a boost work, and cannot make one
-work harder.
+**Gate on the pass, never on the boost.** What a player paid for is unlocked by the pass, and the
+multiplier it brings is only ever shown.
 
-A game **may show** it. `gem.player.boost` carries each boostable currency's multiplier and the
-whole days left, so a reward screen can say "2× Coins"; see
+A player's earnings multiplier comes from **VIP**, a pass that pays +50% Coins, or from a **Boost**
+bought before the Boost was retired. The platform applies it on its own side, when it pays: every
+Coins grant is multiplied, and the earning limits with it. It **never** touches achievement points.
+A game does nothing to make it work, and cannot make it work harder.
+
+A game **may show** it. `gem.player.boost` carries each currency's multiplier and the whole days
+left, so a reward screen can say "+50% Coins"; see
 [what a game must do](what-a-game-must-do.md#the-signed-in-players-boost-show-it-never-gate-on-it).
-A dedicated server can read the same effective boost for a player in its match, and the same rule
-holds there.
+To show what a payout will be, use `gem.gameConfig.preview`, never your own arithmetic on the
+multiplier. A dedicated server can read the same multiplier for a player in its match
+(`gem.match.playerBoost`), and the same rule holds there.
 
-A game **must not gate** anything on it:
+A game **must not gate** anything on the multiplier:
 
 - **No content or power behind it.** No level, item, character, mode, stat, difficulty setting or
-  extra attempt may depend on whether the player is boosted. A boosted and an unboosted player play
-  the same game.
-- **No prices that depend on it**, and no discount or surcharge keyed on boost status.
-- **No matchmaking on it.** Never exclude, separate or wait on a player because of their boost.
-- **No nagging.** No "you're not boosted" loops, interstitials or countdown pressure. The Arcade owns
-  the Boost store; a game does not sell or advertise boosts.
-
-Three reasons, any one of which would be enough. It is **advisory**: the browser value is pushed on
-connect and on change, so it can lag a boost that just started or ended, and the platform's own
-figure is what pays. It is **forgeable** inside your page, so a gate on it is a gate anyone can
-open. And gating on it turns a faster faucet into pay-to-win, which is the line the Arcade's economy
-is drawn on.
+  extra attempt may depend on whether, or by how much, the player earns faster. A player at 1x and a
+  player at 1.5x play the same game.
+- **No prices that depend on it**, and no discount or surcharge keyed on it.
+- **No matchmaking on it.** Never exclude, separate or wait on a player because of it.
+- **No nagging.** No "you're not boosted" loops, interstitials or countdown pressure.
+
+**What VIP unlocks goes behind the pass.** A VIP room, a VIP roll or a VIP track is a
+`requires: [{ kind: 'holds_pass', pass: 'vip' }]` on the item, recipe, bonus or track, which the
+platform checks when it runs; or a decision your function or server makes from its pass read
+(`gem.me.passes` in a function, `gem.match.playerPasses` on a server). The browser's
+`gem.me.passes` draws the door; it never opens it. Offer VIP only before a reward, by the rules in
+[inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell).
+
+Three reasons not to gate on the multiplier, any one of which would be enough. It is **advisory**:
+the browser value is pushed on connect and on change, so it can lag, and the platform's own figure
+is what pays. It is **forgeable** inside your page, so a gate on it is a gate anyone can open. And it
+**is not the purchase**: a player can hold an old Boost without VIP, so a gate on the multiplier
+opens for the wrong player and stays shut for none.
 
 It carries **a day count, never an instant — and capped at 7**, so `7` means "7 or more" — and
-nothing about the tier, the price or whether the player paid at all: free and paid boosts look
-identical to a game. A second-precision expiry would be a near-unique value per player that two
-games could join on, and an exact day count would jump by a purchase's term the moment the player
-paid. Show `7` as "7+ days", never as an end date.
+nothing about the tier, the price or whether the player paid at all. A second-precision expiry
+would be a near-unique value per player that two games could join on, and an exact day count would
+jump by a purchase's term the moment the player paid. Show `7` as "7+ days", never as an end date.
 
 ## Where the rest of it is
 

package/docs/player-sign-in.md

@@ -56,17 +56,26 @@ signs up in place, and when the game is disconnected. It returns a function that
 
 ### Gating a sign-up gift
 
-If your game gives a gift for signing up, offer it only while `signInAvailable` is `true`. That
-means a guest the Arcade can sign up here, so you don't need to work out who is a guest from
-`gem.store.offers()` answering `unavailable` / `sign_in_required`.
-
-On an older Arcade the signal can't do that job alone. It reads `true` for every player there, so a
-gift gated on it alone is offered to players who already have an account. Pressing it answers
-`signed_in` at once, which a player who was signed in all along gets too, so that answer is no
-proof of a sign-up either. Your game can't tell which kind of Arcade it is running in, so for now
-gate the gift on both: `signInAvailable` is `true` **and** the guest test you use today, such as
-`offers()` answering `sign_in_required`. On a current Arcade the two agree for a guest. On an older
-one, the second keeps the gift from players who are already signed in.
+If your game gives a gift for signing up, offer it only while **`gem.player.isGuest`** is `true`:
+
+```js
+const gem = createGem({
+  // Runs for each pushed player, again when a guest signs up in place.
+  onPlayer: (player) => (signUpGift.hidden = !player.isGuest),
+});
+```
+
+`isGuest` is `true` only when the Arcade says the player is a guest it can sign up here. It is
+`false` for a full account, where the Arcade offers no sign-up, and on an older Arcade that does not
+say, so a gift gated on it never reaches a player who already has an account. On such an older
+Arcade no gift shows at all: the safe way to be wrong.
+
+Use it rather than `signInAvailable`, which reads `true` for every player on an older Arcade (it
+keeps a sign-in button working there), and rather than `gem.store.offers()` answering
+`sign_in_required`, which no longer means a guest: a current Arcade answers a guest's `offers()`
+with `ok`, because a guest can buy, and signs them up first. Pressing the ask answers `signed_in`
+for a player who was signed in all along too, so that answer is no proof of a sign-up either; what
+the gift pays is granted by your function or server, which reads the account itself.
 
 ## 1. Save before you ask
 

package/docs/rewarded-ads.md

@@ -213,7 +213,7 @@ the player then did, so **branch on your inventory, never on the outcome**, as f
   The upload refuses it, and `ad: false` with no `platform_prices` too, since then nothing unlocks
   the placement.
 - **Each currency's spend scope applies,** as it does to an item's price
-  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#what-coins-and-gems-may-buy-the-spend-scope)):
+  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#what-coins-may-buy-the-spend-scope)):
   where Coins may price cosmetics only, a Coin price on a placement that grants anything else is
   refused. Gems may price any placement. `gemctl platform config` lists which currencies your
   game may price in, and each one's spend scope: author against it, never against a list you

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.3.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v23.3.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v24.0.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v24.0.1/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 
@@ -829,11 +829,13 @@ The short version: the browser half is what a player's **session** can do, and t
 what a **match** can do. `gem.rooms.join()` has no meaning to a process that exists because a match
 was already allocated.
 
-**`gem.me.passes` is browser and function only**, and that is a limit rather than a principle. The
-platform has a match read of which passes a player in your match holds, but your bundle cannot call
-it: it requires the allocation nonce, which the runtime never hands to a bundle, as the boost read
-does, and it answers `403` to every caller until game servers are granted `passes.read`.
-[arcade-and-store.md](arcade-and-store.md#on-a-dedicated-server) has what to do instead.
+**`gem.me.passes` is browser and function only, and `gem.match.playerPasses(playerId)` is the
+server's.** Both routes behind a player's passes and Boost in your match require the allocation
+nonce, which never enters your bundle, so the platform half of the runtime makes the read for you,
+as it does `gem.match.end()`: `gem.match.playerPasses(playerId)` for what to gate on, and
+`gem.match.playerBoost(playerId)` for display only. Each throws on a runtime image that predates it
+and on a listen host. [arcade-and-store.md](arcade-and-store.md#on-a-dedicated-server) has the
+details.
 
 **Rooms are the case where those two answers differ**, so they are worth stating separately rather
 than filed under "browser-only". `gem.rooms` — join, leave, ready up, quick-join — is a player

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "23.3.0",
+  "version": "24.0.1",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -6043,7 +6043,7 @@
       "transport": "port",
       "$comment": [
         "Ask what the Arcade Store sells to this player, here, for real money:",
-        "Gem packs, Boosts, passes and bundles. Gated by the `store` capability.",
+        "Coin packs, Boosts, passes and bundles. Gated by the `store` capability.",
         "Answered by `gem.storeOffersResult`.",
         "",
         "WHY THE PARENT ANSWERS IT. The price a player pays depends on the",
@@ -6057,9 +6057,13 @@
         "",
         "A READ, NOT AN ACT: no activation, no mutex. Per-session state comes",
         "back as a reason: `store_off` where the store is withheld (an age or",
-        "region policy, a TV, an in-app browser that takes no payment) and",
-        "`sign_in_required` for a guest, who may then be offered",
-        "gem.requestSignIn."
+        "region policy, a TV, an in-app browser that takes no payment).",
+        "",
+        "A GUEST IS ANSWERED `ok`, with what the store would sell them:",
+        "buying takes a guest through sign-up first, in the parent's own",
+        "chrome, and back to the offer. An",
+        "older parent answered a guest `sign_in_required`, and a frame must",
+        "still read that as nothing for sale."
       ],
       "fields": {
         "requestId": {
@@ -6090,6 +6094,23 @@
         "instead, and a purchase of that offer is answered `declined` /",
         "`cancelled`.",
         "",
+        "WHAT A PASS SAYS, AND WHAT IT MUST NOT. A pass offer names its",
+        "offering slug in `pass` and the earning",
+        "multipliers it carries in `earnMultipliers`, so a game can find VIP by",
+        "slug and preview what it would add without naming a SKU or a number.",
+        "A parent lists a pass only where it would open that pass's sheet: an",
+        "offering with `visible_to_games`, to a player who has not declined",
+        "its sheet twice today. For a KNOWN MINOR it leaves the pass out",
+        "exactly as if it were not on sale - the same `ok`, the same other",
+        "offers, no reason - so a game can never tell a minor from a pass that",
+        "is not sold here. A holder still sees it: the sheet adds time.",
+        "",
+        "COIN PACKS ARE `gem_pack`. The kind enum is closed (a fifth value",
+        "would be refused whole by an N-1 frame), so a pack of any platform",
+        "currency crosses as `gem_pack` with `grant` naming the currency, and",
+        "the SDK reports a pack whose `grant.currency` is not GEMS as",
+        "`coin_pack`.",
+        "",
         "THE NAMES ARE THE PLATFORM'S, not a game developer's: the Arcade",
         "Store's own catalog copy, which is why `name` and `description` sit",
         "outside an `untrusted` object.",
@@ -6131,7 +6152,7 @@
               "kind": {
                 "kind": "enum",
                 "values": ["gem_pack", "boost", "pass", "bundle"],
-                "$comment": "What sort of thing it is. A new sort of SKU is left out of this list by the parent, never sent as a fifth value: an N-1 frame would refuse the whole message."
+                "$comment": "What sort of thing it is. A new sort of SKU is left out of this list by the parent, never sent as a fifth value: an N-1 frame would refuse the whole message. `gem_pack` is a pack of ANY platform currency, Coins included: `grant` says which."
               },
               "name": {
                 "kind": "string",
@@ -6158,12 +6179,12 @@
               "grant": {
                 "kind": "object",
                 "optional": true,
-                "$comment": "For a Gem pack: the currency and amount it grants. Absent for every other kind.",
+                "$comment": "For a currency pack (`gem_pack`): the currency and amount it grants. Absent for every other kind.",
                 "fields": {
                   "currency": {
                     "kind": "string",
                     "maxLength": 32,
-                    "$comment": "The platform currency's exact slug, e.g. GEMS."
+                    "$comment": "The platform currency's exact slug, e.g. ARCADE_TICKETS for Coins."
                   },
                   "amount": {
                     "kind": "int",
@@ -6172,6 +6193,34 @@
                     "$comment": "How much of it."
                   }
                 }
+              },
+              "pass": {
+                "kind": "string",
+                "maxLength": 64,
+                "optional": true,
+                "$comment": "For a pass, or a bundle carrying one: the pass's offering slug, e.g. `vip` - the slug `gem.me.passes` and a `holds_pass` requirement name. Absent for everything else, and from an older parent. Additive: no `v` bump."
+              },
+              "earnMultipliers": {
+                "kind": "array",
+                "maxItems": 8,
+                "optional": true,
+                "$comment": "For an offer that makes the player earn a platform currency faster while held - a pass with the `earn_boost` feature, or a Boost: one entry per currency, as `gem.player`'s `boost.multipliers` carry them. Absent or empty when it boosts nothing. The platform's multiplier, never a game's: the preview reads it to say what holding the pass would add.",
+                "items": {
+                  "kind": "object",
+                  "fields": {
+                    "currencySlug": {
+                      "kind": "string",
+                      "maxLength": 32,
+                      "$comment": "The currency's slug, e.g. ARCADE_TICKETS."
+                    },
+                    "multiplierBp": {
+                      "kind": "int",
+                      "min": 10000,
+                      "max": 1000000,
+                      "$comment": "Basis points: 10000 is 1x, 15000 is 1.5x. gem-api clamps what it applies to 10x."
+                    }
+                  }
+                }
               }
             }
           }