castle-web-sdk 0.4.36 → 0.4.37

package/dist/castle.d.ts

@@ -14,9 +14,9 @@ export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, Leaderboard
 export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
-export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
-export type { MultiplayerVoice, VoiceJoinStatus, VoiceMixEntry, VoiceState, } from "./multiplayerVoice";
-export type { MultiplayerSoloReason } from "./commands";
+export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerDestinationJoinResult, MultiplayerDestinationOptions, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
+export type { MultiplayerVoice, VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector, } from "./multiplayerVoice";
+export type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
 export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
 export type { ClientByeFrame, ClientHelloFrame, ClientMessageFrame, ClientPingFrame, ClientPongFrame, ClientReplacedFrame, ClientRosterFrame, ClientToPlatformFrame, ClientToPlatformMessageFrame, MultiplayerPlayer, PlayerIdentity, PlatformToClientFrame, SessionPlayer, SessionType, } from "./multiplayerProtocol";
 export { registerParams } from "./paramsRegistry";

package/dist/commands.d.ts

@@ -103,14 +103,51 @@ export interface MultiplayerGetSessionResult {
     /** Internal local-serve scope for restoring this Play panel after a reload. */
     devReconnectScope?: string;
 }
+export interface MultiplayerJoinDestinationParams {
+    routeId: string;
+    slot: string;
+}
+export type MultiplayerDestinationAudience = "player" | "party" | "public";
+export type MultiplayerJoinDestinationStatus = "ok" | "cancelled" | "full" | "unavailable" | "not_found" | "forbidden" | "party_required";
+export interface MultiplayerJoinDestinationResult {
+    status: MultiplayerJoinDestinationStatus;
+    url: string | null;
+    nonce: string | null;
+    sessionId: string | null;
+    audience: MultiplayerDestinationAudience | null;
+}
 export type VoiceState = "unavailable" | "off" | "joining" | "live";
 export type VoiceJoinStatus = "joined" | "declined" | "unavailable";
 export interface VoiceMixEntry {
     /** 0 (silent) to 1 (full). */
     gain?: number;
-    /** -1 (left) to 1 (right). */
+    /** -1 (left) to 1 (right). Ignored for a player with a 3D position. */
     pan?: number;
 }
