@antha/multiplayer-p2p-lock-step 0.0.1

package/LICENSE-CC0

@@ -0,0 +1,121 @@
+CC0 1.0 Universal
+
+Creative Commons Legal Code
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 electrovir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @antha/multiplayer-p2p-lock-step
+
+A multiplayer mod for the Antha engine that uses peer-to-peer lock-step for game state synchronization.

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

@@ -0,0 +1,37 @@
+import { type ApiAndRoomConnectionState, type MultiplayerClientRooms } from '@antha/multiplayer-core';
+import { type JsonCompatibleValue, type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { P2pLockStepMultiplayerController, type P2pLockStepMultiplayerControllerParams } from './p2p-lock-step-multiplayer-controller.js';
+/**
+ * Engine state added by the p2p-lock-step multiplayer mod.
+ *
+ * @category Internal
+ */
+export type AnthaMultiplayerP2pLockStepState<MultiplayerPacket extends JsonCompatibleValue = any> = {
+    /** Enables verbose multiplayer debug logs. */
+    debugMultiplayer?: boolean | undefined;
+    /** P2p-lock-step controller state. */
+    multiplayerP2pLockStep: {
+        /** Controller used to drive singleplayer or multiplayer frame sync. */
+        multiplayerController: P2pLockStepMultiplayerController<MultiplayerPacket>;
+        /** Current backend API and room connection state. */
+        connectionState: ApiAndRoomConnectionState;
+        /** Rooms currently available for joining. */
+        availableRooms: MultiplayerClientRooms;
+    };
+};
+/**
+ * Options for {@link createAnthaMultiplayerP2pLockStepMod}.
+ *
+ * @category Internal
+ */
+export type AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket extends JsonCompatibleValue = any> = PartialWithUndefined<SelectFrom<P2pLockStepMultiplayerControllerParams<MultiplayerPacket>, {
+    acceptConnection: true;
+    debugMultiplayer: true;
+    gameId: true;
+}>>;
+/**
+ * Create the engine mod that owns p2p-lock-step multiplayer state.
+ *
+ * @category Main
+ */
+export declare function createAnthaMultiplayerP2pLockStepMod<const MultiplayerPacket extends JsonCompatibleValue = any>(options?: Readonly<AnthaMultiplayerP2pLockStepOptions<MultiplayerPacket>>): import("@antha/engine").AnthaMod<NoInfer<AnthaMultiplayerP2pLockStepState<NoInfer<MultiplayerPacket>>>>;

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

@@ -0,0 +1,49 @@
+import { defineAnthaMod } from '@antha/engine';
+import { ControllerConnectionEvent, ControllerRoomListEvent, emptyApiAndRoomConnectionState, } from '@antha/multiplayer-core';
+import { log, } from '@augment-vir/common';
+import { P2pLockStepMultiplayerController, } from './p2p-lock-step-multiplayer-controller.js';
+/**
+ * Create the engine mod that owns p2p-lock-step multiplayer state.
+ *
+ * @category Main
+ */
+export function createAnthaMultiplayerP2pLockStepMod(options = {}) {
+    return defineAnthaMod({
+        modName: 'antha-multiplayer-p2p-lock-step',
+        execute({ state }) {
+            if (options.debugMultiplayer == undefined) {
+                state.debugMultiplayer = options.debugMultiplayer;
+            }
+            if (!state.multiplayerP2pLockStep) {
+                log.if(!!state.debugMultiplayer).faint('[multiplayer] creating p2p-lock-step mod state');
+                state.multiplayerP2pLockStep = {
+                    multiplayerController: new P2pLockStepMultiplayerController({
+                        gameId: options.gameId || 'antha',
+                        acceptConnection: options.acceptConnection,
+                        debugMultiplayer: state.debugMultiplayer,
+                        frameDuration: undefined,
+                    }),
+                    connectionState: emptyApiAndRoomConnectionState,
+                    availableRooms: {},
+                };
+                state.multiplayerP2pLockStep.multiplayerController.listen(ControllerConnectionEvent, ({ detail: newConnectionState }) => {
+                    if (!state.multiplayerP2pLockStep) {
+                        return;
+                    }
+                    log.if(!!state.debugMultiplayer).faint(`[multiplayer] mod connection state updated: api=${String(newConnectionState.api)} room=${String(newConnectionState.room)}`);
+                    state.multiplayerP2pLockStep.connectionState = newConnectionState;
+                });
+                state.multiplayerP2pLockStep.multiplayerController.listen(ControllerRoomListEvent, ({ detail: rooms }) => {
+                    if (!state.multiplayerP2pLockStep) {
+                        return;
+                    }
+                    state.multiplayerP2pLockStep.availableRooms = rooms;
+                });
+            }
+        },
+        cleanup({ state }) {
+            log.if(!!state.debugMultiplayer).faint('[multiplayer] cleaning up p2p-lock-step mod');
+            state.multiplayerP2pLockStep?.multiplayerController.destroy();
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './antha-multiplayer-p2p-lock-step.mod.js';
+export * from './p2p-lock-step-multiplayer-controller.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './antha-multiplayer-p2p-lock-step.mod.js';
+export * from './p2p-lock-step-multiplayer-controller.js';

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

@@ -0,0 +1,229 @@
+import { type ApiAndRoomConnectionState, type ClientId, ControllerClientEvent, ControllerConnectionEvent, ControllerRoomListEvent, type MultiplayerInitParams, type MultiplayerRoomConnection, MultiplayerRoomController, type RoomInput, RoomRejectionError } from '@antha/multiplayer-core';
+import { type JsonCompatibleValue, type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type AnyDuration } from 'date-vir';
+import { ListenTarget, type TypedCustomEventInit } from 'typed-event-target';
+/**
+ * Message type for {@link P2pLockStepMessage}.
+ *
+ * @category Internal
+ */
+export declare enum P2pLockStepMessageType {
+    Actions = "actions",
+    Frame = "frame"
+}
+/**
+ * Data received from {@link ControllerFrameEvent}.
+ *
+ * @category Internal
+ */
+export type FrameEventDetail<MultiplayerPacket extends JsonCompatibleValue> = {
+    packet: MultiplayerPacket;
+    clientId: ClientId;
+};
+/**
+ * Message exchanged by p2p-lock-step clients.
+ *
+ * @category Internal
+ */
+export type P2pLockStepMessage<MultiplayerPacket extends JsonCompatibleValue> = 
+/** Sent from child clients to the host as actions happen. */
+{
+    type: P2pLockStepMessageType.Actions;
+    sourceClientId: ClientId;
+    actions: MultiplayerPacket[];
+} | {
+    type: P2pLockStepMessageType.Frame;
+    actions: FrameEventDetail<MultiplayerPacket>[];
+};
+/**
+ * Constructor parameters for {@link P2pLockStepMultiplayerController}.
+ *
+ * @category Internal
+ */
+export type P2pLockStepMultiplayerControllerParams<Action extends JsonCompatibleValue> = {
+    /**
+     * A unique string id that represents your game so that your lobby server can serve multiple
+     * games at once. Your lobby server will need to know this game id ahead of time and match it to
+     * your frontend's origin.
+     */
+    gameId: string;
+} & PartialWithUndefined<{
+    /**
+     * This is fired when a WebRTC peer attempts to connect to the host client. Return `true` to
+     * accept the connection. Return `false` to reject it.
+     *
+     * @default accept all connections
+     */
+    acceptConnection?: ((connectingClientId: ClientId, controller: P2pLockStepMultiplayerController<Action>) => MaybePromise<boolean>) | undefined;
+    /** Enables verbose multiplayer debug logs. */
+    debugMultiplayer?: boolean | undefined;
+    /**
+     * The duration between each frame. This should probably always be smaller than your supported
+     * render frame duration.
+     *
+     * @default {milliseconds: 10}
+     */
+    frameDuration?: AnyDuration | undefined;
+}>;
+declare const ControllerFrameEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: any;
+}) => import("typed-event-target").TypedCustomEvent<any, "controller-frame">) & 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<any, "controller-frame">, "type">;
+/**
+ * This is fired whenever a new p2p-lock-step frame is received from the host client.
+ *
+ * @category Events
+ */
+export declare class ControllerFrameEvent<MultiplayerPacket extends JsonCompatibleValue> extends ControllerFrameEvent_base {
+    detail: ReadonlyArray<FrameEventDetail<MultiplayerPacket>>;
+    constructor(eventInitDict: TypedCustomEventInit<ReadonlyArray<FrameEventDetail<MultiplayerPacket>>>);
+}
+/**
+ * All events emitted by this controller.
+ *
+ * @category Internal
+ */
+export type AllP2pLockStepMultiplayerControllerEvents<MultiplayerPacket extends JsonCompatibleValue> = ControllerFrameEvent<MultiplayerPacket> | ControllerRoomListEvent | ControllerClientEvent | ControllerConnectionEvent;
+/**
+ * Listener callback for p2p-lock-step frame events.
+ *
+ * @category Internal
+ */
+export type ControllerFrameListener<MultiplayerPacket extends JsonCompatibleValue> = (event: Readonly<ControllerFrameEvent<MultiplayerPacket>>) => MaybePromise<void>;
+/**
+ * An all-in-one controller for singleplayer or p2p-lock-step multiplayer game state.
+ *
+ * @category Main
+ */
+export declare class P2pLockStepMultiplayerController<MultiplayerPacket extends JsonCompatibleValue = any> extends ListenTarget<AllP2pLockStepMultiplayerControllerEvents<MultiplayerPacket>> {
+    protected readonly params: P2pLockStepMultiplayerControllerParams<MultiplayerPacket>;
+    /** The current data flow FPS. */
+    readonly currentFps: number;
+    /** All events emitted by this controller. */
+    static readonly events: {
+        ControllerFrameEvent: typeof ControllerFrameEvent;
+    };
+    /** All events emitted by this controller. */
+    readonly events: {
+        ControllerFrameEvent: typeof ControllerFrameEvent;
+    };
+    static readonly knownErrors: {
+        RoomRejectionError: typeof RoomRejectionError;
+    };
+    readonly knownErrors: {
+        RoomRejectionError: typeof RoomRejectionError;
+    };
+    /** Core multiplayer room controller that owns API, room polling, signaling, and transport. */
+    readonly roomController: MultiplayerRoomController<P2pLockStepMessage<MultiplayerPacket>>;
+    protected readonly localClientId: ClientId;
+    protected roomConnection: MultiplayerRoomConnection<P2pLockStepMessage<MultiplayerPacket>> | undefined;
+    protected clientsResponded: Record<ClientId, boolean>;
+    protected frameActions: FrameEventDetail<MultiplayerPacket>[];
+    protected timeoutId: ReturnType<typeof globalThis.setTimeout> | undefined;
+    protected frameTickReady: boolean;
+    protected frameMs: number | undefined;
+    protected lastFpsCalculation: {
+        timestamp: number;
+        frameCount: number;
+    };
+    protected singleplayer: boolean;
+    constructor(params: P2pLockStepMultiplayerControllerParams<MultiplayerPacket>);
+    /** Current p2p-lock-step connection, exposed for compatibility checks. */
+    get currentConnection(): this | undefined;
+    /** The current client id. */
+    get clientId(): ClientId;
+    /**
+     * Set to `false` to disable room updates, even when still not connected to a room in
+     * multiplayer mode.
+     */
+    get enableRoomUpdates(): boolean;
+    /** Update whether room list polling is enabled while not connected to a room. */
+    set enableRoomUpdates(value: boolean);
+    /** Currently joined room id. If a room has not been joined yet, this will be empty. */
+    get roomId(): import("@antha/multiplayer-core").RoomId | undefined;
+    /** The current connection state of the controller's connection to a backend API. */
+    get apiConnectionState(): ApiAndRoomConnectionState['api'];
+    /** The current connection state of the controller's connection to a multiplayer room. */
+    get roomConnectionState(): ApiAndRoomConnectionState['room'];
+    /** The current multiplayer API client. This will be `undefined` if playing in single player. */
+    get multiplayerApiClient(): Readonly<import("@rest-vir/api").RestVirClient<{
+        apiName: string;
+        endpoints: Readonly<Record<"/" | "/health" | "/rooms", Readonly<import("@rest-vir/api").EndpointDefinition>>>;
+        webSockets: Readonly<Record<"/connect", Readonly<import("@rest-vir/api").WebSocketDefinition>>>;
+    }>> | undefined;
+    /**
+     * Get the current client's WebRTC client id. This will return `undefined` if there is no
+     * current connection.
+     */
+    getClientId(): ClientId | undefined;
+    /**
+     * 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(): ClientId[];
+    /**
+     * 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(): ClientId[];
+    /** Start multiplayer mode. This delegates API connectivity and room polling to multiplayer core. */
+    initMultiplayer(params: Readonly<MultiplayerInitParams>): Promise<void>;
+    /** Start singleplayer mode. */
+    startSingleplayer(): void;
+    /**
+     * Manually run the next frame.
+     *
+     * @throws Error if `frameDuration` has been set.
+     */
+    runFrame(actions?: ReadonlyArray<MultiplayerPacket> | undefined): void;
+    /** The current FPS of the data flow. */
+    getFps(): number;
+    /** Fire an action. This will be sent to all clients in the room so they can process it. */
+    act(actions: MultiplayerPacket | ReadonlyArray<MultiplayerPacket>): void;
+    /** Detects if this controller is the room host or not. */
+    isHost(): boolean;
+    /** Detects if this controller is connected to a room or not. */
+    isConnected(): boolean;
+    /** Cleanup everything. */
+    destroy(): void;
+    /**
+     * Join or create a room.
+     *
+     * @throws `Error` if this controller is already connected to a room.
+     */
+    joinOrCreateRoom(room: Readonly<RoomInput>): Promise<void>;
+    /** Leave the current room or single player connection. */
+    leaveRoom(): void;
+    /** Forward core room-controller events into this frame-sync controller. */
+    protected listenToRoomController(): void;
+    /** Attach an established room transport and publish initial frame readiness. */
+    protected attachMultiplayerRoomConnection(roomConnection: Readonly<MultiplayerRoomConnection<P2pLockStepMessage<MultiplayerPacket>>>): 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. */
+    protected handleReceivedMessage(sourceClientId: ClientId, message: Readonly<P2pLockStepMessage<MultiplayerPacket>>): void;
+    /** Recalculate the current data-flow FPS from completed frames. */
+    protected calculateFps(): void;
+    /** Complete the current frame and schedule the next automatic frame when configured. */
+    protected finishFrame(): void;
+    /** Complete a frame when this host has reached its configured readiness conditions. */
+    protected maybeFinishFrame(): void;
+    /** Write a multiplayer debug log when debug logging is enabled. */
+    protected debugLog(message: string): void;
+}
+export {};

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

@@ -0,0 +1,411 @@
+import { ControllerClientEvent, ControllerConnectionEvent, ControllerMessageEvent, ControllerRoomListEvent, createMultiplayerId, emptyApiAndRoomConnectionState, MultiplayerConnectionState, MultiplayerRoomController, RoomRejectionError, } from '@antha/multiplayer-core';
+import { ensureArray, log, makeWritable, } from '@augment-vir/common';
+import { convertDuration } from 'date-vir';
+import { defineTypedCustomEvent, ListenTarget } from 'typed-event-target';
+/**
+ * Message type for {@link P2pLockStepMessage}.
+ *
+ * @category Internal
+ */
+export var P2pLockStepMessageType;
+(function (P2pLockStepMessageType) {
+    P2pLockStepMessageType["Actions"] = "actions";
+    P2pLockStepMessageType["Frame"] = "frame";
+})(P2pLockStepMessageType || (P2pLockStepMessageType = {}));
+/**
+ * This is fired whenever a new p2p-lock-step frame is received from the host client.
+ *
+ * @category Events
+ */
+export class ControllerFrameEvent extends defineTypedCustomEvent()('controller-frame') {
+    constructor(eventInitDict) {
+        super(eventInitDict);
+    }
+}
+const defaultFrameDuration = {
+    milliseconds: 10,
+};
+/**
+ * An all-in-one controller for singleplayer or p2p-lock-step multiplayer game state.
+ *
+ * @category Main
+ */
+export class P2pLockStepMultiplayerController extends ListenTarget {
+    params;
+    /** The current data flow FPS. */
+    currentFps = 0;
+    /** All events emitted by this controller. */
+    static events = {
+        ControllerFrameEvent,
+    };
+    /** All events emitted by this controller. */
+    events = P2pLockStepMultiplayerController.events;
+    static knownErrors = {
+        RoomRejectionError,
+    };
+    knownErrors = P2pLockStepMultiplayerController.knownErrors;
+    /** Core multiplayer room controller that owns API, room polling, signaling, and transport. */
+    roomController;
+    localClientId = createMultiplayerId.client();
+    roomConnection;
+    clientsResponded = {};
+    frameActions = [];
+    timeoutId;
+    frameTickReady = true;
+    frameMs;
+    lastFpsCalculation = {
+        timestamp: 0,
+        frameCount: 0,
+    };
+    singleplayer = false;
+    constructor(params) {
+        super();
+        this.params = params;
+        this.debugLog(`constructing controller for game '${params.gameId}'`);
+        const frameDuration = params.frameDuration || defaultFrameDuration;
+        this.frameMs = convertDuration(frameDuration, {
+            milliseconds: true,
+        }).milliseconds;
+        this.roomController = new MultiplayerRoomController({
+            gameId: params.gameId,
+            acceptConnection: params.acceptConnection
+                ? (connectingClientId) => {
+                    this.debugLog(`checking incoming connection from ${connectingClientId}`);
+                    return params.acceptConnection?.(connectingClientId, this) ?? true;
+                }
+                : undefined,
+        });
+        this.listenToRoomController();
+    }
+    /** Current p2p-lock-step connection, exposed for compatibility checks. */
+    get currentConnection() {
+        return this.isConnected() ? this : undefined;
+    }
+    /** The current client id. */
+    get clientId() {
+        return this.roomConnection?.clientId || this.localClientId;
+    }
+    /**
+     * Set to `false` to disable room updates, even when still not connected to a room in
+     * multiplayer mode.
+     */
+    get enableRoomUpdates() {
+        return this.roomController.enableRoomUpdates;
+    }
+    /** Update whether room list polling is enabled while not connected to a room. */
+    set enableRoomUpdates(value) {
+        this.roomController.enableRoomUpdates = value;
+    }
+    /** Currently joined room id. If a room has not been joined yet, this will be empty. */
+    get roomId() {
+        return this.roomController.roomId;
+    }
+    /** The current connection state of the controller's connection to a backend API. */
+    get apiConnectionState() {
+        return this.roomController.apiConnectionState;
+    }
+    /** The current connection state of the controller's connection to a multiplayer room. */
+    get roomConnectionState() {
+        return this.roomController.roomConnectionState;
+    }
+    /** The current multiplayer API client. This will be `undefined` if playing in single player. */
+    get multiplayerApiClient() {
+        return this.roomController.multiplayerApiClient;
+    }
+    /**
+     * Get the current client's WebRTC client id. This will return `undefined` if there is no
+     * current connection.
+     */
+    getClientId() {
+        if (this.singleplayer) {
+            return this.localClientId;
+        }
+        return this.roomConnection?.clientId || this.roomController.getClientId();
+    }
+    /**
+     * 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.roomConnection?.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() {
+        if (this.singleplayer) {
+            return [
+                this.localClientId,
+            ];
+        }
+        return this.roomConnection?.getAllClientIds() || [];
+    }
+    /** Start multiplayer mode. This delegates API connectivity and room polling to multiplayer core. */
+    async initMultiplayer(params) {
+        this.debugLog(`initializing multiplayer with backend ${params.backendOrigin}`);
+        await this.roomController.initMultiplayer(params);
+        this.debugLog('multiplayer API initialized');
+    }
+    /** Start singleplayer mode. */
+    startSingleplayer() {
+        if (this.currentConnection) {
+            throw new Error('Cannot start singleplayer with a connection already present.');
+        }
+        this.debugLog('starting singleplayer connection');
+        this.singleplayer = true;
+        this.finishFrame();
+        this.dispatch(new ControllerConnectionEvent({
+            detail: {
+                ...emptyApiAndRoomConnectionState,
+                api: MultiplayerConnectionState.Connected,
+            },
+        }));
+        this.debugLog(`singleplayer connection ready with client ${this.getClientId() || 'unknown'}`);
+    }
+    /**
+     * Manually run the next frame.
+     *
+     * @throws Error if `frameDuration` has been set.
+     */
+    runFrame(actions) {
+        this.debugLog(`runFrame called with ${actions?.length || 0} actions`);
+        if (this.frameMs != undefined) {
+            throw new Error('Cannot manually run frame when frameDuration has been set.');
+        }
+        if (actions) {
+            this.act(actions);
+        }
+        if (this.isHost()) {
+            this.frameTickReady = true;
+            this.maybeFinishFrame();
+        }
+    }
+    /** The current FPS of the data flow. */
+    getFps() {
+        return this.currentFps;
+    }
+    /** Fire an action. This will be sent to all clients in the room so they can process it. */
+    act(actions) {
+        if (!this.currentConnection || !this.currentConnection.isConnected()) {
+            throw new Error('Cannot perform action: not connected to a room.');
+        }
+        const actionArray = ensureArray(actions);
+        this.debugLog(`act called with ${actionArray.length} actions`);
+        this.frameActions = [
+            ...this.frameActions,
+            ...actionArray.map((packet) => {
+                return {
+                    clientId: this.clientId,
+                    packet,
+                };
+            }),
+        ];
+    }
+    /** Detects if this controller is the room host or not. */
+    isHost() {
+        return this.singleplayer || this.roomConnection?.isHost() || false;
+    }
+    /** Detects if this controller is connected to a room or not. */
+    isConnected() {
+        return this.singleplayer || this.roomConnection?.isConnected() || false;
+    }
+    /** Cleanup everything. */
+    destroy() {
+        this.debugLog('destroying controller');
+        globalThis.clearTimeout(this.timeoutId);
+        this.roomConnection = undefined;
+        this.singleplayer = false;
+        this.roomController.destroy();
+        super.destroy();
+    }
+    /**
+     * 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.');
+        }
+        this.debugLog(`joining or creating room '${room.roomName}' (${room.roomId})`);
+        try {
+            await this.roomController.joinOrCreateRoom(room);
+            this.debugLog(`room controller joined room '${room.roomName}' (${room.roomId}); client=${this.roomController.getClientId() || 'unknown'} host=${this.roomController.isHost()}`);
+            if (!this.roomController.currentConnection) {
+                throw new Error('Cannot start p2p-lock-step multiplayer: room connection is missing.');
+            }
+            this.attachMultiplayerRoomConnection(this.roomController.currentConnection);
+            this.debugLog(`attached p2p-lock-step connection; client=${this.getClientId() || 'unknown'} host=${this.isHost()} connected=${this.isConnected()}`);
+        }
+        catch (error) {
+            this.debugLog(`join room failed: ${String(error)}`);
+            this.roomConnection = undefined;
+            throw error;
+        }
+    }
+    /** Leave the current room or single player connection. */
+    leaveRoom() {
+        if (!this.currentConnection) {
+            this.debugLog('leaveRoom called without a current connection');
+            return;
+        }
+        this.debugLog(`leaving room '${this.roomId || 'unknown'}'`);
+        globalThis.clearTimeout(this.timeoutId);
+        this.roomConnection = undefined;
+        this.singleplayer = false;
+        this.roomController.leaveRoom();
+    }
+    /** Forward core room-controller events into this frame-sync controller. */
+    listenToRoomController() {
+        this.roomController.listen(ControllerRoomListEvent, (event) => {
+            this.dispatch(event);
+        });
+        this.roomController.listen(ControllerConnectionEvent, (event) => {
+            this.debugLog(`connection event received: api=${String(event.detail.api)} room=${String(event.detail.room)}`);
+            this.dispatch(event);
+        });
+        this.roomController.listen(ControllerClientEvent, (event) => {
+            this.debugLog(`client event received: ${JSON.stringify(event.detail)}`);
+            if ('newMember' in event.detail) {
+                this.syncNewMember(event.detail.newMember);
+            }
+            this.dispatch(event);
+        });
+        this.roomController.listen((ControllerMessageEvent), (event) => {
+            this.debugLog(`message event received from ${event.sourceClientId}: type=${event.detail.type}`);
+            this.handleReceivedMessage(event.sourceClientId, event.detail);
+        });
+    }
+    /** Attach an established room transport and publish initial frame readiness. */
+    attachMultiplayerRoomConnection(roomConnection) {
+        this.debugLog(`attached room connection; client=${roomConnection.clientId} host=${roomConnection.isHost()} connected=${roomConnection.isConnected()} connectedClients=${roomConnection.getConnectedClientIds().length} allClients=${roomConnection.getAllClientIds().length}`);
+        this.roomConnection = roomConnection;
+        if (roomConnection.isHost()) {
+            this.finishFrame();
+        }
+        else {
+            this.debugLog('attached as member; sending initial readiness actions to host');
+            roomConnection.sendMessage({
+                actions: [],
+                sourceClientId: this.clientId,
+                type: P2pLockStepMessageType.Actions,
+            });
+        }
+    }
+    /** 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()}`);
+        if (this.roomConnection && this.isHost()) {
+            this.roomConnection.sendToOnlyOneClient(clientId, {
+                type: P2pLockStepMessageType.Frame,
+                actions: [],
+            });
+        }
+    }
+    /** Apply received member actions on the host or received frames on member clients. */
+    handleReceivedMessage(sourceClientId, message) {
+        this.debugLog(`received lock-step message from ${sourceClientId}: type=${message.type} host=${this.isHost()}`);
+        if (!this.roomConnection) {
+            this.debugLog('ignored message because no room connection is attached');
+            return;
+        }
+        if (this.isHost() && message.type === P2pLockStepMessageType.Actions) {
+            this.debugLog(`host received ${message.actions.length} actions from ${sourceClientId}`);
+            this.clientsResponded = {
+                ...this.clientsResponded,
+                [sourceClientId]: true,
+            };
+            this.frameActions = [
+                ...this.frameActions,
+                ...message.actions.map((packet) => {
+                    return {
+                        clientId: sourceClientId,
+                        packet,
+                    };
+                }),
+            ];
+            this.maybeFinishFrame();
+        }
+        else if (!this.isHost() && message.type === P2pLockStepMessageType.Frame) {
+            this.debugLog(`member received frame with ${message.actions.length} actions; sending ${this.frameActions.length} local actions back to host`);
+            const currentFrameActions = this.frameActions;
+            this.frameActions = [];
+            this.calculateFps();
+            this.roomConnection.sendMessage({
+                actions: currentFrameActions.map(({ packet }) => {
+                    return packet;
+                }),
+                sourceClientId: this.clientId,
+                type: P2pLockStepMessageType.Actions,
+            });
+            this.dispatch(new ControllerFrameEvent({
+                detail: message.actions,
+            }));
+        }
+    }
+    /** Recalculate the current data-flow FPS from completed frames. */
+    calculateFps() {
+        const now = Date.now();
+        const diff = Date.now() - this.lastFpsCalculation.timestamp;
+        if (diff > 1000) {
+            makeWritable(this).currentFps = this.lastFpsCalculation.frameCount / (diff / 1000);
+            this.lastFpsCalculation = {
+                frameCount: 0,
+                timestamp: now,
+            };
+        }
+        else {
+            this.lastFpsCalculation = {
+                ...this.lastFpsCalculation,
+                frameCount: this.lastFpsCalculation.frameCount + 1,
+            };
+        }
+    }
+    /** Complete the current frame and schedule the next automatic frame when configured. */
+    finishFrame() {
+        const currentFrameActions = this.frameActions;
+        this.frameActions = [];
+        this.roomConnection?.sendMessage({
+            type: P2pLockStepMessageType.Frame,
+            actions: currentFrameActions,
+        });
+        this.dispatch(new ControllerFrameEvent({
+            detail: currentFrameActions,
+        }));
+        this.frameTickReady = false;
+        this.calculateFps();
+        if (this.frameMs) {
+            this.timeoutId = globalThis.setTimeout(() => {
+                this.frameTickReady = true;
+                this.maybeFinishFrame();
+            }, this.frameMs);
+        }
+    }
+    /** Complete a frame when this host has reached its configured readiness conditions. */
+    maybeFinishFrame() {
+        if (!this.isHost()) {
+            this.debugLog('maybeFinishFrame skipped because this client is not host');
+            return;
+        }
+        const clientsReady = this.singleplayer ||
+            this.roomConnection?.getConnectedClientIds().every((clientId) => {
+                return this.clientsResponded[clientId];
+            });
+        if (!this.frameTickReady || !clientsReady) {
+            this.debugLog(`maybeFinishFrame waiting: frameTickReady=${this.frameTickReady} clientsReady=${!!clientsReady}`);
+            return;
+        }
+        this.finishFrame();
+    }
+    /** Write a multiplayer debug log when debug logging is enabled. */
+    debugLog(message) {
+        log.if(!!this.params.debugMultiplayer).faint(`[multiplayer] ${message}`);
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@antha/multiplayer-p2p-lock-step",
+    "version": "0.0.1",
+    "description": "Multiplayer mod for the Antha engine.",
+    "keywords": [
+        "vir",
+        "antha",
+        "WebRTC",
+        "signal server",
+        "multiplayer",
+        "gaming"
+    ],
+    "homepage": "https://github.com/electrovir/antha",
+    "bugs": {
+        "url": "https://github.com/electrovir/antha/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/antha.git"
+    },
+    "license": "(MIT OR CC0-1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "sideEffects": false,
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "test": "virmator test web",
+        "test:coverage": "npm test coverage",
+        "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"
+    },
+    "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",
+        "istanbul-smart-text-reporter": "^1.1.5"
+    },
+    "peerDependencies": {
+        "@antha/multiplayer-core": "^0.0.1"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}