@antha/multiplayer-core 0.0.1

package/dist/multiplayer-api/multiplayer-controller.js

@@ -0,0 +1,331 @@
+import { waitUntil } from '@augment-vir/assert';
+import { ensureError, makeWritable, } from '@augment-vir/common';
+import { convertDuration } from 'date-vir';
+import { defineTypedCustomEvent, ListenTarget } from 'typed-event-target';
+import { WebrtcMultiplayerConnectionUpdateEvent, WebrtcMultiplayerController, WebrtcMultiplayerMessageEvent, } from '../webrtc/webrtc-multiplayer-controller.js';
+import { RoomRejectionError } from './errors.js';
+import { multiplayerHealthEndpoint, multiplayerRoomsEndpoint, } from './multiplayer-api.js';
+import { createMultiplayerApiClient } from './multiplayer-client.js';
+/**
+ * Connection state for {@link MultiplayerRoomController}.
+ *
+ * @category Internal
+ */
+export var MultiplayerConnectionState;
+(function (MultiplayerConnectionState) {
+    MultiplayerConnectionState["Connecting"] = "connecting";
+    MultiplayerConnectionState["Connected"] = "connected";
+    /** The connection has not been started or has been gracefully terminated. */
+    MultiplayerConnectionState["Disconnected"] = "disconnected";
+})(MultiplayerConnectionState || (MultiplayerConnectionState = {}));
+/**
+ * Empty or totally disconnected state for {@link ApiAndRoomConnectionState}.
+ *
+ * @category Internal
+ */
+export const emptyApiAndRoomConnectionState = {
+    room: MultiplayerConnectionState.Disconnected,
+    api: MultiplayerConnectionState.Disconnected,
+};
+/**
+ * This is fired when a room message is received.
+ *
+ * @category Events
+ */
+export class ControllerMessageEvent extends defineTypedCustomEvent()('controller-message') {
+    sourceClientId;
+    constructor(sourceClientId, detail) {
+        super({
+            detail,
+        });
+        this.sourceClientId = sourceClientId;
+    }
+}
+/**
+ * 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 class ControllerRoomListEvent extends defineTypedCustomEvent()('controller-room-list') {
+}
+/**
+ * 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 class ControllerClientEvent extends defineTypedCustomEvent()('controller-client') {
+}
+/**
+ * Fires when the controller's connection state is updated.
+ *
+ * @category Events
+ */
+export class ControllerConnectionEvent extends defineTypedCustomEvent()('controller-connection') {
+}
+/**
+ * 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 class MultiplayerRoomController extends ListenTarget {
+    params;
+    /** All events emitted by this controller. */
+    static events = {
+        ControllerMessageEvent,
+        ControllerRoomListEvent,
+        ControllerClientEvent,
+        ControllerConnectionEvent,
+    };
+    /** All events emitted by this controller. */
+    events = MultiplayerRoomController.events;
+    static knownErrors = {
+        RoomRejectionError,
+    };
+    knownErrors = MultiplayerRoomController.knownErrors;
+    /**
+     * Set to `false` to disable room updates, even when still not connected to a room in
+     * multiplayer mode.
+     */
+    enableRoomUpdates = true;
+    /** Currently joined room id. If a room has not been joined yet, this will be empty. */
+    roomId;
+    /** The current connection state of the controller's connection to a backend API. */
+    apiConnectionState = MultiplayerConnectionState.Disconnected;
+    /** The current connection state of the controller's connection to a multiplayer room. */
+    roomConnectionState = MultiplayerConnectionState.Disconnected;
+    /** Current room connection. */
+    currentConnection;
+    /**
+     * Rooms that have rejected the current player, so the player doesn't keep trying to connect to
+     * them.
+     */
+    rejectedRoomIds = new Set();
+    /**
+     * The current multiplayer API client. This will be `undefined` before multiplayer starts or if
+     * playing in single player.
+     */
+    multiplayerApiClient;
+    /**
+     * 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.
+     */
+    roomUpdateIntervalId;
+    /** This is populated when `.initMultiplayer` is called. */
+    multiplayerParams;
+    /**
+     * Get the current client's WebRTC client id. This will return `undefined` if there is no
+     * current connection.
+     */
+    getClientId() {
+        return this.currentConnection?.clientId;
+    }
+    /**
+     * 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() {
+        return this.currentConnection?.getConnectedClientIds() || [];
+    }
+    /**
+     * 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() {
+        return this.currentConnection?.getAllClientIds() || [];
+    }
+    constructor(params) {
+        super();
+        this.params = params;
+    }
+    /**
+     * Start multiplayer mode. This initializes
+     * {@link MultiplayerRoomController.multiplayerApiClient} and
+     * {@link MultiplayerRoomController.roomUpdateIntervalId}.
+     */
+    async initMultiplayer(params) {
+        if (this.currentConnection) {
+            throw new Error('Cannot start multiplayer mode again when a multiplayer connection already present.');
+        }
+        this.multiplayerParams = params;
+        this.updateConnectionState({
+            api: MultiplayerConnectionState.Connecting,
+        });
+        try {
+            const api = params.multiplayerApiClient ||
+                (await createMultiplayerApiClient({
+                    portScanOptions: params.portScanOptions,
+                    backendOrigin: params.backendOrigin,
+                }));
+            const output = await api.fetch(multiplayerHealthEndpoint).GET();
+            if (!output.Ok) {
+                throw new Error(`Failed to find multiplayer API at ${api.baseUrl}.`);
+            }
+            this.multiplayerApiClient = api;
+            this.updateConnectionState({
+                api: MultiplayerConnectionState.Connected,
+            });
+        }
+        catch (error) {
+            this.updateConnectionState({
+                api: ensureError(error),
+            });
+            throw error;
+        }
+        this.startRoomInterval();
+    }
+    /** Send a generic message to the current room. */
+    sendMessage(message) {
+        if (!this.currentConnection || !this.currentConnection.isConnected()) {
+            throw new Error('Cannot send message: not connected to a room.');
+        }
+        this.currentConnection.sendMessage(message);
+    }
+    /** Detects if this controller is the room host or not. */
+    isHost() {
+        return this.currentConnection?.isHost() || false;
+    }
+    /** Detects if this controller is connected to a room or not. */
+    isConnected() {
+        return this.currentConnection?.isConnected() || false;
+    }
+    /** Cleanup everything. */
+    destroy() {
+        super.destroy();
+        this.updateConnectionState({
+            room: MultiplayerConnectionState.Disconnected,
+            api: MultiplayerConnectionState.Disconnected,
+        });
+        this.currentConnection?.destroy();
+        globalThis.clearInterval(this.roomUpdateIntervalId);
+    }
+    /**
+     * Join or create a room.
+     *
+     * @throws `Error` if this controller is already connected to a room.
+     */
+    async joinOrCreateRoom(room) {
+        if (this.currentConnection) {
+            throw new Error('Cannot join room: connection already established.');
+        }
+        else if (!this.multiplayerApiClient || !this.multiplayerParams) {
+            throw new Error('Cannot join room. Please start this controller in multiplayer mode to join rooms.');
+        }
+        else if (this.rejectedRoomIds.has(room.roomId)) {
+            throw new RoomRejectionError(room);
+        }
+        this.updateConnectionState({
+            room: MultiplayerConnectionState.Connecting,
+        });
+        const currentConnection = new WebrtcMultiplayerController(this.params.gameId, this.multiplayerApiClient, this.multiplayerParams.stunServerUrls || [], room, undefined, this.params.acceptConnection
+            ? (data) => {
+                return this.params.acceptConnection?.(data.connectingClientId, this) ?? true;
+            }
+            : undefined);
+        this.currentConnection = currentConnection;
+        currentConnection.listen((WebrtcMultiplayerMessageEvent), (event) => {
+            this.dispatch(new ControllerMessageEvent(event.sourceClientId, event.detail));
+        });
+        currentConnection.listen(WebrtcMultiplayerConnectionUpdateEvent, (event) => {
+            this.dispatch(new ControllerClientEvent({
+                detail: event.detail,
+            }));
+        });
+        await currentConnection.initConnection();
+        const connectionResult = await waitUntil.isDefined(() => {
+            const connected = currentConnection.isConnected();
+            const destroyed = currentConnection.isDestroyed;
+            return !connected && !destroyed
+                ? undefined
+                : {
+                    connected,
+                    destroyed,
+                };
+        });
+        if (connectionResult.connected) {
+            makeWritable(this).roomId = room.roomId;
+            globalThis.clearInterval(this.roomUpdateIntervalId);
+            this.updateConnectionState({
+                room: MultiplayerConnectionState.Connected,
+            });
+        }
+        else {
+            currentConnection.destroy();
+            this.rejectedRoomIds.add(room.roomId);
+            this.currentConnection = undefined;
+            const error = new RoomRejectionError(room);
+            this.updateConnectionState({
+                room: error,
+            });
+            throw error;
+        }
+    }
+    /** Leave the current room or single player connection. */
+    leaveRoom() {
+        if (!this.currentConnection) {
+            return;
+        }
+        makeWritable(this).roomId = undefined;
+        this.currentConnection.destroy();
+        this.currentConnection = undefined;
+        this.startRoomInterval();
+        this.updateConnectionState({
+            room: MultiplayerConnectionState.Disconnected,
+        });
+    }
+    /** Set the current connection state and fire listeners. */
+    updateConnectionState(state) {
+        if (state.api) {
+            makeWritable(this).apiConnectionState = state.api;
+        }
+        if (state.room) {
+            makeWritable(this).roomConnectionState = state.room;
+        }
+        this.dispatch(new ControllerConnectionEvent({
+            detail: {
+                room: this.roomConnectionState,
+                api: this.apiConnectionState,
+            },
+        }));
+    }
+    /** Starts polling the multiplayer server for room updates and fires listeners. */
+    startRoomInterval() {
+        if (this.multiplayerApiClient) {
+            const roomUpdateMs = this.multiplayerParams?.roomUpdateInterval
+                ? convertDuration(this.multiplayerParams.roomUpdateInterval, {
+                    milliseconds: true,
+                }).milliseconds
+                : 10_000;
+            this.roomUpdateIntervalId = globalThis.setInterval(async () => {
+                if (this.currentConnection ||
+                    !this.multiplayerApiClient ||
+                    !this.enableRoomUpdates) {
+                    return;
+                }
+                const output = await this.multiplayerApiClient.fetch(multiplayerRoomsEndpoint).GET({
+                    searchParams: {
+                        gameId: [this.params.gameId],
+                    },
+                });
+                if (output.Ok) {
+                    this.dispatch(new ControllerRoomListEvent({
+                        detail: output.Ok.responseData,
+                    }));
+                }
+            }, roomUpdateMs);
+        }
+    }
+}

