@antha/multiplayer-p2p-lock-step 0.0.8 → 0.1.1

package/README.md

@@ -1,3 +1,49 @@
 # @antha/multiplayer-p2p-lock-step
 
-A multiplayer mod for the Antha engine that uses peer-to-peer lock-step for game state synchronization.
+This package provides a pre-built [Antha game engine](https://www.npmjs.com/package/@antha/engine) mod for peer-to-peer lock-step multiplayer state synchronization. Players submit actions, and the host distributes them as ordered frames so every client advances game state in the same order.
+
+## Install
+
+```sh
+npm i @antha/multiplayer-p2p-lock-step
+```
+
+## Usage
+
+<!-- example-link: src/readme-examples/creating-lock-step-game.example.ts -->
+
+```TypeScript
+import {AnthaEngine, defineAnthaMod} from '@antha/engine';
+import {
+    type AnthaMultiplayerP2pLockStepState,
+    createAnthaMultiplayerP2pLockStepMod,
+} from '@antha/multiplayer-p2p-lock-step';
+
+type GameState = AnthaMultiplayerP2pLockStepState<string>;
+
+const engine = new AnthaEngine<GameState>({
+    mods: [
+        createAnthaMultiplayerP2pLockStepMod<string>({
+            gameId: 'my-game',
+        }),
+        defineAnthaMod<GameState>({
+            modName: 'game-logic',
+            execute({state}) {
+                const controller = state.multiplayerP2pLockStep?.multiplayerController;
+
+                if (!controller) {
+                    return;
+                }
+                if (!controller.isConnected()) {
+                    controller.startSingleplayer();
+                    controller.act('move-left');
+                }
+
+                return `Network FPS: ${controller.getFps()}`;
+            },
+        }),
+    ],
+});
+
+engine.startLoop();
+```

package/dist/p2p-lock-step-multiplayer-controller.d.ts

@@ -133,6 +133,7 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
     protected timeoutId: ReturnType<typeof globalThis.setTimeout> | undefined;
     protected frameTickReady: boolean;
     protected frameMs: number | undefined;
+    protected joiningRoom: boolean;
     protected lastFpsCalculation: {
         timestamp: number;
         frameCount: number;
@@ -186,9 +187,9 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
      * - For non-host clients, this includes the member client and the host client once connected.
      */
     getAllClientIds(): ClientId[];
-    /** 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;
     /**
      * Manually run the next frame.
@@ -219,6 +220,8 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
     protected listenToRoomController(): void;
     /** Attach an established room transport and publish initial frame readiness. */
     protected attachMultiplayerRoomConnection(roomConnection: Readonly<MultiplayerRoomConnection<P2pLockStepMessage<MultiplayerPacket>>>): void;
+    /** Restart frame production if this client is promoted after losing its previous host. */
+    protected handleNewHost(clientId: ClientId): void;
     /** Send an empty frame to a newly connected member so it can join the frame flow. */
     protected syncNewMember(clientId: ClientId): void;
     /** Apply received member actions on the host or received frames on member clients. */

package/dist/p2p-lock-step-multiplayer-controller.js

@@ -53,6 +53,7 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
     timeoutId;
     frameTickReady = true;
     frameMs;
+    joiningRoom = false;
     lastFpsCalculation = {
         timestamp: 0,
         frameCount: 0,
@@ -68,6 +69,7 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
         }).milliseconds;
         this.roomController = new MultiplayerRoomController({
             gameId: params.gameId,
+            clientId: this.localClientId,
             acceptConnection: params.acceptConnection
                 ? (connectingClientId) => {
                     this.debugLog(`checking incoming connection from ${connectingClientId}`);
@@ -143,13 +145,13 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
         }
         return this.roomConnection?.getAllClientIds() || [];
     }
-    /** 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) {
         this.debugLog(`initializing multiplayer with backend ${params.backendOrigin}`);
         await this.roomController.initMultiplayer(params);
         this.debugLog('multiplayer API initialized');
     }
-    /** 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.');
@@ -223,23 +225,32 @@ export class P2pLockStepMultiplayerController 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 wasSingleplayer = this.singleplayer;
         this.debugLog(`joining or creating room '${room.roomName}' (${room.roomId})`);
-        const roomConnection = await this.joinRoom({
-            previousRoomConnection,
-            room,
-        });
-        if (previousRoomConnection) {
-            globalThis.clearTimeout(this.timeoutId);
-            this.clientsResponded = {};
-            this.frameActions = [];
-            this.frameTickReady = true;
+        this.joiningRoom = true;
+        try {
+            const roomConnection = await this.joinRoom({
+                previousRoomConnection,
+                room,
+            });
+            if (previousRoomConnection) {
+                globalThis.clearTimeout(this.timeoutId);
+                this.clientsResponded = {};
+                this.frameActions = [];
+                this.frameTickReady = true;
+            }
+            else if (wasSingleplayer) {
+                globalThis.clearTimeout(this.timeoutId);
+                this.frameTickReady = true;
+            }
+            this.singleplayer = false;
+            this.attachMultiplayerRoomConnection(roomConnection);
+            this.debugLog(`attached p2p-lock-step connection; client=${this.getClientId() || 'unknown'} host=${this.isHost()} connected=${this.isConnected()}`);
+        }
+        finally {
+            this.joiningRoom = false;
         }
-        this.attachMultiplayerRoomConnection(roomConnection);
-        this.debugLog(`attached p2p-lock-step connection; client=${this.getClientId() || 'unknown'} host=${this.isHost()} connected=${this.isConnected()}`);
     }
     /** Join through the core room controller while preserving the wrapper connection on failure. */
     async joinRoom({ previousRoomConnection, room, }) {
@@ -283,6 +294,9 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
             if ('newMember' in event.detail) {
                 this.syncNewMember(event.detail.newMember);
             }
+            else if ('newHost' in event.detail) {
+                this.handleNewHost(event.detail.newHost);
+            }
             this.dispatch(event);
         });
         this.roomController.listen((ControllerMessageEvent), (event) => {
@@ -306,6 +320,19 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
             });
         }
     }
+    /** Restart frame production if this client is promoted after losing its previous host. */
+    handleNewHost(clientId) {
+        if (this.joiningRoom ||
+            clientId !== this.localClientId ||
+            !this.roomConnection ||
+            !this.roomConnection.isHost()) {
+            return;
+        }
+        globalThis.clearTimeout(this.timeoutId);
+        this.clientsResponded = {};
+        this.frameTickReady = true;
+        this.finishFrame();
+    }
     /** Send an empty frame to a newly connected member so it can join the frame flow. */
     syncNewMember(clientId) {
         this.debugLog(`syncNewMember called for ${clientId}; host=${this.isHost()}`);

package/package.json

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