@antha/multiplayer-p2p-authoritative-host 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-authoritative-host
+
+A multiplayer strategy for Antha where the room host owns canonical state and peers send inputs to that host.

package/dist/antha-multiplayer-p2p-authoritative-host.mod.d.ts

@@ -0,0 +1,41 @@
+import { type ApiAndRoomConnectionState, type MultiplayerClientRooms } from '@antha/multiplayer-core';
+import { type JsonCompatibleValue, type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { P2pAuthoritativeHostMultiplayerController, type P2pAuthoritativeHostMultiplayerControllerParams } from './p2p-authoritative-host-multiplayer-controller.js';
+/**
+ * Engine state added by the p2p-authoritative-host multiplayer mod.
+ *
+ * @category Internal
+ */
+export type AnthaMultiplayerP2pAuthoritativeHostState<Input extends JsonCompatibleValue = any, State extends JsonCompatibleValue = any> = {
+    /** P2p-authoritative-host controller state. */
+    multiplayerP2pAuthoritativeHost: {
+        /** Controller used to drive singleplayer or multiplayer state sync. */
+        multiplayerController: P2pAuthoritativeHostMultiplayerController<Input, State>;
+        /** Current backend API and room connection state. */
+        connectionState: ApiAndRoomConnectionState;
+        /** Rooms currently available for joining. */
+        availableRooms: MultiplayerClientRooms;
+        /** Latest state emitted by the multiplayer controller. */
+        currentState: State;
+    };
+};
+/**
+ * Options for {@link createAnthaMultiplayerP2pAuthoritativeHostMod}.
+ *
+ * @category Internal
+ */
+export type AnthaMultiplayerP2pAuthoritativeHostOptions<Input extends JsonCompatibleValue = any, State extends JsonCompatibleValue = any> = SelectFrom<P2pAuthoritativeHostMultiplayerControllerParams<Input, State>, {
+    applyInput: true;
+    createInitialState: true;
+}> & PartialWithUndefined<SelectFrom<P2pAuthoritativeHostMultiplayerControllerParams<Input, State>, {
+    acceptConnection: true;
+    gameId: true;
+    shouldAcceptInput: true;
+    tick: true;
+}>>;
+/**
+ * Create the engine mod that owns p2p-authoritative-host multiplayer state.
+ *
+ * @category Main
+ */
+export declare function createAnthaMultiplayerP2pAuthoritativeHostMod<const Input extends JsonCompatibleValue = any, const State extends JsonCompatibleValue = any>(options: Readonly<AnthaMultiplayerP2pAuthoritativeHostOptions<Input, State>>): import("@antha/engine").AnthaMod<NoInfer<AnthaMultiplayerP2pAuthoritativeHostState<NoInfer<Input>, State>>>;

package/dist/antha-multiplayer-p2p-authoritative-host.mod.js

@@ -0,0 +1,61 @@
+import { defineAnthaMod } from '@antha/engine';
+import { ControllerConnectionEvent, ControllerRoomListEvent, emptyApiAndRoomConnectionState, } from '@antha/multiplayer-core';
+import { ControllerStateEvent, P2pAuthoritativeHostMultiplayerController, } from './p2p-authoritative-host-multiplayer-controller.js';
+/**
+ * Create the engine mod that owns p2p-authoritative-host multiplayer state.
+ *
+ * @category Main
+ */
+export function createAnthaMultiplayerP2pAuthoritativeHostMod(options) {
+    return defineAnthaMod({
+        modName: 'antha-multiplayer-p2p-authoritative-host',
+        execute({ state }) {
+            if (!state.multiplayerP2pAuthoritativeHost) {
+                state.multiplayerP2pAuthoritativeHost = createP2pAuthoritativeHostState(options);
+                state.multiplayerP2pAuthoritativeHost.multiplayerController.listen(ControllerConnectionEvent, ({ detail: newConnectionState }) => {
+                    if (!state.multiplayerP2pAuthoritativeHost) {
+                        return;
+                    }
+                    state.multiplayerP2pAuthoritativeHost.connectionState = newConnectionState;
+                });
+                state.multiplayerP2pAuthoritativeHost.multiplayerController.listen(ControllerRoomListEvent, ({ detail: rooms }) => {
+                    if (!state.multiplayerP2pAuthoritativeHost) {
+                        return;
+                    }
+                    state.multiplayerP2pAuthoritativeHost.availableRooms = rooms;
+                });
+                state.multiplayerP2pAuthoritativeHost.multiplayerController.listen((ControllerStateEvent), ({ detail }) => {
+                    if (!state.multiplayerP2pAuthoritativeHost) {
+                        return;
+                    }
+                    state.multiplayerP2pAuthoritativeHost.currentState = detail.state;
+                });
+            }
+        },
+        cleanup({ state }) {
+            state.multiplayerP2pAuthoritativeHost?.multiplayerController.destroy();
+        },
+    });
+}
+function createP2pAuthoritativeHostState(options) {
+    const multiplayerController = new P2pAuthoritativeHostMultiplayerController({
+        gameId: options.gameId || 'antha',
+        applyInput: options.applyInput,
+        createInitialState: options.createInitialState,
+        ...(options.acceptConnection && {
+            acceptConnection: options.acceptConnection,
+        }),
+        ...(options.shouldAcceptInput && {
+            shouldAcceptInput: options.shouldAcceptInput,
+        }),
+        ...(options.tick && {
+            tick: options.tick,
+        }),
+    });
+    return {
+        multiplayerController,
+        connectionState: emptyApiAndRoomConnectionState,
+        availableRooms: {},
+        currentState: multiplayerController.getState(),
+    };
+}

package/dist/index.d.ts

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

package/dist/index.js

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

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

@@ -0,0 +1,247 @@
+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 { ListenTarget, type TypedCustomEventInit } from 'typed-event-target';
+/**
+ * Message type for {@link P2pAuthoritativeHostMessage}.
+ *
+ * @category Internal
+ */
+export declare enum P2pAuthoritativeHostMessageType {
+    Input = "input",
+    StateSnapshot = "state-snapshot"
+}
+/**
+ * A state snapshot emitted when the authoritative state changes.
+ *
+ * @category Internal
+ */
+export type P2pAuthoritativeHostStateSnapshot<State extends JsonCompatibleValue> = {
+    sequence: number;
+    state: State;
+};
+/**
+ * Data received from {@link ControllerStateEvent}.
+ *
+ * @category Internal
+ */
+export type StateEventDetail<Input extends JsonCompatibleValue, State extends JsonCompatibleValue> = P2pAuthoritativeHostStateSnapshot<State> & PartialWithUndefined<{
+    clientId: ClientId;
+    input: Input;
+}>;
+/**
+ * Messages exchanged by the authoritative-host state strategy.
+ *
+ * @category Internal
+ */
+export type P2pAuthoritativeHostMessage<Input extends JsonCompatibleValue, State extends JsonCompatibleValue> = {
+    type: P2pAuthoritativeHostMessageType.Input;
+    input: Input;
+} | ({
+    type: P2pAuthoritativeHostMessageType.StateSnapshot;
+} & StateEventDetail<Input, State>);
+/**
+ * Game-specific logic for an authoritative-host connection.
+ *
+ * @category Internal
+ */
+export type P2pAuthoritativeHostGameDefinition<Input extends JsonCompatibleValue, State extends JsonCompatibleValue> = {
+    /** Create the initial game state before singleplayer or multiplayer starts. */
+    createInitialState: () => State;
+    /** Apply an accepted input to the current authoritative state. */
+    applyInput: (params: Readonly<{
+        clientId: ClientId;
+        input: Readonly<Input>;
+        state: Readonly<State>;
+    }>) => State;
+    /** Return `false` to reject an input before it changes authoritative state. */
+    shouldAcceptInput?: (params: Readonly<{
+        clientId: ClientId;
+        input: Readonly<Input>;
+        state: Readonly<State>;
+    }>) => boolean | undefined;
+    /** Advance authoritative state from elapsed time without a player input. */
+    tick?: (params: Readonly<{
+        elapsedMs: number;
+        state: Readonly<State>;
+    }>) => State;
+};
+/**
+ * Constructor parameters for {@link P2pAuthoritativeHostMultiplayerController}.
+ *
+ * @category Internal
+ */
+export type P2pAuthoritativeHostMultiplayerControllerParams<Input extends JsonCompatibleValue, State 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;
+} & P2pAuthoritativeHostGameDefinition<Input, State> & 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: P2pAuthoritativeHostMultiplayerController<Input, State>) => MaybePromise<boolean>) | undefined;
+}>;
+declare const ControllerStateEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: any;
+}) => import("typed-event-target").TypedCustomEvent<any, "controller-state">) & 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-state">, "type">;
+/**
+ * This is fired whenever the local authoritative-host state view updates.
+ *
+ * @category Events
+ */
+export declare class ControllerStateEvent<State extends JsonCompatibleValue, Input extends JsonCompatibleValue = any> extends ControllerStateEvent_base {
+    detail: Readonly<StateEventDetail<Input, State>>;
+    constructor(eventInitDict: TypedCustomEventInit<Readonly<StateEventDetail<Input, State>>>);
+}
+/**
+ * All events emitted by this controller.
+ *
+ * @category Internal
+ */
+export type AllP2pAuthoritativeHostMultiplayerControllerEvents<Input extends JsonCompatibleValue, State extends JsonCompatibleValue> = ControllerStateEvent<State, Input> | ControllerRoomListEvent | ControllerClientEvent | ControllerConnectionEvent;
+/**
+ * An all-in-one controller for singleplayer or p2p-authoritative-host multiplayer game state.
+ *
+ * @category Main
+ */
+export declare class P2pAuthoritativeHostMultiplayerController<Input extends JsonCompatibleValue = any, State extends JsonCompatibleValue = any> extends ListenTarget<AllP2pAuthoritativeHostMultiplayerControllerEvents<Input, State>> {
+    protected readonly params: P2pAuthoritativeHostMultiplayerControllerParams<Input, State>;
+    /** All events emitted by this controller. */
+    static readonly events: {
+        ControllerStateEvent: typeof ControllerStateEvent;
+    };
+    /** All events emitted by this controller. */
+    readonly events: {
+        ControllerStateEvent: typeof ControllerStateEvent;
+    };
+    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<P2pAuthoritativeHostMessage<Input, State>>;
+    protected readonly localClientId: ClientId;
+    protected roomConnection: MultiplayerRoomConnection<P2pAuthoritativeHostMessage<Input, State>> | undefined;
+    protected currentState: State;
+    protected currentSequence: number;
+    protected singleplayer: boolean;
+    constructor(params: P2pAuthoritativeHostMultiplayerControllerParams<Input, State>);
+    /** Current p2p-authoritative-host 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[];
+    /** Get the latest local state view. */
+    getState(): State;
+    /** Start multiplayer mode. This delegates API connectivity and room polling to multiplayer core. */
+    initMultiplayer(params: Readonly<MultiplayerInitParams>): Promise<void>;
+    /** Start singleplayer mode. */
+    startSingleplayer(): void;
+    /** Send or apply a local input. */
+    act(input: Readonly<Input>): void;
+    /** Advance authoritative time-based state. Only the host advances canonical state. */
+    tick(elapsedMs?: number): 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 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;
+    /** Validate and apply an input against the current authoritative state. */
+    protected applyInput({ clientId, input, }: Readonly<{
+        clientId: ClientId;
+        input: Readonly<Input>;
+    }>): void;
+    /** Publish a new authoritative state that was not caused by a player input. */
+    protected updateState(state: State): void;
+    /** Publish a new authoritative state caused by a player input. */
+    protected updateStateFromInput({ clientId, input, state, }: Readonly<{
+        clientId: ClientId;
+        input: Readonly<Input>;
+        state: State;
+    }>): void;
+    /** Dispatch the typed state event to local listeners. */
+    protected dispatchState(detail: Readonly<StateEventDetail<Input, State>>): void;
+    /** 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>;
+    /** Create the local state event detail for the current sequence and state. */
+    protected createStateEventDetail(source?: Readonly<PartialWithUndefined<{
+        clientId: ClientId;
+        input: Readonly<Input>;
+    }>>): StateEventDetail<Input, State>;
+}
+export {};

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

