@indiegems/gem-web-sdk 13.4.2 → 14.0.0

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v13.4.2, 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` v14.0.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.
 
@@ -5854,6 +5854,30 @@ connected, and only to an arcade that draws a menu.
 **Returns.** whether the message left the frame — `false` before the bridge is
   up, for an arcade with no menu, and past this frame's own limit.
 
+<a id="gemframe-declaresettings"></a>
+
+## GemFrame.declareSettings
+
+```ts
+declareSettings(settings: { id: string; label: string; kind: "toggle" | "slider" | "choice"; value: string | number | boolean; quick?: boolean; icon?: string; min?: number; max?: number; step?: number; options?: { id: string; label: string }[] }[]): boolean
+```
+
+Mirror up to eight of your game's own settings into the arcade's menu —
+the whole list each time, the latest one winning.
+
+Prefer `gem.settings.declare`, which checks each entry, holds the list
+across a reconnect and calls your handlers when the player changes one.
+This one sends only while connected, and only to an arcade that draws game
+settings.
+
+| Parameter | Type |
+| --- | --- |
+| `settings` | `{ id: string; label: string; kind: "toggle" \| "slider" \| "choice"; value: string \| number \| boolean; quick?: boolean; icon?: string; min?: number; max?: number; step?: number; options?: { id: string; label: string }[] }[]` |
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade that draws no game settings, for a list the schema
+  refuses, and past this frame's own limit.
+
 <a id="gemframe-setgemcorner"></a>
 
 ## GemFrame.setGemCorner
@@ -7222,6 +7246,470 @@ const { accepted, why } = result.json();
   own `Err`. `TransportRefusal` for an input that is neither bytes nor
   JSON, before anything is sent. `AuthError` if the token cannot be renewed.
 
+<a id="gemgamesettingicon"></a>
+
+## GemGameSettingIcon
+
+```ts
+type GemGameSettingIcon = "music" | "sfx" | "voice" | "eye" | "text" | "hint" | "speed" | "bright" | "controls" | "star"
+```
+
+The icon codes a declared setting may carry — the Arcade draws the glyph. An
+icon is optional, and a setting without one gets the Arcade's generic glyph.
+
+<a id="gemgamesettingvalue"></a>
+
+## GemGameSettingValue
+
+```ts
+type GemGameSettingValue = boolean | number | string
+```
+
+The value of a declared setting: `boolean` for a toggle, `number` for a
+slider, and an option's `id` for a choice.
+
+<a id="gemgamesettingbase"></a>
+
+## GemGameSettingBase
+
+```ts
+interface GemGameSettingBase
+```
+
+What every declared setting has, whatever its kind.
+
+<a id="gemgamesettingbase-id"></a>
+
+## GemGameSettingBase.id
+
+```ts
+readonly id: string
+```
+
+Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in
+one declaration. It is what [GemGameSettingChange.id](#gemgamesettingchange-id) carries back.
+
+<a id="gemgamesettingbase-label"></a>
+
+## GemGameSettingBase.label
+
+```ts
+readonly label: string
+```
+
+What the player reads, 1 to 40 characters, **already in the player's
+language** (`gem.prefs.locale`): the Arcade does not translate it. Cut at
+40 characters.
+
+<a id="gemgamesettingbase-icon"></a>
+
+## GemGameSettingBase.icon
+
+```ts
+readonly icon?: GemGameSettingIcon
+```
+
+One of the Arcade's icon codes; a code this SDK does not know is left out
+(with a warning) and the setting is kept with the generic glyph.
+
+<a id="gemgametogglesetting"></a>
+
+## GemGameToggleSetting
+
+```ts
+interface GemGameToggleSetting
+```
+
+An on/off setting — Music, Color help.
+
+<a id="gemgametogglesetting-id"></a>
+
+## GemGameToggleSetting.id
+
+```ts
+readonly id: string
+```
+
+Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in
+one declaration. It is what [GemGameSettingChange.id](#gemgamesettingchange-id) carries back.
+
+<a id="gemgametogglesetting-label"></a>
+
+## GemGameToggleSetting.label
+
+```ts
+readonly label: string
+```
+
+What the player reads, 1 to 40 characters, **already in the player's
+language** (`gem.prefs.locale`): the Arcade does not translate it. Cut at
+40 characters.
+
+<a id="gemgametogglesetting-icon"></a>
+
+## GemGameToggleSetting.icon
+
+```ts
+readonly icon?: GemGameSettingIcon
+```
+
+One of the Arcade's icon codes; a code this SDK does not know is left out
+(with a warning) and the setting is kept with the generic glyph.
+
+<a id="gemgametogglesetting-kind"></a>
+
+## GemGameToggleSetting.kind
+
+```ts
+readonly kind: "toggle"
+```
+
+`'toggle'`: what kind of setting this is.
+
+<a id="gemgametogglesetting-value"></a>
+
+## GemGameToggleSetting.value
+
+```ts
+readonly value: boolean
+```
+
+Whether it is on now.
+
+<a id="gemgametogglesetting-quick"></a>
+
+## GemGameToggleSetting.quick
+
+```ts
+readonly quick?: boolean
+```
+
+Ask for this toggle in the menu's quick row, beside the Arcade's own Sound
+and Vibration. The first two toggles that ask get it; a third is shown only
+in the settings list.
+
+<a id="gemgameslidersetting"></a>
+
+## GemGameSliderSetting
+
+```ts
+interface GemGameSliderSetting
+```
+
+A number between two ends — Music volume, Game speed.
+
+<a id="gemgameslidersetting-id"></a>
+
+## GemGameSliderSetting.id
+
+```ts
+readonly id: string
+```
+
+Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in
+one declaration. It is what [GemGameSettingChange.id](#gemgamesettingchange-id) carries back.
+
+<a id="gemgameslidersetting-label"></a>
+
+## GemGameSliderSetting.label
+
+```ts
+readonly label: string
+```
+
+What the player reads, 1 to 40 characters, **already in the player's
+language** (`gem.prefs.locale`): the Arcade does not translate it. Cut at
+40 characters.
+
+<a id="gemgameslidersetting-icon"></a>
+
+## GemGameSliderSetting.icon
+
+```ts
+readonly icon?: GemGameSettingIcon
+```
+
+One of the Arcade's icon codes; a code this SDK does not know is left out
+(with a warning) and the setting is kept with the generic glyph.
+
+<a id="gemgameslidersetting-kind"></a>
+
+## GemGameSliderSetting.kind
+
+```ts
+readonly kind: "slider"
+```
+
+`'slider'`: what kind of setting this is.
+
+<a id="gemgameslidersetting-value"></a>
+
+## GemGameSliderSetting.value
+
+```ts
+readonly value: number
+```
+
+The number now. Clamped into `[min, max]` and snapped onto `step` before it
+is sent.
+
+<a id="gemgameslidersetting-min"></a>
+
+## GemGameSliderSetting.min
+
+```ts
+readonly min?: number
+```
+
+The lowest value, `0` when left out. Within ±1 000 000, below `max`.
+
+<a id="gemgameslidersetting-max"></a>
+
+## GemGameSliderSetting.max
+
+```ts
+readonly max?: number
+```
+
+The highest value, `100` when left out. Within ±1 000 000, above `min`.
+
+<a id="gemgameslidersetting-step"></a>
+
+## GemGameSliderSetting.step
+
+```ts
+readonly step?: number
+```
+
+The increment from `min`, `1` when left out. Greater than `0`.
+
+<a id="gemgamesettingoption"></a>
+
+## GemGameSettingOption
+
+```ts
+interface GemGameSettingOption
+```
+
+One answer of a [GemGameChoiceSetting](#gemgamechoicesetting).
+
+<a id="gemgamesettingoption-id"></a>
+
+## GemGameSettingOption.id
+
+```ts
+readonly id: string
+```
+
+Your own name for the answer, 1 to 40 of `A-Z a-z 0-9 _ -`.
+
+<a id="gemgamesettingoption-label"></a>
+
+## GemGameSettingOption.label
+
+```ts
+readonly label: string
+```
+
+What the player reads, 1 to 40 characters, already translated.
+
+<a id="gemgamechoicesetting"></a>
+
+## GemGameChoiceSetting
+
+```ts
+interface GemGameChoiceSetting
+```
+
+One of two to four answers — Difficulty: Easy, Normal, Hard.
+
+<a id="gemgamechoicesetting-id"></a>
+
+## GemGameChoiceSetting.id
+
+```ts
+readonly id: string
+```
+
+Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in
+one declaration. It is what [GemGameSettingChange.id](#gemgamesettingchange-id) carries back.
+
+<a id="gemgamechoicesetting-label"></a>
+
+## GemGameChoiceSetting.label
+
+```ts
+readonly label: string
+```
+
+What the player reads, 1 to 40 characters, **already in the player's
+language** (`gem.prefs.locale`): the Arcade does not translate it. Cut at
+40 characters.
+
+<a id="gemgamechoicesetting-icon"></a>
+
+## GemGameChoiceSetting.icon
+
+```ts
+readonly icon?: GemGameSettingIcon
+```
+
+One of the Arcade's icon codes; a code this SDK does not know is left out
+(with a warning) and the setting is kept with the generic glyph.
+
+<a id="gemgamechoicesetting-kind"></a>
+
+## GemGameChoiceSetting.kind
+
+```ts
+readonly kind: "choice"
+```
+
+`'choice'`: what kind of setting this is.
+
+<a id="gemgamechoicesetting-value"></a>
+
+## GemGameChoiceSetting.value
+
+```ts
+readonly value: string
+```
+
+The `id` of the option chosen now.
+
+<a id="gemgamechoicesetting-options"></a>
+
+## GemGameChoiceSetting.options
+
+```ts
+readonly options: readonly GemGameSettingOption[]
+```
+
+Two to four answers, ids unique. A fifth and later are left out.
+
+<a id="gemgamesetting"></a>
+
+## GemGameSetting
+
+```ts
+type GemGameSetting = GemGameToggleSetting | GemGameSliderSetting | GemGameChoiceSetting
+```
+
+One of your game's settings, as `gem.settings.declare` mirrors it into the
+Arcade's menu: a toggle, a slider or a choice.
+
+<a id="gemgamesettingchange"></a>
+
+## GemGameSettingChange
+
+```ts
+interface GemGameSettingChange
+```
+
+The player changed one of your declared settings in the Arcade's menu.
+
+<a id="gemgamesettingchange-id"></a>
+
+## GemGameSettingChange.id
+
+```ts
+readonly id: string
+```
+
+The setting's `id`, from your latest declaration.
+
+<a id="gemgamesettingchange-value"></a>
+
+## GemGameSettingChange.value
+
+```ts
+readonly value: GemGameSettingValue
+```
+
+The new value, of the setting's kind: a `boolean` for a toggle, a `number`
+inside a slider's range and on its step, an option's `id` for a choice.
+
+<a id="gamesettingsapi"></a>
+
+## GameSettingsApi
+
+```ts
+interface GameSettingsApi
+```
+
+`gem.settings` — mirror up to eight of your game's own settings into the
+Arcade's Gem menu. Your own settings button and screen stay: this is a
+second door to a few of the same settings, never the only one.
+
+<a id="gamesettingsapi-declare"></a>
+
+## GameSettingsApi.declare
+
+```ts
+declare(settings: readonly GemGameSetting[]): boolean
+```
+
+Show up to eight of your settings in the Arcade's menu, in this order — the
+whole list each time, the latest call winning. `declare([])` takes them
+all back out.
+
+```js
+gem.settings.declare([
+  { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, quick: true, icon: 'music' },
+  { id: 'speed', label: t('Game speed'), kind: 'slider', value: speed, min: 0.5, max: 2, step: 0.25 },
+]);
+```
+
+**Keep your own settings button and screen** — top-right, on every screen.
+This mirrors a few of those settings; it never replaces them, and an
+embedder that draws no game settings shows none of it.
+
+**Declare again whenever your own screen changes a value**, so the menu
+never shows a stale one. Mark at most two toggles `quick` (good ones:
+Music, Sound effects, Color help). **Never declare the Arcade's own
+settings** — master volume or mute, vibration, graphics quality, controls:
+the Arcade already has them and they reach you as `gem.prefs`.
+
+An entry that breaks a rule is left out, with a warning through your
+`log`; nothing throws.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `settings` | `readonly GemGameSetting[]` | Up to eight settings, in the order to show them. |
+
+**Returns.** `true` when the Arcade has been told, or will be within half a
+  second; `false` before the bridge is up (the list is held and sent when
+  it connects), under an embedder that draws no game settings, and for an
+  argument that is not an array.
+
+<a id="gamesettingsapi-onchange"></a>
+
+## GameSettingsApi.onChange
+
+```ts
+onChange(handler: (change: GemGameSettingChange) => void): () => void
+```
+
+Called when the player changes one of your declared settings in the
+Arcade's menu. Apply it at once, **even while paused** — the menu holds
+the pause, and the player should hear the music stop while it is open —
+and keep it where you keep that setting's other changes.
+
+```js
+gem.settings.onChange(({ id, value }) => {
+  if (id === 'music') setMusic(value === true);
+});
+```
+
+The SDK has already written the new value into your declaration, so there
+is no need to declare again for this change.
+
+| Parameter | Type |
+| --- | --- |
+| `handler` | `(change: GemGameSettingChange) => void` |
+
+**Returns.** A function that removes the handler.
+
 <a id="arcade_embedders"></a>
 
 ## ARCADE_EMBEDDERS
@@ -7761,21 +8249,22 @@ readonly onScreenshot?: (request: { maxWidth: number; maxHeight: number }) => Pr
 Supply the screenshot yourself, instead of letting the SDK find it.
 
 **You do not need this to get screenshots.** By default the SDK captures
-your largest visible canvas, which is right for almost every game.
-
-⚠️ A WebGL game must create its context with `{ preserveDrawingBuffer: true }`
-for that default to work — without it the SDK refuses the capture rather
-than sending your team a black image, and your reports arrive with no
-picture. That is a one-line change and NOT a reason to reach for this
-option.
+your largest visible canvas, which is right for almost every game: 2D,
+WebGL or WebGPU, and WITHOUT `preserveDrawingBuffer`, which you should leave
+off. The SDK reads the canvas right after a frame you draw, or keeps the
+last one you drew before your loop stopped. That needs `createGem` called
+before your renderer is made, and drawing inside `requestAnimationFrame`.
 
 Reach for it when the default genuinely cannot work, or when you want a say
 per moment:
 
-- your canvas is an `OffscreenCanvas` driven from a worker, or a WebGPU
-  surface — nothing on the page can read either, no flag changes that, and
-  the platform reports `unreadable` rather than `unsupported` precisely so
-  you do not go looking for a flag;
+- your canvas is an `OffscreenCanvas` driven from a worker. Nothing on the
+  page can read it, no flag changes that, and the platform reports
+  `unreadable` rather than `unsupported` precisely so you do not go looking
+  for a flag;
+- you draw outside `requestAnimationFrame`, so there is no moment the SDK
+  can read your canvas in: render, then `createImageBitmap(canvas)`, in the
+  same task;
 - you draw across several layered canvases and want them composited;
 - you want to decline while something specific is on screen.
 
@@ -9297,6 +9786,35 @@ camera.pitch += t.pitch;
 
 See the guide's "Camera and look controls" section.
 
+<a id="gem-settings"></a>
+
+## Gem.settings
+
+```ts
+readonly settings: GameSettingsApi
+```
+
+Mirror up to eight of your game's own settings — Music, Color help, Game
+speed — into the Arcade's Gem menu, and hear when the player changes one
+there. Up to two toggles can sit in the menu's quick row.
+
+```js
+gem.settings.declare([
+  { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, quick: true, icon: 'music' },
+]);
+gem.settings.onChange(({ id, value }) => {
+  if (id === 'music') setMusic(value === true); // even while paused
+});
+```
+
+**A mirror, never a replacement: your game still draws its own settings
+button and screen**, and every setting you declare is on that screen too.
+Declare again whenever your screen changes a value. Never declare the
+Arcade's own settings — master volume or mute, vibration, graphics,
+controls; they reach you as `gem.prefs`.
+
+See the guide's "Game settings" section.
+
 <a id="gem-analytics"></a>
 
 ## Gem.analytics

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v13.4.2, 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` v14.0.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.