castle-web-sdk 0.4.36 → 0.4.38

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,6 +1,7 @@
-import type { MultiplayerSoloReason } from "./commands";
+import type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
-import { type MultiplayerPlayer } from "./multiplayerProtocol";
+import type { Json } from "./types";
+import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
 import { type MultiplayerVoice } from "./multiplayerVoice";
 export type MultiplayerJoinOptions = {
     mode: "named";
@@ -10,6 +11,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";
@@ -28,6 +40,63 @@ export interface MultiplayerRoster {
     players: MultiplayerPlayer[];
     you: MultiplayerPlayer | null;
 }
+export interface MultiplayerCharacterAudience {
+    disclosure?: MultiplayerCharacterDisclosure;
+    playerIds?: string[];
+    characterIds?: string[];
+}
+export interface MultiplayerCharacterTurnRequest {
+    requestId: string;
+    operationId: string;
+    characterId: string;
+    input: string;
+    audience?: MultiplayerCharacterAudience;
+}
+export interface MultiplayerCharacterTurnAdmission {
+    operationId: string;
+    status: "queued" | "completed" | "interrupted";
+    replayed: boolean;
+}
+export interface MultiplayerCharacterTurnStatusResult {
+    operationId: string;
+    status: MultiplayerCharacterTurnStatus;
+    jobStatus: MultiplayerCharacterTurnStatus;
+    turnStatus: "admitted" | "reply_committed" | "completed" | "interrupted";
+    response?: string;
+    progress?: {
+        response: string;
+    };
+    replayed: boolean;
+}
+export type MultiplayerWorldCharacterCommand = {
+    type: "perform_action";
+    characterId: string;
+    actionId: string;
+    parameters?: Json;
+    consentQuote?: string;
+} | {
+    type: "record_event";
+    eventTypeId: string;
+    data?: Json;
+};
+export type MultiplayerWorldCharacterQuery = {
+    type: "inspect";
+} | {
+    type: "status";
+    operationId: string;
+} | {
+    type: "history";
+    characterId?: string;
+    limit?: number;
+    cursor?: string;
+};
+export interface MultiplayerWorldCharacterCommandResult {
+    operationId: string;
+    status: "applied" | "ineligible";
+    replayed: boolean;
+    result: unknown;
+    worldRevision: string;
+}
 export interface MultiplayerConnection {
     readonly state: MultiplayerConnectionState;
     readonly playerId: string;
@@ -40,6 +109,19 @@ export interface MultiplayerConnection {
     readonly soloReason: MultiplayerSoloReason | null;
     /** Sends byte payloads as binary frames and all other payloads as JSON. */
     send(data: unknown): void;
+    /** Requests one billed character turn through this authenticated world socket. */
+    requestCharacterTurn(request: MultiplayerCharacterTurnRequest): Promise<MultiplayerCharacterTurnAdmission>;
+    /** Recovers the durable status of a prior operation after reconnecting. */
+    getCharacterTurnStatus(operationId: string): Promise<MultiplayerCharacterTurnStatusResult>;
+    requestCharacterCommand(request: {
+        requestId: string;
+        operationId: string;
+        command: MultiplayerWorldCharacterCommand;
+    }): Promise<MultiplayerWorldCharacterCommandResult>;
+    readCharacters<T = unknown>(request: {
+        requestId: string;
+        query: MultiplayerWorldCharacterQuery;
+    }): Promise<T>;
     /** Receives binary payloads as Uint8Array values and JSON payloads otherwise. */
     onMessage(callback: (data: unknown) => void): () => void;
     onRoster(callback: (roster: MultiplayerRoster) => void): () => void;
@@ -50,5 +132,6 @@ export interface MultiplayerConnection {
 }
 export interface CastleMultiplayerApi {
     join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
+    joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;
 }
 export declare const Multiplayer: CastleMultiplayerApi;