+export type VoiceVector = [number, number, number];
+export interface VoiceListener {
+    position: VoiceVector;
+    /** The direction the listener faces; need not be normalized. */
+    forward: VoiceVector;
+    /** Defaults to [0, 1, 0]. */
+    up?: VoiceVector;
+}
+export interface VoiceSpatialOptions {
+    /** How volume falls off with distance; default "inverse". */
+    distanceModel?: "linear" | "inverse" | "exponential";
+    /** Distance at which a voice is at full volume; default 1. */
+    refDistance?: number;
+    /** Beyond this, a voice gets no quieter ("linear": silent); default 100. */
+    maxDistance?: number;
+    /** How fast volume falls off; default 1. */
+    rolloff?: number;
+}
+export interface VoiceSpatialUpdate {
+    listener?: VoiceListener;
+    /** Keyed by userId. `null` returns a player to plain gain and pan. */
+    positions?: Record<string, VoiceVector | null>;
+    options?: VoiceSpatialOptions;
+}
 export interface CharacterSummary {
     id: string;
     version: string;
@@ -303,6 +340,7 @@ export interface CommandParams {
         style: HapticStyle;
     };
     "multiplayer.getSession": MultiplayerGetSessionParams;
+    "multiplayer.joinDestination": MultiplayerJoinDestinationParams;
     "voice.getState": {
         sessionId: string;
     };
@@ -316,6 +354,9 @@ export interface CommandParams {
         sessionId: string;
         mix: Record<string, VoiceMixEntry>;
     };
+    "voice.setSpatial": {
+        sessionId: string;
+    } & VoiceSpatialUpdate;
     "characters.open": {
         characterId: string;
     };
@@ -438,6 +479,7 @@ export interface CommandResult {
     "portal.info": PortalInfoResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
+    "multiplayer.joinDestination": MultiplayerJoinDestinationResult;
     "voice.getState": {
         state: VoiceState;
     };
@@ -450,6 +492,9 @@ export interface CommandResult {
     "voice.setMix": {
         ok: true;
     };
+    "voice.setSpatial": {
+        ok: true;
+    };
     "characters.open": CharacterAdmission;
     "characters.send": CharacterOperation;
     "characters.status": CharacterOperation;

package/dist/multiplayer.d.ts

@@ -1,4 +1,4 @@
-import type { MultiplayerSoloReason } from "./commands";
+import type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
 import { type MultiplayerPlayer } from "./multiplayerProtocol";
 import { type MultiplayerVoice } from "./multiplayerVoice";
@@ -10,6 +10,17 @@ export type MultiplayerJoinOptions = {
 } | {
     mode: "public";
 };
+export interface MultiplayerDestinationOptions {
+    routeId: string;
+    slot: string;
+}
+export type MultiplayerDestinationJoinResult = {
+    status: "joined";
+    connection: MultiplayerConnection;
+    audience: MultiplayerDestinationAudience;
+} | {
+    status: "cancelled" | "full" | "unavailable" | "not_found" | "forbidden" | "party_required";
+};
 export type MultiplayerConnectionState = "acquiring" | "connecting" | "connected" | "reconnecting" | "closed";
 export type MultiplayerStateMetadata = {
     type: "connectionLost";
@@ -50,5 +61,6 @@ export interface MultiplayerConnection {
 }
 export interface CastleMultiplayerApi {
     join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
+    joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;
 }
 export declare const Multiplayer: CastleMultiplayerApi;

package/dist/multiplayer.js

@@ -8,11 +8,15 @@ const RECONNECT_BUDGET_MS = 30_000;
 const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
 const INVALID_DEV_RECONNECT_CLOSE_CODE = 4003;
 let activeConnection = null;
-export const Multiplayer = { join };
+let latestJoinAttempt = 0;
+let pendingDestinationJoin = null;
+export const Multiplayer = { join, joinDestination };
 async function join(options) {
     const params = joinParams(options);
+    latestJoinAttempt += 1;
+    cancelPendingDestinationJoin();
     activeConnection?.leave();
-    const connection = new MultiplayerConnectionImpl(params, () => {
+    const connection = new MultiplayerConnectionImpl({ command: "multiplayer.getSession", params }, () => {
         if (activeConnection === connection)
             activeConnection = null;
     });
@@ -20,9 +24,80 @@ async function join(options) {
     await connection.start();
     return connection;
 }
+async function joinDestination(options) {
+    const params = destinationParams(options);
+    const attempt = ++latestJoinAttempt;
+    cancelPendingDestinationJoin();
+    if (activeConnection?.matchesDestination(params)) {
+        return {
+            status: "joined",
+            connection: activeConnection,
+            audience: activeConnection.destinationAudience,
+        };
+    }
+    const previousConnection = activeConnection;
+    const controller = new AbortController();
+    const pending = { controller, connection: null };
+    pendingDestinationJoin = pending;
+    let acquired;
+    try {
+        acquired = await hostRequest("multiplayer.joinDestination", params, {
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (pendingDestinationJoin === pending)
+            pendingDestinationJoin = null;
+        if (attempt !== latestJoinAttempt || controller.signal.aborted) {
+            return { status: "cancelled" };
+        }
+        const status = destinationStatusFromError(error);
+        if (status)
+            return { status };
+        throw error;
+    }
+    if (attempt !== latestJoinAttempt)
+        return { status: "cancelled" };
+    if (acquired.status !== "ok") {
+        if (pendingDestinationJoin === pending)
+            pendingDestinationJoin = null;
+        return { status: acquired.status };
+    }
+    if (!acquired.url || !acquired.nonce || !acquired.audience) {
+        if (pendingDestinationJoin === pending)
+            pendingDestinationJoin = null;
+        return { status: "unavailable" };
+    }
+    const connection = new MultiplayerConnectionImpl({ command: "multiplayer.joinDestination", params }, () => {
+        if (activeConnection === connection)
+            activeConnection = null;
+    }, acquired.audience);
+    pending.connection = connection;
+    try {
+        await connection.start(acquired);
+    }
+    catch (error) {
+        if (pendingDestinationJoin === pending)
+            pendingDestinationJoin = null;
+        if (attempt !== latestJoinAttempt || controller.signal.aborted) {
+            return { status: "cancelled" };
+        }
+        throw error;
+    }
+    if (pendingDestinationJoin === pending)
+        pendingDestinationJoin = null;
+    if (attempt !== latestJoinAttempt) {
+        connection.leave();
+        return { status: "cancelled" };
+    }
+    previousConnection?.leave();
+    activeConnection = connection;
+    return { status: "joined", connection, audience: acquired.audience };
+}
 class MultiplayerConnectionImpl {
-    params;
+    request;
     onClosed;
+    destinationAudience;
     currentState = "acquiring";
     currentPlayerId = "";
     currentSessionId = "";
@@ -45,9 +120,10 @@ class MultiplayerConnectionImpl {
         players: () => this.roster?.players ?? [],
         isSolo: () => this.solo,
     });
-    constructor(params, onClosed) {
-        this.params = params;
+    constructor(request, onClosed, destinationAudience = null) {
+        this.request = request;
         this.onClosed = onClosed;
+        this.destinationAudience = destinationAudience;
     }
     get state() {
         return this.currentState;
@@ -67,9 +143,9 @@ class MultiplayerConnectionImpl {
     get voice() {
         return this.voiceImpl;
     }
-    async start() {
+    async start(initial) {
         try {
-            await this.acquire();
+            await this.acquire(initial);
         }
         catch (error) {
             const castleError = asCastleError(error);
@@ -117,9 +193,16 @@ class MultiplayerConnectionImpl {
             return;
         this.finish({ type: "left" });
     }
-    async acquire() {
+    matchesDestination(params) {
+        return (this.currentState !== "closed" &&
+            this.request.command === "multiplayer.joinDestination" &&
+            this.request.params.routeId === params.routeId &&
+            this.request.params.slot === params.slot &&
+            this.destinationAudience !== null);
+    }
+    async acquire(initial) {
         this.transition("acquiring");
-        const result = await hostRequest("multiplayer.getSession", this.params);
+        const result = initial ?? await requestAcquisition(this.request);
         this.assertOpen();
         if (result.status === "solo") {
             this.connectSolo(result);
@@ -131,8 +214,11 @@ class MultiplayerConnectionImpl {
         this.solo = false;
         this.currentSoloReason = null;
         this.baseUrl = result.url;
-        this.devReconnectStorageKey = result.devReconnectScope
-            ? `castle-dev-mp-reconnect:${result.url}:${result.sessionId}:${result.devReconnectScope}`
+        const devReconnectScope = "devReconnectScope" in result
+            ? result.devReconnectScope
+            : undefined;
+        this.devReconnectStorageKey = devReconnectScope
+            ? `castle-dev-mp-reconnect:${result.url}:${result.sessionId}:${devReconnectScope}`
             : null;
         this.transition("connecting");
         const savedToken = this.devReconnectStorageKey
@@ -436,6 +522,62 @@ function joinParams(options) {
     }
     throw invalidJoinOptions();
 }
+function destinationParams(options) {
+    if (!options ||
+        typeof options !== "object" ||
+        typeof options.routeId !== "string" ||
+        !/^[A-Za-z0-9_-]{1,64}$/.test(options.routeId) ||
+        typeof options.slot !== "string" ||
+        options.slot.length === 0 ||
+        options.slot.includes("\0") ||
+        !isValidUnicode(options.slot) ||
+        new TextEncoder().encode(options.slot).byteLength > 128) {
+        throw multiplayerError("INVALID_ARGUMENT", "Multiplayer.joinDestination requires a valid routeId and a non-empty slot of at most 128 bytes.", "Multiplayer.joinDestination");
+    }
+    return { routeId: options.routeId, slot: options.slot };
+}
+function cancelPendingDestinationJoin() {
+    const pending = pendingDestinationJoin;
+    pendingDestinationJoin = null;
+    pending?.controller.abort();
+    pending?.connection?.leave();
+}
+async function requestAcquisition(request) {
+    if (request.command === "multiplayer.getSession") {
+        return hostRequest(request.command, request.params);
+    }
+    return hostRequest(request.command, request.params);
+}
+function destinationStatusFromError(error) {
+    if (!(error instanceof CastleError))
+        return null;
+    switch (error.code) {
+        case "CAULDRON_DESTINATION_NOT_FOUND":
+            return "not_found";
+        case "CAULDRON_DESTINATION_FORBIDDEN":
+            return "forbidden";
+        case "CAULDRON_DESTINATION_PARTY_REQUIRED":
+            return "party_required";
+        case "CAULDRON_DESTINATION_FULL":
+            return "full";
+        case "CAULDRON_DESTINATION_UNAVAILABLE":
+        case "CAULDRON_DESTINATION_CONFIG_CHANGED":
+            return "unavailable";
+        case "CANCELLED":
+            return "cancelled";
+        default:
+            return null;
+    }
+}
+function isValidUnicode(value) {
+    try {
+        encodeURIComponent(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function invalidJoinOptions() {
     return multiplayerError("INVALID_ARGUMENT", "Multiplayer.join requires named, party, or public options.");
 }

package/dist/multiplayerVoice.d.ts

@@ -1,7 +1,7 @@
-import type { VoiceEvent, VoiceJoinStatus, VoiceMixEntry, VoiceState } from "./commands";
+import type { VoiceEvent, VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector } from "./commands";
 import type { MultiplayerPlayer } from "./multiplayerProtocol";
 export declare const VOICE_MIX_INTERVAL_MS = 100;
-export type { VoiceJoinStatus, VoiceMixEntry, VoiceState };
+export type { VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector, };
 export interface MultiplayerVoice {
     /** "unavailable" when this host, deck, session or player can't have voice. */
     readonly state: VoiceState;
@@ -18,6 +18,19 @@ export interface MultiplayerVoice {
      * full volume, centered). Sent at most ten times a second; the latest values win.
      */
     setMix(mix: Record<string, VoiceMixEntry>): void;
+    /**
+     * 3D voice: where the listener (usually the local player's camera) is and faces, in
+     * the deck's world units, y up. With positions set, voices come from their place in
+     * the world (distance, left/right, front/behind, above/below; best on headphones).
+     */
+    setListener(listener: VoiceListener): void;
+    /**
+     * Where each player's voice comes from, keyed by playerId. `null` returns a player
+     * to plain gain and pan. Their `setMix` gain still applies; their pan does not.
+     */
+    setPositions(positions: Record<string, VoiceVector | null>): void;
+    /** How voices fade with distance. Defaults: inverse, refDistance 1, maxDistance 100, rolloff 1. */
+    setSpatialOptions(options: VoiceSpatialOptions): void;
     onState(callback: (state: VoiceState) => void): () => void;
     /** The playerIds speaking right now; called whenever that set changes. */
     onSpeaking(callback: (playerIds: string[]) => void): () => void;
@@ -39,6 +52,12 @@ export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
     private speaking;
     private pendingMix;
     private sentMix;
+    private pendingListener;
+    private pendingPositions;
+    private pendingOptions;
+    private sentListener;
+    private sentPositions;
+    private sentOptions;
     private mixTimer;
     private lastMixSentAt;
     private disposed;
@@ -51,6 +70,9 @@ export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
     private askToJoin;
     leave(): void;
     setMix(mix: Record<string, VoiceMixEntry>): void;
+    setListener(listener: VoiceListener): void;
+    setPositions(positions: Record<string, VoiceVector | null>): void;
+    setSpatialOptions(options: VoiceSpatialOptions): void;
     onState(callback: (state: VoiceState) => void): () => void;
     onSpeaking(callback: (playerIds: string[]) => void): () => void;
     receive(event: VoiceEvent): void;
@@ -62,6 +84,8 @@ export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
     private sendLeave;
     private setState;
     private emitSpeaking;
+    private hasPending;
     private scheduleMix;
     private flushMix;
+    private takeSpatial;
 }

package/dist/multiplayerVoice.js

@@ -31,6 +31,13 @@ export class MultiplayerVoiceImpl {
     speaking = [];
     pendingMix = {};
     sentMix = {};
+    // Spatial state: pending (not yet sent) and sent (re-sent when a call restarts).
+    pendingListener = null;
+    pendingPositions = {};
+    pendingOptions = null;
+    sentListener = null;
+    sentPositions = {};
+    sentOptions = null;
     mixTimer = null;
     lastMixSentAt = 0;
     disposed = false;
@@ -163,6 +170,45 @@ export class MultiplayerVoiceImpl {
         }
         this.scheduleMix();
     }
+    setListener(listener) {
+        if (this.disposed || !listener || typeof listener !== "object")
+            return;
+        const position = vector(listener.position);
+        const forward = vector(listener.forward);
+        const up = listener.up === undefined ? undefined : vector(listener.up);
+        // A zero direction faces nowhere (a player standing still, say): keep the last
+        // listener rather than send one the host would drop.
+        if (!position || !forward || up === null || isZero(forward) || (up && isZero(up)))
+            return;
+        this.pendingListener = up ? { position, forward, up } : { position, forward };
+        this.scheduleMix();
+    }
+    setPositions(positions) {
+        if (this.disposed || !positions || typeof positions !== "object")
+            return;
+        const players = this.access.players();
+        for (const [playerId, value] of Object.entries(positions)) {
+            const player = players.find((candidate) => candidate.playerId === playerId);
+            if (!player)
+                continue;
+            if (value === null) {
+                this.pendingPositions[player.userId] = null;
+                continue;
+            }
+            const position = vector(value);
+            if (position)
+                this.pendingPositions[player.userId] = position;
+        }
+        this.scheduleMix();
+    }
+    setSpatialOptions(options) {
+        if (this.disposed || !options || typeof options !== "object")
+            return;
+        // Cumulative: the host fills every missing field with its default, so each send
+        // carries everything the deck has set so far.
+        this.pendingOptions = { ...this.sentOptions, ...this.pendingOptions, ...options };
+        this.scheduleMix();
+    }
     onState(callback) {
         this.states.add(callback);
         callListener(callback, this.currentState);
@@ -198,6 +244,14 @@ export class MultiplayerVoiceImpl {
             if (!userIds.has(userId))
                 delete this.sentMix[userId];
         }
+        for (const userId of Object.keys(this.pendingPositions)) {
+            if (!userIds.has(userId))
+                delete this.pendingPositions[userId];
+        }
+        for (const userId of Object.keys(this.sentPositions)) {
+            if (!userIds.has(userId))
+                delete this.sentPositions[userId];
+        }
         this.emitSpeaking();
     }
     // The game connection ended: voice for its session goes with it.
@@ -230,6 +284,12 @@ export class MultiplayerVoiceImpl {
         this.speakingUserIds = [];
         this.pendingMix = {};
         this.sentMix = {};
+        this.pendingListener = null;
+        this.pendingPositions = {};
+        this.pendingOptions = null;
+        this.sentListener = null;
+        this.sentPositions = {};
+        this.sentOptions = null;
         this.emitSpeaking();
     }
     sendLeave(sessionId) {
@@ -249,6 +309,12 @@ export class MultiplayerVoiceImpl {
             for (const userId of Object.keys(this.sentMix)) {
                 this.pendingMix[userId] ??= {};
             }
+            this.pendingListener ??= this.sentListener;
+            this.pendingOptions ??= this.sentOptions;
+            for (const [userId, position] of Object.entries(this.sentPositions)) {
+                if (!(userId in this.pendingPositions))
+                    this.pendingPositions[userId] = position;
+            }
             this.scheduleMix();
         }
     }
@@ -265,8 +331,14 @@ export class MultiplayerVoiceImpl {
         for (const callback of this.speakers)
             callListener(callback, playerIds.slice());
     }
+    hasPending() {
+        return (Object.keys(this.pendingMix).length > 0 ||
+            Object.keys(this.pendingPositions).length > 0 ||
+            this.pendingListener !== null ||
+            this.pendingOptions !== null);
+    }
     scheduleMix() {
-        if (this.mixTimer !== null || Object.keys(this.pendingMix).length === 0)
+        if (this.mixTimer !== null || !this.hasPending())
             return;
         const wait = Math.max(0, this.lastMixSentAt + VOICE_MIX_INTERVAL_MS - Date.now());
         this.mixTimer = setTimeout(() => {
@@ -290,11 +362,54 @@ export class MultiplayerVoiceImpl {
             mix[userId] = full;
         }
         this.pendingMix = {};
-        if (Object.keys(mix).length === 0)
+        const spatial = this.takeSpatial(userIds);
+        if (Object.keys(mix).length === 0 && !spatial)
             return;
         this.lastMixSentAt = Date.now();
-        void hostRequest("voice.setMix", { sessionId: this.voiceSessionId, mix }).catch(() => { });
+        if (Object.keys(mix).length > 0) {
+            void hostRequest("voice.setMix", { sessionId: this.voiceSessionId, mix }).catch(() => { });
+        }
+        if (spatial) {
+            void hostRequest("voice.setSpatial", { sessionId: this.voiceSessionId, ...spatial }).catch(() => { });
+        }
     }
+    takeSpatial(userIds) {
+        const update = {};
+        if (this.pendingListener) {
+            update.listener = this.pendingListener;
+            this.sentListener = this.pendingListener;
+        }
+        if (this.pendingOptions) {
+            update.options = this.pendingOptions;
+            this.sentOptions = this.pendingOptions;
+        }
+        const positions = {};
+        for (const [userId, position] of Object.entries(this.pendingPositions)) {
+            if (!userIds.has(userId))
+                continue;
+            positions[userId] = position;
+            if (position)
+                this.sentPositions[userId] = position;
+            else
+                delete this.sentPositions[userId];
+        }
+        if (Object.keys(positions).length > 0)
+            update.positions = positions;
+        this.pendingListener = null;
+        this.pendingOptions = null;
+        this.pendingPositions = {};
+        return update.listener || update.options || update.positions ? update : null;
+    }
+}
+function vector(value) {
+    return Array.isArray(value) &&
+        value.length === 3 &&
+        value.every((component) => typeof component === "number" && Number.isFinite(component))
+        ? [value[0], value[1], value[2]]
+        : null;
+}
+function isZero(value) {
+    return value[0] === 0 && value[1] === 0 && value[2] === 0;
 }
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));

package/dist/server/platformHandle.d.ts

@@ -1,3 +1,4 @@
+import type { Json } from "../types";
 export type MultiplayerSessionMode = "named" | "party" | "public";
 export interface PlayerIdentity {
     userId: string;
@@ -11,6 +12,15 @@ export interface PlatformSessionConfig {
     readonly mode: MultiplayerSessionMode;
     readonly tickRate: number;
     readonly maxPlayers: number;
+    readonly world?: PlatformWorldSnapshot;
+}
+export interface PlatformWorldCheckpoint {
+    version: number;
+    value: Json;
+}
+export interface PlatformWorldSnapshot {
+    revision: string;
+    checkpoint: PlatformWorldCheckpoint | null;
 }
 export interface PlatformHandle {
     send(connId: string, text: string): void;
@@ -34,5 +44,8 @@ export interface PlatformHandle {
     storage?(op: string, argsJson: string): Promise<string>;
     /** False when the host cannot broker storage, so a call can fail at once. */
     readonly storageEnabled?: boolean;
+    /** Persistent-world checkpoint broker. The host stamps the hidden world binding. */
+    worldCheckpointRead?(): Promise<string>;
+    worldCheckpointCommit?(argsJson: string): Promise<string>;
     readonly config: PlatformSessionConfig;
 }

package/dist/server/wrapper.d.ts

@@ -1,6 +1,7 @@
 import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
+import type { Json } from "../types";
 import { type ServerStorage } from "./storage";
-export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlayerIdentity, } from "./platformHandle";
+export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlayerIdentity, } from "./platformHandle";
 export type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
 export interface MultiplayerServerPlayer extends PlayerIdentity {
     playerId: string;
@@ -18,12 +19,40 @@ export interface MultiplayerServerSession {
      * when its last player leaves and its memory goes with it.
      */
     readonly storage: ServerStorage;
+    /** A durable checkpoint for an opted-in persistent destination. */
+    readonly world: MultiplayerServerWorld | null;
     /** Sends bytes as a binary message and all other payloads as JSON. */
     send(playerId: string, data: unknown): void;
     /** Broadcasts bytes as a binary message and all other payloads as JSON. */
     broadcast(data: unknown, options?: MultiplayerBroadcastOptions): void;
     disconnect(playerId: string, reason?: string): void;
 }
+export interface MultiplayerWorldCheckpoint {
+    version: number;
+    value: Json;
+}
+export interface MultiplayerWorldSnapshot {
+    revision: string;
+    checkpoint: MultiplayerWorldCheckpoint | null;
+}
+export interface MultiplayerWorldCommitInput {
+    expectedRevision: string;
+    operationId: string;
+    checkpoint: MultiplayerWorldCheckpoint;
+}
+export interface MultiplayerWorldCommitReceipt {
+    revision: string;
+    replayed: boolean;
+    operationId: string;
+}
+export interface MultiplayerServerWorld {
+    /** The checkpoint acquired before this runtime started. */
+    readonly snapshot: MultiplayerWorldSnapshot;
+    /** Reads the latest durable checkpoint, for example after a revision conflict. */
+    read(): Promise<MultiplayerWorldSnapshot>;
+    /** Commits exactly against expectedRevision; conflicts never partially write. */
+    commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
+}
 type CallbackResult = unknown;
 export interface MultiplayerServerCallbacks {
     onStart?: (session: MultiplayerServerSession) => CallbackResult;

package/dist/server/wrapper.js

@@ -1,4 +1,5 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
+import { encodeStorageValue } from "../storageJson";
 import { createServerStorage } from "./storage";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
@@ -68,6 +69,7 @@ function createAuthorSession(platformHandle, players) {
         deckId: platformHandle.config.deckId,
         mode: platformHandle.config.mode,
         storage: createServerStorage(platformHandle),
+        world: createServerWorld(platformHandle),
         send(playerId, data) {
             if (isBinaryPayload(data)) {
                 requireSendBinary(platformHandle);
@@ -106,6 +108,96 @@ function createAuthorSession(platformHandle, players) {
         },
     };
 }
+const WORLD_OPERATION_ID_MAX_BYTES = 128;
+const WORLD_OPERATION_ID_MAX_CHARACTERS = 120;
+const WORLD_CHECKPOINT_VERSION_MAX = 2_147_483_647;
+function createServerWorld(platformHandle) {
+    if (!platformHandle.config.world)
+        return null;
+    if (typeof platformHandle.worldCheckpointRead !== "function" ||
+        typeof platformHandle.worldCheckpointCommit !== "function") {
+        throw worldError("The persistent-world checkpoint broker is unavailable.", "read");
+    }
+    const initial = parseWorldSnapshot(platformHandle.config.world, "read");
+    return Object.freeze({
+        snapshot: initial,
+        async read() {
+            const result = await platformHandle.worldCheckpointRead();
+            return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
+        },
+        async commit(input) {
+            const expectedRevision = assertWorldRevision(input?.expectedRevision);
+            const operationId = assertWorldOperationId(input?.operationId);
+            const checkpoint = assertWorldCheckpoint(input?.checkpoint);
+            const raw = await platformHandle.worldCheckpointCommit(JSON.stringify({
+                expectedRevision,
+                operationId,
+                checkpoint,
+            }));
+            const result = parsePlatformJson(raw, "commit");
+            if (typeof result.replayed !== "boolean") {
+                throw worldError("The platform returned an invalid commit receipt.", "commit");
+            }
+            return Object.freeze({
+                revision: assertWorldRevision(result.revision),
+                replayed: result.replayed,
+                operationId,
+            });
+        },
+    });
+}
+function parseWorldSnapshot(value, operation) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw worldError("The platform returned an invalid world checkpoint.", "read");
+    }
+    const raw = value;
+    return Object.freeze({
+        revision: assertWorldRevision(raw.revision),
+        checkpoint: raw.checkpoint === null
+            ? null
+            : assertWorldCheckpoint(raw.checkpoint, operation),
+    });
+}
+function assertWorldCheckpoint(value, operation = "commit") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw worldError("A world checkpoint requires version and value.", operation);
+    }
+    const raw = value;
+    if (!Number.isSafeInteger(raw.version) ||
+        raw.version < 0 ||
+        raw.version > WORLD_CHECKPOINT_VERSION_MAX) {
+        throw worldError(`A world checkpoint version must be an integer from 0 through ${WORLD_CHECKPOINT_VERSION_MAX}.`, operation);
+    }
+    const text = encodeStorageValue(raw.value, `session.world.${operation}`);
+    const normalized = JSON.parse(text);
+    return Object.freeze({ version: raw.version, value: normalized });
+}
+function assertWorldRevision(value) {
+    if (typeof value === "string" && /^(?:0|[1-9][0-9]*)$/.test(value))
+        return value;
+    throw worldError("A world checkpoint revision must be a canonical decimal string.", "commit");
+}
+function assertWorldOperationId(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > WORLD_OPERATION_ID_MAX_CHARACTERS ||
+        value.includes("\0") ||
+        new TextEncoder().encode(value).byteLength > WORLD_OPERATION_ID_MAX_BYTES) {
+        throw worldError(`A world checkpoint operation id must be at most ${WORLD_OPERATION_ID_MAX_CHARACTERS} characters and ${WORLD_OPERATION_ID_MAX_BYTES} bytes.`, "commit");
+    }
+    return value;
+}
+function parsePlatformJson(value, operation) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw worldError("The platform returned an invalid world checkpoint response.", operation);
+    }
+}
+function worldError(message, operation) {
+    return new TypeError(`session.world.${operation}: ${message}`);
+}
 function requireSendBinary(platformHandle) {
     if (typeof platformHandle.sendBinary !== "function")
         unsupportedBinaryRuntime();

package/dist/transport.js

@@ -23,6 +23,7 @@ const INTERACTIVE_COMMANDS = new Set([
     "pass.offer",
     "snapshot.offer",
     "portal.open",
+    "multiplayer.joinDestination",
     // The host's voice prompt and the browser's microphone permission.
     "voice.requestJoin",
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.36",
+  "version": "0.4.37",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"