package/dist/multiplayer-api/multiplayer-socket-messages.d.ts

@@ -0,0 +1,141 @@
+import { MultiplayerWebSocketMessageType } from '../webrtc/web-rtc-communication.js';
+/**
+ * A shape definition for {@link ClientIdentification} when joining or creating a room.
+ *
+ * @category Internal
+ */
+export declare const clientIdShape: import("object-shape-tester").Shape<{
+    /** This id is used to keep track of each client on the multiplayer server. */
+    clientId: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<import("../multiplayer-id.js").ClientId>>;
+    /**
+     * The id of the room that the user is communicating with. Set this either to to an existing
+     * room to join that room, or a new id to create a new room.
+     */
+    roomId: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<import("../multiplayer-id.js").RoomId>>;
+    /** The name of the room to create or join. */
+    roomName: string;
+}>;
+/**
+ * Data included in each multiplayer server message that is used to identify the message client and
+ * the room they wish to join or host.
+ *
+ * @category Internal
+ */
+export type ClientIdentification = typeof clientIdShape.runtimeType;
+/**
+ * Base shape definition for every message type.
+ *
+ * @category Internal
+ */
+export declare const baseMessageShape: import("object-shape-tester").Shape<{
+    /**
+     * The id of the original message. If a message is ever a response to another message, the
+     * message id will remain the same throughout the chain.
+     */
+    messageId: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<import("../multiplayer-id.js").SocketMessageId>>;
+}>;
+/**
+ * ==========================================================
+ *
+ * # Message Shape Definitions
+ *
+ * ==========================================================
+ */
+/**
+ * Shape definition for "answer" messages.
+ *
+ * @category Internal
+ */
+export declare const answerMessageShape: import("object-shape-tester").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<{
+    clientId: import("../multiplayer-id.js").ClientId;
+    roomId: import("../multiplayer-id.js").RoomId;
+    roomName: string;
+} & {
+    messageId: import("../multiplayer-id.js").SocketMessageId;
+} & {
+    type: MultiplayerWebSocketMessageType.Answer;
+    data: {
+        type: MultiplayerWebSocketMessageType.Answer;
+        sdp: string;
+    } | {
+        rejected: true;
+    };
+}>>>;
+/**
+ * Shape definition for "host ping" messages.
+ *
+ * @category Internal
+ */
+export declare const hostPingMessageShape: import("object-shape-tester").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<{
+    clientId: import("../multiplayer-id.js").ClientId;
+    roomId: import("../multiplayer-id.js").RoomId;
+    roomName: string;
+} & {
+    messageId: import("../multiplayer-id.js").SocketMessageId;
+} & {
+    type: MultiplayerWebSocketMessageType.HostPing;
+    clientSecret: string;
+    clientCount: number;
+    roomPassword: string;
+}>>>;
+/**
+ * Shape definition for "offer" messages forwarded from the multiplayer server to the host.
+ *
+ * @category Internal
+ */
+export declare const forwardedOfferMessageShape: import("object-shape-tester").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<{
+    clientId: import("../multiplayer-id.js").ClientId;
+    roomId: import("../multiplayer-id.js").RoomId;
+    roomName: string;
+} & {
+    messageId: import("../multiplayer-id.js").SocketMessageId;
+} & {
+    type: MultiplayerWebSocketMessageType.Offer;
+    data: {
+        type: MultiplayerWebSocketMessageType.Offer;
+        sdp: string;
+    };
+}>>>;
+/**
+ * Shape definition for "offer" messages.
+ *
+ * @category Internal
+ */
+export declare const offerMessageShape: import("object-shape-tester").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<{
+    messageId: import("../multiplayer-id.js").SocketMessageId;
+} & {
+    clientId: import("../multiplayer-id.js").ClientId;
+    roomId: import("../multiplayer-id.js").RoomId;
+    roomName: string;
+} & {
+    type: MultiplayerWebSocketMessageType.Offer;
+    data: {
+        type: MultiplayerWebSocketMessageType.Offer;
+        sdp: string;
+    };
+} & {
+    clientSecret: string;
+    roomPassword: string;
+}>>>;
+/**
+ * Shape definition for "offer result" messages.
+ *
+ * @category Internal
+ */
+export declare const offerResultShape: import("object-shape-tester").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<{
+    messageId: import("../multiplayer-id.js").SocketMessageId;
+} & {
+    type: MultiplayerWebSocketMessageType.OfferResult;
+    hostClientId: import("../multiplayer-id.js").ClientId;
+}>>>;
+/**
+ * Shape definition for error messages.
+ *
+ * @category Internal
+ */
+export declare const errorMessageShape: import("object-shape-tester").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<{
+    messageId: import("../multiplayer-id.js").SocketMessageId;
+} & {
+    type: MultiplayerWebSocketMessageType.Error;
+    errorMessage: string;
+}>>>;

