castle-web-sdk 0.4.35 → 0.4.37

package/dist/multiplayerVoice.d.ts

@@ -0,0 +1,91 @@
+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, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector, };
+export interface MultiplayerVoice {
+    /** "unavailable" when this host, deck, session or player can't have voice. */
+    readonly state: VoiceState;
+    /**
+     * Asks the player to join voice. The host shows its own prompt; nothing happens
+     * without the player's say-so. Resolves once they have chosen.
+     */
+    requestJoin(): Promise<VoiceJoinStatus>;
+    /** Leaves voice, or withdraws a pending request. The game connection is unaffected. */
+    leave(): void;
+    /**
+     * Suggested volume (0-1) and stereo position (-1 left to 1 right) per player,
+     * keyed by playerId. Players and fields not named keep their last value (initially
+     * 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;
+}
+export interface VoiceSessionAccess {
+    sessionId(): string;
+    players(): MultiplayerPlayer[];
+    isSolo(): boolean;
+}
+export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
+    private readonly access;
+    private currentState;
+    private voiceSessionId;
+    private attaching;
+    private hostStateVersion;
+    private pendingJoin;
+    private joinRequest;
+    private speakingUserIds;
+    private speaking;
+    private pendingMix;
+    private sentMix;
+    private pendingListener;
+    private pendingPositions;
+    private pendingOptions;
+    private sentListener;
+    private sentPositions;
+    private sentOptions;
+    private mixTimer;
+    private lastMixSentAt;
+    private disposed;
+    private readonly states;
+    private readonly speakers;
+    constructor(access: VoiceSessionAccess);
+    get state(): VoiceState;
+    attach(): Promise<void>;
+    requestJoin(): Promise<VoiceJoinStatus>;
+    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;
+    rosterChanged(): void;
+    dispose(): void;
+    private isCurrent;
+    private withdraw;
+    private endSession;
+    private sendLeave;
+    private setState;
+    private emitSpeaking;
+    private hasPending;
+    private scheduleMix;
+    private flushMix;
+    private takeSpatial;
+}

package/dist/multiplayerVoice.js

@@ -0,0 +1,424 @@
+import { hostRequest, setVoiceEventHandler } from "./transport";
+// Voice chat in a multiplayer session. The host (castle.xyz or the Castle app) owns
+// the microphone, the call and playback, and shows its own prompt and live-mic badge; a
+// deck never touches audio. What a deck gets: whether voice is on, a way to ask the
+// player to join, who is speaking, and a suggested volume and stereo position per
+// player (proximity chat). Push-to-talk and muting are the player's, in the host's UI.
+// A deck driving proximity every frame sends far more than the host needs.
+export const VOICE_MIX_INTERVAL_MS = 100;
+const DEFAULT_MIX = { gain: 1, pan: 0 };
+let activeVoice = null;
+function dispatchVoiceEvent(event) {
+    activeVoice?.receive(event);
+}
+// One multiplayer connection is live at a time, so one voice receives host events.
+function setActiveVoice(voice, current) {
+    if (current && activeVoice !== current)
+        return;
+    activeVoice = voice;
+}
+export class MultiplayerVoiceImpl {
+    access;
+    currentState = "unavailable";
+    // The session this voice state belongs to; "" before the first attach or in solo.
+    voiceSessionId = "";
+    attaching = null;
+    // Bumped on every host state event, so a join reply never overrides a newer one.
+    hostStateVersion = 0;
+    pendingJoin = null;
+    joinRequest = null;
+    speakingUserIds = [];
+    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;
+    states = new Set();
+    speakers = new Set();
+    constructor(access) {
+        this.access = access;
+    }
+    get state() {
+        return this.currentState;
+    }
+    // Called by the connection whenever it (re)gains a session. A reconnect keeps the
+    // session; a re-acquisition may land in a different one, or in solo, and voice for
+    // the old session ends with it. Asks the host where voice stands; a host without
+    // voice (an older app, local dev) answers with an error or "unavailable".
+    attach() {
+        if (this.disposed)
+            return Promise.resolve();
+        setActiveVoice(this);
+        setVoiceEventHandler(dispatchVoiceEvent);
+        const sessionId = this.access.isSolo() ? "" : this.access.sessionId();
+        if (this.voiceSessionId !== sessionId) {
+            this.endSession();
+            // The old session's state means nothing for the new one until the host answers.
+            this.setState("unavailable");
+        }
+        this.voiceSessionId = sessionId;
+        if (!sessionId) {
+            this.setState("unavailable");
+            this.attaching = null;
+            return Promise.resolve();
+        }
+        const attaching = hostRequest("voice.getState", { sessionId }).then((result) => {
+            if (this.isCurrent(sessionId))
+                this.setState(result.state);
+        }, () => {
+            if (this.isCurrent(sessionId))
+                this.setState("unavailable");
+        });
+        this.attaching = attaching;
+        return attaching;
+    }
+    // A second call while the player is still choosing shares the first one's answer.
+    requestJoin() {
+        if (!this.joinRequest) {
+            const request = this.askToJoin().finally(() => {
+                if (this.joinRequest === request)
+                    this.joinRequest = null;
+            });
+            this.joinRequest = request;
+        }
+        return this.joinRequest;
+    }
+    async askToJoin() {
+        // Registered before any waiting, so leave() or a session change can withdraw a
+        // request that hasn't reached the host yet.
+        const pending = new AbortController();
+        this.pendingJoin = pending;
+        // `join()` resolves at hello, before the host has said whether voice is on. A
+        // reconnect can attach again meanwhile; wait for the latest answer.
+        let awaited = null;
+        while (this.attaching && this.attaching !== awaited) {
+            awaited = this.attaching;
+            await awaited;
+        }
+        if (pending.signal.aborted ||
+            this.disposed ||
+            !this.voiceSessionId ||
+            this.currentState === "unavailable" ||
+            this.currentState === "live") {
+            if (this.pendingJoin === pending)
+                this.pendingJoin = null;
+            if (pending.signal.aborted || this.currentState !== "live")
+                return "unavailable";
+            return "joined";
+        }
+        const sessionId = this.voiceSessionId;
+        const version = this.hostStateVersion;
+        this.setState("joining");
+        let status;
+        try {
+            ({ status } = await hostRequest("voice.requestJoin", { sessionId }, { signal: pending.signal }));
+        }
+        catch {
+            status = "unavailable";
+        }
+        finally {
+            if (this.pendingJoin === pending)
+                this.pendingJoin = null;
+        }
+        if (pending.signal.aborted || !this.isCurrent(sessionId)) {
+            // Withdrawn, or the game connection ended, while the player was choosing. The
+            // abort already cancelled the request at the host, whose executor undoes a
+            // "yes" that lands anyway.
+            return "unavailable";
+        }
+        if (version === this.hostStateVersion) {
+            this.setState(status === "joined" ? "live" : status === "unavailable" ? "unavailable" : "off");
+        }
+        return status;
+    }
+    leave() {
+        if (this.disposed)
+            return;
+        const inVoice = this.currentState === "live" || this.currentState === "joining";
+        if (!inVoice && this.pendingJoin === null)
+            return;
+        this.withdraw();
+        if (inVoice) {
+            this.setState("off");
+            this.sendLeave(this.voiceSessionId);
+        }
+    }
+    setMix(mix) {
+        if (this.disposed || !mix || typeof mix !== "object")
+            return;
+        const players = this.access.players();
+        for (const [playerId, entry] of Object.entries(mix)) {
+            const player = players.find((candidate) => candidate.playerId === playerId);
+            if (!player || !entry || typeof entry !== "object")
+                continue;
+            const next = { ...this.pendingMix[player.userId] };
+            if (typeof entry.gain === "number" && Number.isFinite(entry.gain)) {
+                next.gain = clamp(entry.gain, 0, 1);
+            }
+            if (typeof entry.pan === "number" && Number.isFinite(entry.pan)) {
+                next.pan = clamp(entry.pan, -1, 1);
+            }
+            this.pendingMix[player.userId] = next;
+        }
+        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);
+        return () => this.states.delete(callback);
+    }
+    onSpeaking(callback) {
+        this.speakers.add(callback);
+        callListener(callback, this.speaking.slice());
+        return () => this.speakers.delete(callback);
+    }
+    receive(event) {
+        if (this.disposed || !this.voiceSessionId || event.sessionId !== this.voiceSessionId) {
+            return;
+        }
+        if (event.type === "state") {
+            this.hostStateVersion += 1;
+            this.setState(event.state);
+            return;
+        }
+        this.speakingUserIds = event.userIds.slice();
+        this.emitSpeaking();
+    }
+    // The roster changed: speakers are re-mapped, and mixes for players who left dropped.
+    rosterChanged() {
+        if (this.disposed)
+            return;
+        const userIds = new Set(this.access.players().map((player) => player.userId));
+        for (const userId of Object.keys(this.pendingMix)) {
+            if (!userIds.has(userId))
+                delete this.pendingMix[userId];
+        }
+        for (const userId of Object.keys(this.sentMix)) {
+            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.
+    dispose() {
+        if (this.disposed)
+            return;
+        this.endSession();
+        this.setState("unavailable");
+        this.disposed = true;
+        if (this.mixTimer !== null)
+            clearTimeout(this.mixTimer);
+        this.mixTimer = null;
+        setActiveVoice(null, this);
+    }
+    isCurrent(sessionId) {
+        return !this.disposed && sessionId !== "" && sessionId === this.voiceSessionId;
+    }
+    // Cancels a pending request, so a retry starts a fresh prompt.
+    withdraw() {
+        this.pendingJoin?.abort();
+        this.pendingJoin = null;
+        this.joinRequest = null;
+    }
+    // Leaves the current voice session, if the player is in it or being asked.
+    endSession() {
+        const inVoice = this.currentState === "live" || this.currentState === "joining" || this.pendingJoin !== null;
+        this.withdraw();
+        if (inVoice && this.voiceSessionId)
+            this.sendLeave(this.voiceSessionId);
+        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) {
+        void hostRequest("voice.leave", { sessionId }).catch(() => { });
+    }
+    setState(state) {
+        if (this.currentState === state)
+            return;
+        this.currentState = state;
+        if (state !== "live")
+            this.speakingUserIds = [];
+        this.emitSpeaking();
+        for (const callback of this.states)
+            callListener(callback, state);
+        if (state === "live") {
+            // A rejoined call starts from scratch at the host: send the deck's mix again.
+            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();
+        }
+    }
+    emitSpeaking() {
+        const userIds = new Set(this.speakingUserIds);
+        const playerIds = this.access
+            .players()
+            .filter((player) => userIds.has(player.userId))
+            .map((player) => player.playerId)
+            .sort();
+        if (playerIds.join("\n") === this.speaking.join("\n"))
+            return;
+        this.speaking = playerIds;
+        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 || !this.hasPending())
+            return;
+        const wait = Math.max(0, this.lastMixSentAt + VOICE_MIX_INTERVAL_MS - Date.now());
+        this.mixTimer = setTimeout(() => {
+            this.mixTimer = null;
+            this.flushMix();
+        }, wait);
+    }
+    // Held until the player is in voice, then sent: the latest mix is what matters. Each
+    // entry goes out whole, so a field the deck didn't name keeps its last value.
+    flushMix() {
+        if (this.disposed || !this.voiceSessionId || this.currentState !== "live")
+            return;
+        const userIds = new Set(this.access.players().map((player) => player.userId));
+        const mix = {};
+        for (const [userId, entry] of Object.entries(this.pendingMix)) {
+            if (!userIds.has(userId))
+                continue;
+            const previous = this.sentMix[userId] ?? DEFAULT_MIX;
+            const full = { gain: entry.gain ?? previous.gain, pan: entry.pan ?? previous.pan };
+            this.sentMix[userId] = full;
+            mix[userId] = full;
+        }
+        this.pendingMix = {};
+        const spatial = this.takeSpatial(userIds);
+        if (Object.keys(mix).length === 0 && !spatial)
+            return;
+        this.lastMixSentAt = Date.now();
+        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));
+}
+function callListener(callback, value) {
+    try {
+        callback(value);
+    }
+    catch {
+        // One deck listener must not break voice or other listeners.
+    }
+}

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;