@indiegems/gem-web-sdk 10.1.1 → 10.3.0

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v10.1.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.
+Generated from `@indiegems/gem-web-sdk/sdk` v10.3.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.
 
@@ -4590,6 +4590,417 @@ only when your studio corrects a running period; clients may hold the old
 content for up to an hour afterwards, and the hash is how a verifier tells
 them apart.
 
+<a id="gemlookspeed"></a>
+
+## GemLookSpeed
+
+```ts
+interface GemLookSpeed
+```
+
+A look speed per axis, in radians: per CSS px for a pointer, per second at
+full tilt for a stick.
+
+<a id="gemlookspeed-yaw"></a>
+
+## GemLookSpeed.yaw
+
+```ts
+readonly yaw: number
+```
+
+Across: radians of yaw.
+
+<a id="gemlookspeed-pitch"></a>
+
+## GemLookSpeed.pitch
+
+```ts
+readonly pitch: number
+```
+
+Up/down: radians of pitch.
+
+<a id="gemlookbase"></a>
+
+## GemLookBase
+
+```ts
+interface GemLookBase
+```
+
+The shape of `gem.controls.LOOK_BASE`: Roblox's base look speeds and the
+stick and touch shaping constants `gem.controls.look()` applies.
+
+<a id="gemlookbase-touch"></a>
+
+## GemLookBase.touch
+
+```ts
+readonly touch: GemLookSpeed
+```
+
+Radians per CSS px, for touch and pen: 1° across, 0.66° up/down.
+
+<a id="gemlookbase-mouse"></a>
+
+## GemLookBase.mouse
+
+```ts
+readonly mouse: GemLookSpeed
+```
+
+Radians per CSS px, for a mouse: 0.5° across, 0.385° up/down.
+
+<a id="gemlookbase-stick"></a>
+
+## GemLookBase.stick
+
+```ts
+readonly stick: GemLookSpeed
+```
+
+Radians per second at full tilt, for a gamepad stick: 240° across, 184.8° up/down.
+
+<a id="gemlookbase-stickdeadzone"></a>
+
+## GemLookBase.stickDeadzone
+
+```ts
+readonly stickDeadzone: number
+```
+
+A stick axis below this magnitude turns nothing: 0.1.
+
+<a id="gemlookbase-stickcurve"></a>
+
+## GemLookBase.stickCurve
+
+```ts
+readonly stickCurve: number
+```
+
+The stick curve's curvature `k` in `(e^(k·d) − 1) / (e^k − 1)`: 2.
+
+<a id="gemlookbase-touchpitchmin"></a>
+
+## GemLookBase.touchPitchMin
+
+```ts
+readonly touchPitchMin: number
+```
+
+The least fraction of the pitch speed a touch drag keeps straight up or down: 0.25.
+
+<a id="gemlookoptions"></a>
+
+## GemLookOptions
+
+```ts
+interface GemLookOptions
+```
+
+The game's own overrides for `gem.controls.look()` — what the player chose in
+YOUR settings screen. Each one wins over the Arcade's value; leave one out to
+follow the Arcade.
+
+<a id="gemlookoptions-sensitivity"></a>
+
+## GemLookOptions.sensitivity
+
+```ts
+readonly sensitivity?: number
+```
+
+The player's own look speed for touch, mouse and pen, as a multiplier
+(`1` = the base speed). Wins over `gem.prefs.recommended.lookSensitivity`.
+
+<a id="gemlookoptions-gamepadsensitivity"></a>
+
+## GemLookOptions.gamepadSensitivity
+
+```ts
+readonly gamepadSensitivity?: number
+```
+
+The player's own look speed for a gamepad stick, as a multiplier. Wins
+over `gem.prefs.recommended.gamepadLookSensitivity`.
+
+<a id="gemlookoptions-inverty"></a>
+
+## GemLookOptions.invertY
+
+```ts
+readonly invertY?: boolean
+```
+
+The player's own inverted up/down look. Wins over
+`gem.prefs.recommended.invertLookY`.
+
+<a id="gemlookdelta"></a>
+
+## GemLookDelta
+
+```ts
+interface GemLookDelta
+```
+
+A turn to apply to your camera, in radians to ADD: `yaw` positive turns
+right (clockwise seen from above), `pitch` positive looks up.
+
+<a id="gemlookdelta-yaw"></a>
+
+## GemLookDelta.yaw
+
+```ts
+readonly yaw: number
+```
+
+Radians to add to the camera's yaw; positive turns right.
+
+<a id="gemlookdelta-pitch"></a>
+
+## GemLookDelta.pitch
+
+```ts
+readonly pitch: number
+```
+
+Radians to add to the camera's pitch; positive looks up.
+
+<a id="gemlook"></a>
+
+## GemLook
+
+```ts
+interface GemLook
+```
+
+The look helper `gem.controls.look()` returns. Pure math: it listens to
+nothing and moves no camera — feed it the deltas your input code already
+has and add what it returns to your camera's yaw and pitch, then clamp the
+pitch as you always do.
+
+<a id="gemlook-frompointer"></a>
+
+## GemLook.fromPointer
+
+```ts
+fromPointer(dx: number, dy: number, pointerType: string, pitch?: number): GemLookDelta
+```
+
+A pointer move — a touch drag, a mouse move (under pointer lock,
+`movementX` / `movementY`) or a pen — turned into a look turn.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `dx` | `number` | The move across, in CSS px, right positive. |
+| `dy` | `number` | The move down the screen, in CSS px, DOWN positive (as
+  `PointerEvent` reports it). Dragging up looks up. |
+| `pointerType` | `string` | The event's `pointerType`: `'touch'` and `'pen'` take
+  the touch speeds, anything else the mouse speeds. |
+| `pitch` | `number` | The camera's current pitch in radians (0 = the horizon,
+  positive = looking up), for the touch slowdown near straight up or
+  down. Leave it out to skip the slowdown. |
+
+<a id="gemlook-fromstick"></a>
+
+## GemLook.fromStick
+
+```ts
+fromStick(x: number, y: number, dt: number): GemLookDelta
+```
+
+A right stick turned into a look turn over one frame.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `x` | `number` | The stick's horizontal axis as the Gamepad API reports it,
+  −1..1, right positive. |
+| `y` | `number` | The stick's vertical axis as the Gamepad API reports it, −1..1,
+  DOWN positive. Pushing up looks up. |
+| `dt` | `number` | The frame's duration in seconds. |
+
+<a id="gemlook-set"></a>
+
+## GemLook.set
+
+```ts
+set(options: GemLookOptions): void
+```
+
+Change your game's overrides — call it when the player changes a setting
+in your settings screen. Each key you pass replaces that override; a key
+passed as `undefined` removes it, so that input follows the Arcade again;
+a key you leave out is unchanged.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `GemLookOptions` |
+
+**Throws.** TypeError when a sensitivity is not a finite number above 0, or
+  `invertY` is not a boolean.
+
+<a id="controlsapi"></a>
+
+## ControlsApi
+
+```ts
+interface ControlsApi
+```
+
+`gem.controls` — the player's camera and controls settings: tell the Arcade
+which ones your game leaves to the player, and turn look input into a camera
+turn at the player's sensitivity.
+
+**Guides.** [what-a-game-must-do](../what-a-game-must-do.md)
+
+<a id="controlsapi-declare"></a>
+
+## ControlsApi.declare
+
+```ts
+declare(uses: GemControlsDeclaration): boolean
+```
+
+Tell the Arcade which of the player's camera and controls settings your
+game uses, and for each one who decides it: `'player'` — you apply the
+Arcade's value from `gem.prefs.recommended` (or the player's own choice
+in your settings, which wins) — or `'game'` — you decide it yourself, and
+the Arcade's Settings shows that row as "Set by this game". Leave out a
+setting your game does not use.
+
+```js
+gem.controls.declare({
+  lookSensitivity: 'player',
+  gamepadLookSensitivity: 'player',
+  invertLookY: 'player',
+  touchMovement: 'game', // this game always uses a fixed stick
+});
+```
+
+**It is screen state, not a toggle.** Each call is the whole answer and
+replaces the last. The SDK holds it and sends it again after every
+reconnect, so call it once at boot, and again only when the answer
+changes. Any other key or value is dropped.
+
+| Parameter | Type |
+| --- | --- |
+| `uses` | `GemControlsDeclaration` |
+
+**Returns.** `true` when the Arcade was told now; `false` before the bridge is
+  up (the declaration is held and sent when it connects), outside the
+  Arcade, and under an embedder that does not show these settings. Never
+  throws.
+
+<a id="controlsapi-look"></a>
+
+## ControlsApi.look
+
+```ts
+look(options?: GemLookOptions): GemLook
+```
+
+Make a look helper: Roblox's camera-input math at the player's look
+sensitivity and invert. Make one and keep it.
+
+```js
+const look = gem.controls.look();
+// A mouse under pointer lock; for touch, pass the change in clientX/clientY.
+canvas.addEventListener('pointermove', (e) => {
+  if (document.pointerLockElement !== canvas) return;
+  const t = look.fromPointer(e.movementX, e.movementY, e.pointerType, camera.pitch);
+  camera.yaw += t.yaw;
+  camera.pitch = clamp(camera.pitch + t.pitch, -1.4, 1.4);
+});
+```
+
+The sensitivity and invert are read **live** on every call: the Arcade's
+`gem.prefs.recommended` values, unless `options` (or a later
+[GemLook.set](#gemlook-set)) gives your game's own, which win.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `GemLookOptions` |
+
+**Throws.** TypeError when an option is malformed, as [GemLook.set](#gemlook-set).
+
+<a id="controlsapi-look_base"></a>
+
+## ControlsApi.LOOK_BASE
+
+```ts
+readonly LOOK_BASE: GemLookBase
+```
+
+The base speeds `look` applies at 1×, in radians. Frozen.
+
+<a id="gemcontrolchoice"></a>
+
+## GemControlChoice
+
+```ts
+type GemControlChoice = "player" | "game"
+```
+
+Who decides one camera or controls setting: `'player'` — your game applies
+the Arcade's value, or the player's own in-game choice, which wins — or
+`'game'` — your game decides it itself, and the Arcade's Settings shows the
+row as "Set by this game".
+
+<a id="gemcontrolsdeclaration"></a>
+
+## GemControlsDeclaration
+
+```ts
+interface GemControlsDeclaration
+```
+
+What `gem.controls.declare` takes: for each of the player's camera and
+controls settings your game uses, who decides it. Leave a setting out when
+your game does not use it at all — the Arcade then says "This game doesn't
+use this" beside that row.
+
+<a id="gemcontrolsdeclaration-looksensitivity"></a>
+
+## GemControlsDeclaration.lookSensitivity
+
+```ts
+readonly lookSensitivity?: GemControlChoice
+```
+
+Look speed for touch, mouse and pen — `gem.prefs.recommended.lookSensitivity`.
+
+<a id="gemcontrolsdeclaration-gamepadlooksensitivity"></a>
+
+## GemControlsDeclaration.gamepadLookSensitivity
+
+```ts
+readonly gamepadLookSensitivity?: GemControlChoice
+```
+
+Look speed for a gamepad stick — `gem.prefs.recommended.gamepadLookSensitivity`.
+
+<a id="gemcontrolsdeclaration-invertlooky"></a>
+
+## GemControlsDeclaration.invertLookY
+
+```ts
+readonly invertLookY?: GemControlChoice
+```
+
+Inverted up/down look — `gem.prefs.recommended.invertLookY`.
+
+<a id="gemcontrolsdeclaration-touchmovement"></a>
+
+## GemControlsDeclaration.touchMovement
+
+```ts
+readonly touchMovement?: GemControlChoice
+```
+
+The touch movement thumbstick, floating or fixed — `gem.prefs.recommended.touchMovement`.
+
 <a id="device_settings_max_bytes"></a>
 
 ## DEVICE_SETTINGS_MAX_BYTES
@@ -5149,6 +5560,30 @@ wallet.
 **Returns.** whether the message left the frame — `false` before the bridge is
   up, for an arcade with no wallet, and past this frame's own limit.
 
+<a id="gemframe-declarecontrols"></a>
+
+## GemFrame.declareControls
+
+```ts
+declareControls(uses: GemControlsDeclaration): boolean
+```
+
+Tell the arcade which of the player's camera and controls settings your
+game leaves to the player and which it decides itself — the whole answer
+each time, the latest one winning.
+
+Prefer `gem.controls.declare`, which holds the declaration across a
+reconnect. This one sends only while connected, and only to an arcade
+that shows these settings.
+
+| Parameter | Type |
+| --- | --- |
+| `uses` | `GemControlsDeclaration` |
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade that does not show these settings, and past this
+  frame's own limit.
+
 <a id="gemframe-setmenu"></a>
 
 ## GemFrame.setMenu
@@ -5198,6 +5633,24 @@ arcade that handles share.
   up, for an arcade that does not handle share, and past this frame's own
   limit of six a minute.
 
+<a id="gemframe-requestavatarpicker"></a>
+
+## GemFrame.requestAvatarPicker
+
+```ts
+requestAvatarPicker(): boolean
+```
+
+Ask the arcade to open its own avatar picker over your game. Nothing comes
+back: a changed portrait arrives as a new `gem.player`, through `onPlayer`.
+
+Prefer `gem.openAvatarPicker`, which documents what a game does with the
+change.
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade that has no avatar picker here, and past this frame's
+  own limit of six a minute.
+
 <a id="gemframe-requestvibrate"></a>
 
 ## GemFrame.requestVibrate
@@ -5332,7 +5785,10 @@ The precomposed `Name#0001`. It contains the name, so it is
 readonly avatarIconId?: string
 ```
 
-The id of the player's portrait item, when they have one.
+The id of the player's portrait item, when they have one — what a game
+that draws Arcade avatars keys its own model on. On `gem.player` it
+changes when the player wears another portrait, and `onPlayer` runs again;
+see `gem.openAvatarPicker`.
 
 <a id="friend-avatariconurl"></a>
 
@@ -7137,7 +7593,10 @@ The precomposed `Name#0001`. It contains the name, so it is
 readonly avatarIconId?: string
 ```
 
-The id of the player's portrait item, when they have one.
+The id of the player's portrait item, when they have one — what a game
+that draws Arcade avatars keys its own model on. On `gem.player` it
+changes when the player wears another portrait, and `onPlayer` runs again;
+see `gem.openAvatarPicker`.
 
 <a id="gemplayer-avatariconurl"></a>
 
@@ -7244,8 +7703,9 @@ readonly recommended: GemRecommendedSettings | null
 ```
 
 The player's Arcade-wide defaults for this device — a volume, battery
-saver, a keyboard layout, the gamepad's confirm button and vibration — or
-`null` when the Arcade did not send them.
+saver, a keyboard layout, the gamepad's confirm button, vibration, and the
+camera and controls settings (look sensitivity, gamepad look sensitivity,
+invert look, touch movement) — or `null` when the Arcade did not send them.
 
 **Recommendations only; the player's own choice in your game wins.** Start
 a setting from here while the player has made no choice of their own for
@@ -7329,6 +7789,54 @@ readonly vibration: boolean
 
 Whether the player wants vibration and controller rumble.
 
+<a id="gemrecommendedsettings-looksensitivity"></a>
+
+## GemRecommendedSettings.lookSensitivity
+
+```ts
+readonly lookSensitivity: number
+```
+
+The player's look speed for touch, mouse and pen, as a percentage of the
+base speeds: `100` is 1×, from `20` (0.2×) to `400` (4×). `100` when the
+Arcade did not say. `gem.controls.look()` applies it for you.
+
+<a id="gemrecommendedsettings-gamepadlooksensitivity"></a>
+
+## GemRecommendedSettings.gamepadLookSensitivity
+
+```ts
+readonly gamepadLookSensitivity: number
+```
+
+The player's look speed for a gamepad stick, as a percentage: `100` is 1×,
+from `20` to `400`. `100` when the Arcade did not say.
+`gem.controls.look()` applies it for you.
+
+<a id="gemrecommendedsettings-invertlooky"></a>
+
+## GemRecommendedSettings.invertLookY
+
+```ts
+readonly invertLookY: boolean
+```
+
+Whether the player wants up/down look inverted: pushing up or dragging up
+looks down. Flips pitch only, never yaw. `false` when the Arcade did not
+say. `gem.controls.look()` applies it for you.
+
+<a id="gemrecommendedsettings-touchmovement"></a>
+
+## GemRecommendedSettings.touchMovement
+
+```ts
+readonly touchMovement: "floating" | "fixed"
+```
+
+On a touch screen, the movement thumbstick the player wants: `'floating'`
+appears where the thumb lands, `'fixed'` stays in one place. `'floating'`
+when the Arcade did not say. Your game draws the stick.
+
 <a id="gemcohort"></a>
 
 ## GemCohort
@@ -8108,6 +8616,63 @@ shareButton.onclick = () => {
 
 **Guides.** [getting-started](../getting-started.md)
 
+<a id="gem-avatarpickeravailable"></a>
+
+## Gem.avatarPickerAvailable
+
+```ts
+readonly avatarPickerAvailable: boolean
+```
+
+Whether the arcade will open its avatar picker for [Gem.openAvatarPicker](#gem-openavatarpicker)
+here. Decide from it whether to show your own "Change avatar" button, and
+read it again in the click handler — it is read live.
+
+`false` outside the arcade, before the bridge is up, after the session
+ends, and under an embedder that has no avatar picker.
+
+<a id="gem-openavatarpicker"></a>
+
+## Gem.openAvatarPicker
+
+```ts
+openAvatarPicker(): boolean
+```
+
+Open the arcade's avatar picker over your game, so the player can change
+the Arcade avatar they wear without leaving it. For a game that draws
+Arcade avatars — whole characters the player owns as Arcade items — put a
+"Change avatar" button in your own UI and call this from it:
+
+```js
+changeAvatar.hidden = !gem.avatarPickerAvailable;
+changeAvatar.onclick = () => {
+  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;
+};
+```
+
+**The change arrives as a new player, not as an answer.** Nothing comes
+back from this call. When the player picks a different avatar, the arcade
+pauses your game while the picker is open, then sends the player again —
+your `onPlayer` callback runs and [Gem.player](#gem-player) holds the new
+[PlayerIdentity.avatarIconId](#playeridentity-avatariconid) — and resumes it. Redraw from
+`onPlayer`, which also runs when the player changes their avatar from the
+arcade's own menu without your game asking. A player who closes the picker
+unchanged produces nothing at all.
+
+**Your server learns it only when it reads the room again.** A
+server-authoritative game reads each member's `avatar_icon_id` from the
+room read (`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or
+`gem.room.get()` on a dedicated server); nothing tells the server the
+player changed. So when `onPlayer` brings a different `avatarIconId`, have
+your client tell your server, and have the server re-read the room — never
+trust the id the client sends.
+
+**Returns.** `true` when the arcade was asked; `false` when it was not and
+  never will be for this call — outside the arcade, before the bridge is
+  up, under an embedder with no avatar picker, or past six asks a minute.
+  It never throws and never waits.
+
 <a id="gem-vibration"></a>
 
 ## Gem.vibration
@@ -8142,6 +8707,32 @@ function onHit() {
 
 **Guides.** [vibration](../vibration.md)
 
+<a id="gem-controls"></a>
+
+## Gem.controls
+
+```ts
+readonly controls: ControlsApi
+```
+
+The player's camera and controls settings — look sensitivity, gamepad look
+sensitivity, invert look and touch movement, which arrive in
+`gem.prefs.recommended`. Two things to do with them:
+
+```js
+// 1. Tell the Arcade which ones your game leaves to the player.
+gem.controls.declare({ lookSensitivity: 'player', invertLookY: 'player' });
+
+// 2. Turn look input into a camera turn at the player's sensitivity.
+const look = gem.controls.look();
+// dx, dy: the pointer's move in CSS px since the last event.
+const t = look.fromPointer(dx, dy, e.pointerType, camera.pitch);
+camera.yaw += t.yaw;
+camera.pitch += t.pitch;
+```
+
+See the guide's "Camera and look controls" section.
+
 <a id="gem-analytics"></a>
 
 ## Gem.analytics
@@ -9686,7 +10277,10 @@ The precomposed `Name#0001`. It contains the name, so it is
 readonly avatarIconId?: string
 ```
 
-The id of the player's portrait item, when they have one.
+The id of the player's portrait item, when they have one — what a game
+that draws Arcade avatars keys its own model on. On `gem.player` it
+changes when the player wears another portrait, and `onPlayer` runs again;
+see `gem.openAvatarPicker`.
 
 <a id="playeridentity-avatariconurl"></a>
 
@@ -12239,7 +12833,10 @@ The precomposed `Name#0001`. It contains the name, so it is
 readonly avatarIconId?: string
 ```
 
-The id of the player's portrait item, when they have one.
+The id of the player's portrait item, when they have one — what a game
+that draws Arcade avatars keys its own model on. On `gem.player` it
+changes when the player wears another portrait, and `onPlayer` runs again;
+see `gem.openAvatarPicker`.
 
 <a id="leaderboardentry-avatariconurl"></a>
 
@@ -13681,7 +14278,10 @@ The precomposed `Name#0001`. It contains the name, so it is
 readonly avatarIconId?: string
 ```
 
-The id of the player's portrait item, when they have one.
+The id of the player's portrait item, when they have one — what a game
+that draws Arcade avatars keys its own model on. On `gem.player` it
+changes when the player wears another portrait, and `onPlayer` runs again;
+see `gem.openAvatarPicker`.
 
 <a id="playerprofile-avatariconurl"></a>
 
@@ -15996,7 +16596,10 @@ The precomposed `Name#0001`. It contains the name, so it is
 readonly avatarIconId?: string
 ```
 
-The id of the player's portrait item, when they have one.
+The id of the player's portrait item, when they have one — what a game
+that draws Arcade avatars keys its own model on. On `gem.player` it
+changes when the player wears another portrait, and `onPlayer` runs again;
+see `gem.openAvatarPicker`.
 
 <a id="roommember-avatariconurl"></a>
 
@@ -16761,7 +17364,10 @@ The precomposed `Name#0001`. It contains the name, so it is
 readonly avatarIconId?: string
 ```
 
-The id of the player's portrait item, when they have one.
+The id of the player's portrait item, when they have one — what a game
+that draws Arcade avatars keys its own model on. On `gem.player` it
+changes when the player wears another portrait, and `onPlayer` runs again;
+see `gem.openAvatarPicker`.
 
 <a id="showcasefriendentry-avatariconurl"></a>