package/dist/multiplayer-api/multiplayer-socket-messages.js

@@ -0,0 +1,114 @@
+import { defineShape, exactShape, intersectShape, unionShape } from 'object-shape-tester';
+import { multiplayerIdShapes } from '../multiplayer-id.js';
+import { MultiplayerWebSocketMessageType, webrtcAnswerShape, webrtcOfferShape, } from '../webrtc/web-rtc-communication.js';
+/**
+ * A shape definition for {@link ClientIdentification} when joining or creating a room.
+ *
+ * @category Internal
+ */
+export const clientIdShape = defineShape({
+    /** This id is used to keep track of each client on the multiplayer server. */
+    clientId: multiplayerIdShapes.client(),
+    /**
+     * The id of the room that the user is communicating with. Set this either to to an existing
+     * room to join that room, or a new id to create a new room.
+     */
+    roomId: multiplayerIdShapes.room(),
+    /** The name of the room to create or join. */
+    roomName: '',
+});
+/**
+ * Base shape definition for every message type.
+ *
+ * @category Internal
+ */
+export const baseMessageShape = defineShape({
+    /**
+     * The id of the original message. If a message is ever a response to another message, the
+     * message id will remain the same throughout the chain.
+     */
+    messageId: multiplayerIdShapes.socketMessage(),
+});
+/**
+ * ==========================================================
+ *
+ * # Message Shape Definitions
+ *
+ * ==========================================================
+ */
+/**
+ * Shape definition for "answer" messages.
+ *
+ * @category Internal
+ */
+export const answerMessageShape = defineShape(intersectShape(clientIdShape, baseMessageShape, {
+    type: exactShape(MultiplayerWebSocketMessageType.Answer),
+    /**
+     * This data object matches the `RTCSessionDescriptionInit` type from the TS lib. This data
+     * should be passed into `RTCPeerConnection.setRemoteDescription` to accept a WebRTC
+     * answer.
+     */
+    data: unionShape({
+        rejected: exactShape(true),
+    }, webrtcAnswerShape),
+}));
+/**
+ * Shape definition for "host ping" messages.
+ *
+ * @category Internal
+ */
+export const hostPingMessageShape = defineShape(intersectShape(clientIdShape, baseMessageShape, {
+    type: exactShape(MultiplayerWebSocketMessageType.HostPing),
+    /** This secret is used to verify that the sender is indeed the host of the current room. */
+    clientSecret: '',
+    clientCount: -1,
+    roomPassword: '',
+}));
+/**
+ * Shape definition for "offer" messages forwarded from the multiplayer server to the host.
+ *
+ * @category Internal
+ */
+export const forwardedOfferMessageShape = defineShape(intersectShape(clientIdShape, baseMessageShape, {
+    type: exactShape(MultiplayerWebSocketMessageType.Offer),
+    /**
+     * This data object matches the `RTCSessionDescriptionInit` type from the TS lib. This data
+     * should be passed into `RTCPeerConnection.setRemoteDescription` when creating an offer.
+     */
+    data: webrtcOfferShape,
+}));
+/**
+ * Shape definition for "offer" messages.
+ *
+ * @category Internal
+ */
+export const offerMessageShape = defineShape(intersectShape(forwardedOfferMessageShape, baseMessageShape, {
+    /**
+     * This secret is used to verify that a client is a host of a room. Do not share this with
+     * other clients.
+     */
+    clientSecret: '',
+    /**
+     * Set this when joining a room with a password or when creating a room to set a room
+     * password.
+     */
+    roomPassword: '',
+}));
+/**
+ * Shape definition for "offer result" messages.
+ *
+ * @category Internal
+ */
+export const offerResultShape = defineShape(intersectShape(baseMessageShape, {
+    type: exactShape(MultiplayerWebSocketMessageType.OfferResult),
+    hostClientId: multiplayerIdShapes.client(),
+}));
+/**
+ * Shape definition for error messages.
+ *
+ * @category Internal
+ */
+export const errorMessageShape = defineShape(intersectShape(baseMessageShape, {
+    type: exactShape(MultiplayerWebSocketMessageType.Error),
+    errorMessage: '',
+}));

