@antha/multiplayer-core 0.0.1

package/dist/multiplayer-api/multiplayer-controller.d.ts

@@ -0,0 +1,417 @@
+import { type JsonCompatibleValue, type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type FindPortOptions } from '@rest-vir/api';
+import { type AnyDuration } from 'date-vir';
+import { ListenTarget } from 'typed-event-target';
+import { type ClientId, type RoomId } from '../multiplayer-id.js';
+import { type RoomInput } from '../webrtc/webrtc-multiplayer-controller.js';
+import { RoomRejectionError } from './errors.js';
+import { type MultiplayerApiClient } from './multiplayer-client.js';
+/**
+ * Connection state for {@link MultiplayerRoomController}.
+ *
+ * @category Internal
+ */
+export declare enum MultiplayerConnectionState {
+    Connecting = "connecting",
+    Connected = "connected",
+    /** The connection has not been started or has been gracefully terminated. */
+    Disconnected = "disconnected"
+}
+/**
+ * API and room connection state for {@link MultiplayerRoomController}.
+ *
+ * @category Internal
+ */
+export type ApiAndRoomConnectionState = {
+    api: MultiplayerConnectionState | Error;
+    room: MultiplayerConnectionState | Error;
+};
+/**
+ * Empty or totally disconnected state for {@link ApiAndRoomConnectionState}.
+ *
+ * @category Internal
+ */
+export declare const emptyApiAndRoomConnectionState: Readonly<ApiAndRoomConnectionState>;
+/**
+ * The generic room transport surface exposed by {@link MultiplayerRoomController}. This will be
+ * implemented differently by each multiplayer state sync paradigm. Meaning, a different
+ * implementation for p2p-lock-step syncing, a different implementation for authoritative server
+ * state syncing, etc.
+ *
+ * @category Internal
+ */
+export type MultiplayerRoomConnection<Message extends JsonCompatibleValue> = {
+    /** The id assigned to the local room client. */
+    clientId: ClientId;
+    /** Whether the local client is currently the room host. */
+    isHost(): boolean;
+    /** Whether the local client has an active room connection. */
+    isConnected(): boolean;
+    /** Get the ids of clients with active peer connections. */
+    getConnectedClientIds(): ClientId[];
+    /** Get every known client id in the room, including the host when known. */
+    getAllClientIds(): ClientId[];
+    /** Send a message through the room connection. */
+    sendMessage(message: Readonly<Message>): void;
+    /** Send a message to one specific room client. */
+    sendToOnlyOneClient(clientId: ClientId, message: Readonly<Message>): void;
+    /** Terminate the room connection and release transport resources. */
+    destroy(): void;
+};
+/**
+ * Constructor parameters for {@link MultiplayerRoomController}.
+ *
+ * @category Internal
+ */
+export type MultiplayerRoomControllerParams<Message extends JsonCompatibleValue> = {
+    /**
+     * A unique string id that represents your game so that your lobby server can serve multiple
+     * games at once. Your lobby server will need to know this game id ahead of time and match it to
+     * your frontend's origin.
+     *
+     * If this is left empty, make sure your lobby server (if you have any) handles that, and only
+     * handles one game at a time.
+     */
+    gameId: string;
+} & PartialWithUndefined<{
+    /**
+     * This is fired when a WebRTC peer attempts to connect to the host client (this will only be
+     * fired if your client is the host). Return `true` to accept the connection. Return `false` to
+     * reject it.
+     *
+     * @default accept all connections
+     */
+    acceptConnection?: ((connectingClientId: ClientId, controller: MultiplayerRoomController<Message>) => MaybePromise<boolean>) | undefined;
+}>;
+/**
+ * Multiplayer mode parameters for {@link MultiplayerRoomController}.
+ *
+ * @category Internal
+ */
+export type MultiplayerInitParams = {
+    /**
+     * The origin of the server running the multiplayer API.
+     *
+     * @example 'http://localhost:3000'
+     */
+    backendOrigin: string;
+} & PartialWithUndefined<{
+    /**
+     * Set to `undefined` or `false` to disable port scanning. Set to `true` to enable port
+     * scanning. Set to an options object to configure port scanning.
+     *
+     * It is useful to enable this so that clients can find the port that your multiplayer server is
+     * running on in case it must change. Note that port scanning will not be active if your
+     * `backendOrigin` does not contain a port.
+     *
+     * @default undefined
+     */
+    portScanOptions: Omit<FindPortOptions, 'startOrigin'> | boolean;
+    /**
+     * How long to wait before fetching the list of rooms again.
+     *
+     * @default {seconds: 10}
+     */
+    roomUpdateInterval: AnyDuration;
+    /**
+     * Optional stun server URLs to help with routing WebRTC connections. This is entirely optional,
+     * but might help with clients attempting to establish connections to each other.
+     */
+    stunServerUrls: ReadonlyArray<string>;
+    /** If set, this will override the internal multiplayer API. */
+    multiplayerApiClient: Readonly<MultiplayerApiClient>;
+}>;
+declare const ControllerMessageEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: any;
+}) => import("typed-event-target").TypedCustomEvent<any, "controller-message">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<any, "controller-message">, "type">;
+/**
+ * This is fired when a room message is received.
+ *
+ * @category Events
+ */
+export declare class ControllerMessageEvent<Message extends JsonCompatibleValue> extends ControllerMessageEvent_base {
+    readonly sourceClientId: ClientId;
+    detail: Message;
+    constructor(sourceClientId: ClientId, detail: Message);
+}
+declare const ControllerRoomListEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: Readonly<Partial<Record<RoomId, {
+        roomId: RoomId;
+        roomName: string;
+        clientCount: number;
+        hasRoomPassword: boolean;
+    }>>>;
+}) => import("typed-event-target").TypedCustomEvent<Readonly<Partial<Record<RoomId, {
+    roomId: RoomId;
+    roomName: string;
+    clientCount: number;
+    hasRoomPassword: boolean;
+}>>>, "controller-room-list">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Readonly<Partial<Record<RoomId, {
+    roomId: RoomId;
+    roomName: string;
+    clientCount: number;
+    hasRoomPassword: boolean;
+}>>>, "controller-room-list">, "type">;
+/**
+ * This is called whenever the room list updates, even if there were no changes to the room list.
+ * Note that room list updates are paused while the controller is connected to an actual room.
+ *
+ * @category Events
+ */
+export declare class ControllerRoomListEvent extends ControllerRoomListEvent_base {
+}
+declare const ControllerClientEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: Readonly<((Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "newHost">> & Partial<Record<"newMember" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "newMember">> & Partial<Record<"newHost" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "lostHost">> & Partial<Record<"newHost" | "newMember" | "lostMember", never>>) | (Required<Pick<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "lostMember">> & Partial<Record<"newHost" | "newMember" | "lostHost", never>>)) & Omit<{
+        newHost: ClientId;
+        newMember: ClientId;
+        lostHost: ClientId;
+        lostMember: ClientId;
+    }, "newHost" | "newMember" | "lostHost" | "lostMember">>;
+}) => import("typed-event-target").TypedCustomEvent<Readonly<((Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost">> & Partial<Record<"newMember" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newMember">> & Partial<Record<"newHost" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostHost">> & Partial<Record<"newHost" | "newMember" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostMember">> & Partial<Record<"newHost" | "newMember" | "lostHost", never>>)) & Omit<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost" | "newMember" | "lostHost" | "lostMember">>, "controller-client">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Readonly<((Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost">> & Partial<Record<"newMember" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newMember">> & Partial<Record<"newHost" | "lostHost" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostHost">> & Partial<Record<"newHost" | "newMember" | "lostMember", never>>) | (Required<Pick<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "lostMember">> & Partial<Record<"newHost" | "newMember" | "lostHost", never>>)) & Omit<{
+    newHost: ClientId;
+    newMember: ClientId;
+    lostHost: ClientId;
+    lostMember: ClientId;
+}, "newHost" | "newMember" | "lostHost" | "lostMember">>, "controller-client">, "type">;
+/**
+ * This is fired in the following situations:
+ *
+ * - A new host for the room was selected
+ * - The room host was lost
+ * - A new room client was added (only fired on the host client)
+ * - A room client was lost (only fired on the host client)
+ *
+ * @category Events
+ */
+export declare class ControllerClientEvent extends ControllerClientEvent_base {
+}
+declare const ControllerConnectionEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: ApiAndRoomConnectionState;
+}) => import("typed-event-target").TypedCustomEvent<ApiAndRoomConnectionState, "controller-connection">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<ApiAndRoomConnectionState, "controller-connection">, "type">;
+/**
+ * Fires when the controller's connection state is updated.
+ *
+ * @category Events
+ */
+export declare class ControllerConnectionEvent extends ControllerConnectionEvent_base {
+}
+/**
+ * All events emitted by this controller.
+ *
+ * @category Internal
+ */
+export type AllMultiplayerRoomControllerEvents<Message extends JsonCompatibleValue> = ControllerMessageEvent<Message> | ControllerRoomListEvent | ControllerClientEvent | ControllerConnectionEvent;
+/**
+ * A generic multiplayer room controller. It manages API connectivity, room discovery, WebRTC
+ * signaling, and generic room messages. It does not impose a game-state synchronization strategy.
+ *
+ * @category Main
+ */
+export declare class MultiplayerRoomController<Message extends JsonCompatibleValue = any> extends ListenTarget<AllMultiplayerRoomControllerEvents<Message>> {
+    protected readonly params: MultiplayerRoomControllerParams<Message>;
+    /** All events emitted by this controller. */
+    static readonly events: {
+        ControllerMessageEvent: typeof ControllerMessageEvent;
+        ControllerRoomListEvent: typeof ControllerRoomListEvent;
+        ControllerClientEvent: typeof ControllerClientEvent;
+        ControllerConnectionEvent: typeof ControllerConnectionEvent;
+    };
+    /** All events emitted by this controller. */
+    readonly events: {
+        ControllerMessageEvent: typeof ControllerMessageEvent;
+        ControllerRoomListEvent: typeof ControllerRoomListEvent;
+        ControllerClientEvent: typeof ControllerClientEvent;
+        ControllerConnectionEvent: typeof ControllerConnectionEvent;
+    };
+    static readonly knownErrors: {
+        RoomRejectionError: typeof RoomRejectionError;
+    };
+    readonly knownErrors: {
+        RoomRejectionError: typeof RoomRejectionError;
+    };
+    /**
+     * Set to `false` to disable room updates, even when still not connected to a room in
+     * multiplayer mode.
+     */
+    enableRoomUpdates: boolean;
+    /** Currently joined room id. If a room has not been joined yet, this will be empty. */
+    readonly roomId: RoomId | undefined;
+    /** The current connection state of the controller's connection to a backend API. */
+    readonly apiConnectionState: ApiAndRoomConnectionState['api'];
+    /** The current connection state of the controller's connection to a multiplayer room. */
+    readonly roomConnectionState: ApiAndRoomConnectionState['room'];
+    /** Current room connection. */
+    currentConnection: MultiplayerRoomConnection<Message> | undefined;
+    /**
+     * Rooms that have rejected the current player, so the player doesn't keep trying to connect to
+     * them.
+     */
+    protected rejectedRoomIds: Set<RoomId>;
+    /**
+     * The current multiplayer API client. This will be `undefined` before multiplayer starts or if
+     * playing in single player.
+     */
+    multiplayerApiClient: Readonly<MultiplayerApiClient> | undefined;
+    /**
+     * Used to keep track of the room update interval. This will be set when the controller is
+     * constructed in multiplayer mode or when a room is left. This will be cleared when a room is
+     * joined or if the controller is destroyed.
+     */
+    protected roomUpdateIntervalId: ReturnType<typeof globalThis.setInterval> | undefined;
+    /** This is populated when `.initMultiplayer` is called. */
+    protected multiplayerParams: Readonly<MultiplayerInitParams> | undefined;
+    /**
+     * Get the current client's WebRTC client id. This will return `undefined` if there is no
+     * current connection.
+     */
+    getClientId(): ClientId | undefined;
+    /**
+     * Get all connected client ids.
+     *
+     * - For host clients, this indicates how many member clients are connected to the host client,
+     *   _not_ including the host itself.
+     * - For non-host clients, this only lists the local connection used to reach the host.
+     */
+    getConnectedClientIds(): ClientId[];
+    /**
+     * Get all room client ids.
+     *
+     * - For host clients, this indicates how many clients are connected to the room, including the
+     *   host client itself.
+     * - For non-host clients, this includes the member client and the host client once connected.
+     */
+    getAllClientIds(): ClientId[];
+    constructor(params: MultiplayerRoomControllerParams<Message>);
+    /**
+     * Start multiplayer mode. This initializes
+     * {@link MultiplayerRoomController.multiplayerApiClient} and
+     * {@link MultiplayerRoomController.roomUpdateIntervalId}.
+     */
+    initMultiplayer(params: Readonly<MultiplayerInitParams>): Promise<void>;
+    /** Send a generic message to the current room. */
+    sendMessage(message: Readonly<Message>): void;
+    /** Detects if this controller is the room host or not. */
+    isHost(): boolean;
+    /** Detects if this controller is connected to a room or not. */
+    isConnected(): boolean;
+    /** Cleanup everything. */
+    destroy(): void;
+    /**
+     * Join or create a room.
+     *
+     * @throws `Error` if this controller is already connected to a room.
+     */
+    joinOrCreateRoom(room: Readonly<RoomInput>): Promise<void>;
+    /** Leave the current room or single player connection. */
+    leaveRoom(): void;
+    /** Set the current connection state and fire listeners. */
+    protected updateConnectionState(state: Partial<ApiAndRoomConnectionState>): void;
+    /** Starts polling the multiplayer server for room updates and fires listeners. */
+    protected startRoomInterval(): void;
+}
+export {};