@@ -0,0 +1,342 @@
+import { ControllerClientEvent, ControllerConnectionEvent, ControllerMessageEvent, ControllerRoomListEvent, createMultiplayerId, emptyApiAndRoomConnectionState, MultiplayerConnectionState, MultiplayerRoomController, RoomRejectionError, } from '@antha/multiplayer-core';
+import { defineTypedCustomEvent, ListenTarget } from 'typed-event-target';
+/**
+ * Message type for {@link P2pAuthoritativeHostMessage}.
+ *
+ * @category Internal
+ */
+export var P2pAuthoritativeHostMessageType;
+(function (P2pAuthoritativeHostMessageType) {
+    P2pAuthoritativeHostMessageType["Input"] = "input";
+    P2pAuthoritativeHostMessageType["StateSnapshot"] = "state-snapshot";
+})(P2pAuthoritativeHostMessageType || (P2pAuthoritativeHostMessageType = {}));
+/**
+ * This is fired whenever the local authoritative-host state view updates.
+ *
+ * @category Events
+ */
+export class ControllerStateEvent extends defineTypedCustomEvent()('controller-state') {
+    constructor(eventInitDict) {
+        super(eventInitDict);
+    }
+}
+/**
+ * An all-in-one controller for singleplayer or p2p-authoritative-host multiplayer game state.
+ *
+ * @category Main
+ */
+export class P2pAuthoritativeHostMultiplayerController extends ListenTarget {
+    params;
+    /** All events emitted by this controller. */
+    static events = {
+        ControllerStateEvent,
+    };
+    /** All events emitted by this controller. */
+    events = P2pAuthoritativeHostMultiplayerController.events;
+    static knownErrors = {
+        RoomRejectionError,
+    };
+    knownErrors = P2pAuthoritativeHostMultiplayerController.knownErrors;
+    /** Core multiplayer room controller that owns API, room polling, signaling, and transport. */
+    roomController;
+    localClientId = createMultiplayerId.client();
+    roomConnection;
+    currentState;
+    currentSequence = 0;
+    singleplayer = false;
+    constructor(params) {
+        super();
+        this.params = params;
+        this.currentState = params.createInitialState();
+        this.roomController = new MultiplayerRoomController({
+            gameId: params.gameId,
+            acceptConnection: params.acceptConnection
+                ? (connectingClientId) => {
+                    return params.acceptConnection?.(connectingClientId, this) ?? true;
+                }
+                : undefined,
+        });
+        this.listenToRoomController();
+    }
+    /** Current p2p-authoritative-host 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() || [];
+    }
+    /** Get the latest local state view. */
+    getState() {
+        return this.currentState;
+    }
+    /** Start multiplayer mode. This delegates API connectivity and room polling to multiplayer core. */
+    async initMultiplayer(params) {
+        await this.roomController.initMultiplayer(params);
+    }
+    /** Start singleplayer mode. */
+    startSingleplayer() {
+        if (this.currentConnection) {
+            throw new Error('Cannot start singleplayer with a connection already present.');
+        }
+        this.singleplayer = true;
+        this.dispatchState(this.createStateEventDetail());
+        this.dispatch(new ControllerConnectionEvent({
+            detail: {
+                ...emptyApiAndRoomConnectionState,
+                api: MultiplayerConnectionState.Connected,
+            },
+        }));
+    }
+    /** Send or apply a local input. */
+    act(input) {
+        if (!this.currentConnection || !this.currentConnection.isConnected()) {
+            throw new Error('Cannot perform input: not connected to a room.');
+        }
+        if (this.isHost()) {
+            this.applyInput({
+                clientId: this.clientId,
+                input,
+            });
+        }
+        else {
+            this.roomConnection?.sendMessage({
+                type: P2pAuthoritativeHostMessageType.Input,
+                input,
+            });
+        }
+    }
+    /** Advance authoritative time-based state. Only the host advances canonical state. */
+    tick(elapsedMs = 0) {
+        if (!this.isHost() || !this.params.tick) {
+            return;
+        }
+        this.updateState(this.params.tick({
+            elapsedMs,
+            state: this.currentState,
+        }));
+    }
+    /** 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.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.');
+        }
+        try {
+            await this.roomController.joinOrCreateRoom(room);
+            if (!this.roomController.currentConnection) {
+                throw new Error('Cannot start p2p-authoritative-host multiplayer: room connection is missing.');
+            }
+            this.attachMultiplayerRoomConnection(this.roomController.currentConnection);
+        }
+        catch (error) {
+            this.roomConnection = undefined;
+            throw error;
+        }
+    }
+    /** Leave the current room or single player connection. */
+    leaveRoom() {
+        if (!this.currentConnection) {
+            return;
+        }
+        this.roomConnection = undefined;
+        this.singleplayer = false;
+        this.roomController.leaveRoom();
+    }
+    /** Forward core room-controller events into this state-sync controller. */
+    listenToRoomController() {
+        this.roomController.listen(ControllerRoomListEvent, (event) => {
+            this.dispatch(event);
+        });
+        this.roomController.listen(ControllerConnectionEvent, (event) => {
+            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) => {
+            this.handleReceivedMessage(event.sourceClientId, event.detail);
+        });
+    }
+    /** Attach an established room transport and publish the current state view. */
+    attachMultiplayerRoomConnection(roomConnection) {
+        this.roomConnection = roomConnection;
+        this.dispatchState(this.createStateEventDetail());
+        if (this.isHost()) {
+            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,
+            });
+        }
+        else if (!this.isHost() &&
+            message.type === P2pAuthoritativeHostMessageType.StateSnapshot &&
+            message.sequence >= this.currentSequence) {
+            this.currentSequence = message.sequence;
+            this.currentState = message.state;
+            this.dispatchState(message);
+        }
+    }
+    /** Validate and apply an input against the current authoritative state. */
+    applyInput({ clientId, input, }) {
+        const shouldAcceptInput = this.params.shouldAcceptInput?.({
+            clientId,
+            input,
+            state: this.currentState,
+        }) ?? true;
+        if (shouldAcceptInput) {
+            this.updateStateFromInput({
+                clientId,
+                input,
+                state: this.params.applyInput({
+                    clientId,
+                    input,
+                    state: this.currentState,
+                }),
+            });
+        }
+    }
+    /** Publish a new authoritative state that was not caused by a player input. */
+    updateState(state) {
+        this.currentState = state;
+        this.currentSequence++;
+        const detail = this.createStateEventDetail();
+        this.dispatchState(detail);
+        this.sendStateSnapshot(detail);
+    }
+    /** Publish a new authoritative state caused by a player input. */
+    updateStateFromInput({ clientId, input, state, }) {
+        this.currentState = state;
+        this.currentSequence++;
+        const detail = this.createStateEventDetail({
+            clientId,
+            input,
+        });
+        this.dispatchState(detail);
+        this.sendStateSnapshot(detail);
+    }
+    /** Dispatch the typed state event to local listeners. */
+    dispatchState(detail) {
+        this.dispatch(new ControllerStateEvent({
+            detail,
+        }));
+    }
+    /** Broadcast a state snapshot when the local client is the host. */
+    sendStateSnapshot(detail) {
+        if (this.roomConnection && this.isHost()) {
+            this.roomConnection.sendMessage(this.createStateSnapshotMessage(detail));
+        }
+    }
+    /** Create a network message from state event detail. */
+    createStateSnapshotMessage(detail) {
+        return {
+            ...detail,
+            type: P2pAuthoritativeHostMessageType.StateSnapshot,
+        };
+    }
+    /** Create the local state event detail for the current sequence and state. */
+    createStateEventDetail(source = {}) {
+        return {
+            ...source,
+            sequence: this.currentSequence,
+            state: this.currentState,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "@antha/multiplayer-p2p-authoritative-host",
+    "version": "0.0.1",
+    "description": "P2P authoritative-host multiplayer strategy 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/common": "^31.73.1",
+        "typed-event-target": "^4.3.1"
+    },
+    "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",
+        "istanbul-smart-text-reporter": "^1.1.5"
+    },
+    "peerDependencies": {
+        "@antha/multiplayer-core": "^0.0.1"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}