@indiegems/gem-web-sdk 13.4.3 → 14.0.1

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.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` v14.0.1, 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,500 @@ 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.
+
+In the Gem Arcade the icon also fills its fixed quick row (Music, Sound,
+Color, Vibration): the first **toggle** with `'music'` is the Music slot
+and the first toggle with `'eye'` is the Color slot. Give those two icons
+to your music on/off and colour-help toggles, and to no other setting.
+
+<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.
+
+In the Gem Arcade the icon also fills its fixed quick row (Music, Sound,
+Color, Vibration): the first **toggle** with `'music'` is the Music slot
+and the first toggle with `'eye'` is the Color slot. Give those two icons
+to your music on/off and colour-help toggles, and to no other setting.
+
+<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
+```
+
+**Ignored by the Gem Arcade**, whose quick row is fixed — Music, Sound,
+Color, Vibration — and filled by [GemGameSettingBase.icon](#gemgamesettingbase-icon)
+(`'music'`, `'eye'`), not by this flag. Kept for other embedders, which
+may show the first two toggles that ask in a quick row of their own;
+leaving it out is fine.
+
+<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.
+
+In the Gem Arcade the icon also fills its fixed quick row (Music, Sound,
+Color, Vibration): the first **toggle** with `'music'` is the Music slot
+and the first toggle with `'eye'` is the Color slot. Give those two icons
+to your music on/off and colour-help toggles, and to no other setting.
+
+<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.
+
+In the Gem Arcade the icon also fills its fixed quick row (Music, Sound,
+Color, Vibration): the first **toggle** with `'music'` is the Music slot
+and the first toggle with `'eye'` is the Color slot. Give those two icons
+to your music on/off and colour-help toggles, and to no other setting.
+
+<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 your game's own settings, up to eight, into the
+Arcade's Gem menu. Your own settings button and screen stay: this is a
+second door to 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, icon: 'music' },
+  { id: 'colors', label: t('Color help'), kind: 'toggle', value: colorHelp, icon: 'eye' },
+  { 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 those settings; it never replaces them, and an embedder that
+draws no game settings shows none of it.
+
+The Gem Arcade's Settings screen lists **every** setting you declare, so
+declare all of yours. Its quick row is fixed — Music, Sound, Color and
+Vibration (phones and tablets), with the Arcade's own labels: your first
+toggle with `icon: 'music'` fills Music, your first with `icon: 'eye'`
+fills Color, and a slot you do not fill stays greyed. It ignores `quick`.
+
+**Declare again whenever your own screen changes a value**, so the menu
+never shows a stale one. **Never declare a second mute or vibration
+switch** — the quick row has the Arcade's own. Your game's own volume,
+music and sound-effects levels are yours to declare; graphics quality and
+the controls defaults stay the Arcade's and reach you as
+`gem.prefs.recommended`.
+
+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
@@ -9298,6 +9816,38 @@ 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 your game's own settings, up to eight — Music, Color help, Game
+speed — into the Arcade's Gem menu, and hear when the player changes one
+there. The Arcade's Settings screen lists every one; its fixed quick row
+takes your first toggle with `icon: 'music'` as Music and your first with
+`icon: 'eye'` as Color (`quick` is ignored by the Gem Arcade).
+
+```js
+gem.settings.declare([
+  { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, 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 a
+second mute or vibration switch — the Arcade's quick row has them; your
+own volume and music or sound-effects levels are fine, and graphics and
+controls defaults stay the Arcade's (`gem.prefs.recommended`).
+
+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.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` v14.0.1, 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.