@indiegems/gem-web-sdk 9.1.3 → 10.0.0

package/CHANGELOG.md

@@ -16,6 +16,25 @@ 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.
 
+## 10.0.0
+
+Upgrading from 9.1.4. Impact: required.
+
+### Rebuild
+
+- The OrderSource type now accepts two more values, test_account_provision and developer_grant. Recompile your game. If your code handles order sources in an exhaustive switch or a lookup table typed by OrderSource, add handling for both new values, or the build may fail to compile.
+
+### New capability
+
+- A game can now put a player in a matchmaking queue for a mode that needs a formed lobby. Call RoomManager.queueForMatch with the template slugs you want. It returns a MatchTicket whose outcome settles once and whose cancel method leaves the queue. When the platform finds a match it creates the room, seats everyone and starts the match, and you follow it with the same code you use for any joined room. Options are described by QueueForMatchOptions. Ticket endings are described by MatchTicketOutcome, and the waiting state by MatchTicketStatus. RoomManager.currentTicket exposes the ticket the player is waiting on. The SDK keeps the ticket alive by itself, cancels it when the tab closes, and lets a player queue from inside a room. After a match the player leaves the room they queued from when the tab closes.
+- The lower-level rooms API now has createTicket, heartbeatTicket and cancelTicket calls for working with matchmaking tickets directly. Most games should use RoomManager.queueForMatch, which sends the heartbeats and cancellation for you.
+
+## 9.1.4
+
+Upgrading from 9.1.3. Impact: none.
+
+Nothing in this release asks anything of a game.
+
 ## 9.1.3
 
 Upgrading from 9.1.2. Impact: none.

package/README.md

@@ -5,8 +5,7 @@ progress, leaderboards, currencies and items, rooms and matches, and the server
 One dependency covers both halves of a game — the browser client and its dedicated server.
 
 **Everything you need to build against it is in this package.** The guides are in [`docs/`](docs/),
-the full API reference is in [`docs/api/`](docs/api/), and both are the same text the Gem Arcade
-developer site serves at <https://gemarcade.com/developer/docs>, at the version you installed.
+the full API reference is in [`docs/api/`](docs/api/), and both describe the version you installed.
 Read them here rather than guessing from the type declarations, which carry signatures only.
 
 ## Start here

package/dist/function.d.ts

