@antha/multiplayer-p2p-authoritative-host 0.0.8 → 0.1.1

package/README.md

@@ -1,3 +1,55 @@
 # @antha/multiplayer-p2p-authoritative-host
 
-A multiplayer strategy for Antha where the room host owns canonical state and peers send inputs to that host.
+This package provides a pre-built [Antha game engine](https://www.npmjs.com/package/@antha/engine) mod for peer-to-peer multiplayer where the room host owns the canonical game state. Clients submit inputs to the host, and the host publishes updated state snapshots to the room.
+
+## Install
+
+```sh
+npm i @antha/multiplayer-p2p-authoritative-host
+```
+
+## Usage
+
+<!-- example-link: src/readme-examples/creating-authoritative-host.example.ts -->
+
+```TypeScript
+import {AnthaEngine, defineAnthaMod} from '@antha/engine';
+import {
+    type AnthaMultiplayerP2pAuthoritativeHostState,
+    createAnthaMultiplayerP2pAuthoritativeHostMod,
+} from '@antha/multiplayer-p2p-authoritative-host';
+
+type GameState = AnthaMultiplayerP2pAuthoritativeHostState<number, number>;
+
+const engine = new AnthaEngine<GameState>({
+    mods: [
+        createAnthaMultiplayerP2pAuthoritativeHostMod<number, number>({
+            gameId: 'counter-game',
+            createInitialState() {
+                return 0;
+            },
+            applyInput({input, state}) {
+                return state + input;
+            },
+        }),
+        defineAnthaMod<GameState>({
+            modName: 'game-logic',
+            execute({state}) {
+                const controller = state.multiplayerP2pAuthoritativeHost?.multiplayerController;
+
+                if (!controller) {
+                    return;
+                }
+                if (!controller.isConnected()) {
+                    controller.startSingleplayer();
+                    controller.act(1);
+                }
+
+                return `Score: ${controller.getState()}`;
+            },
+        }),
+    ],
+});
+
+engine.startLoop();
+```

package/dist/p2p-authoritative-host-multiplayer-controller.d.ts

@@ -1,4 +1,4 @@
-import { type ApiAndRoomConnectionState, type ClientId, ControllerClientEvent, ControllerConnectionEvent, ControllerRoomListEvent, type ControllerRoomListListener, type MultiplayerInitParams, type MultiplayerRoomConnection, MultiplayerRoomController, type RoomInput, RoomRejectionError } from '@antha/multiplayer-core';
+import { type ApiAndRoomConnectionState, type ClientId, ControllerClientEvent, ControllerConnectionEvent, ControllerRoomListEvent, type ControllerRoomListListener, type MultiplayerInitParams, type MultiplayerRoomConnection, MultiplayerRoomController, type RoomInput, RoomRejectionError, type SocketMessageId } from '@antha/multiplayer-core';
 import { type JsonCompatibleValue, type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
 import { ListenTarget, type RemoveListenerCallback, type TypedCustomEventInit } from 'typed-event-target';
 /**
@@ -8,6 +8,7 @@ import { ListenTarget, type RemoveListenerCallback, type TypedCustomEventInit }
  */
 export declare enum P2pAuthoritativeHostMessageType {
     Input = "input",
+    StateRequest = "state-request",
     StateSnapshot = "state-snapshot"
 }
 /**
@@ -18,7 +19,10 @@ export declare enum P2pAuthoritativeHostMessageType {
 export type P2pAuthoritativeHostStateSnapshot<State extends JsonCompatibleValue> = {
     sequence: number;
     state: State;
-};
+} & PartialWithUndefined<{
+    /** Identifies the state request that this snapshot fulfills. */
+    stateSyncId: SocketMessageId;
+}>;
 /**
  * Data received from {@link ControllerStateEvent}.
  *
@@ -36,6 +40,9 @@ export type StateEventDetail<Input extends JsonCompatibleValue, State extends Js
 export type P2pAuthoritativeHostMessage<Input extends JsonCompatibleValue, State extends JsonCompatibleValue> = {
     type: P2pAuthoritativeHostMessageType.Input;
     input: Input;
+} | {
+    type: P2pAuthoritativeHostMessageType.StateRequest;
+    stateSyncId: SocketMessageId;
 } | ({
     type: P2pAuthoritativeHostMessageType.StateSnapshot;
 } & StateEventDetail<Input, State>);
@@ -141,6 +148,7 @@ export declare class P2pAuthoritativeHostMultiplayerController<Input extends Jso
     protected roomConnection: MultiplayerRoomConnection<P2pAuthoritativeHostMessage<Input, State>> | undefined;
     protected currentState: State;
     protected currentSequence: number;
+    protected pendingStateSyncId: SocketMessageId | undefined;
     protected singleplayer: boolean;
     constructor(params: P2pAuthoritativeHostMultiplayerControllerParams<Input, State>);
     /** Current p2p-authoritative-host connection, exposed for compatibility checks. */
@@ -192,9 +200,9 @@ export declare class P2pAuthoritativeHostMultiplayerController<Input extends Jso
     getAllClientIds(): ClientId[];
     /** Get the latest local state view. */
     getState(): State;
-    /** Start multiplayer mode. This delegates API connectivity and room polling to multiplayer core. */
+    /** Initialize multiplayer API access without opening a room or starting host pings. */
     initMultiplayer(params: Readonly<MultiplayerInitParams>): Promise<void>;
-    /** Start singleplayer mode. */
+    /** Start local play without contacting the multiplayer API. This can later open into a room. */
     startSingleplayer(): void;
     /** Send or apply a local input. */
     act(input: Readonly<Input>): void;
@@ -208,21 +216,18 @@ export declare class P2pAuthoritativeHostMultiplayerController<Input extends Jso
     destroy(): void;
     /** Join or create a room. */
     joinOrCreateRoom(room: Readonly<RoomInput>): Promise<void>;
-    /** Join through the core room controller while preserving the wrapper connection on failure. */
-    protected joinRoom({ previousRoomConnection, room, }: Readonly<{
-        previousRoomConnection: MultiplayerRoomConnection<P2pAuthoritativeHostMessage<Input, State>> | undefined;
-        room: Readonly<RoomInput>;
-    }>): Promise<MultiplayerRoomConnection<P2pAuthoritativeHostMessage<Input, State>>>;
+    /** Join through the core room controller after its candidate connection is state-synchronized. */
+    protected joinRoom(room: Readonly<RoomInput>): Promise<MultiplayerRoomConnection<P2pAuthoritativeHostMessage<Input, State>>>;
     /** Leave the current room or single player connection. */
     leaveRoom(): void;
     /** Forward core room-controller events into this state-sync controller. */
     protected listenToRoomController(): void;
     /** Attach an established room transport and publish the current state view. */
     protected attachMultiplayerRoomConnection(roomConnection: Readonly<MultiplayerRoomConnection<P2pAuthoritativeHostMessage<Input, State>>>): void;
-    /** Send the latest authoritative state to a newly connected member. */
-    protected syncNewMember(clientId: ClientId): void;
     /** Apply received inputs on the host or received state snapshots on member clients. */
     protected handleReceivedMessage(sourceClientId: ClientId, message: Readonly<P2pAuthoritativeHostMessage<Input, State>>): void;
+    /** Attach and synchronize a candidate room before the core controller commits to it. */
+    protected prepareRoomConnection(roomConnection: Readonly<MultiplayerRoomConnection<P2pAuthoritativeHostMessage<Input, State>>>): Promise<void>;
     /** Validate and apply an input against the current authoritative state. */
     protected applyInput({ clientId, input, }: Readonly<{
         clientId: ClientId;
@@ -241,7 +246,7 @@ export declare class P2pAuthoritativeHostMultiplayerController<Input extends Jso
     /** Broadcast a state snapshot when the local client is the host. */
     protected sendStateSnapshot(detail: Readonly<StateEventDetail<Input, State>>): void;
     /** Create a network message from state event detail. */
-    protected createStateSnapshotMessage(detail: Readonly<StateEventDetail<Input, State>>): P2pAuthoritativeHostMessage<Input, State>;
+    protected createStateSnapshotMessage(detail: Readonly<StateEventDetail<Input, State>>, stateSyncId?: SocketMessageId | undefined): P2pAuthoritativeHostMessage<Input, State>;
     /** Create the local state event detail for the current sequence and state. */
     protected createStateEventDetail(source?: Readonly<PartialWithUndefined<{
         clientId: ClientId;

package/dist/p2p-authoritative-host-multiplayer-controller.js

@@ -1,4 +1,5 @@
 import { ControllerClientEvent, ControllerConnectionEvent, ControllerMessageEvent, ControllerRoomListEvent, createMultiplayerId, emptyApiAndRoomConnectionState, MultiplayerConnectionState, MultiplayerRoomController, RoomRejectionError, } from '@antha/multiplayer-core';
+import { assertWrap, waitUntil } from '@augment-vir/assert';
 import { defineTypedCustomEvent, ListenTarget, } from 'typed-event-target';
 /**
  * Message type for {@link P2pAuthoritativeHostMessage}.
@@ -8,6 +9,7 @@ import { defineTypedCustomEvent, ListenTarget, } from 'typed-event-target';
 export var P2pAuthoritativeHostMessageType;
 (function (P2pAuthoritativeHostMessageType) {
     P2pAuthoritativeHostMessageType["Input"] = "input";
+    P2pAuthoritativeHostMessageType["StateRequest"] = "state-request";
     P2pAuthoritativeHostMessageType["StateSnapshot"] = "state-snapshot";
 })(P2pAuthoritativeHostMessageType || (P2pAuthoritativeHostMessageType = {}));
 /**
@@ -43,6 +45,7 @@ export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
     roomConnection;
     currentState;
     currentSequence = 0;
+    pendingStateSyncId;
     singleplayer = false;
     constructor(params) {
         super();
@@ -50,6 +53,10 @@ export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
         this.currentState = params.createInitialState();
         this.roomController = new MultiplayerRoomController({
             gameId: params.gameId,
+            clientId: this.localClientId,
+            prepareConnection: async (connection) => {
+                await this.prepareRoomConnection(connection);
+            },
             acceptConnection: params.acceptConnection
                 ? (connectingClientId) => {
                     return params.acceptConnection?.(connectingClientId, this) ?? true;
@@ -128,11 +135,11 @@ export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
     getState() {
         return this.currentState;
     }
-    /** Start multiplayer mode. This delegates API connectivity and room polling to multiplayer core. */
+    /** Initialize multiplayer API access without opening a room or starting host pings. */
     async initMultiplayer(params) {
         await this.roomController.initMultiplayer(params);
     }
-    /** Start singleplayer mode. */
+    /** Start local play without contacting the multiplayer API. This can later open into a room. */
     startSingleplayer() {
         if (this.currentConnection) {
             throw new Error('Cannot start singleplayer with a connection already present.');
@@ -191,29 +198,16 @@ export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
     }
     /** Join or create a room. */
     async joinOrCreateRoom(room) {
-        if (this.singleplayer) {
-            throw new Error('Cannot join room: connection already established.');
-        }
-        const previousRoomConnection = this.roomConnection;
-        const roomConnection = await this.joinRoom({
-            previousRoomConnection,
-            room,
-        });
+        const roomConnection = await this.joinRoom(room);
         this.attachMultiplayerRoomConnection(roomConnection);
     }
-    /** Join through the core room controller while preserving the wrapper connection on failure. */
-    async joinRoom({ previousRoomConnection, room, }) {
-        try {
-            await this.roomController.joinOrCreateRoom(room);
-            if (!this.roomController.currentConnection) {
-                throw new Error('Cannot start p2p-authoritative-host multiplayer: room connection is missing.');
-            }
-            return this.roomController.currentConnection;
-        }
-        catch (error) {
-            this.roomConnection = previousRoomConnection;
-            throw error;
+    /** Join through the core room controller after its candidate connection is state-synchronized. */
+    async joinRoom(room) {
+        await this.roomController.joinOrCreateRoom(room);
+        if (!this.roomController.currentConnection) {
+            throw new Error('Cannot start p2p-authoritative-host multiplayer: room connection is missing.');
         }
+        return this.roomController.currentConnection;
     }
     /** Leave the current room or single player connection. */
     leaveRoom() {
@@ -233,9 +227,6 @@ export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
             this.dispatch(event);
         });
         this.roomController.listen(ControllerClientEvent, (event) => {
-            if ('newMember' in event.detail) {
-                this.syncNewMember(event.detail.newMember);
-            }
             this.dispatch(event);
         });
         this.roomController.listen((ControllerMessageEvent), (event) => {
@@ -250,29 +241,68 @@ export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
             this.sendStateSnapshot(this.createStateEventDetail());
         }
     }
-    /** Send the latest authoritative state to a newly connected member. */
-    syncNewMember(clientId) {
-        if (this.roomConnection && this.isHost()) {
-            this.roomConnection.sendToOnlyOneClient(clientId, this.createStateSnapshotMessage(this.createStateEventDetail()));
-        }
-    }
     /** Apply received inputs on the host or received state snapshots on member clients. */
     handleReceivedMessage(sourceClientId, message) {
         if (!this.roomConnection) {
             return;
         }
-        if (this.isHost() && message.type === P2pAuthoritativeHostMessageType.Input) {
-            this.applyInput({
-                clientId: sourceClientId,
-                input: message.input,
-            });
+        const messageHandlers = {
+            [P2pAuthoritativeHostMessageType.Input]: () => {
+                if (this.isHost() && 'input' in message) {
+                    this.applyInput({
+                        clientId: sourceClientId,
+                        input: assertWrap.isDefined(message.input),
+                    });
+                }
+            },
+            [P2pAuthoritativeHostMessageType.StateRequest]: () => {
+                if (this.isHost() && 'stateSyncId' in message) {
+                    this.roomConnection?.sendToOnlyOneClient(sourceClientId, this.createStateSnapshotMessage(this.createStateEventDetail(), assertWrap.isDefined(message.stateSyncId)));
+                }
+            },
+            [P2pAuthoritativeHostMessageType.StateSnapshot]: () => {
+                if (!this.isHost() && 'state' in message) {
+                    const fulfillsPendingSync = this.pendingStateSyncId != undefined &&
+                        message.stateSyncId === this.pendingStateSyncId;
+                    if (fulfillsPendingSync || message.sequence >= this.currentSequence) {
+                        this.currentSequence = message.sequence;
+                        this.currentState = message.state;
+                        this.dispatchState(message);
+                        if (fulfillsPendingSync) {
+                            this.pendingStateSyncId = undefined;
+                        }
+                    }
+                }
+            },
+        };
+        messageHandlers[message.type]();
+    }
+    /** Attach and synchronize a candidate room before the core controller commits to it. */
+    async prepareRoomConnection(roomConnection) {
+        const previousRoomConnection = this.roomConnection;
+        const previousState = this.currentState;
+        const previousSequence = this.currentSequence;
+        const wasSingleplayer = this.singleplayer;
+        this.roomConnection = roomConnection;
+        this.singleplayer = false;
+        try {
+            if (!roomConnection.isHost()) {
+                const stateSyncId = createMultiplayerId.socketMessage();
+                this.pendingStateSyncId = stateSyncId;
+                roomConnection.sendMessage({
+                    type: P2pAuthoritativeHostMessageType.StateRequest,
+                    stateSyncId,
+                });
+                await waitUntil.isTrue(() => this.pendingStateSyncId !== stateSyncId);
+            }
         }
-        else if (!this.isHost() &&
-            message.type === P2pAuthoritativeHostMessageType.StateSnapshot &&
-            message.sequence >= this.currentSequence) {
-            this.currentSequence = message.sequence;
-            this.currentState = message.state;
-            this.dispatchState(message);
+        catch (error) {
+            this.pendingStateSyncId = undefined;
+            this.roomConnection = previousRoomConnection;
+            this.currentState = previousState;
+            this.currentSequence = previousSequence;
+            this.singleplayer = wasSingleplayer;
+            throw error;
         }
     }
     /** Validate and apply an input against the current authoritative state. */
@@ -326,10 +356,13 @@ export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
         }
     }
     /** Create a network message from state event detail. */
-    createStateSnapshotMessage(detail) {
+    createStateSnapshotMessage(detail, stateSyncId) {
         return {
             ...detail,
             type: P2pAuthoritativeHostMessageType.StateSnapshot,
+            ...(stateSyncId && {
+                stateSyncId,
+            }),
         };
     }
     /** Create the local state event detail for the current sequence and state. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/multiplayer-p2p-authoritative-host",
-    "version": "0.0.8",
+    "version": "0.1.1",
     "description": "P2P authoritative-host multiplayer strategy for the Antha engine.",
     "keywords": [
         "vir",
@@ -36,19 +36,19 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/common": "^31.73.1",
-        "typed-event-target": "^4.3.1"
+        "@augment-vir/assert": "^32.2.2",
+        "@augment-vir/common": "^32.2.2",
+        "typed-event-target": "^4.3.3"
     },
     "devDependencies": {
-        "@augment-vir/assert": "^31.73.1",
-        "@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"
     },
     "peerDependencies": {
-        "@antha/multiplayer-core": "^0.0.8"
+        "@antha/multiplayer-core": "^0.1.1"
     },
     "engines": {
         "node": ">=22"