@indiegems/gem-web-sdk 13.0.0 → 13.2.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.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.
+Generated from `@indiegems/gem-web-sdk/sdk` v13.2.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.
 
@@ -286,7 +286,7 @@ the button could pay right now is [AdsApi.rewardedStatus](#adsapi-rewardedstatus
 
 Absent when your game declares none.
 
-**Guides.** [cross-promotion](../cross-promotion.md)
+**Guides.** [rewarded-ads](../rewarded-ads.md)
 
 <a id="gameconfig-version"></a>
 
@@ -2902,6 +2902,9 @@ type AdFormat = "interstitial" | "rewarded"
 Which kind of break this is.
 
 `interstitial` is a panel the player dismisses and nothing follows from.
+**Deprecated:** signal a platform moment with `gem.moments.signal` instead.
+It keeps working — the arcade treats it as a platform moment — and `14.0.0`
+is the earliest release that may remove it (`docs/deprecation-policy.md`).
 
 `rewarded` is a button the player pressed for a reward, such as a revive or
 an extra attempt, that your game config declares for the placement in
@@ -3021,7 +3024,7 @@ Which of the three answers this is.
 interface AdsApi
 ```
 
-The cross-promotion surface. `gem.ads` is one of these.
+Rewarded ads, and the deprecated interstitial ask. `gem.ads` is one of these.
 
 <a id="adsapi-requestad"></a>
 
@@ -3033,6 +3036,10 @@ requestAd(req: AdRequest): Promise<AdOutcome>
 
 Ask whether the arcade has anything to show at this break in play.
 
+**For a break in play, signal a platform moment with
+`gem.moments.signal` instead: `format: 'interstitial'` is deprecated.** It
+keeps working until at least `14.0.0`. A `rewarded` ask is unchanged.
+
 NOTHING REJECTS, and the answer is usually `no_ad`. Every local refusal —
 an arcade that does not do this at all, a call while another is still in
 flight, a `placement` this module will not send — resolves `no_ad` rather
@@ -3070,16 +3077,6 @@ An `interstitial` needs no press.
 
 **Returns.** The arcade's answer. Always resolves; never rejects.
 
-```ts
-const { outcome } = await gem.ads.requestAd({
-  placement: 'level-complete',
-  format: 'interstitial',
-});
-// `no_ad` is the ordinary answer. There is nothing to show and nothing
-// to draw; carry straight on to the next level.
-startNextLevel();
-```
-
 ```ts
 // A rewarded ask, from the button's own click: the ask comes first, and
 // the inventory read comes after it.
@@ -3142,7 +3139,7 @@ if (status.nextEligibleAt !== undefined) {
 }
 ```
 
-**Guides.** [cross-promotion](../cross-promotion.md)
+**Guides.** [rewarded-ads](../rewarded-ads.md)
 
 <a id="rewardedstatus"></a>
 
@@ -3482,7 +3479,7 @@ is what says which events exist, which dimensions each has and which values
 each dimension may take. An undeclared name or key is not stored — it comes
 back as a rejection, which the SDK prints to the console during development.
 
-⚠️ **Detail older than 30 days is gone.** Raw events live 30 days; the daily
+⚠️ **Detail older than 60 days is gone.** Raw events live 60 days; the daily
 counters live 400. Anything you want to be able to ask about a year from now
 has to be a declared dimension today.
 
@@ -3594,9 +3591,14 @@ the page.
 A refusal that could clear on its own — a 429 from the rate limiter, a 503
 while the platform's idempotency store is unreachable — KEEPS the queue
 and rejects, so the next flush sends the same events rather than losing
-them. A refusal that cannot clear discards the batch it was sent for,
+them. The SDK's own flushes then hold off for the longer of the server's
+`Retry-After` and a cooldown that doubles from 10 seconds, up to five
+minutes. A refusal that cannot clear discards the batch it was sent for,
 because resending it can only fail identically.
 
+One flush at a time: called while another is still on the wire, this
+resolves at once with nothing sent, and what is queued goes out after it.
+
 | Parameter | Type |
 | --- | --- |
 | `options` | `AnalyticsFlushOptions` |
@@ -3925,6 +3927,100 @@ for the avatars already worn when you subscribe: read
 
 **Returns.** a function that stops the calls. Calling it twice is harmless.
 
+<a id="avatarrignode"></a>
+
+## AvatarRigNode
+
+```ts
+interface AvatarRigNode
+```
+
+One node of a rig family's tree: its exact, case-sensitive name, and the
+name of the node it is a DIRECT child of. `parent` is `null` for the rig's
+root, which is a root node of the scene.
+
+<a id="avatarrignode-node"></a>
+
+## AvatarRigNode.node
+
+```ts
+readonly node: string
+```
+
+The node's name, exact and case-sensitive.
+
+<a id="avatarrignode-parent"></a>
+
+## AvatarRigNode.parent
+
+```ts
+readonly parent: string | null
+```
+
+The node it is a direct child of; `null` for the rig's root.
+
+<a id="avatarrigs"></a>
+
+## AvatarRigs
+
+```ts
+interface AvatarRigs
+```
+
+The rig families this SDK knows, by name.
+
+<a id="avatarrigs-small_human"></a>
+
+## AvatarRigs.small_human
+
+```ts
+readonly small_human: readonly AvatarRigNode[]
+```
+
+The toy rig: rigid limbs on a body, eight nodes.
+
+<a id="avatarrigs-adult_human"></a>
+
+## AvatarRigs.adult_human
+
+```ts
+readonly adult_human: readonly AvatarRigNode[]
+```
+
+The adult humanoid with fingers: 56 nodes, world-aligned at rest.
+
+<a id="avatar_rigs"></a>
+
+## AVATAR_RIGS
+
+```ts
+AVATAR_RIGS: AvatarRigs
+```
+
+Every node each rig family requires, with the node it is a direct child of,
+parents before children. Frozen: read it, never change it.
+
+The platform refuses an upload whose model is missing one of these, has one
+under another parent, or has one twice (`rig_mismatch`). Extra nodes are
+allowed anywhere. `adult_human` also requires every one of its nodes to be
+world-aligned at rest; that rule is not in this list, see the guide.
+
+```js
+import { AVATAR_RIGS } from '@indiegems/gem-web-sdk/sdk';
+
+// Every joint of the worn avatar, by name.
+const joints = new Map(
+  AVATAR_RIGS.adult_human.map(({ node }) => [node, gltf.scene.getObjectByName(node)]),
+);
+
+// A test that one of your own models is on the rig.
+for (const { node, parent } of AVATAR_RIGS.adult_human) {
+  const found = gltf.scene.getObjectByName(node);
+  if (!found) throw new Error(`missing ${node}`);
+  if (parent !== null && found.parent?.name !== parent) throw new Error(`${node} is not under ${parent}`);
+}
+```
+
 <a id="gemapierror"></a>
 
 ## GemApiError
@@ -5347,7 +5443,7 @@ interface RewardCue
 ```
 
 A platform-currency reward on its way to the arcade — in the Gem Arcade, a
-flight into the Gem button at the top-left of your frame — what
+flight into the Gem button, in whichever corner of your frame it sits — what
 `gem.cueReward` takes.
 
 <a id="rewardcue-currencyslug"></a>
@@ -5408,6 +5504,18 @@ y: number
 
 From the top edge of your viewport.
 
+<a id="gemcorner"></a>
+
+## GemCorner
+
+```ts
+type GemCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right"
+```
+
+A corner of your frame, for `gem.setGemCorner`: where you would like the
+arcade's Gem button to sit. `'top-left'` is where it sits unless you ask.
+Physical corners: `'top-left'` is the top-left in every language.
+
 <a id="framestate"></a>
 
 ## FrameState
@@ -5737,6 +5845,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-setgemcorner"></a>
+
+## GemFrame.setGemCorner
+
+```ts
+setGemCorner(corner: GemCorner): boolean
+```
+
+Ask the arcade to put its own control over your game — the Gem button —
+in this corner of your frame: the whole answer each time, the latest one
+winning.
+
+Prefer `gem.setGemCorner`, which holds the corner across a reconnect.
+This one sends only while connected, and only to an arcade that can move
+its control.
+
+| Parameter | Type |
+| --- | --- |
+| `corner` | `GemCorner` |
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade that cannot move its control, for a value that is not
+  one of the four corners, and past this frame's own limit.
+
 <a id="gemframe-requestshare"></a>
 
 ## GemFrame.requestShare
@@ -8303,7 +8435,7 @@ readonly reserved: readonly GemReservedArea[]
 ```
 
 Rectangles of your frame the arcade's own controls cover — in the Gem
-Arcade, its Gem button in the top-left corner, and the frame-rate readout
+Arcade, its Gem button in whichever corner it sits, and the frame-rate readout
 beside it while the player shows it; an embedder that draws wallets over
 your game adds theirs (see `setWalletVisible`). Keep essential UI and touch
 targets out of them. Empty when the arcade covers nothing.
@@ -8821,6 +8953,25 @@ every account on the device shares it, and it can vanish at any time. A
 game must boot correctly from `null`. Progress belongs in `gem.me.saves`;
 a setting that must follow the player belongs in `gem.me.settings`.
 
+<a id="gem-moments"></a>
+
+## Gem.moments
+
+```ts
+readonly moments: MomentsApi
+```
+
+Platform moments — **every game, at every break.** Signal one from the
+player's press that leaves a natural break in play (Next, Retry, Back to
+menu), and the arcade may show one of its own offers over your paused
+game. It usually shows nothing.
+
+Required by the release checklist at every important break, whether or
+not your game has a shop of its own. Never resolves a reason, never
+rejects, and `shown` grants nothing.
+
+**Guides.** [platform-moments](../platform-moments.md)
+
 <a id="gem-ads"></a>
 
 ## Gem.ads
@@ -8829,13 +8980,15 @@ a setting that must follow the player belongs in `gem.me.settings`.
 readonly ads: AdsApi
 ```
 
-One full-screen cross-promotion at a natural break in play, rendered by
-the arcade over your paused game.
+Rewarded ads, and the deprecated interstitial ask.
 
-Ask at a break the player already expects — a level ending, a round
-finishing — never mid-input. **The answer is usually no, and that is
-ordinary rather than a failure:** carry straight on, and draw no
-placeholder while you wait.
+**`format: 'interstitial'` is deprecated: signal a platform moment with
+`gem.moments.signal` instead.** It keeps working until at least `14.0.0`
+(`docs/deprecation-policy.md`); the arcade treats it as a platform moment.
+
+A rewarded ask comes from the player's press on your own button. **The
+answer is usually no, and that is ordinary rather than a failure:** carry
+straight on, and draw no placeholder while you wait.
 
 Nothing here rejects. The arcade pauses your game while a panel is up and
 resumes it when the promise settles, so you do not pause anything yourself.
@@ -8848,7 +9001,7 @@ about the player. What you can read is your own economy:
 `rewardedStatus(placement)` says whether a rewarded placement could pay
 right now under your own declared caps — never whether an ad will play.
 
-**Guides.** [cross-promotion](../cross-promotion.md)
+**Guides.** [rewarded-ads](../rewarded-ads.md)
 
 <a id="gem-account"></a>
 
@@ -9430,7 +9583,7 @@ cueReward(cue: RewardCue): boolean
 
 Tell the arcade a platform-currency reward is on its way, so it **shows it
 landing**: in the Gem Arcade the currency flies from `origin` into the Gem
-button at the top-left of your frame, which pops as each mark lands, and
+button, wherever on your frame it sits, which pops as each mark lands, and
 the player's total moves once the platform confirms the grant. The Gem
 Arcade draws no wallet over your game: the player sees their Gems and
 Tickets in the Gem menu. A payout you do not cue still flies, from the
@@ -9532,8 +9685,9 @@ gem.setMenu({
 ```
 
 **Your settings are not in it: draw your own settings button, always** —
-top-right, clear of `gem.viewport.reserved`. The Arcade's menu never opens
-your settings screen.
+top-right, with your Back button just to its left, clear of
+`gem.viewport.reserved`. The Arcade's menu never opens your settings
+screen.
 
 **It is screen state, not a toggle.** Each call is the whole answer and
 replaces the last, so call it again when the entries change — a new
@@ -9553,6 +9707,46 @@ should not assume the game was paused by you.
   up (the menu is held and sent when it connects) and under an embedder
   that draws no menu.
 
+<a id="gem-setgemcorner"></a>
+
+## Gem.setGemCorner
+
+```ts
+setGemCorner(corner: GemCorner): boolean
+```
+
+Ask the arcade to put its Gem button — its one control over your game,
+top-left unless you ask — in another corner of your frame.
+
+```js
+// This game's own HUD needs the top-left, so the Gem goes top-right.
+gem.setGemCorner('top-right');
+```
+
+**Leave it top-left unless your own HUD needs that corner**, and then pick
+one corner for the whole game — at most one per orientation. A Gem that
+moves between screens is a way out the player has to look for. In
+landscape the bottom corners sit where a player's thumbs hold the sticks.
+
+**Lay out around `gem.viewport.reserved`, never around the corner you
+asked for.** The arcade moves the Gem on its own terms: not while the
+player is using it or its menu is open, not more often than every few
+seconds, and never over a corner the player chose for themselves. The
+rectangles say where it actually is, and the `--gem-reserved-*` CSS
+properties follow them.
+
+**It is screen state, not a toggle.** Each call is the whole answer and
+replaces the last. A value that is not one of the four corners is ignored,
+with a warning on the console, and changes nothing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `corner` | `GemCorner` | `'top-left'`, `'top-right'`, `'bottom-left'` or `'bottom-right'`. |
+
+**Returns.** `true` when the arcade was told now; `false` before the bridge is
+  up (the corner is held and sent when it connects), under an embedder that
+  cannot move its control, and for a value that is not a corner.
+
 <a id="gem-exit"></a>
 
 ## Gem.exit
@@ -10352,7 +10546,7 @@ The match this connection belongs to.
 ## MatchConnection.protocol
 
 ```ts
-readonly protocol: "dedicated" | "p2p" | "loopback"
+readonly protocol: "p2p" | "dedicated" | "loopback"
 ```
 
 What is on the other end: `dedicated` (the platform's server), `p2p` (the
@@ -10544,13 +10738,21 @@ putting it in an `<img src>`.
 ## Avatar3dFamily
 
 ```ts
-type Avatar3dFamily = "small_human" | string & object
+type Avatar3dFamily = "small_human" | "adult_human" | string & object
 ```
 
 A rig family — the skeleton contract a 3D avatar is built on, and what a
-game declares it can animate. `small_human` is the first: a `root` node
-with a `body` child, which holds `head`, `arm_l`, `arm_r`, `leg_l` and
-`leg_r`, and a `hand_socket` under `arm_r`.
+game declares it can animate. Two today:
+
+- `small_human`, the toy rig: a `root` node with a `body` child, which holds
+  `head`, `arm_l`, `arm_r`, `leg_l` and `leg_r`, and a `hand_socket` under
+  `arm_r`.
+- `adult_human`, a full humanoid with fingers: 56 nodes from `root` and
+  `hips` down to `toes_r`, every one world-aligned at rest, so one clip plays
+  on every avatar in the family.
+
+`AVATAR_RIGS` (from `@indiegems/gem-web-sdk/sdk`) lists every node of
+both, with its parent.
 
 Open-ended (`| (string & {})`) so a family the platform adds later does not
 break a `switch` you compiled against this version: keep a `default` arm and
@@ -10853,6 +11055,152 @@ so portraits appear only against production and loopback.
 | --- | --- |
 | `url` | `string \| undefined` |
 
+<a id="momentkind"></a>
+
+## MomentKind
+
+```ts
+type MomentKind = "level_end" | "run_end" | "match_end" | "menu_return" | "other_break"
+```
+
+Which kind of break a platform moment is. A closed set — there will not be a
+sixth:
+
+- `level_end` — a level, stage, wave or puzzle finished, won or lost.
+- `run_end` — game over, death, or a run banked, in an endless, arcade or
+  roguelike game.
+- `match_end` — a multiplayer round or match finished and the player is
+  leaving its results.
+- `menu_return` — the player chose to go back to the title, a main menu or
+  level select. A return, never the first arrival.
+- `other_break` — any other natural stop: a story chapter, a between-waves
+  shop.
+
+It is a label, for the arcade's analytics, the dev host's log and the release
+checklist. It never changes what the arcade decides for your game.
+
+**Guides.** [platform-moments](../platform-moments.md)
+
+<a id="momentsignal"></a>
+
+## MomentSignal
+
+```ts
+interface MomentSignal
+```
+
+A platform moment: which kind of break the player is leaving, and optionally
+your own name for the screen.
+
+<a id="momentsignal-kind"></a>
+
+## MomentSignal.kind
+
+```ts
+kind: MomentKind
+```
+
+Which kind of break this is. Required.
+
+<a id="momentsignal-placement"></a>
+
+## MomentSignal.placement
+
+```ts
+placement?: string
+```
+
+Optional: your own name for the screen the player is leaving —
+`world-1-3`, `results`. **1 to 32 characters of `a-z`, `0-9`, `-` and
+`_`.** It appears only in the dev host's log, so a reviewer can map each
+moment to a screen. It is never sent to the platform, never stored, never
+shown to a player and never sent to an ad network.
+
+<a id="momentresult"></a>
+
+## MomentResult
+
+```ts
+interface MomentResult
+```
+
+What the arcade answers at a platform moment.
+
+<a id="momentresult-shown"></a>
+
+## MomentResult.shown
+
+```ts
+readonly shown: boolean
+```
+
+Whether the arcade showed anything of its own at this break. Usually
+`false`. Either way, carry on exactly as you would have. **It grants
+nothing**, and it never says what was shown or why nothing was.
+
+<a id="momentsapi"></a>
+
+## MomentsApi
+
+```ts
+interface MomentsApi
+```
+
+Platform moments. `gem.moments` is one of these.
+
+<a id="momentsapi-signal"></a>
+
+## MomentsApi.signal
+
+```ts
+signal(moment: MomentSignal): Promise<MomentResult>
+```
+
+Signal a platform moment: the player is leaving a natural break in play.
+The arcade may show one of its own offers over your paused game, and
+usually shows nothing.
+
+**Call it from the player's press that LEAVES the break** — Next, Retry,
+Back to menu — once per break. Start your own transition in parallel, and
+start play when this settles. **Never** mid-input, during a timed
+sequence, on a timer, on boot or the first arrival at the title, or from a
+player-opened pause menu (choosing Quit to menu from it is a
+`menu_return`). No press is required by the SDK; the rule is about when a
+break really is one.
+
+NOTHING REJECTS. It resolves `{ shown: false }` without asking for an
+arcade that does not do platform moments, a `kind` or `placement` outside
+the grammar, a call before `gem.frame.ready()`, a call while another is in
+flight, a call within 10 seconds of the last answer, or no answer within
+three minutes — and each of those, except an arcade that does not do it
+(said once a session), is reported to your `onError` handler with code
+`'internal'` and a message beginning with a stable token:
+`moments_unsupported`, `moments_invalid_argument`, `moments_before_ready`,
+`moments_in_flight`, `moments_called_repeatedly` or `moments_timeout`.
+
+The arcade pauses and resumes your game through the ordinary
+`gem.pause`, so you do not pause anything yourself.
+
+⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency
+on it, and never pop your own offer at a break that settled `shown: true`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `moment` | `MomentSignal` | Which kind of break, and optionally your name for the screen. |
+
+**Returns.** Whether the arcade showed anything. Always resolves; never rejects.
+
+```ts
+// From the press that LEAVES the break — Next, Retry, Back to menu.
+async function onNextPressed() {
+  startLevelTransition(); // your fade or loading beat, in parallel
+  await gem.moments.signal({ kind: 'level_end', placement: 'world-1-3' });
+  startNextLevel(); // settled either way; never grant anything on `shown`
+}
+```
+
+**Guides.** [platform-moments](../platform-moments.md)
+
 <a id="dedicatedserverfailure"></a>
 
 ## DedicatedServerFailure

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v13.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.
+Generated from `@indiegems/gem-web-sdk/sdk` v13.2.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.
 
@@ -440,6 +440,22 @@ It buys the same budget a read gets — see [ClientOptions.maxRetries](#clientop
 final: only the failures [GemApiError.retryable](#gemapierror-retryable) describes, and a
 connection that died with no answer, are attempted again.
 
+<a id="requestoptions-retryratelimited"></a>
+
+## RequestOptions.retryRateLimited
+
+```ts
+readonly retryRateLimited?: boolean
+```
+
+Set `false` to make a 429 final for this call instead of waiting out
+`Retry-After` and trying again.
+
+For a caller that keeps its own queue and its own cooldown, such as a
+batch sender on a timer: retrying inside the call only spends more of the
+same limit, and holds the caller's queue while it does. Every other
+failure is retried exactly as before. Defaults to `true`.
+
 <a id="versionedgetoptions"></a>
 
 ## VersionedGetOptions
@@ -2523,9 +2539,14 @@ Send what is queued now, and find out what happened to it.
 
 Resolves with the platform's own answer, INCLUDING per-event rejections, which
 arrive inside a 200 rather than as an error. A refusal that could clear on
-its own — a 429, a 503 — keeps the queue and rejects; one that cannot
+its own — a 429, a 503 — keeps the queue and rejects, and the SDK's own
+flushes then hold off for the longer of the server's `Retry-After` and a
+cooldown that doubles from 10 seconds, up to five minutes; one that cannot
 discards the batch, because resending it can only fail the same way.
 
+One flush at a time: called while another is on the wire, this waits for
+it and then sends what is left.
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `signal` | `AbortSignal` | Cancels the call — not the queue. |