package/dist/multiplayer-id.d.ts

@@ -0,0 +1,59 @@
+import { type Branded } from '@augment-vir/common';
+import { type TUnsafe } from '@sinclair/typebox';
+import { type Shape } from 'object-shape-tester';
+/**
+ * Unique id for a multiplayer room client.
+ *
+ * @category Internal
+ */
+export type ClientId = Branded<`${typeof idPrefixes.client}${string}`, 'multiplayer-client-id'>;
+/**
+ * Unique id for a multiplayer room.
+ *
+ * @category Internal
+ */
+export type RoomId = Branded<`${typeof idPrefixes.room}${string}`, 'multiplayer-room-id'>;
+/**
+ * Unique id for a multiplayer signaling socket message.
+ *
+ * @category Internal
+ */
+export type SocketMessageId = Branded<`${typeof idPrefixes.socketMessage}${string}`, 'multiplayer-socket-message-id'>;
+/**
+ * String prefixes used to distinguish multiplayer id types.
+ *
+ * @category Internal
+ */
+export declare const idPrefixes: {
+    /** Prefix for {@link RoomId}. */
+    readonly room: "r_";
+    /** Prefix for {@link ClientId}. */
+    readonly client: "c_";
+    /** Prefix for {@link SocketMessageId}. */
+    readonly socketMessage: "sm_";
+};
+/**
+ * Map of multiplayer id keys to their branded id types.
+ *
+ * @category Internal
+ */
+export type IdMap = {
+    /** Branded room id type. */
+    room: RoomId;
+    /** Branded client id type. */
+    client: ClientId;
+    /** Branded socket message id type. */
+    socketMessage: SocketMessageId;
+};
+/**
+ * Create branded multiplayer ids with the correct prefix for each id type.
+ *
+ * @category Internal
+ */
+export declare const createMultiplayerId: { [IdType in keyof typeof idPrefixes]: () => IdMap[IdType]; };
+/**
+ * Runtime shapes for validating branded multiplayer ids.
+ *
+ * @category Internal
+ */
+export declare const multiplayerIdShapes: { [IdType in keyof typeof idPrefixes]: () => Shape<TUnsafe<IdMap[IdType]>>; };

