castle-web-sdk 0.4.36 → 0.4.38

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;
@@ -24,6 +34,9 @@ export interface PlatformHandle {
     on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
     on(event: "replaced", callback: () => unknown): void;
     on(event: "shutdown", callback: (reason?: string) => unknown): void;
+    on(event: "worldCharacterTurn", callback: (request: PlatformWorldCharacterTurn) => unknown): void;
+    on(event: "worldCharacterCommand", callback: (request: PlatformWorldCharacterCommand) => unknown): void;
+    on(event: "worldCharacterRead", callback: (request: PlatformWorldCharacterRead) => unknown): void;
     /**
      * Deck storage. Strings in and strings out, like the rest of this handle, so a
      * runtime other than the Node shim can implement it without knowing what storage is.
@@ -34,5 +47,46 @@ 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>;
+    worldCharacterSend?(grantId: string): Promise<string>;
+    worldCharacterCommand?(grantId: string): Promise<string>;
+    worldCharacterRead?(grantId: string): Promise<string>;
+    worldCharacterReject?(grantId: string, code?: string): void;
     readonly config: PlatformSessionConfig;
 }
+export interface PlatformWorldCharacterCommand {
+    grantId: string;
+    requestId: string;
+    operationId: string;
+    speaker: PlayerIdentity & {
+        playerId: string;
+    };
+    command: unknown;
+}
+export interface PlatformWorldCharacterRead {
+    grantId: string;
+    requestId: string;
+    speaker: PlayerIdentity & {
+        playerId: string;
+    };
+    query: unknown;
+}
+export interface PlatformWorldCharacterTurn {
+    grantId: string;
+    requestId: string;
+    operationId: string;
+    speaker: PlayerIdentity & {
+        playerId: string;
+    };
+    characterId: string;
+    input: string;
+    audience: {
+        disclosure: "participants" | "world";
+        players: Array<PlayerIdentity & {
+            playerId: string;
+        }>;
+        characterIds: string[];
+    };
+}

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,86 @@ 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>;
+    readonly characters: MultiplayerServerWorldCharacters;
+}
+export interface MultiplayerServerWorldCharacters {
+    publicInspect<T = unknown>(): Promise<T>;
+    publicRelay(input: {
+        operationId: string;
+        sourceId: string;
+        transmittingCharacterId: string;
+        recipientCharacterIds: string[];
+    }): Promise<unknown>;
+}
+export interface MultiplayerWorldCharacterCommandRequest {
+    readonly requestId: string;
+    readonly operationId: string;
+    readonly speaker: MultiplayerServerPlayer;
+    readonly command: Readonly<Record<string, unknown>>;
+    apply(): Promise<unknown>;
+    reject(code?: string): void;
+}
+export interface MultiplayerWorldCharacterReadRequest {
+    readonly requestId: string;
+    readonly speaker: MultiplayerServerPlayer;
+    readonly query: Readonly<Record<string, unknown>>;
+    read<T = unknown>(): Promise<T>;
+    reject(code?: string): void;
+}
+export interface MultiplayerWorldCharacterAdmission {
+    operationId: string;
+    status: "queued" | "completed" | "interrupted";
+    replayed: boolean;
+}
+export interface MultiplayerWorldCharacterTurn {
+    readonly requestId: string;
+    readonly operationId: string;
+    readonly speaker: MultiplayerServerPlayer;
+    readonly characterId: string;
+    readonly input: string;
+    readonly audience: {
+        readonly disclosure: "participants" | "world";
+        readonly players: readonly MultiplayerServerPlayer[];
+        readonly characterIds: readonly string[];
+    };
+    /** Durably admits the exact host-authorized request. No arguments can broaden it. */
+    send(): Promise<MultiplayerWorldCharacterAdmission>;
+    /** Explicitly rejects the request before admission. */
+    reject(code?: string): void;
+}
 type CallbackResult = unknown;
 export interface MultiplayerServerCallbacks {
     onStart?: (session: MultiplayerServerSession) => CallbackResult;
@@ -31,6 +106,9 @@ export interface MultiplayerServerCallbacks {
     onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
     /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
     onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
+    onWorldCharacterTurn?: (session: MultiplayerServerSession, turn: MultiplayerWorldCharacterTurn) => CallbackResult;
+    onWorldCharacterCommand?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterCommandRequest) => CallbackResult;
+    onWorldCharacterRead?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterReadRequest) => CallbackResult;
     onTick?: (session: MultiplayerServerSession) => CallbackResult;
     onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
     /**