@indiegems/gem-web-sdk 21.1.1 → 22.0.0

package/dist/sdk.d.ts

@@ -1497,6 +1497,7 @@ declare class ProfilesApi {
 }
 interface FunctionInvokeOptions {
     readonly signal?: AbortSignal;
+    readonly cueId?: string;
 }
 interface FunctionResult {
     readonly bytes: Uint8Array;
@@ -1520,6 +1521,7 @@ declare class FunctionsApi {
     #private;
     constructor(invoke: (body: Uint8Array, options?: {
         signal?: AbortSignal;
+        cue_id?: string;
     }) => Promise<BytesResponse>);
     invoke(input: unknown, options?: FunctionInvokeOptions): Promise<FunctionResult>;
 }
@@ -4252,6 +4254,7 @@ declare function initiateInventoryTransfer(api: GameApi, body: InitiateTransferR
     signal?: AbortSignal;
 }): Promise<TransferResponse>;
 declare function invokeFunction(api: GameApi, body: Uint8Array, options?: {
+    "cue_id"?: string;
     signal?: AbortSignal;
 }): Promise<BytesResponse>;
 declare function kickPlayer(api: GameApi, game_room_id: string, player_id: string, options?: {
@@ -4785,6 +4788,7 @@ interface PlayerBoost {
 }
 interface RewardCue {
     currencySlug: string;
+    cueId?: string;
     expected?: number;
     origin?: {
         x: number;
@@ -4792,6 +4796,7 @@ interface RewardCue {
     };
 }
 type GemCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+type RewardPresentation = "arcade" | "game";
 interface MenuStyle {
     readonly ground: string;
     readonly accent: string;
@@ -4901,6 +4906,7 @@ declare class GemFrame {
     }>): boolean;
     declareSettings(settings: GemSettingsDeclare["settings"]): boolean;
     setGemCorner(corner: GemCorner): boolean;
+    setRewardPresentation(mode: RewardPresentation): boolean;
     setMenuStyle(style: MenuStyle | null): boolean;
     requestShare(params: ReadonlyArray<{
         readonly key: string;
@@ -5355,6 +5361,7 @@ interface Gem {
     reportMuted(muted: boolean): void;
     showPortraitBorders(name: string | null): void;
     cueReward(cue: RewardCue): boolean;
+    setRewardPresentation(mode: RewardPresentation): boolean;
     setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean;
     setMenu(menu: GameMenu): boolean;
     setGemCorner(corner: GemCorner): boolean;
@@ -5385,4 +5392,4 @@ interface ExitAnalytics {
 }
 declare function leaveAndExit(rooms: ExitRooms, bridge: ExitBridge | null, reason?: string, analytics?: ExitAnalytics): Promise<void>;
 declare function createGem(options?: GemOptions): Gem;
-export { ARCADE_EMBEDDERS, AVATAR_RIGS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, type AppLinksOutcome, type AppListing, type AppStore, type ArcadeApi, type ArcadeAvailability, type ArcadeOffer, type ArcadeOutcome, type ArcadeOutcomeKind, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Avatar3dOffer, type Avatar3dPrice, type Avatar3dPurchaseRequest, type AvatarRigNode, type AvatarRigs, type Avatars3dApi, type Base64String, type BootMark, type BootTimeline, type BrandingApi, type BrandingAsset, type BrandingAssetOptions, type BrandingCurrency, type BrandingImageOptions, type BrandingList, type BrandingLookup, type BrandingTheme, type BrandingVariant, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type ControlsApi, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameCard, type GameConfig, type GameMenu, type GameMenuItem, type GamePass, type GameServerLink, type GameSettingsApi, type Gem, GemApiError, type GemAudioChannels, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemControlBox, type GemCorner, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemGameChoiceSetting, type GemGameSetting, type GemGameSettingBase, type GemGameSettingChange, type GemGameSettingIcon, type GemGameSettingOption, type GemGameSettingValue, type GemGameSliderSetting, type GemGameToggleSetting, type GemGraphicsQuality, type GemGraphicsRoute, type GemGraphicsRouteEntry, type GemIdentity, type GemInsets, type GemLook, type GemLookBase, type GemLookDelta, type GemLookOptions, type GemLookSpeed, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPreferredRoute, type GemPrefs, type GemRecommendedSettings, type GemReservedArea, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type GraphicsApi, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchBackfillState, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchPlayerReport, type MatchPlayerReportResult, type MatchServeOptions, type MatchTransport, type MenuStyle, type MessageMeta, type MomentKind, type MomentResult, type MomentSignal, type MomentsApi, type MultiTransportSession, PLATFORM_EVENTS, type PassesApi, type PassesEvent, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, type PlayerScope, PlayerText, type PreferredRouteOptions, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PurchaseSettlement, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, ShareRefusal, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SimilarGamesOutcome, type SnapshotCurrency, type SnapshotItem, type StoreApi, type StoreOffersOutcome, type StoreSettlement, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, type VibrationApi, type WalletVisibleOptions, type WornAvatar3d$1 as WornAvatar3d, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, experimentSelection, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };
+export { ARCADE_EMBEDDERS, AVATAR_RIGS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, type AppLinksOutcome, type AppListing, type AppStore, type ArcadeApi, type ArcadeAvailability, type ArcadeOffer, type ArcadeOutcome, type ArcadeOutcomeKind, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Avatar3dOffer, type Avatar3dPrice, type Avatar3dPurchaseRequest, type AvatarRigNode, type AvatarRigs, type Avatars3dApi, type Base64String, type BootMark, type BootTimeline, type BrandingApi, type BrandingAsset, type BrandingAssetOptions, type BrandingCurrency, type BrandingImageOptions, type BrandingList, type BrandingLookup, type BrandingTheme, type BrandingVariant, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type ControlsApi, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameCard, type GameConfig, type GameMenu, type GameMenuItem, type GamePass, type GameServerLink, type GameSettingsApi, type Gem, GemApiError, type GemAudioChannels, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemControlBox, type GemCorner, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemGameChoiceSetting, type GemGameSetting, type GemGameSettingBase, type GemGameSettingChange, type GemGameSettingIcon, type GemGameSettingOption, type GemGameSettingValue, type GemGameSliderSetting, type GemGameToggleSetting, type GemGraphicsQuality, type GemGraphicsRoute, type GemGraphicsRouteEntry, type GemIdentity, type GemInsets, type GemLook, type GemLookBase, type GemLookDelta, type GemLookOptions, type GemLookSpeed, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPreferredRoute, type GemPrefs, type GemRecommendedSettings, type GemReservedArea, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type GraphicsApi, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchBackfillState, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchPlayerReport, type MatchPlayerReportResult, type MatchServeOptions, type MatchTransport, type MenuStyle, type MessageMeta, type MomentKind, type MomentResult, type MomentSignal, type MomentsApi, type MultiTransportSession, PLATFORM_EVENTS, type PassesApi, type PassesEvent, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, type PlayerScope, PlayerText, type PreferredRouteOptions, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PurchaseSettlement, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardPresentation, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, ShareRefusal, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SimilarGamesOutcome, type SnapshotCurrency, type SnapshotItem, type StoreApi, type StoreOffersOutcome, type StoreSettlement, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, type VibrationApi, type WalletVisibleOptions, type WornAvatar3d$1 as WornAvatar3d, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, experimentSelection, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };

package/dist/server-api.d.ts

@@ -1326,6 +1326,7 @@ declare function initiateInventoryTransfer(api: GameApi, body: InitiateTransferR
     signal?: AbortSignal;
 }): Promise<TransferResponse>;
 declare function invokeFunction(api: GameApi, body: Uint8Array, options?: {
+    "cue_id"?: string;
     signal?: AbortSignal;
 }): Promise<BytesResponse>;
 declare function kickPlayer(api: GameApi, game_room_id: string, player_id: string, options?: {

package/dist/server.d.ts

@@ -1404,6 +1404,7 @@ declare function initiateInventoryTransfer(api: GameApi, body: InitiateTransferR
     signal?: AbortSignal;
 }): Promise<TransferResponse>;
 declare function invokeFunction(api: GameApi, body: Uint8Array, options?: {
+    "cue_id"?: string;
     signal?: AbortSignal;
 }): Promise<BytesResponse>;
 declare function kickPlayer(api: GameApi, game_room_id: string, player_id: string, options?: {
@@ -1723,6 +1724,7 @@ interface ServerAnalytics {
 }
 interface FunctionInvokeOptions {
     readonly signal?: AbortSignal;
+    readonly cueId?: string;
 }
 interface FunctionResult {
     readonly bytes: Uint8Array;
@@ -1746,6 +1748,7 @@ declare class FunctionsApi {
     #private;
     constructor(invoke: (body: Uint8Array, options?: {
         signal?: AbortSignal;
+        cue_id?: string;
     }) => Promise<BytesResponse>);
     invoke(input: unknown, options?: FunctionInvokeOptions): Promise<FunctionResult>;
 }

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v21.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/function` v22.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/function` exports exactly the symbols on this page and nothing else.
 

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v21.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` v22.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.
 
@@ -7180,6 +7180,24 @@ The platform currency's slug, as `gem.platform.currencies.get()` lists it —
 `GEMS` or `ARCADE_TICKETS`. It decides what flies — gems or coins — and
 which of the player's totals the payout moves.
 
+<a id="rewardcue-cueid"></a>
+
+## RewardCue.cueId
+
+```ts
+cueId?: string
+```
+
+Your id for this award, so the arcade flies it once. Make one per award
+with `crypto.randomUUID()` and pass the same one as the `cueId` of the
+`gem.functions.invoke` that pays it; then the cue and the payout may reach
+the arcade in either order. 1 to 64 letters, digits, `_` or `-`; anything
+else is left out (with a console warning, from `gem.cueReward`), and the
+cue still goes.
+
+For animation only: it moves no balance. Leave it out and the arcade pairs
+the cue with the payout by currency and timing.
+
 <a id="rewardcue-expected"></a>
 
 ## RewardCue.expected
@@ -7238,6 +7256,18 @@ 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="rewardpresentation"></a>
+
+## RewardPresentation
+
+```ts
+type RewardPresentation = "arcade" | "game"
+```
+
+Who decides when your platform-currency payouts are shown landing, for
+`gem.setRewardPresentation`: `'arcade'`, the default, or `'game'`, when each
+payout waits for your `gem.cueReward`.
+
 <a id="menustyle"></a>
 
 ## MenuStyle
@@ -7646,6 +7676,29 @@ its control.
   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-setrewardpresentation"></a>
+
+## GemFrame.setRewardPresentation
+
+```ts
+setRewardPresentation(mode: RewardPresentation): boolean
+```
+
+Tell the arcade who decides when your platform-currency payouts are shown
+landing: the whole answer each time, the latest one winning.
+
+Prefer `gem.setRewardPresentation`, which holds the answer across a
+reconnect. This one sends only while connected, and only to an arcade
+that can hold a payout for your cue.
+
+| Parameter | Type |
+| --- | --- |
+| `mode` | `RewardPresentation` |
+
+**Returns.** whether the message left the frame: `false` before the bridge is
+  up, for an arcade that cannot hold a payout, for a value that is neither
+  `'arcade'` nor `'game'`, and past this frame's own limit.
+
 <a id="gemframe-setmenustyle"></a>
 
 ## GemFrame.setMenuStyle
@@ -8726,6 +8779,24 @@ readonly signal?: AbortSignal
 
 Cancel the call. A call already cancelled sends nothing.
 
+<a id="functioninvokeoptions-cueid"></a>
+
+## FunctionInvokeOptions.cueId
+
+```ts
+readonly cueId?: string
+```
+
+The id of the reward this call pays, so the Gem Arcade flies it once:
+the same `cueId` you pass to `gem.cueReward` for it, one
+`crypto.randomUUID()` per award. The platform hands it back on the payout
+it shows the arcade, and nowhere else: your function never sees it, and
+neither the answer nor a receipt carries it.
+
+1 to 64 letters, digits, `_` or `-`. Anything else is left out with a
+console warning, and the call still goes: it decides an animation, never
+whether the call pays.
+
 <a id="functionresult"></a>
 
 ## FunctionResult
@@ -9009,6 +9080,15 @@ const result = await gem.functions.invoke({ v: 2, runId, finishMs });
 const { accepted, why } = result.json();
 ```
 
+When the call pays a reward the player sees, pass the reward's `cueId`, the
+same one the page gives `gem.cueReward` for it, and the Gem Arcade flies it
+once:
+
+```js
+const cueId = crypto.randomUUID(); // one per award, also passed to the cue
+await gem.functions.invoke({ claim: 'daily' }, { cueId });
+```
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `input` | `unknown` | Bytes, or a value to send as JSON. |
@@ -12231,6 +12311,30 @@ gem.cueReward({
 });
 ```
 
+**When your function pays it, give both calls one `cueId`.** Make one per
+award with `crypto.randomUUID()`, pass it here and to the
+`gem.functions.invoke` that pays, and the arcade flies that reward once,
+whichever reaches it first — so you may cue before the call or after it
+returns:
+
+```js
+const cueId = crypto.randomUUID();
+const result = await gem.functions.invoke({ claim: 'daily' }, { cueId });
+gem.cueReward({ currencySlug: 'GEMS', expected: 15, origin, cueId });
+```
+
+A payout that is not a function call (your own game server's) has no id
+to share: cue it with none, and the arcade pairs the two by currency and
+timing.
+
+**When is up to the arcade unless you say otherwise.** By default the cue
+is paired with its payout only within about half a second either side of
+your server's write; a payout with no cue by then flies from the middle of
+your frame, and a cue that comes later adds nothing. To show the payout at
+a later moment of your own, such as a Claim tap on the win card or the
+screen the player returns to, call `gem.setRewardPresentation('game')` once
+at boot: each payout then waits for your cue.
+
 **This is the platform-currency animation, and the only one.** The display
 of every platform currency — Gems and Coins alike — belongs to the
 arcade: a game draws no flight or celebration of its own for one and keeps
@@ -12252,6 +12356,53 @@ landed — which it does on every channel, dev and test included.
   before the bridge is up, or under an embedder with no wallet. On `false`
   the game does nothing: it draws no animation of its own in its place.
 
+<a id="gem-setrewardpresentation"></a>
+
+## Gem.setRewardPresentation
+
+```ts
+setRewardPresentation(mode: RewardPresentation): boolean
+```
+
+Say who decides when your platform-currency payouts are shown landing: the
+arcade (`'arcade'`, the default) or your game (`'game'`). Call it once at
+boot when your reward moment comes after your server pays, such as a Claim
+tap on the win card or the next screen the player sees.
+
+```js
+gem.setRewardPresentation('game'); // at boot
+// ...the server pays when the board is won; later, on Claim:
+gem.cueReward({ currencySlug: 'ARCADE_TICKETS', expected: 20, origin });
+```
+
+**With `'game'`, your cue supplies the moment and the payout supplies the
+number.** The arcade holds each payout's presentation for its currency
+rather than flying it from the middle of your frame. Each `cueReward`
+releases up to its `expected` of what is held (all of it when it names no
+amount) and flies it from its `origin`, and the arcade's wallet chip over
+your game counts up as the marks land. A cue that finds nothing held waits
+for the next payout of its currency, so cue before or after the write, in
+either order.
+
+**It delays the show, never the money.** What is paid, when, and every
+ceiling are unchanged, and the arcade's menu and every purchase see the
+player's true total at once. A payout no cue releases within five minutes
+lands quietly, with no flight, so a game can never hide one.
+
+**It is screen state, not a toggle**, held before the bridge is up and
+re-sent after every reconnect. Switching back to `'arcade'` lands whatever
+is held. A value that is neither is ignored, with a warning on the console,
+and changes nothing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `mode` | `RewardPresentation` | `'game'` to present each payout on your cue, `'arcade'` for the default. |
+
+**Returns.** `true` when the arcade was told now; `false` before the bridge is
+  up (the answer is held and sent when it connects), under an embedder
+  that presents every payout its own way, and for a value that is neither.
+  On `false` from an embedder, keep cueing as usual: nothing else changes.
+
 <a id="gem-setwalletvisible"></a>
 
 ## Gem.setWalletVisible

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v21.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` v22.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.
 
@@ -1489,6 +1489,24 @@ readonly signal?: AbortSignal
 
 Cancel the call. A call already cancelled sends nothing.
 
+<a id="functioninvokeoptions-cueid"></a>
+
+## FunctionInvokeOptions.cueId
+
+```ts
+readonly cueId?: string
+```
+
+The id of the reward this call pays, so the Gem Arcade flies it once:
+the same `cueId` you pass to `gem.cueReward` for it, one
+`crypto.randomUUID()` per award. The platform hands it back on the payout
+it shows the arcade, and nowhere else: your function never sees it, and
+neither the answer nor a receipt carries it.
+
+1 to 64 letters, digits, `_` or `-`. Anything else is left out with a
+console warning, and the call still goes: it decides an animation, never
+whether the call pays.
+
 <a id="functionresult"></a>
 
 ## FunctionResult
@@ -1772,6 +1790,15 @@ const result = await gem.functions.invoke({ v: 2, runId, finishMs });
 const { accepted, why } = result.json();
 ```
 
+When the call pays a reward the player sees, pass the reward's `cueId`, the
+same one the page gives `gem.cueReward` for it, and the Gem Arcade flies it
+once:
+
+```js
+const cueId = crypto.randomUUID(); // one per award, also passed to the cue
+await gem.functions.invoke({ claim: 'daily' }, { cueId });
+```
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `input` | `unknown` | Bytes, or a value to send as JSON. |

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "21.1.1"
+    "version": "22.0.0"
   },
   "entries": [
     {
@@ -8556,6 +8556,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RewardCue.cueId",
+          "name": "cueId",
+          "anchor": "rewardcue-cueid",
+          "group": "platform",
+          "signature": "cueId?: string",
+          "documented": true,
+          "summary": "Your id for this award, so the arcade flies it once. Make one per award\nwith `crypto.randomUUID()` and pass the same one as the `cueId` of the\n`gem.functions.invoke` that pays it; then the cue and the payout may reach\nthe arcade in either order. 1 to 64 letters, digits, `_` or `-`; anything\nelse is left out (with a console warning, from `gem.cueReward`), and the\ncue still goes.\n\nFor animation only: it moves no balance. Leave it out and the arcade pairs\nthe cue with the payout by currency and timing.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RewardCue.expected",
           "name": "expected",
@@ -8636,6 +8652,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RewardPresentation",
+          "name": "RewardPresentation",
+          "anchor": "rewardpresentation",
+          "group": "platform",
+          "signature": "type RewardPresentation = \"arcade\" | \"game\"",
+          "documented": true,
+          "summary": "Who decides when your platform-currency payouts are shown landing, for\n`gem.setRewardPresentation`: `'arcade'`, the default, or `'game'`, when each\npayout waits for your `gem.cueReward`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "MenuStyle",
           "name": "MenuStyle",
@@ -9064,6 +9096,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.setRewardPresentation",
+          "name": "setRewardPresentation",
+          "anchor": "gemframe-setrewardpresentation",
+          "group": "frame",
+          "signature": "setRewardPresentation(mode: RewardPresentation): boolean",
+          "documented": true,
+          "summary": "Tell the arcade who decides when your platform-currency payouts are shown\nlanding: the whole answer each time, the latest one winning.\n\nPrefer `gem.setRewardPresentation`, which holds the answer across a\nreconnect. This one sends only while connected, and only to an arcade\nthat can hold a payout for your cue.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "mode",
+              "type": "RewardPresentation",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame: `false` before the bridge is\n  up, for an arcade that cannot hold a payout, for a value that is neither\n  `'arcade'` nor `'game'`, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.setMenuStyle",
           "name": "setMenuStyle",
@@ -10203,6 +10258,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FunctionInvokeOptions.cueId",
+          "name": "cueId",
+          "anchor": "functioninvokeoptions-cueid",
+          "group": "functions",
+          "signature": "readonly cueId?: string",
+          "documented": true,
+          "summary": "The id of the reward this call pays, so the Gem Arcade flies it once:\nthe same `cueId` you pass to `gem.cueReward` for it, one\n`crypto.randomUUID()` per award. The platform hands it back on the payout\nit shows the arcade, and nowhere else: your function never sees it, and\nneither the answer nor a receipt carries it.\n\n1 to 64 letters, digits, `_` or `-`. Anything else is left out with a\nconsole warning, and the call still goes: it decides an animation, never\nwhether the call pays.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FunctionResult",
           "name": "FunctionResult",
@@ -10482,7 +10553,7 @@
           "group": "functions",
           "signature": "invoke(input: unknown, options?: FunctionInvokeOptions): Promise<FunctionResult>",
           "documented": true,
-          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-game.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```",
+          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-game.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```\n\nWhen the call pays a reward the player sees, pass the reward's `cueId`, the\nsame one the page gives `gem.cueReward` for it, and the Gem Arcade flies it\nonce:\n\n```js\nconst cueId = crypto.randomUUID(); // one per award, also passed to the cue\nawait gem.functions.invoke({ claim: 'daily' }, { cueId });\n```",
           "deprecated": null,
           "params": [
             {
@@ -13703,7 +13774,7 @@
           "group": "start",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game unless you ask (`setWalletVisible`):\nthe player sees their Gems and Coins in the Gem menu. A payout you do not\ncue still flies, from the middle of your frame, so cue the ones the player\nearns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game unless you ask (`setWalletVisible`):\nthe player sees their Gems and Coins in the Gem menu. A payout you do not\ncue still flies, from the middle of your frame, so cue the ones the player\nearns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**When your function pays it, give both calls one `cueId`.** Make one per\naward with `crypto.randomUUID()`, pass it here and to the\n`gem.functions.invoke` that pays, and the arcade flies that reward once,\nwhichever reaches it first — so you may cue before the call or after it\nreturns:\n\n```js\nconst cueId = crypto.randomUUID();\nconst result = await gem.functions.invoke({ claim: 'daily' }, { cueId });\ngem.cueReward({ currencySlug: 'GEMS', expected: 15, origin, cueId });\n```\n\nA payout that is not a function call (your own game server's) has no id\nto share: cue it with none, and the arcade pairs the two by currency and\ntiming.\n\n**When is up to the arcade unless you say otherwise.** By default the cue\nis paired with its payout only within about half a second either side of\nyour server's write; a payout with no cue by then flies from the middle of\nyour frame, and a cue that comes later adds nothing. To show the payout at\na later moment of your own, such as a Claim tap on the win card or the\nscreen the player returns to, call `gem.setRewardPresentation('game')` once\nat boot: each payout then waits for your cue.\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
           "deprecated": null,
           "params": [
             {
@@ -13719,6 +13790,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.setRewardPresentation",
+          "name": "setRewardPresentation",
+          "anchor": "gem-setrewardpresentation",
+          "group": "start",
+          "signature": "setRewardPresentation(mode: RewardPresentation): boolean",
+          "documented": true,
+          "summary": "Say who decides when your platform-currency payouts are shown landing: the\narcade (`'arcade'`, the default) or your game (`'game'`). Call it once at\nboot when your reward moment comes after your server pays, such as a Claim\ntap on the win card or the next screen the player sees.\n\n```js\ngem.setRewardPresentation('game'); // at boot\n// ...the server pays when the board is won; later, on Claim:\ngem.cueReward({ currencySlug: 'ARCADE_TICKETS', expected: 20, origin });\n```\n\n**With `'game'`, your cue supplies the moment and the payout supplies the\nnumber.** The arcade holds each payout's presentation for its currency\nrather than flying it from the middle of your frame. Each `cueReward`\nreleases up to its `expected` of what is held (all of it when it names no\namount) and flies it from its `origin`, and the arcade's wallet chip over\nyour game counts up as the marks land. A cue that finds nothing held waits\nfor the next payout of its currency, so cue before or after the write, in\neither order.\n\n**It delays the show, never the money.** What is paid, when, and every\nceiling are unchanged, and the arcade's menu and every purchase see the\nplayer's true total at once. A payout no cue releases within five minutes\nlands quietly, with no flight, so a game can never hide one.\n\n**It is screen state, not a toggle**, held before the bridge is up and\nre-sent after every reconnect. Switching back to `'arcade'` lands whatever\nis held. A value that is neither is ignored, with a warning on the console,\nand changes nothing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "mode",
+              "type": "RewardPresentation",
+              "optional": false,
+              "summary": "`'game'` to present each payout on your cue, `'arcade'` for the default."
+            }
+          ],
+          "returns": "`true` when the arcade was told now; `false` before the bridge is\n  up (the answer is held and sent when it connects), under an embedder\n  that presents every payout its own way, and for a value that is neither.\n  On `false` from an embedder, keep cueing as usual: nothing else changes.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.setWalletVisible",
           "name": "setWalletVisible",
@@ -26721,6 +26815,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FunctionInvokeOptions.cueId",
+          "name": "cueId",
+          "anchor": "functioninvokeoptions-cueid",
+          "group": "functions",
+          "signature": "readonly cueId?: string",
+          "documented": true,
+          "summary": "The id of the reward this call pays, so the Gem Arcade flies it once:\nthe same `cueId` you pass to `gem.cueReward` for it, one\n`crypto.randomUUID()` per award. The platform hands it back on the payout\nit shows the arcade, and nowhere else: your function never sees it, and\nneither the answer nor a receipt carries it.\n\n1 to 64 letters, digits, `_` or `-`. Anything else is left out with a\nconsole warning, and the call still goes: it decides an animation, never\nwhether the call pays.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FunctionResult",
           "name": "FunctionResult",
@@ -27000,7 +27110,7 @@
           "group": "functions",
           "signature": "invoke(input: unknown, options?: FunctionInvokeOptions): Promise<FunctionResult>",
           "documented": true,
-          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-server.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```",
+          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-server.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```\n\nWhen the call pays a reward the player sees, pass the reward's `cueId`, the\nsame one the page gives `gem.cueReward` for it, and the Gem Arcade flies it\nonce:\n\n```js\nconst cueId = crypto.randomUUID(); // one per award, also passed to the cue\nawait gem.functions.invoke({ claim: 'daily' }, { cueId });\n```",
           "deprecated": null,
           "params": [
             {

package/docs/arcade-economy.md

@@ -237,7 +237,9 @@ animates every payout into the right total. Gems and Coins follow the same rules
   `onPause(false)` if you keep anything worked out from it, such as a greyed-out Buy button.
 - **No celebration of your own.** At a payout, cue the arcade's wallet with `gem.cueReward`, naming
   the currency that paid — `currencySlug: 'GEMS'` from the gem on your reward screen,
-  `'ARCADE_TICKETS'` from the coin. If it returns `false`, do nothing
+  `'ARCADE_TICKETS'` from the coin. If it returns `false`, do nothing. When your serverless function
+  pays it, pass one `cueId` (a `crypto.randomUUID()`) to both the cue and the `gem.functions.invoke`
+  call, and the reward flies once
   ([inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet)).
 - **No "daily max" of your own making.** Your game cannot see what every other game paid the player,
   and must not compute a maximum. To show how much more your game can pay, read

package/docs/changelog.md

@@ -16,6 +16,20 @@ 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.
 
+## 22.0.0
+
+Upgrading from 21.1.1. Impact: required.
+
+### Rebuild
+
+- The function invoke options gained an optional cueId field, which changes the signatures of the functions API constructor, the server API invoke function member and the standalone invoke function. Nothing is required of existing calls; recompiling is enough.
+- The frame message union, the list of frame-to-parent messages and the capability type each gained a reward presentation entry. Recompiling is enough, unless your code switches exhaustively over these types, in which case add a case for the new entry.
+
+### New capability
+
+- A game can now make one id per award and pass it to both the reward cue call and the function invoke call, so the Arcade pairs the cue with its payout and the reward flies once. An id that is malformed is left out with a console warning and never throws. Passing an id is optional and existing calls behave as before.
+- A server-paid game whose reward moment comes after the payout can now declare that its own reward cue decides when the payout is shown, instead of leaving the timing to the Arcade. Under the game choice the Arcade holds each payout's presentation until a cue releases it, and a payout that no cue releases within a limited time lands quietly. Only the presentation changes; what is paid, when it is paid, and every limit stay the same. The declaration is remembered until the Arcade connection is ready and sent again after each reconnect, and it takes effect only when the Arcade offers the matching capability.
+
 ## 21.1.1
 
 Upgrading from 21.1.0. Impact: none.

package/docs/daily-challenges.md

@@ -324,7 +324,9 @@ Four things to know before you ship one:
 player's Gems and Coins in its own chrome, and without a cue a payout flies from the middle of
 your frame, not from the payout the player is looking at. At the moment your game shows the challenge complete, call
 `gem.cueReward` with the currency that paid (`GEMS` or `ARCADE_TICKETS`) and the centre of its icon
-beside the payout on your completion screen, and the payout flies from there into the Gem button:
+beside the payout on your completion screen, and the payout flies from there into the Gem button.
+When a serverless function pays it, give the cue and the `gem.functions.invoke` call one `cueId`
+so it flies once:
 [inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet).
 **If it returns `false`, do nothing** — no celebration of your own, no counter, no flight;
 platform-currency display belongs to the arcade, and a game not connected to it shows no

package/docs/getting-started.md

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