package/dist/multiplayer-id.js

@@ -0,0 +1,38 @@
+import { check } from '@augment-vir/assert';
+import { createCuid2, mapObjectValues } from '@augment-vir/common';
+import { createCustomShape } from 'object-shape-tester';
+/**
+ * String prefixes used to distinguish multiplayer id types.
+ *
+ * @category Internal
+ */
+export const idPrefixes = {
+    /** Prefix for {@link RoomId}. */
+    room: 'r_',
+    /** Prefix for {@link ClientId}. */
+    client: 'c_',
+    /** Prefix for {@link SocketMessageId}. */
+    socketMessage: 'sm_',
+};
+/**
+ * Create branded multiplayer ids with the correct prefix for each id type.
+ *
+ * @category Internal
+ */
+export const createMultiplayerId = mapObjectValues(idPrefixes, (idKey, prefix) => {
+    return () => `${prefix}${createCuid2()}`;
+});
+/**
+ * Runtime shapes for validating branded multiplayer ids.
+ *
+ * @category Internal
+ */
+export const multiplayerIdShapes = mapObjectValues(idPrefixes, (idKey) => {
+    return createCustomShape({
+        checkValue(value) {
+            return check.isString(value) && value.startsWith(idPrefixes[idKey]);
+        },
+        default: '',
+        name: `${idKey} multiplayer id shape`,
+    });
+});