@antha/multiplayer-p2p-lock-step 0.21.0 → 0.22.0

package/dist/antha-multiplayer-p2p-lock-step.mod.d.ts

@@ -34,7 +34,7 @@ export declare function isMultiplayerRoomConnected({ multiplayerP2pLockStep, }:
  *
  * @category Internal
  */
-export type AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket extends JsonCompatibleValue = any, State extends AnthaMultiplayerP2pLockStepState<MultiplayerPacket> = AnthaMultiplayerP2pLockStepState<MultiplayerPacket>> = PartialWithUndefined<SelectFrom<P2pLockStepMultiplayerControllerParams<MultiplayerPacket>, {
+export type AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket extends JsonCompatibleValue = any, State extends AnthaMultiplayerP2pLockStepState<MultiplayerPacket> = AnthaMultiplayerP2pLockStepState<MultiplayerPacket>, StateSync extends JsonCompatibleValue = JsonCompatibleValue> = PartialWithUndefined<SelectFrom<P2pLockStepMultiplayerControllerParams<MultiplayerPacket>, {
     acceptConnection: true;
     debugMultiplayer: true;
     frameDuration: true;
@@ -60,6 +60,32 @@ export type AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket extends JsonCom
             state: Partial<State>;
         }>) => MaybePromise<number | undefined>;
     };
