@antha/multiplayer-core 0.0.8 → 0.1.1

package/README.md

@@ -1,3 +1,23 @@
 # @antha/multiplayer-core
 
-Core multiplayer room, API, and WebRTC utilities for Antha.
+This package provides the room, signaling, WebRTC, and identifier utilities behind the [Antha game engine](https://www.npmjs.com/package/@antha/engine)'s peer-to-peer multiplayer features. Use it directly to build a custom multiplayer strategy, or use one of the strategy packages for a ready-made approach.
+
+## Install
+
+```sh
+npm i @antha/multiplayer-core
+```
+
+## Usage
+
+<!-- example-link: src/readme-examples/creating-multiplayer-client.example.ts -->
+
+```TypeScript
+import {createMultiplayerApiClient, createMultiplayerId} from '@antha/multiplayer-core';
+
+const roomId = createMultiplayerId.room();
+const multiplayerApiClient = await createMultiplayerApiClient({
+    backendOrigin: 'http://localhost:9348',
+    portScanOptions: false,
+});
+```

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

@@ -75,6 +75,13 @@ export type MultiplayerRoomControllerParams<Message extends JsonCompatibleValue>
      */
     gameId: string;
 } & PartialWithUndefined<{
+    /** Reuse an existing local client id when establishing a multiplayer connection. */
+    clientId: ClientId;
+    /**
+     * Prepare a newly connected room before it replaces the current room. Throwing keeps the
+     * current room connected and discards the candidate connection.
+     */
+    prepareConnection: (connection: Readonly<MultiplayerRoomConnection<Message>>) => MaybePromise<void>;
     /**
      * 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
@@ -388,8 +395,8 @@ export declare class MultiplayerRoomController<Message extends JsonCompatibleVal
     getAllClientIds(): ClientId[];
     constructor(params: MultiplayerRoomControllerParams<Message>);
     /**
-     * Start multiplayer mode. This initializes
-     * {@link MultiplayerRoomController.multiplayerApiClient}.
+     * Initialize multiplayer API access. This does not open a room or start host pings; those begin
+     * when {@link MultiplayerRoomController.joinOrCreateRoom} establishes a room connection.
      */
     initMultiplayer(params: Readonly<MultiplayerInitParams>): Promise<void>;
     /**

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

@@ -145,8 +145,8 @@ export class MultiplayerRoomController extends ListenTarget {
         this.params = params;
     }
     /**
-     * Start multiplayer mode. This initializes
-     * {@link MultiplayerRoomController.multiplayerApiClient}.
+     * Initialize multiplayer API access. This does not open a room or start host pings; those begin
+     * when {@link MultiplayerRoomController.joinOrCreateRoom} establishes a room connection.
      */
     async initMultiplayer(params) {
         if (this.currentConnection) {
@@ -233,7 +233,7 @@ export class MultiplayerRoomController extends ListenTarget {
         this.updateConnectionState({
             room: MultiplayerConnectionState.Connecting,
         });
-        const currentConnection = new WebrtcMultiplayerController(this.params.gameId, this.multiplayerApiClient, this.multiplayerParams.stunServerUrls || [], room, undefined, this.params.acceptConnection
+        const currentConnection = new WebrtcMultiplayerController(this.params.gameId, this.multiplayerApiClient, this.multiplayerParams.stunServerUrls || [], room, this.params.clientId, this.params.acceptConnection
             ? (data) => {
                 return this.params.acceptConnection?.(data.connectingClientId, this) ?? true;
             }
@@ -259,6 +259,7 @@ export class MultiplayerRoomController extends ListenTarget {
                     };
             });
             if (connectionResult.connected) {
+                await this.params.prepareConnection?.(currentConnection);
                 this.currentConnection = currentConnection;
                 previousConnection?.destroy();
                 makeWritable(this).roomId = room.roomId;

package/dist/room-handler-server/multiplayer-room-handler.js

@@ -34,6 +34,7 @@ export function createMultiplayerRoomHandler(options) {
         },
         /** Get the client-friendly room listing for a game. */
         getRoomsForFetching(gameId) {
+            updateRoomsForFetching(gameId, state);
             return state.roomsForFetching[gameId] || {};
         },
         /** Force an immediate update of the rooms-for-fetching cache for a game. */
@@ -177,20 +178,36 @@ function processQueueItem(state, { message, transport, gameId, }) {
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     }
     else if (message.type === MultiplayerWebSocketMessageType.HostPing) {
-        if (room && room.hostClient.clientSecret === message.clientSecret) {
-            room.clientCount = message.clientCount;
-            room.roomName = message.roomName;
-            room.roomPassword = message.roomPassword;
-            room.lastHostPingTimestamp = Date.now();
-            updateRoomsForFetching(gameId, state);
-        }
-        else {
+        const existingRoom = state.rooms[gameId]?.[message.roomId];
+        if (existingRoom && existingRoom.hostClient.clientSecret !== message.clientSecret) {
+            /** A client that isn't the room's host is trying to ping it. */
             transport.send({
                 messageId: message.messageId,
                 type: MultiplayerWebSocketMessageType.Error,
                 errorMessage: 'Invalid room to ping.',
             });
         }
+        else {
+            /** Refresh the room, re-establishing it if needed. */
+            const pingedRoom = existingRoom ?? {
+                clientsAwaitingAnswer: {},
+                hostClient: currentClient,
+                roomId: message.roomId,
+                roomName: message.roomName,
+                roomPassword: message.roomPassword,
+                clientCount: message.clientCount,
+                lastHostPingTimestamp: Date.now(),
+            };
+            pingedRoom.hostClient = currentClient;
+            pingedRoom.clientCount = message.clientCount;
+            pingedRoom.roomName = message.roomName;
+            pingedRoom.roomPassword = message.roomPassword;
+            pingedRoom.lastHostPingTimestamp = Date.now();
+            getOrSet(state.rooms, gameId, () => {
+                return {};
+            })[pingedRoom.roomId] = pingedRoom;
+            updateRoomsForFetching(gameId, state);
+        }
     }
     else {
         transport.send({

package/dist/webrtc/webrtc-controller.d.ts

@@ -78,8 +78,8 @@ export type WebrtcEvents<MessageData extends JsonCompatibleValue> = WebrtcMessag
  */
 export declare class WebrtcController<MessageData extends JsonCompatibleValue> extends ListenTarget<WebrtcEvents<MessageData>> {
     readonly clientId: ClientId;
-    private dataChannel;
-    private connection;
+    protected dataChannel: undefined | Readonly<RTCDataChannel>;
+    protected connection: undefined | Readonly<RTCPeerConnection>;
     /** Indicates whether the WebRTC connection is live or not. */
     readonly isConnected: boolean;
     constructor(clientId: ClientId);
@@ -98,7 +98,9 @@ export declare class WebrtcController<MessageData extends JsonCompatibleValue> e
      */
     sendMessage(data: Readonly<MessageData>): void;
     destroy(): void;
-    private handleDataChannel;
-    private createConnection;
+    /** Attach connection and message handling to a WebRTC data channel. */
+    protected handleDataChannel(dataChannel: Readonly<RTCDataChannel>): void;
+    /** Create a peer connection and wait for ICE candidate gathering to finish. */
+    protected createConnection(stunServerUrls: ReadonlyArray<string>): Promise<void>;
 }
 export {};

package/dist/webrtc/webrtc-controller.js

@@ -120,6 +120,7 @@ export class WebrtcController extends ListenTarget {
         this.connection?.close();
         super.destroy();
     }
+    /** Attach connection and message handling to a WebRTC data channel. */
     handleDataChannel(dataChannel) {
         this.dataChannel?.close();
         this.dataChannel = dataChannel;
@@ -144,6 +145,7 @@ export class WebrtcController extends ListenTarget {
             }));
         });
     }
+    /** Create a peer connection and wait for ICE candidate gathering to finish. */
     createConnection(stunServerUrls) {
         if (this.connection) {
             throw new Error('Connection already created!');

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

@@ -1,10 +1,11 @@
-import { type JsonCompatibleValue, type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
-import { type RequireExactlyOne } from 'type-fest';
+import { type JsonCompatibleValue, type MaybePromise, type PartialWithUndefined, PromiseQueue, type RequireExactlyOne } from '@augment-vir/common';
+import { type ClientWebSocket } from '@rest-vir/api';
 import { ListenTarget } from 'typed-event-target';
-import { type MultiplayerConnectClientMessage } from '../multiplayer-api/multiplayer-api.js';
+import { type MultiplayerConnectClientMessage, multiplayerConnectWebSocket } from '../multiplayer-api/multiplayer-api.js';
 import { type MultiplayerApiClient } from '../multiplayer-api/multiplayer-client.js';
 import { type ClientId } from '../multiplayer-id.js';
 import { MultiplayerWebSocketMessageType } from './web-rtc-communication.js';
+import { WebrtcController } from './webrtc-controller.js';
 declare const WebrtcMultiplayerMessageEvent_base: (new (eventInitDict: {
     bubbles?: boolean;
     cancelable?: boolean;
@@ -169,8 +170,8 @@ export type ShouldAllowConnectionCheck<Controller> = (data: {
  * @category Internal
  */
 export declare class WebrtcMultiplayerController<MessageData extends JsonCompatibleValue = any> extends ListenTarget<WebrtcMultiplayerMessageEvent<MessageData> | WebrtcMultiplayerConnectionUpdateEvent> {
-    private readonly gameId;
-    private readonly multiplayerApiClient;
+    protected readonly gameId: string;
+    protected readonly multiplayerApiClient: Readonly<MultiplayerApiClient>;
     readonly stunServerUrls: ReadonlyArray<string>;
     readonly multiplayerRoom: Readonly<RoomInput>;
     /** The randomized client id for this controller and client. */
@@ -182,17 +183,20 @@ export declare class WebrtcMultiplayerController<MessageData extends JsonCompati
      *
      * @default accept all connections
      */
-    private readonly shouldAllowConnectionCheck;
+    protected readonly shouldAllowConnectionCheck: ShouldAllowConnectionCheck<WebrtcMultiplayerController<MessageData>>;
     readonly hostClientId: ClientId | undefined;
     /**
      * Connections between multiple WebRTC peers.
      *
      * A connection with the current client's id is the init connection.
      */
-    private connections;
-    private webSocket;
-    private readonly clientSecret;
+    protected connections: Record<ClientId, WebrtcController<MessageData>>;
+    protected webSocket: ClientWebSocket<typeof multiplayerConnectWebSocket> | undefined;
+    protected readonly clientSecret: string;
     readonly isDestroyed: boolean;
+    protected hostPingTimeoutId: ReturnType<typeof setTimeout> | undefined;
+    protected reconnectPromise: Promise<void> | undefined;
+    protected isCleaningUpConnection: boolean;
     constructor(gameId: string, multiplayerApiClient: Readonly<MultiplayerApiClient>, stunServerUrls: ReadonlyArray<string>, multiplayerRoom: Readonly<RoomInput>, 
     /** The randomized client id for this controller and client. */
     clientId?: ClientId, 
@@ -255,9 +259,97 @@ export declare class WebrtcMultiplayerController<MessageData extends JsonCompati
      *   if the WebRTC connections already exist).
      */
     initConnection(): Promise<boolean>;
-    private sendHostPing;
-    private connectionQueue;
-    private setupWebSocket;
-    private createNewConnection;
+    /** Send the current room client count to the multiplayer server and schedule the next update. */
+    protected sendHostPing(): void;
+    /** Reconnect this room member after it loses its connection to the host. */
+    protected reconnectAfterHostLoss(): void;
+    protected connectionQueue: PromiseQueue;
+    /** Create or reuse the WebSocket used for multiplayer room signaling. */
+    protected setupWebSocket(): Promise<ClientWebSocket<Readonly<{
+        path: "/connect";
+        clientMessage: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<{
+            clientId: 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;
+            };
+        }> | import("@sinclair/typebox").TUnsafe<{
+            clientId: ClientId;
+            roomId: import("../multiplayer-id.js").RoomId;
+            roomName: string;
+        } & {
+            messageId: import("../multiplayer-id.js").SocketMessageId;
+        } & {
+            type: MultiplayerWebSocketMessageType.HostPing;
+            clientSecret: string;
+            clientCount: number;
+            roomPassword: string;
+        }> | import("@sinclair/typebox").TUnsafe<{
+            messageId: import("../multiplayer-id.js").SocketMessageId;
+        } & {
+            clientId: ClientId;
+            roomId: import("../multiplayer-id.js").RoomId;
+            roomName: string;
+        } & {
+            type: MultiplayerWebSocketMessageType.Offer;
+            data: {
+                type: MultiplayerWebSocketMessageType.Offer;
+                sdp: string;
+            };
+        } & {
+            clientSecret: string;
+            roomPassword: string;
+        }>)[]>>;
+        hostMessage: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<{
+            clientId: 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;
+            };
+        }> | import("@sinclair/typebox").TUnsafe<{
+            clientId: ClientId;
+            roomId: import("../multiplayer-id.js").RoomId;
+            roomName: string;
+        } & {
+            messageId: import("../multiplayer-id.js").SocketMessageId;
+        } & {
+            type: MultiplayerWebSocketMessageType.Offer;
+            data: {
+                type: MultiplayerWebSocketMessageType.Offer;
+                sdp: string;
+            };
+        }> | import("@sinclair/typebox").TUnsafe<{
+            messageId: import("../multiplayer-id.js").SocketMessageId;
+        } & {
+            type: MultiplayerWebSocketMessageType.OfferResult;
+            hostClientId: ClientId;
+        }> | import("@sinclair/typebox").TUnsafe<{
+            messageId: import("../multiplayer-id.js").SocketMessageId;
+        } & {
+            type: MultiplayerWebSocketMessageType.Error;
+            errorMessage: string;
+        }>)[]>>;
+        searchParams: {
+            readonly gameId: import("object-shape-tester").Shape<import("@sinclair/typebox").TTuple<[import("@sinclair/typebox").TString]>>;
+        };
+    }>>>;
+    /** Create and track a WebRTC connection for the given client. */
+    protected createNewConnection(clientId: ClientId): WebrtcController<MessageData>;
 }
 export {};

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

@@ -1,5 +1,5 @@
 import { assert, waitUntil } from '@augment-vir/assert';
-import { PromiseQueue, ensureErrorAndPrependMessage, extractErrorMessage, filterMap, getObjectTypedValues, log, makeWritable, mergeDefinedProperties, randomString, removeDuplicates, stringify, } from '@augment-vir/common';
+import { PromiseQueue, ensureErrorAndPrependMessage, extractErrorMessage, filterMap, getObjectTypedValues, log, makeWritable, mergeDefinedProperties, randomString, removeDuplicates, retry, stringify, } from '@augment-vir/common';
 import { ListenTarget, defineTypedCustomEvent } from 'typed-event-target';
 import { multiplayerConnectWebSocket, } from '../multiplayer-api/multiplayer-api.js';
 import { createMultiplayerId } from '../multiplayer-id.js';
@@ -65,6 +65,9 @@ export class WebrtcMultiplayerController extends ListenTarget {
     webSocket;
     clientSecret = randomString(32);
     isDestroyed = false;
+    hostPingTimeoutId;
+    reconnectPromise;
+    isCleaningUpConnection = false;
     constructor(gameId, multiplayerApiClient, stunServerUrls, multiplayerRoom, 
     /** The randomized client id for this controller and client. */
     clientId = createMultiplayerId.client(), 
@@ -144,6 +147,8 @@ export class WebrtcMultiplayerController extends ListenTarget {
     /** Destroy this controller and clean everything up. */
     destroy() {
         makeWritable(this).isDestroyed = true;
+        globalThis.clearTimeout(this.hostPingTimeoutId);
+        this.hostPingTimeoutId = undefined;
         Object.values(this.connections).forEach((connection) => connection.destroy());
         void this.webSocket?.close();
         this.connectionQueue.destroy();
@@ -197,31 +202,50 @@ export class WebrtcMultiplayerController extends ListenTarget {
             // connections already exist
             return false;
         }
-        const newConnection = this.createNewConnection(this.clientId);
-        const newOffer = await newConnection.createOffer(this.stunServerUrls);
-        const webSocket = await this.setupWebSocket();
-        const reply = await webSocket.sendAndWaitForReply({
-            message: {
-                messageId: createMultiplayerId.socketMessage(),
-                type: MultiplayerWebSocketMessageType.Offer,
-                clientId: this.clientId,
-                clientSecret: this.clientSecret,
-                data: newOffer,
-                ...this.multiplayerRoom,
-            },
-            replyCheck(message) {
-                return message.type === MultiplayerWebSocketMessageType.OfferResult;
-            },
-        });
-        assert.strictEquals(reply.type, MultiplayerWebSocketMessageType.OfferResult);
-        /**
-         * `hostClientId` will be set by the already attached listener. We just need to wait until
-         * it does, because we need to know who the host is before calling `sendHostPing`.
-         */
-        await waitUntil.isDefined(() => this.hostClientId);
-        this.sendHostPing();
-        return true;
+        try {
+            const newConnection = this.createNewConnection(this.clientId);
+            const newOffer = await newConnection.createOffer(this.stunServerUrls);
+            const webSocket = await this.setupWebSocket();
+            const reply = await webSocket.sendAndWaitForReply({
+                message: {
+                    messageId: createMultiplayerId.socketMessage(),
+                    type: MultiplayerWebSocketMessageType.Offer,
+                    clientId: this.clientId,
+                    clientSecret: this.clientSecret,
+                    data: newOffer,
+                    ...this.multiplayerRoom,
+                },
+                replyCheck(message) {
+                    return message.type === MultiplayerWebSocketMessageType.OfferResult;
+                },
+            });
+            assert.strictEquals(reply.type, MultiplayerWebSocketMessageType.OfferResult);
+            /**
+             * `hostClientId` will be set by the already attached listener. We just need to wait
+             * until it does, because we need to know who the host is before calling
+             * `sendHostPing`.
+             */
+            await waitUntil.isDefined(() => this.hostClientId);
+            this.sendHostPing();
+            return true;
+        }
+        catch (error) {
+            this.isCleaningUpConnection = true;
+            try {
+                this.connections[this.clientId]?.destroy();
+                delete this.connections[this.clientId];
+                globalThis.clearTimeout(this.hostPingTimeoutId);
+                this.hostPingTimeoutId = undefined;
+                await this.webSocket?.close();
+                this.webSocket = undefined;
+            }
+            finally {
+                this.isCleaningUpConnection = false;
+            }
+            throw error;
+        }
     }
+    /** Send the current room client count to the multiplayer server and schedule the next update. */
     sendHostPing() {
         if (this.isHost() && this.webSocket) {
             this.webSocket.send({
@@ -232,10 +256,29 @@ export class WebrtcMultiplayerController extends ListenTarget {
                 clientSecret: this.clientSecret,
                 ...this.multiplayerRoom,
             });
-            setTimeout(() => this.sendHostPing(), 1000);
+            this.hostPingTimeoutId = setTimeout(() => this.sendHostPing(), 1000);
         }
     }
+    /** Reconnect this room member after it loses its connection to the host. */
+    reconnectAfterHostLoss() {
+        if (this.isDestroyed || this.reconnectPromise || this.isCleaningUpConnection) {
+            return;
+        }
+        this.reconnectPromise = retry(3, () => this.initConnection(), {
+            interval: {
+                seconds: 1,
+            },
+        })
+            .then(() => undefined)
+            .catch((error) => {
+            log.warning(ensureErrorAndPrependMessage(error, 'Failed to reconnect to the multiplayer room.'));
+        })
+            .finally(() => {
+            this.reconnectPromise = undefined;
+        });
+    }
     connectionQueue = new PromiseQueue();
+    /** Create or reuse the WebSocket used for multiplayer room signaling. */
     async setupWebSocket() {
         if (this.webSocket &&
             (this.webSocket.readyState === WebSocket.OPEN ||
@@ -342,12 +385,15 @@ export class WebrtcMultiplayerController extends ListenTarget {
                 },
                 close: () => {
                     this.webSocket = undefined;
+                    globalThis.clearTimeout(this.hostPingTimeoutId);
+                    this.hostPingTimeoutId = undefined;
                 },
             },
         });
         this.webSocket = webSocket;
         return webSocket;
     }
+    /** Create and track a WebRTC connection for the given client. */
     createNewConnection(clientId) {
         const newController = new WebrtcController(clientId);
         this.connections[clientId] = newController;
@@ -382,7 +428,7 @@ export class WebrtcMultiplayerController extends ListenTarget {
                      * If this member client has lost connection to its host, we've got to get it
                      * back!
                      */
-                    void this.initConnection();
+                    this.reconnectAfterHostLoss();
                 }
             }
         });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/multiplayer-core",
-    "version": "0.0.8",
+    "version": "0.1.1",
     "description": "Core functionalities for Antha multiplayer mods.",
     "keywords": [
         "vir",
@@ -36,21 +36,20 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.73.1",
-        "@augment-vir/common": "^31.73.1",
-        "@rest-vir/api": "^2.2.0",
-        "@sinclair/typebox": "^0.34.49",
-        "date-vir": "^8.5.0",
-        "object-shape-tester": "^6.14.0",
-        "type-fest": "^5.7.0",
-        "typed-event-target": "^4.3.1",
-        "url-vir": "^2.1.9"
+        "@augment-vir/assert": "^32.2.2",
+        "@augment-vir/common": "^32.2.2",
+        "@rest-vir/api": "^2.3.1",
+        "@sinclair/typebox": "^0.34.52",
+        "date-vir": "^9.0.0",
+        "object-shape-tester": "^6.14.1",
+        "typed-event-target": "^4.3.3",
+        "url-vir": "^2.2.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.73.1",
-        "@web/dev-server-esbuild": "^1.0.5",
-        "@web/test-runner": "^0.20.2",
-        "@web/test-runner-playwright": "^0.11.1",
+        "@augment-vir/test": "^32.2.2",
+        "@web/dev-server-esbuild": "^2.0.0",
+        "@web/test-runner": "^1.0.0",
+        "@web/test-runner-playwright": "^1.0.0",
         "istanbul-smart-text-reporter": "^1.1.5"
     },
     "engines": {