@indiegems/gem-web-sdk 14.0.3 → 15.1.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v14.0.3, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v15.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -3553,6 +3553,72 @@ them, whatever you set here.
 | --- | --- |
 | `props` | `Readonly<Record<string, AnalyticsValue>>` |
 
+<a id="analyticsapi-experiment"></a>
+
+## AnalyticsApi.experiment
+
+```ts
+experiment(key: string, count: number): Promise<number>
+```
+
+Which arm of one of your experiments this player gets — the same answer on
+every call, every refresh and every device. Use it wherever you would have
+picked an arm with `Math.random()`, which deals a player a new arm on each
+visit and makes the test unreadable.
+
+Pass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings
+and get one of them. A string listed twice is twice as likely.
+
+```js
+const tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);
+const layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2
+```
+
+The selection is a hash of the key and the signed-in player's id — FNV-1a
+32-bit over `"<key>:<playerId>"`, then MurmurHash3's 32-bit finalizer, mod
+the arm count; see
+[experimentSelection](#experimentselection), which computes the same answer for an id you
+hold. Hashing the key in is what keeps your experiments independent: the
+players in one experiment's first arm are not the same players in every
+other experiment's first arm.
+
+⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new
+count or list re-deals every player. To start over on purpose, use a new
+key.
+
+⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and
+the SDK does not add it to your events. To analyse an experiment, declare a
+dimension for it on the events you want to break down, with the arms as its
+values, named after the experiment, and pass the selection there yourself:
+`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.
+Never the platform's `variant` field, which belongs to store-page
+experiments.
+
+WAITS FOR THE PLAYER. The id arrives with the first play token, so a call
+during boot waits for it, and rejects as [Gem.awaitIdentity](#gem-awaitidentity) does
+when none arrives — outside the Arcade, the Gem Editor or the dev host.
+There is no random fallback: catch the rejection and play your control arm.
+A guest is selected by their guest id, which is stable for as long as their
+guest account lasts; once they sign in to an account they are that
+account's player, and its selection applies.
+
+In a serverless function it selects for the player who invoked it, with
+no wait, and rejects when a game server invoked it.
+
+Works with analytics turned off: it reads no setting and sends nothing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Names the experiment — any non-empty string. |
+| `count` | `number` | How many arms, an integer from 1 to 2048 — or, in the list
+  form, `options`: the arms themselves, 1 to 2048 strings. |
+
+**Returns.** The arm's index, or the chosen string.
+
+**Throws.** TypeError for an empty key or a list holding something other than
+  strings; RangeError for a count or list size outside 1 to 2048. Both
+  reject before waiting for the player.
+
 <a id="analyticsapi-environment"></a>
 
 ## AnalyticsApi.environment
@@ -3680,6 +3746,47 @@ The runtime companion to [PlatformEventName](#platformeventname), for a game tha
 show what it gets for free, or to check a funnel step it authored against
 what the platform actually emits.
 
+<a id="experimentselection"></a>
+
+## experimentSelection
+
+```ts
+function experimentSelection(key: string, playerId: string, count: number): number
+```
+
+Which arm of an experiment a player gets — the same answer for the same key
+and player, every time, anywhere.
+
+In a game, call [AnalyticsApi.experiment](#analyticsapi-experiment) instead: it is this, with
+the signed-in player's id filled in. This form takes the id, for code that
+has one in hand — a dedicated server reproducing what a member's client
+picked, or a test.
+
+Pass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings
+and get one of them. A string listed twice is twice as likely, which is how
+to weight an arm.
+
+The answer is `fmix32(fnv1a32("<key>:<playerId>")) % count`: FNV-1a 32-bit
+over the UTF-8 bytes of the key, a colon and the player id, then
+MurmurHash3's 32-bit finalizer, as an unsigned integer — with a list, the
+index into it. The hash is fixed, so any other language can reproduce a
+selection; docs/analytics.md has it written out.
+
+⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new
+count or list re-deals every player. To start over on purpose, use a new
+key.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Names the experiment — any non-empty string, and the only thing
+  that makes one experiment's split independent of another's. |
+| `playerId` | `string` | The player to select for — [GemIdentity.playerId](#gemidentity-playerid). |
+| `count` | `number` | How many arms, an integer from 1 to 2048 — or, in the list
+  form, `options`: the arms themselves, 1 to 2048 strings. |
+
+**Throws.** TypeError for an empty key or player id, or a list holding something
+  other than strings; RangeError for a count or list size outside 1 to 2048.
+
 <a id="avatar3dprice"></a>
 
 ## Avatar3dPrice
@@ -8136,6 +8243,46 @@ rather than cut it, say. The arcade shows its mute button for your game
 either way where it shows one, so `false` is a promise that your handler goes quiet on
 `muted: true`, and the release checklist holds you to it.
 
+<a id="gemoptions-onaudiochannels"></a>
+
+## GemOptions.onAudioChannels
+
+```ts
+readonly onAudioChannels?: (channels: GemAudioChannels) => void
+```
+
+The player turned your game's music, or its sound effects, on or off with
+the Arcade's **Music** and **Sound** switches. Passing this tells the
+Arcade your game honours the two separately, so both switches work for it.
+
+Called once the Arcade's preferences first arrive, and again whenever
+either value changes. **Turn your music off while `music` is false, and
+your sound effects off while `sounds` is false**, and back on when they
+are true:
+
+```js
+createGem({
+  allowedEmbedders,
+  onAudioChannels: ({ music, sounds }) => {
+    musicBus.gain.value = music ? 1 : 0;   // the music only
+    effectsBus.gain.value = sounds ? 1 : 0; // everything else
+  },
+});
+```
+
+Both are `true` until the Arcade says otherwise, and under an Arcade that
+has no such switches. They are the player's Arcade switches, **not your
+game's settings**: apply them on top of your own music and sound settings
+(music plays while `music` AND your own music setting are on) and never
+save them as the player's choice in your game. `muted` is unchanged —
+still the master mute the SDK applies for you.
+
+Without this option the Arcade cannot tell your music from your effects:
+it mutes your whole game when the player turns both off, and its Music
+switch flips your own `icon: 'music'` toggle when you declared one with
+[Gem.settings](#gem-settings). The same two values are always readable as
+`gem.prefs.music` and `gem.prefs.sounds`.
+
 <a id="gemoptions-selectabletext"></a>
 
 ## GemOptions.selectableText
@@ -8614,6 +8761,38 @@ the SDK counts your document's frames and reports them itself while this
 is true, and the Arcade draws the readout in its own chrome. Do not draw a
 counter of your own over it. `false` when the Arcade never said.
 
+<a id="gemprefs-music"></a>
+
+## GemPrefs.music
+
+```ts
+readonly music: boolean
+```
+
+The player wants your game's music on — the Arcade's **Music** switch.
+`true` when the Arcade never said.
+
+While it is false, stop your music and keep your sound effects playing.
+It sits on top of `muted` and of your own music setting, and is never
+saved as one: see [GemOptions.onAudioChannels](#gemoptions-onaudiochannels), which is how your
+game tells the Arcade it honours this.
+
+<a id="gemprefs-sounds"></a>
+
+## GemPrefs.sounds
+
+```ts
+readonly sounds: boolean
+```
+
+The player wants your game's sound effects on — the Arcade's **Sound**
+switch: every sound that is not your music. `true` when the Arcade never
+said.
+
+While it is false, silence your effects and keep your music playing. It
+sits on top of `muted` and of your own sound settings, and is never saved
+as one: see [GemOptions.onAudioChannels](#gemoptions-onaudiochannels).
+
 <a id="gemprefs-locale"></a>
 
 ## GemPrefs.locale
@@ -8654,6 +8833,39 @@ const volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;
 Unlike `muted` and `reducedMotion`, nothing here is applied for you, and
 nothing obliges you to use it. See the guide's "Game settings" section.
 
+<a id="gemaudiochannels"></a>
+
+## GemAudioChannels
+
+```ts
+interface GemAudioChannels
+```
+
+Which of your game's two audio channels the player wants on, from the
+Arcade's **Music** and **Sound** switches — what
+[GemOptions.onAudioChannels](#gemoptions-onaudiochannels) is called with. Both are `true` when the
+Arcade never said.
+
+<a id="gemaudiochannels-music"></a>
+
+## GemAudioChannels.music
+
+```ts
+readonly music: boolean
+```
+
+Play your music. While false, stop it and keep your effects.
+
+<a id="gemaudiochannels-sounds"></a>
+
+## GemAudioChannels.sounds
+
+```ts
+readonly sounds: boolean
+```
+
+Play your sound effects. While false, silence them and keep your music.
+
 <a id="gemrecommendedsettings"></a>
 
 ## GemRecommendedSettings

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v14.0.3, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v15.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "14.0.3"
+    "version": "15.1.0"
   },
   "entries": [
     {
@@ -4393,6 +4393,35 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AnalyticsApi.experiment",
+          "name": "experiment",
+          "anchor": "analyticsapi-experiment",
+          "group": "analytics",
+          "signature": "experiment(key: string, count: number): Promise<number>",
+          "documented": true,
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": "The arm's index, or the chosen string.",
+          "throws": "TypeError for an empty key or a list holding something other than\n  strings; RangeError for a count or list size outside 1 to 2048. Both\n  reject before waiting for the player.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsApi.environment",
           "name": "environment",
@@ -4496,6 +4525,41 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "experimentSelection",
+          "name": "experimentSelection",
+          "anchor": "experimentselection",
+          "group": "analytics",
+          "signature": "function experimentSelection(key: string, playerId: string, count: number): number",
+          "documented": true,
+          "summary": "Which arm of an experiment a player gets — the same answer for the same key\nand player, every time, anywhere.\n\nIn a game, call [AnalyticsApi.experiment](api-reference-game.md#analyticsapi-experiment) instead: it is this, with\nthe signed-in player's id filled in. This form takes the id, for code that\nhas one in hand — a dedicated server reproducing what a member's client\npicked, or a test.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely, which is how\nto weight an arm.\n\nThe answer is `fmix32(fnv1a32(\"<key>:<playerId>\")) % count`: FNV-1a 32-bit\nover the UTF-8 bytes of the key, a colon and the player id, then\nMurmurHash3's 32-bit finalizer, as an unsigned integer — with a list, the\nindex into it. The hash is fixed, so any other language can reproduce a\nselection; docs/analytics.md has it written out.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string, and the only thing\n  that makes one experiment's split independent of another's."
+            },
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": "The player to select for — [GemIdentity.playerId](api-reference-game.md#gemidentity-playerid)."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": null,
+          "throws": "TypeError for an empty key or player id, or a list holding something\n  other than strings; RangeError for a count or list size outside 1 to 2048.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Avatar3dPrice",
           "name": "Avatar3dPrice",
@@ -9368,6 +9432,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemOptions.onAudioChannels",
+          "name": "onAudioChannels",
+          "anchor": "gemoptions-onaudiochannels",
+          "group": "start",
+          "signature": "readonly onAudioChannels?: (channels: GemAudioChannels) => void",
+          "documented": true,
+          "summary": "The player turned your game's music, or its sound effects, on or off with\nthe Arcade's **Music** and **Sound** switches. Passing this tells the\nArcade your game honours the two separately, so both switches work for it.\n\nCalled once the Arcade's preferences first arrive, and again whenever\neither value changes. **Turn your music off while `music` is false, and\nyour sound effects off while `sounds` is false**, and back on when they\nare true:\n\n```js\ncreateGem({\n  allowedEmbedders,\n  onAudioChannels: ({ music, sounds }) => {\n    musicBus.gain.value = music ? 1 : 0;   // the music only\n    effectsBus.gain.value = sounds ? 1 : 0; // everything else\n  },\n});\n```\n\nBoth are `true` until the Arcade says otherwise, and under an Arcade that\nhas no such switches. They are the player's Arcade switches, **not your\ngame's settings**: apply them on top of your own music and sound settings\n(music plays while `music` AND your own music setting are on) and never\nsave them as the player's choice in your game. `muted` is unchanged —\nstill the master mute the SDK applies for you.\n\nWithout this option the Arcade cannot tell your music from your effects:\nit mutes your whole game when the player turns both off, and its Music\nswitch flips your own `icon: 'music'` toggle when you declared one with\n[Gem.settings](api-reference-game.md#gem-settings). The same two values are always readable as\n`gem.prefs.music` and `gem.prefs.sounds`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemOptions.selectableText",
           "name": "selectableText",
@@ -9799,6 +9879,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemPrefs.music",
+          "name": "music",
+          "anchor": "gemprefs-music",
+          "group": "player",
+          "signature": "readonly music: boolean",
+          "documented": true,
+          "summary": "The player wants your game's music on — the Arcade's **Music** switch.\n`true` when the Arcade never said.\n\nWhile it is false, stop your music and keep your sound effects playing.\nIt sits on top of `muted` and of your own music setting, and is never\nsaved as one: see [GemOptions.onAudioChannels](api-reference-game.md#gemoptions-onaudiochannels), which is how your\ngame tells the Arcade it honours this.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPrefs.sounds",
+          "name": "sounds",
+          "anchor": "gemprefs-sounds",
+          "group": "player",
+          "signature": "readonly sounds: boolean",
+          "documented": true,
+          "summary": "The player wants your game's sound effects on — the Arcade's **Sound**\nswitch: every sound that is not your music. `true` when the Arcade never\nsaid.\n\nWhile it is false, silence your effects and keep your music playing. It\nsits on top of `muted` and of your own sound settings, and is never saved\nas one: see [GemOptions.onAudioChannels](api-reference-game.md#gemoptions-onaudiochannels).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemPrefs.locale",
           "name": "locale",
@@ -9831,6 +9943,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemAudioChannels",
+          "name": "GemAudioChannels",
+          "anchor": "gemaudiochannels",
+          "group": "player",
+          "signature": "interface GemAudioChannels",
+          "documented": true,
+          "summary": "Which of your game's two audio channels the player wants on, from the\nArcade's **Music** and **Sound** switches — what\n[GemOptions.onAudioChannels](api-reference-game.md#gemoptions-onaudiochannels) is called with. Both are `true` when the\nArcade never said.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemAudioChannels.music",
+          "name": "music",
+          "anchor": "gemaudiochannels-music",
+          "group": "player",
+          "signature": "readonly music: boolean",
+          "documented": true,
+          "summary": "Play your music. While false, stop it and keep your effects.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemAudioChannels.sounds",
+          "name": "sounds",
+          "anchor": "gemaudiochannels-sounds",
+          "group": "player",
+          "signature": "readonly sounds: boolean",
+          "documented": true,
+          "summary": "Play your sound effects. While false, silence them and keep your music.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemRecommendedSettings",
           "name": "GemRecommendedSettings",
@@ -27936,6 +28096,35 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AnalyticsApi.experiment",
+          "name": "experiment",
+          "anchor": "analyticsapi-experiment",
+          "group": "analytics",
+          "signature": "experiment(key: string, count: number): Promise<number>",
+          "documented": true,
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": "The arm's index, or the chosen string.",
+          "throws": "TypeError for an empty key or a list holding something other than\n  strings; RangeError for a count or list size outside 1 to 2048. Both\n  reject before waiting for the player.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsApi.environment",
           "name": "environment",

package/docs/changelog.md

@@ -16,6 +16,33 @@ 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.
 
+## 15.1.0
+
+Upgrading from 15.0.0. Impact: none.
+
+### New capability
+
+- AnalyticsApi.experiment gives a player a stable experiment arm. Pass an experiment key and either an arm count or a list of options. It returns the same arm for that player on every call, refresh and device: an index from zero up to one less than the count, or one of the strings in the list. Games that picked an arm with a random number landed a player in a different arm on every refresh, so no test could be read. Switching to this call fixes that. Different experiment keys are independent of each other. Nothing is recorded for you. To analyse an experiment, declare a dimension on the events you choose and pass the selection yourself. The call rejects when there is no player.
+- experimentSelection computes the same arm as AnalyticsApi.experiment from an experiment key, a player id you hold, and an arm count or list of options. Use it where the SDK is not running, such as a dedicated game server or an analytics query, to reproduce which arm a player was given.
+
+## 15.0.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 14.0.3. Impact: required.
+
+### Must change
+
+- GemCapability changed its signature.
+- GemHost.sendPrefs changed its signature.
+
+### New capability
+
+- GemAudioChannels was added.
+- GemOptions.onAudioChannels was added.
+- GemPrefs.music was added.
+- GemPrefs.sounds was added.
+
 ## 14.0.3
 
 Upgrading from 14.0.2. Impact: none.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "94baa26268843ba926462633ddec8aaca56aabf79ee6639aaf77df68474debc7",
-      "updated": "2026-10-17T00:33:31Z"
+      "sha256": "afced8f94514818eca6de3e72bdd988b2cee10925086c3bfa47c0a8ec8967454",
+      "updated": "2026-10-23T00:13:14Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "7858f383ced2f344a4f7852bd4d0ae8d3a2f114f21d2e6e7660e64dd6e2220ae",
-      "updated": "2026-10-21T20:47:06Z"
+      "sha256": "6b47b52430c201a1eb48a4823b6e3ca59d1e82982428eab0ab7ac3016cc044c1",
+      "updated": "2026-10-23T00:49:37Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "5b5a3affd113400ea9aecbc6af254831ff543278c125a9a11a18fa08ed390171",
-      "updated": "2026-10-21T20:47:06Z"
+      "sha256": "68ddb1e937d14ba27aadbb2cd19ae59d0cb9048ec2d4435b4d80f87e8ac1eb1a",
+      "updated": "2026-10-23T00:49:37Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "72e4035ee007042a4bae279afd4440f36c8d64e0c750978fac6a150fad190d78",
-      "updated": "2026-10-21T20:47:06Z"
+      "sha256": "c30b720cf1b65dc4e7a2ed25f1dfc86d9c86ba11d69509b45c63183649f3a7aa",
+      "updated": "2026-10-23T00:49:37Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "a0f1fd58acd28c72cca3574032c087ffbe2cb34e311086c99eceec7e2f9b7f20",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "1dae31932542cf7d49e8b1c1bc456e62cfb72204e88ea776919cca12c690c859",
+      "updated": "2026-10-22T15:46:02Z"
     }
   ]
 }

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/v14.0.3/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v14.0.3/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v15.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v15.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```