+    /**
+     * Sends the host's state to each peer that joins, so games don't need their own sync
+     * packets. A joining peer skips every frame until its state is loaded, and desync checks
+     * skip it until then too. The host pauses frames while `createStateSync` runs.
+     *
+     * @default joining peers receive no state
+     */
+    stateSync: {
+        /** Called on the host, right after applying a frame, to capture the state to send. */
+        createStateSync: (params: Readonly<{
+            state: Partial<State>;
+        }>) => MaybePromise<StateSync>;
+        /** Called on a joining (or resyncing) peer to replace its state with the host's. */
+        loadStateSync: (params: Readonly<{
+            stateSync: StateSync;
+            multiplayerController: P2pLockStepMultiplayerController<MultiplayerPacket>;
+            state: Partial<State>;
+        }>) => MaybePromise<void>;
+        /**
+         * When `desyncCheck` is also set, a peer that detects a desync reloads the host's state
+         * (after `MultiplayerControllerDesyncEvent` is emitted).
+         *
+         * @default desyncs are only reported
+         */
+        resyncOnDesync?: boolean | undefined;
+    };
     /** Applies an individual action from within a frame event. */
     handlePacket: (params: Readonly<{
         packet: Readonly<MultiplayerFramePacket<MultiplayerPacket>>;
@@ -84,4 +110,4 @@ export type AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket extends JsonCom
  *
  * @category Main
  */
-export declare function createAnthaMultiplayerP2pLockStepMod<const MultiplayerPacket extends JsonCompatibleValue = any, State extends AnthaMultiplayerP2pLockStepState<MultiplayerPacket> = AnthaMultiplayerP2pLockStepState<MultiplayerPacket>>(options?: Readonly<AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket, NoInfer<State>>>): import("@antha/engine").AnthaMod<NoInfer<State>>;
+export declare function createAnthaMultiplayerP2pLockStepMod<const MultiplayerPacket extends JsonCompatibleValue = any, State extends AnthaMultiplayerP2pLockStepState<MultiplayerPacket> = AnthaMultiplayerP2pLockStepState<MultiplayerPacket>, StateSync extends JsonCompatibleValue = JsonCompatibleValue>(options?: Readonly<AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket, NoInfer<State>, NoInfer<StateSync>>>): import("@antha/engine").AnthaMod<NoInfer<State>>;

package/dist/antha-multiplayer-p2p-lock-step.mod.js

@@ -1,7 +1,7 @@
 import { defineAnthaMod, ModExecutionTriggerType } from '@antha/engine';
 import { emptyApiAndRoomConnectionState, MultiplayerControllerClientStatusEvent, MultiplayerControllerConnectionEvent, } from '@antha/multiplayer-core';
 import { awaitedBlockingMap, log, } from '@augment-vir/common';
-import { MultiplayerControllerFrameEvent, P2pLockStepMultiplayerController, } from './p2p-lock-step-multiplayer-controller.js';
+import { MultiplayerControllerFrameEvent, MultiplayerControllerStateSyncEvent, P2pLockStepMultiplayerController, } from './p2p-lock-step-multiplayer-controller.js';
 /**
  * Indicates whether a p2p-lock-step multiplayer room is currently connected.
  *
@@ -18,20 +18,28 @@ export function isMultiplayerRoomConnected({ multiplayerP2pLockStep, }) {
  * @category Main
  */
 export function createAnthaMultiplayerP2pLockStepMod(options = {}) {
+    const shouldHandleFrames = !!(options.handlePacket ||
+        options.runFrameUpdate ||
+        options.desyncCheck ||
+        options.stateSync);
     return defineAnthaMod({
         modName: 'antha-multiplayer-p2p-lock-step',
         initState: {
             debugMultiplayer: options.debugMultiplayer,
             multiplayerLockstepTick: 0,
         },
-        trigger: options.handlePacket ||
-            options.runFrameUpdate ||
-            options.desyncCheck ||
-            options.handleClientStatus
+        trigger: shouldHandleFrames || options.handleClientStatus
             ? {
                 event: [
-                    ...(options.handlePacket || options.runFrameUpdate || options.desyncCheck
-                        ? [MultiplayerControllerFrameEvent]
+                    ...(shouldHandleFrames
+                        ? [
+                            MultiplayerControllerFrameEvent,
+                        ]
+                        : []),
+                    ...(options.stateSync
+                        ? [
+                            MultiplayerControllerStateSyncEvent,
+                        ]
                         : []),
                     ...(options.handleClientStatus
                         ? [MultiplayerControllerClientStatusEvent]
@@ -54,7 +62,9 @@ export function createAnthaMultiplayerP2pLockStepMod(options = {}) {
                         acceptConnection: options.acceptConnection,
                         debugMultiplayer: state.debugMultiplayer,
                         desyncCheckInterval: options.desyncCheck?.interval,
+                        enableStateSync: !!options.stateSync,
                         frameDuration: options.frameDuration,
+                        resyncOnDesync: options.stateSync?.resyncOnDesync,
                     }),
                     connectionState: emptyApiAndRoomConnectionState,
                 };
@@ -82,8 +92,19 @@ export function createAnthaMultiplayerP2pLockStepMod(options = {}) {
                         });
                         return;
                     }
+                    else if (event instanceof MultiplayerControllerStateSyncEvent) {
+                        await options.stateSync?.loadStateSync({
+                            stateSync: event.detail
+                                .stateSync,
+                            multiplayerController: state.multiplayerP2pLockStep.multiplayerController,
+                            state,
+                        });
+                        state.multiplayerP2pLockStep.multiplayerController.finishStateSync();
+                        return;
+                    }
                     else if (event instanceof MultiplayerControllerFrameEvent &&
-                        (options.handlePacket || options.runFrameUpdate || options.desyncCheck)) {
+                        shouldHandleFrames &&
+                        !state.multiplayerP2pLockStep.multiplayerController.awaitingStateSync) {
                         state.multiplayerP2pLockStep.multiplayerController.checkStateHash(event);
                         if (options.handlePacket) {
                             for (const detail of event.detail.packets) {
@@ -123,6 +144,11 @@ export function createAnthaMultiplayerP2pLockStepMod(options = {}) {
                                 }),
                             });
                         }
+                        if (event.detail.shouldSendStateSync && options.stateSync) {
+                            state.multiplayerP2pLockStep.multiplayerController.sendStateSync(await options.stateSync.createStateSync({
+                                state,
+                            }));
+                        }
                     }
                 });
             }

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

@@ -9,7 +9,8 @@ import { ListenTarget, type RemoveListenerCallback, type TypedCustomEventInit }
  */
 export declare enum P2pLockStepMessageType {
     Actions = "actions",
-    Frame = "frame"
+    Frame = "frame",
+    StateSyncRequest = "state-sync-request"
 }
 /**
  * A single action within a {@link MultiplayerFrame}.
@@ -38,6 +39,12 @@ export type MultiplayerFrame<MultiplayerPacket extends JsonCompatibleValue> = {
      * {@link P2pLockStepMultiplayerController.reportStateHash} right after applying it.
      */
     shouldReportNextFrameHash: boolean;