@@ -168,7 +168,7 @@ type BucketConfig = Boundary & {
 type BucketResetInterval = "never" | "daily" | "weekly" | "monthly";
 type EntityType = "player" | "character";
 type ItemCategory = "cosmetic" | "progression";
-type OrderSource = "real_money_purchase" | "real_money_refund" | "full_game_purchase" | "full_game_refund" | "platform_purchase" | "reward" | "admin" | "system" | "promo" | "game_consume" | "play" | "recipe" | "transfer" | "platform_funded_game_inventory_purchase" | "earning_reset";
+type OrderSource = "real_money_purchase" | "real_money_refund" | "full_game_purchase" | "full_game_refund" | "platform_purchase" | "reward" | "admin" | "system" | "promo" | "game_consume" | "play" | "recipe" | "transfer" | "platform_funded_game_inventory_purchase" | "earning_reset" | "test_account_provision" | "developer_grant";
 type PlatformPrice = {
     "platform_currency_id": string;
     "price": number;

package/dist/game.d.ts

@@ -147,6 +147,11 @@ type AffixSelection = {
     "pool": AffixPoolRef;
     "respect_groups"?: boolean;
 };
+type BackfillPolicy = "fill_existing_first" | "prefer_new_match";
+type BackfillSettings = {
+    "enabled": boolean;
+    "policy"?: BackfillPolicy;
+};
 type Boundary = {
     "boundary"?: string;
     "reset_time"?: string;
@@ -220,11 +225,20 @@ type LevelDefinition = {
     "rewards"?: RecipeOperation[];
     "threshold": number;
 };
+type MatchmakingSettings = {
+    "backfill"?: null | BackfillSettings;
+    "cluster_stagger_seconds"?: number;
+    "enabled": boolean;
+    "fill_window_seconds"?: number;
+    "strategy"?: MatchmakingStrategy;
+    "ticket_expiry_seconds"?: number | null;
+};
+type MatchmakingStrategy = "fifo";
 type OrderBySpec = {
     "column": RunValueColumn;
     "direction": SortDirection;
 };
-type OrderSource = "real_money_purchase" | "real_money_refund" | "full_game_purchase" | "full_game_refund" | "platform_purchase" | "reward" | "admin" | "system" | "promo" | "game_consume" | "play" | "recipe" | "transfer" | "platform_funded_game_inventory_purchase" | "earning_reset";
+type OrderSource = "real_money_purchase" | "real_money_refund" | "full_game_purchase" | "full_game_refund" | "platform_purchase" | "reward" | "admin" | "system" | "promo" | "game_consume" | "play" | "recipe" | "transfer" | "platform_funded_game_inventory_purchase" | "earning_reset" | "test_account_provision" | "developer_grant";
 type OverflowBehavior = "fail" | "clamp" | "allow";
 type PityEffect = "guarantee_tier" | {
     "weight_boost": {
@@ -442,6 +456,7 @@ type SnapshotGameRoomTemplate = {
     "id": string;
     "idle_timeout_seconds"?: number | null;
     "match_type": string;
+    "matchmaking"?: null | MatchmakingSettings;
     "max_match_duration_seconds"?: number | null;
     "max_players": number;
     "min_players": number;
@@ -513,6 +528,7 @@ type SnapshotProgression = {
     "display_name"?: string | null;
     "icon_url"?: string | null;
     "id": string;
+    "localized"?: Record<string, unknown>;
     "progression_type": string;
     "slug"?: string | null;
     "sort_order": number;
@@ -550,6 +566,7 @@ type SnapshotRewardedPlacement = {
     "grants": SnapshotRewardGrant[];
     "max_held"?: number | null;
     "max_per_day"?: number | null;
+    "min_watch_secs"?: number | null;
     "placement": string;
     "reward_class": string;
     "without_ads": string;
@@ -1514,26 +1531,6 @@ interface ClusterTarget {
     readonly id: string;
     readonly pressure: string;
 }
-type RoomArgScalar = string | number | boolean;
-type RoomArgValue$1 = RoomArgScalar | readonly RoomArgScalar[];
-type RoomArgs = Readonly<Record<string, RoomArgValue$1>>;
-type RoomArgType = "string" | "int" | "float" | "bool" | (string & {});
-interface RoomArgEntry {
-    readonly name: string;
-    readonly type: RoomArgType;
-    readonly list: boolean;
-    readonly required: boolean;
-    readonly mutable: boolean;
-    readonly fixed?: RoomArgValue$1;
-    readonly default?: RoomArgValue$1;
-    readonly description?: string;
-    readonly allowed?: readonly RoomArgScalar[];
-    readonly min?: number;
-    readonly max?: number;
-    readonly minItems?: number;
-    readonly maxItems?: number;
-    readonly maxLength?: number;
-}
 type DedicatedServerFailure = "timeout" | "aborted" | "allocation_failed" | "no_server_ready" | "start_rate_limited" | "p2p_unavailable" | "unsupported_protocol" | "credential_expired" | "credential_reused" | "join_rate_limited" | "signaling_unavailable" | "signaling_failed" | "offer_refused" | "invalid_sdp" | "media_refused" | "connection_failed" | "join_refused" | "match_ended" | "misconfigured";
 declare class DedicatedServerError extends Error {
     readonly reason: DedicatedServerFailure;
@@ -1642,6 +1639,26 @@ interface TransportAdvert {
 declare function readTemplateTransports(value: unknown): readonly TransportKind[] | null;
 declare function readTransportAdvert(settings: unknown, forMatch?: string): TransportAdvert | null;
 declare function webTransportAvailable(): boolean;
+type RoomArgScalar = string | number | boolean;
+type RoomArgValue$1 = RoomArgScalar | readonly RoomArgScalar[];
+type RoomArgs = Readonly<Record<string, RoomArgValue$1>>;
+type RoomArgType = "string" | "int" | "float" | "bool" | (string & {});
+interface RoomArgEntry {
+    readonly name: string;
+    readonly type: RoomArgType;
+    readonly list: boolean;
+    readonly required: boolean;
+    readonly mutable: boolean;
+    readonly fixed?: RoomArgValue$1;
+    readonly default?: RoomArgValue$1;
+    readonly description?: string;
+    readonly allowed?: readonly RoomArgScalar[];
+    readonly min?: number;
+    readonly max?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly maxLength?: number;
+}
 type RoomStatus = "open" | "in_game" | "closed" | (string & {});
 type MatchConnectionState = "disconnected" | "connecting" | "connected" | "suspended";
 type MatchSessionPhase = "none" | "starting" | "ready" | "connected" | "suspended" | "ended" | (string & {});
@@ -1739,6 +1756,38 @@ interface RoomOperationError {
     readonly message: string;
     readonly retryable: boolean;
 }
+interface QueueForMatchOptions {
+    readonly templateSlugs: readonly string[];
+    readonly partyId?: string;
+    readonly signal?: AbortSignal;
+}
+type MatchTicketStatus = "queued" | "matched" | "expired" | "cancelled" | "failed" | "lost" | "unavailable";
+type MatchTicketOutcome = {
+    readonly status: "matched";
+    readonly room: Room;
+} | {
+    readonly status: "expired";
+    readonly reason: string;
+} | {
+    readonly status: "cancelled";
+    readonly reason: string;
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+} | {
+    readonly status: "lost";
+} | {
+    readonly status: "unavailable";
+};
+interface MatchTicket {
+    readonly id: string;
+    readonly status: MatchTicketStatus;
+    readonly partySize: number;
+    readonly queuedAt: number;
+    readonly expiresAt: number;
+    readonly outcome: Promise<MatchTicketOutcome>;
+    cancel(): Promise<MatchTicketOutcome>;
+}
 interface CreateRoomOptions {
     readonly name: string;
     readonly maxPlayers?: number;
@@ -1881,6 +1930,7 @@ interface RoomManager {
     join(roomId: string, options?: JoinRoomOptions): Promise<Room>;
     joinByCode(code: string, options?: JoinRoomOptions): Promise<Room>;
     quickJoin(options: QuickJoinOptions): Promise<Room>;
+    queueForMatch(options: QueueForMatchOptions): Promise<MatchTicket>;
     list(options?: ListRoomsOptions): Promise<RoomPage>;
     myRooms(signal?: AbortSignal): Promise<readonly RoomSummary[]>;
     leave(options?: {
@@ -1906,6 +1956,7 @@ interface RoomManager {
     }): Promise<void>;
     readonly gameId: string | null;
     readonly currentRoom: Room | null;
+    readonly currentTicket: MatchTicket | null;
     readonly currentMatch: ReadyMatch | null;
     readonly matchConnectionState: MatchConnectionState;
     readonly matchSession: MatchSession;