+    /**
+     * On the host, whether to pass the state from right after applying this frame to
+     * {@link P2pLockStepMultiplayerController.sendStateSync}. The host produces no more frames until
+     * it does.
+     */
+    shouldSendStateSync: boolean;
 }>;
 /**
  * Message exchanged by p2p-lock-step clients.
@@ -65,7 +72,13 @@ export type P2pLockStepMessage<MultiplayerPacket extends JsonCompatibleValue> =
     shouldReportNextFrameHash: boolean;
     /** The host's state hash from right after the most recent desync check frame. */
     stateHash: number;
-}>);
+    /** On synchronization frames, the host's state for the receiving client to load. */
+    stateSync: JsonCompatibleValue;
+}>)
+/** Sent from a child client to the host to ask for the host's current state. */
+ | {
+    type: P2pLockStepMessageType.StateSyncRequest;
+};
 /**
  * Each {@link P2pLockStepMessage} variant, keyed by its message type.
  *
@@ -107,6 +120,23 @@ export type P2pLockStepMultiplayerControllerParams<Action extends JsonCompatible
     acceptConnection?: ((connectingClientId: ClientId, multiplayerController: P2pLockStepMultiplayerController<Action>) => MaybePromise<boolean>) | undefined;
     /** Enables verbose multiplayer debug logs. */
     debugMultiplayer?: boolean | undefined;
+    /**
+     * Sends the host's state to each client that joins. When a client joins, the host's next frame
+     * event has `shouldSendStateSync` set, and the host produces no more frames until that state is
+     * passed to {@link P2pLockStepMultiplayerController.sendStateSync}. The joining client emits
+     * {@link MultiplayerControllerStateSyncEvent} with that state, and ignores every frame before it
+     * (see {@link P2pLockStepMultiplayerController.awaitingStateSync}).
+     *
+     * @default joining clients receive no state
+     */
+    enableStateSync?: boolean | undefined;
+    /**
+     * When `enableStateSync` is also set, a client that detects a desync asks the host for its
+     * state with {@link P2pLockStepMultiplayerController.requestStateSync}.
+     *
+     * @default desyncs are only reported
+     */
+    resyncOnDesync?: boolean | undefined;
     /**
      * The duration between desync check frames, rounded to a whole number of frames. Ignored when
      * `frameDuration` is zero, because then frames only run manually. Every peer's frame event for
@@ -172,12 +202,40 @@ declare const MultiplayerControllerDesyncEvent_base: (new (eventInitDict: {
  */
 export declare class MultiplayerControllerDesyncEvent extends MultiplayerControllerDesyncEvent_base {
 }
+declare const MultiplayerControllerStateSyncEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: Readonly<{
+        stateSync: JsonCompatibleValue;
+    }>;
+}) => import("typed-event-target").TypedCustomEvent<Readonly<{
+    stateSync: JsonCompatibleValue;
+}>, "multiplayer-controller-state-sync">) & 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<{
+    stateSync: JsonCompatibleValue;
+}>, "multiplayer-controller-state-sync">, "type">;
+/**
+ * This is fired on a client when it receives the host's state, when it joins or after it calls
+ * {@link P2pLockStepMultiplayerController.requestStateSync}. Load the state, then call
+ * {@link P2pLockStepMultiplayerController.finishStateSync} before applying any later frame.
+ *
+ * @category Events
+ */
+export declare class MultiplayerControllerStateSyncEvent extends MultiplayerControllerStateSyncEvent_base {
+}
 /**
  * All events emitted by this controller.
  *
  * @category Internal
  */
-export type AllP2pLockStepMultiplayerControllerEvents<MultiplayerPacket extends JsonCompatibleValue> = MultiplayerControllerFrameEvent<MultiplayerPacket> | MultiplayerControllerDesyncEvent | MultiplayerControllerRoomListEvent | MultiplayerControllerClientStatusEvent | MultiplayerControllerConnectionEvent;
+export type AllP2pLockStepMultiplayerControllerEvents<MultiplayerPacket extends JsonCompatibleValue> = MultiplayerControllerFrameEvent<MultiplayerPacket> | MultiplayerControllerDesyncEvent | MultiplayerControllerStateSyncEvent | MultiplayerControllerRoomListEvent | MultiplayerControllerClientStatusEvent | MultiplayerControllerConnectionEvent;
 /**
  * Listener callback for p2p-lock-step frame events.
  *
@@ -197,11 +255,13 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
     static readonly events: {
         MultiplayerControllerDesyncEvent: typeof MultiplayerControllerDesyncEvent;
         MultiplayerControllerFrameEvent: typeof MultiplayerControllerFrameEvent;
+        MultiplayerControllerStateSyncEvent: typeof MultiplayerControllerStateSyncEvent;
     };
     /** All events emitted by this controller. */
     readonly events: {
         MultiplayerControllerDesyncEvent: typeof MultiplayerControllerDesyncEvent;
         MultiplayerControllerFrameEvent: typeof MultiplayerControllerFrameEvent;
+        MultiplayerControllerStateSyncEvent: typeof MultiplayerControllerStateSyncEvent;
     };
     static readonly knownErrors: {
         RoomRejectionError: typeof RoomRejectionError;
@@ -228,6 +288,17 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
     protected nextFrameStateHash: number | undefined;
     /** On clients, this client's state hash from the most recent check frame. */
     protected localStateHash: number | undefined;
+    /** On the host, clients whose state sync will be requested by the next frame. */
+    protected stateSyncRequestClientIds: ClientId[];
+    /** On the host, clients waiting for {@link P2pLockStepMultiplayerController.sendStateSync}. */
+    protected stateSyncFrameClientIds: ClientId[];
+    /**
+     * Whether this client is waiting for the host's state, after joining a room with
+     * `enableStateSync` set or after {@link P2pLockStepMultiplayerController.requestStateSync}.
+     * Frame events received while waiting should not be applied: the host's state already includes
+     * them. Desync checks are skipped while waiting.
+     */
+    awaitingStateSync: boolean;
     protected joiningRoom: boolean;
     protected lastFpsCalculation: {
         timestamp: number;
@@ -312,6 +383,22 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
      * emits {@link MultiplayerControllerDesyncEvent} if they differ.
      */
     checkStateHash(frameEvent: Readonly<MultiplayerControllerFrameEvent<MultiplayerPacket>>): void;
+    /**
+     * On clients, asks the host for its current state, which arrives as a
+     * {@link MultiplayerControllerStateSyncEvent}. Requires `enableStateSync`. Does nothing on the
+     * host or while already waiting.
+     */
+    requestStateSync(): void;
+    /**
+     * Call on clients right after loading the state from a
+     * {@link MultiplayerControllerStateSyncEvent}, so that later frames are applied again.
+     */
+    finishStateSync(): void;
+    /**
+     * Call on the host right after applying a frame event whose `shouldSendStateSync` is set. Sends
+     * the state to every client waiting for it, then resumes frame production.
+     */
+    sendStateSync(stateSync: JsonCompatibleValue): void;
     /** Detects if this controller is the room host or not. */
     isHost(): boolean;
     /** Detects if this controller is connected to a room or not. */
@@ -333,7 +420,10 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
     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. */
+    /**
+     * Send an empty frame to a newly connected member so it can join the frame flow, or queue a
+     * state sync for it when `enableStateSync` is set.
+     */
     protected syncNewMember(clientId: ClientId): void;
     /**
      * Per message type, whether only the host or only member clients handle it and how. Messages
@@ -355,6 +445,10 @@ export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends
      * {@link P2pLockStepMultiplayerController.messageHandlers}.
      */
     protected handleReceivedMessage<Type extends P2pLockStepMessageType>(sourceClientId: ClientId, message: P2pLockStepMessageByType<MultiplayerPacket>[Type]): void;
+    /** On the host, queue a state sync for a client if it isn't already queued. */
+    protected queueStateSync(clientId: ClientId): void;
+    /** Forget pending state syncs, such as when frames restart under a new host or room. */
+    protected resetStateSync(): void;
     /** Forget pending state hashes, such as when frames restart under a new host or room. */
     protected resetDesyncCheck(): void;
     /** Recalculate the current data-flow FPS from completed frames. */

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

@@ -11,6 +11,7 @@ export var P2pLockStepMessageType;
 (function (P2pLockStepMessageType) {
     P2pLockStepMessageType["Actions"] = "actions";
     P2pLockStepMessageType["Frame"] = "frame";
+    P2pLockStepMessageType["StateSyncRequest"] = "state-sync-request";
 })(P2pLockStepMessageType || (P2pLockStepMessageType = {}));
 /**
  * This is fired whenever a new p2p-lock-step frame is received from the host client.
@@ -31,6 +32,15 @@ export class MultiplayerControllerFrameEvent extends defineTypedCustomEvent()('m
  */
 export class MultiplayerControllerDesyncEvent extends defineTypedCustomEvent()('multiplayer-controller-desync') {
 }
+/**
+ * This is fired on a client when it receives the host's state, when it joins or after it calls
+ * {@link P2pLockStepMultiplayerController.requestStateSync}. Load the state, then call
+ * {@link P2pLockStepMultiplayerController.finishStateSync} before applying any later frame.
+ *
+ * @category Events
+ */
+export class MultiplayerControllerStateSyncEvent extends defineTypedCustomEvent()('multiplayer-controller-state-sync') {
+}
 const defaultFrameDuration = {
     milliseconds: 10,
 };
@@ -47,6 +57,7 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
     static events = {
         MultiplayerControllerDesyncEvent,
         MultiplayerControllerFrameEvent,
+        MultiplayerControllerStateSyncEvent,
     };
     /** All events emitted by this controller. */
     events = P2pLockStepMultiplayerController.events;
@@ -73,6 +84,17 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
     nextFrameStateHash;
     /** On clients, this client's state hash from the most recent check frame. */
     localStateHash;
+    /** On the host, clients whose state sync will be requested by the next frame. */
+    stateSyncRequestClientIds = [];
+    /** On the host, clients waiting for {@link P2pLockStepMultiplayerController.sendStateSync}. */
+    stateSyncFrameClientIds = [];
+    /**
+     * Whether this client is waiting for the host's state, after joining a room with
+     * `enableStateSync` set or after {@link P2pLockStepMultiplayerController.requestStateSync}.
+     * Frame events received while waiting should not be applied: the host's state already includes
+     * them. Desync checks are skipped while waiting.
+     */
+    awaitingStateSync = false;
     joiningRoom = false;
     lastFpsCalculation = {
         timestamp: 0,
@@ -183,6 +205,7 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
             throw new Error('Cannot start singleplayer with a connection already present.');
         }
         this.debugLog('starting singleplayer connection');
+        this.resetStateSync();
         this.singleplayer = true;
         this.finishFrame();
         this.dispatch(new MultiplayerControllerConnectionEvent({
@@ -236,7 +259,10 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
      * `undefined` when there's no state to hash yet, which skips this check.
      */
     reportStateHash({ frameEvent, stateHash, }) {
-        if (!this.isHost()) {
+        if (this.awaitingStateSync) {
+            return;
+        }
+        else if (!this.isHost()) {
             this.localStateHash = stateHash;
         }
         else if (frameEvent === this.latestCheckFrameEvent) {
@@ -250,7 +276,8 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
      * emits {@link MultiplayerControllerDesyncEvent} if they differ.
      */
     checkStateHash(frameEvent) {
-        if (frameEvent.detail.hostStateHash == undefined ||
+        if (this.awaitingStateSync ||
+            frameEvent.detail.hostStateHash == undefined ||
             this.localStateHash == undefined ||
             frameEvent.detail.hostStateHash === this.localStateHash) {
             return;
@@ -263,6 +290,55 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
         this.dispatch(new MultiplayerControllerDesyncEvent({
             detail: desync,
         }));
+        if (this.params.resyncOnDesync) {
+            this.requestStateSync();
+        }
+    }
+    /**
+     * On clients, asks the host for its current state, which arrives as a
+     * {@link MultiplayerControllerStateSyncEvent}. Requires `enableStateSync`. Does nothing on the
+     * host or while already waiting.
+     */
+    requestStateSync() {
+        if (!this.params.enableStateSync || this.isHost() || this.awaitingStateSync) {
+            return;
+        }
+        this.debugLog('requesting state sync from host');
+        this.awaitingStateSync = true;
+        this.localStateHash = undefined;
+        this.roomConnection?.sendMessage({
+            type: P2pLockStepMessageType.StateSyncRequest,
+        });
+    }
+    /**
+     * Call on clients right after loading the state from a
+     * {@link MultiplayerControllerStateSyncEvent}, so that later frames are applied again.
+     */
+    finishStateSync() {
+        this.awaitingStateSync = false;
+        this.localStateHash = undefined;
+    }
+    /**
+     * Call on the host right after applying a frame event whose `shouldSendStateSync` is set. Sends
+     * the state to every client waiting for it, then resumes frame production.
+     */
+    sendStateSync(stateSync) {
+        const connectedClientIds = this.getConnectedClientIds();
+        this.stateSyncFrameClientIds
+            .filter((clientId) => {
+            return connectedClientIds.includes(clientId);
+        })
+            .forEach((clientId) => {
+            this.debugLog(`sending state sync to ${clientId}`);
+            this.roomConnection?.sendToOnlyOneClient(clientId, {
+                type: P2pLockStepMessageType.Frame,
+                packets: [],
+                isSynchronizationFrame: true,
+                stateSync,
+            });
+        });
+        this.stateSyncFrameClientIds = [];
+        this.maybeFinishFrame();
     }
     /** Detects if this controller is the room host or not. */
     isHost() {
@@ -293,6 +369,7 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
                 room,
             });
             this.resetDesyncCheck();
+            this.resetStateSync();
             if (previousRoomConnection) {
                 globalThis.clearTimeout(this.timeoutId);
                 this.clientsResponded = {};
@@ -304,6 +381,7 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
                 this.frameTickReady = true;
             }
             this.singleplayer = false;
+            this.awaitingStateSync = !!this.params.enableStateSync && !roomConnection.isHost();
             this.attachMultiplayerRoomConnection(roomConnection);
             this.debugLog(`attached p2p-lock-step connection; client=${this.getClientId() || 'unknown'} host=${this.isHost()} connected=${this.isConnected()}`);
         }
@@ -335,6 +413,7 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
         }
         this.debugLog(`leaving room '${this.roomId || 'unknown'}'`);
         globalThis.clearTimeout(this.timeoutId);
+        this.resetStateSync();
         this.roomConnection = undefined;
         this.singleplayer = false;
         this.roomController.leaveRoom();
@@ -390,13 +469,20 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
         globalThis.clearTimeout(this.timeoutId);
         this.clientsResponded = {};
         this.resetDesyncCheck();
+        this.resetStateSync();
         this.frameTickReady = true;
         this.finishFrame();
     }
-    /** Send an empty frame to a newly connected member so it can join the frame flow. */
+    /**
+     * Send an empty frame to a newly connected member so it can join the frame flow, or queue a
+     * state sync for it when `enableStateSync` is set.
+     */
     syncNewMember(clientId) {
         this.debugLog(`syncNewMember called for ${clientId}; host=${this.isHost()}`);
-        if (this.roomConnection && this.isHost()) {
+        if (this.params.enableStateSync) {
+            this.queueStateSync(clientId);
+        }
+        else if (this.roomConnection && this.isHost()) {
             this.roomConnection.sendToOnlyOneClient(clientId, {
                 type: P2pLockStepMessageType.Frame,
                 packets: [],
@@ -442,7 +528,14 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
                     sourceClientId: this.clientId,
                     type: P2pLockStepMessageType.Actions,
                 });
-                if (!message.isSynchronizationFrame) {
+                if (message.stateSync !== undefined) {
+                    this.dispatch(new MultiplayerControllerStateSyncEvent({
+                        detail: {
+                            stateSync: message.stateSync,
+                        },
+                    }));
+                }
+                else if (!message.isSynchronizationFrame) {
                     this.calculateFps();
                     this.dispatch(new MultiplayerControllerFrameEvent({
                         detail: {
@@ -454,6 +547,12 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
                 }
             },
         },
+        [P2pLockStepMessageType.StateSyncRequest]: {
+            isForHost: true,
+            handle: ({ sourceClientId }) => {
+                this.queueStateSync(sourceClientId);
+            },
+        },
     };
     /**
      * Route a received message to its handler in
@@ -474,6 +573,25 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
             });
         }
     }
+    /** On the host, queue a state sync for a client if it isn't already queued. */
+    queueStateSync(clientId) {
+        if (!this.isHost() ||
+            this.stateSyncRequestClientIds.includes(clientId) ||
+            this.stateSyncFrameClientIds.includes(clientId)) {
+            return;
+        }
+        this.debugLog(`queueing state sync for ${clientId}`);
+        this.stateSyncRequestClientIds = [
+            ...this.stateSyncRequestClientIds,
+            clientId,
+        ];
+    }
+    /** Forget pending state syncs, such as when frames restart under a new host or room. */
+    resetStateSync() {
+        this.stateSyncRequestClientIds = [];
+        this.stateSyncFrameClientIds = [];
+        this.awaitingStateSync = false;
+    }
     /** Forget pending state hashes, such as when frames restart under a new host or room. */
     resetDesyncCheck() {
         this.latestCheckFrameEvent = undefined;
@@ -508,6 +626,12 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
         const shouldReportNextFrameHash = !!this.desyncCheckFrameInterval &&
             !(this.producedFrameCount % this.desyncCheckFrameInterval) &&
             this.getAllClientIds().length > 1;
+        const shouldSendStateSync = !!this.stateSyncRequestClientIds.length;
+        this.stateSyncFrameClientIds = [
+            ...this.stateSyncFrameClientIds,
+            ...this.stateSyncRequestClientIds,
+        ];
+        this.stateSyncRequestClientIds = [];
         this.roomConnection?.sendMessage({
             type: P2pLockStepMessageType.Frame,
             packets: currentFrameActions,
@@ -522,6 +646,9 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
             detail: {
                 packets: currentFrameActions,
                 shouldReportNextFrameHash,
+                ...(shouldSendStateSync && {
+                    shouldSendStateSync,
+                }),
             },
         });
         if (shouldReportNextFrameHash) {
@@ -547,8 +674,8 @@ export class P2pLockStepMultiplayerController extends ListenTarget {
             this.roomConnection?.getConnectedClientIds().every((clientId) => {
                 return this.clientsResponded[clientId];
             });
-        if (!this.frameTickReady || !clientsReady) {
-            this.debugLog(`maybeFinishFrame waiting: frameTickReady=${this.frameTickReady} clientsReady=${!!clientsReady}`);
+        if (!this.frameTickReady || !clientsReady || this.stateSyncFrameClientIds.length) {
+            this.debugLog(`maybeFinishFrame waiting: frameTickReady=${this.frameTickReady} clientsReady=${!!clientsReady} stateSyncs=${this.stateSyncFrameClientIds.length}`);
             return;
         }
         this.finishFrame();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/multiplayer-p2p-lock-step",
-    "version": "0.21.0",
+    "version": "0.22.0",
     "description": "Multiplayer mod for the Antha engine.",
     "keywords": [
         "vir",
@@ -42,7 +42,7 @@
         "typed-event-target": "^4.3.3"
     },
     "devDependencies": {
-        "@antha/multiplayer-core": "^0.21.0",
+        "@antha/multiplayer-core": "^0.22.0",
         "@augment-vir/test": "^32.3.0",
         "@web/dev-server-esbuild": "^2.0.0",
         "@web/test-runner": "^1.0.0",
@@ -50,7 +50,7 @@
         "istanbul-smart-text-reporter": "^1.1.5"
     },
     "peerDependencies": {
-        "@antha/multiplayer-core": "^0.21.0"
+        "@antha/multiplayer-core": "^0.22.0"
     },
     "engines": {
         "node": ">=22"