@series-inc/rundot-syncplay 5.23.0-beta.7

package/dist/multiplayer-service.js

@@ -0,0 +1,429 @@
+import { defaultChecksum } from './canonical.js';
+import { createDeterministicCommandTimeline, createDeterministicCommandTimelineSnapshot, } from './commands.js';
+import { createDeterministicLocalAuthorityRuntime, } from './local-authority.js';
+import { deterministicLocalAuthorityWireProtocol } from './local-authority-wire.js';
+export function createDeterministicAuthorityServer(options) {
+    if (!Number.isInteger(options.players) || options.players < 1) {
+        throw new Error('Deterministic authority server players must be a positive integer');
+    }
+    const runtime = createDeterministicLocalAuthorityRuntime(options.players, options);
+    const commandTimeline = createAuthorityCommandTimeline(options);
+    const botSlots = new Set();
+    const connectedSlots = new Set();
+    const inputHistory = [];
+    const lifecycleEvents = [];
+    let closed = false;
+    const server = {
+        protocol: deterministicLocalAuthorityWireProtocol,
+        players: options.players,
+        get botSlots() {
+            assertOpen();
+            return [...botSlots].sort(compareNumbers);
+        },
+        get state() {
+            assertOpen();
+            return runtime.state;
+        },
+        connectClient(clientOptions) {
+            assertOpen();
+            assertClientSlot(options.players, clientOptions.slot);
+            if (clientOptions.spectator === true && clientOptions.bot === true) {
+                throw new Error('Deterministic multiplayer client cannot be both a spectator and a bot');
+            }
+            const existingClient = runtime.state.clients[clientOptions.slot];
+            if (clientOptions.spectator === true && botSlots.has(clientOptions.slot)) {
+                throw new Error(`Deterministic multiplayer slot ${clientOptions.slot} is already registered as a bot`);
+            }
+            if (clientOptions.bot === true && existingClient?.spectator === true) {
+                throw new Error(`Deterministic multiplayer slot ${clientOptions.slot} is already registered as a spectator`);
+            }
+            if (connectedSlots.has(clientOptions.slot)) {
+                throw new Error(`Deterministic multiplayer slot ${clientOptions.slot} is already connected`);
+            }
+            if (clientOptions.lateJoin === true) {
+                runtime.lateJoin(clientOptions.slot);
+                lifecycleEvents.push({ kind: 'lateJoin', slot: clientOptions.slot, frame: runtime.state.frame });
+            }
+            if (clientOptions.spectator === true) {
+                runtime.addSpectator(clientOptions.slot);
+                lifecycleEvents.push({ kind: 'spectator', slot: clientOptions.slot, frame: runtime.state.frame });
+            }
+            if (clientOptions.bot === true) {
+                botSlots.add(clientOptions.slot);
+            }
+            connectedSlots.add(clientOptions.slot);
+            return createLocalClientConnection(runtime, commandTimeline, () => server.botSlots, () => inputHistory, () => lifecycleEvents, (input) => inputHistory.push(input), (event) => lifecycleEvents.push(event), clientOptions.slot, clientRole(clientOptions), assertOpen);
+        },
+        stepFrames(count) {
+            assertOpen();
+            if (!Number.isInteger(count) || count < 0) {
+                throw new Error('Deterministic authority server step count must be a non-negative integer');
+            }
+            for (let frame = 0; frame < count; frame += 1) {
+                runtime.step();
+                commandTimeline?.setCurrentFrame(runtime.state.frame);
+            }
+        },
+        pollCommands(frame, pollOptions = {}) {
+            assertOpen();
+            return requireCommandTimeline(commandTimeline).poll(frame, pollOptions.slot, pollOptions.channelId);
+        },
+        commandSnapshot() {
+            assertOpen();
+            return requireCommandTimeline(commandTimeline).snapshot();
+        },
+        snapshot() {
+            assertOpen();
+            return runtime.snapshot();
+        },
+        checksums() {
+            assertOpen();
+            return createAuthorityChecksums(runtime, commandTimeline);
+        },
+        exportCertificationArtifact() {
+            assertOpen();
+            return createCertificationArtifact(runtime, commandTimeline, server.botSlots, inputHistory, lifecycleEvents);
+        },
+        close() {
+            closed = true;
+        },
+    };
+    function assertOpen() {
+        if (closed) {
+            throw new Error('Deterministic authority server is closed');
+        }
+    }
+    return server;
+}
+export function createSyncplayClient(options) {
+    const connection = options.connection;
+    return {
+        slot: connection.slot,
+        role: connection.role,
+        submitInput(input) {
+            return connection.submitInput(input);
+        },
+        submitCommand(command) {
+            return connection.submitCommand(command);
+        },
+        pollCommands(frame, commandOptions = {}) {
+            return connection.pollCommands(frame, commandOptions);
+        },
+        commandSnapshot() {
+            return connection.commandSnapshot();
+        },
+        lateJoin() {
+            return connection.lateJoin();
+        },
+        disconnect() {
+            connection.disconnect();
+        },
+        reconnect() {
+            connection.reconnect();
+        },
+        snapshot() {
+            return connection.snapshot();
+        },
+        checksums() {
+            return connection.checksums();
+        },
+        exportCertificationArtifact() {
+            return connection.exportCertificationArtifact();
+        },
+    };
+}
+export function verifyDeterministicAuthorityCertificationArtifact(artifact) {
+    const diagnostics = [];
+    if (artifact.schemaVersion !== 1) {
+        diagnostics.push('schema-version-mismatch');
+    }
+    if (artifact.protocol !== deterministicLocalAuthorityWireProtocol) {
+        diagnostics.push('protocol-mismatch');
+    }
+    if (artifact.players !== artifact.snapshot.state.players) {
+        diagnostics.push('players-mismatch');
+    }
+    if (artifact.frame !== artifact.snapshot.state.frame) {
+        diagnostics.push('frame-mismatch');
+    }
+    if (artifact.snapshotChecksum !== defaultChecksum(artifact.snapshot)) {
+        diagnostics.push('snapshot-checksum-mismatch');
+    }
+    if (artifact.checksums.authorityChecksum !== defaultChecksum(artifact.snapshot.state)) {
+        diagnostics.push('authority-checksum-mismatch');
+    }
+    if (artifact.checksums.clientChecksum !== defaultChecksum(artifact.snapshot.clientStateBySlot)) {
+        diagnostics.push('client-checksum-mismatch');
+    }
+    if (artifact.checksums.authorityProjectionChecksum !== defaultChecksum(artifact.snapshot.state.stateBySlot)) {
+        diagnostics.push('authority-projection-checksum-mismatch');
+    }
+    if (artifact.checksums.clientProjectionChecksum !== defaultChecksum(artifact.snapshot.clientStateBySlot)) {
+        diagnostics.push('client-projection-checksum-mismatch');
+    }
+    if (artifact.checksums.commandChecksum !== artifact.snapshot.commandChecksum) {
+        diagnostics.push('command-checksum-mismatch');
+    }
+    if (artifact.checksums.convergence !== (artifact.checksums.authorityProjectionChecksum === artifact.checksums.clientProjectionChecksum)) {
+        diagnostics.push('convergence-mismatch');
+    }
+    if (!sameNumberList(artifact.botSlots, [...artifact.botSlots].sort(compareNumbers))) {
+        diagnostics.push('bot-slots-order-mismatch');
+    }
+    if (!sameNumberList(artifact.lateJoinSlots, artifact.snapshot.lateJoinSlots)) {
+        diagnostics.push('late-join-slots-mismatch');
+    }
+    if (!sameNumberList(artifact.spectatorSlots, artifact.snapshot.spectatorSlots)) {
+        diagnostics.push('spectator-slots-mismatch');
+    }
+    const replay = replayAuthorityCertificationHistory(artifact.players, artifact.frame, artifact.inputHistory, artifact.lifecycleEvents);
+    if (artifact.replay.mismatches !== replay.mismatches) {
+        diagnostics.push('replay-mismatches-mismatch');
+    }
+    if (artifact.replay.replayedAuthorityChecksum !== replay.replayedAuthorityChecksum) {
+        diagnostics.push('replay-authority-evidence-mismatch');
+    }
+    if (artifact.replay.replayedProjectionChecksum !== replay.replayedProjectionChecksum) {
+        diagnostics.push('replay-projection-evidence-mismatch');
+    }
+    if (replay.replayedAuthorityChecksum !== artifact.checksums.authorityChecksum) {
+        diagnostics.push('replay-authority-checksum-mismatch');
+    }
+    if (replay.replayedProjectionChecksum !== artifact.checksums.authorityProjectionChecksum) {
+        diagnostics.push('replay-projection-checksum-mismatch');
+    }
+    if (artifact.commandSnapshot === undefined) {
+        if (artifact.commandSnapshotChecksum !== undefined || artifact.checksums.commandTimelineChecksum !== undefined) {
+            diagnostics.push('command-snapshot-mismatch');
+        }
+    }
+    else {
+        const recomputedCommandSnapshot = createDeterministicCommandTimelineSnapshot({
+            currentFrame: artifact.commandSnapshot.currentFrame,
+            accepted: artifact.commandSnapshot.accepted,
+            rejected: artifact.commandSnapshot.rejected,
+        });
+        if (artifact.commandSnapshotChecksum !== recomputedCommandSnapshot.checksum) {
+            diagnostics.push('command-snapshot-checksum-mismatch');
+        }
+        if (artifact.checksums.commandTimelineChecksum !== defaultChecksum({
+            accepted: recomputedCommandSnapshot.accepted,
+            rejected: recomputedCommandSnapshot.rejected,
+        })) {
+            diagnostics.push('command-timeline-checksum-mismatch');
+        }
+    }
+    const replayMismatches = replay.mismatches;
+    return {
+        result: diagnostics.length === 0 ? 'pass' : 'fail',
+        diagnostics,
+        replayMismatches,
+        convergence: artifact.checksums.convergence,
+    };
+}
+function createLocalClientConnection(runtime, commandTimeline, getBotSlots, getInputHistory, getLifecycleEvents, recordInput, recordLifecycle, slot, role, assertOpen) {
+    return {
+        slot,
+        role,
+        submitInput(input) {
+            assertOpen();
+            const inputMessage = {
+                slot,
+                senderSlot: slot,
+                frame: input.frame,
+                value: input.value,
+                data: input.data,
+                delay: input.delay,
+                inputId: input.inputId,
+            };
+            const accepted = runtime.submitInput(inputMessage);
+            recordInput({ accepted, ...inputMessage });
+            return { accepted, slot, frame: input.frame };
+        },
+        submitCommand(command) {
+            assertOpen();
+            const timeline = requireCommandTimeline(commandTimeline);
+            const normalizedCommand = {
+                id: command.id,
+                slot: command.slot ?? slot,
+                frame: command.frame,
+                channelId: command.channelId,
+                payload: command.payload,
+                ...(command.predicted === undefined ? {} : { predicted: command.predicted }),
+            };
+            const rejection = role === 'spectator'
+                ? timeline.recordFromSlot(-1, normalizedCommand)
+                : timeline.recordFromSlot(slot, normalizedCommand);
+            return {
+                accepted: rejection === undefined,
+                slot,
+                frame: command.frame,
+                commandId: command.id,
+                ...(rejection === undefined ? {} : { rejectionReason: rejection.reason }),
+            };
+        },
+        pollCommands(frame, options = {}) {
+            assertOpen();
+            return requireCommandTimeline(commandTimeline).poll(frame, options.slot, options.channelId);
+        },
+        commandSnapshot() {
+            assertOpen();
+            return requireCommandTimeline(commandTimeline).snapshot();
+        },
+        lateJoin() {
+            assertOpen();
+            runtime.lateJoin(slot);
+            recordLifecycle({ kind: 'lateJoin', slot, frame: runtime.state.frame });
+            return { slot, frame: runtime.state.frame };
+        },
+        disconnect() {
+            assertOpen();
+            runtime.disconnect(slot);
+            recordLifecycle({ kind: 'disconnect', slot, frame: runtime.state.frame });
+        },
+        reconnect() {
+            assertOpen();
+            runtime.reconnect(slot);
+            recordLifecycle({ kind: 'reconnect', slot, frame: runtime.state.frame });
+        },
+        snapshot() {
+            assertOpen();
+            return runtime.snapshot();
+        },
+        checksums() {
+            assertOpen();
+            return createAuthorityChecksums(runtime, commandTimeline);
+        },
+        exportCertificationArtifact() {
+            assertOpen();
+            return createCertificationArtifact(runtime, commandTimeline, getBotSlots(), getInputHistory(), getLifecycleEvents());
+        },
+    };
+}
+function createCertificationArtifact(runtime, commandTimeline, botSlots, inputHistory, lifecycleEvents) {
+    const snapshot = runtime.snapshot();
+    const checksums = createAuthorityChecksums(runtime, commandTimeline);
+    const commandSnapshot = commandTimeline?.snapshot();
+    const replay = replayAuthorityCertificationHistory(snapshot.state.players, snapshot.state.frame, inputHistory, lifecycleEvents);
+    const artifact = {
+        schemaVersion: 1,
+        result: checksums.convergence ? 'pass' : 'fail',
+        protocol: deterministicLocalAuthorityWireProtocol,
+        players: snapshot.state.players,
+        frame: snapshot.state.frame,
+        replayMismatches: checksums.convergence ? 0 : 1,
+        botSlots: [...botSlots].sort(compareNumbers),
+        lateJoinSlots: snapshot.lateJoinSlots,
+        spectatorSlots: snapshot.spectatorSlots,
+        inputHistory: inputHistory.map((input) => ({ ...input })),
+        lifecycleEvents: lifecycleEvents.map((event) => ({ ...event })),
+        replay,
+        snapshotChecksum: defaultChecksum(snapshot),
+        checksums,
+        snapshot,
+        ...(commandSnapshot === undefined ? {} : {
+            commandSnapshotChecksum: commandSnapshot.checksum,
+            commandSnapshot,
+        }),
+    };
+    const verification = verifyDeterministicAuthorityCertificationArtifact(artifact);
+    return {
+        ...artifact,
+        result: verification.result,
+        replayMismatches: verification.replayMismatches,
+    };
+}
+function createAuthorityCommandTimeline(options) {
+    if (options.commandChannels === undefined) {
+        return undefined;
+    }
+    return createDeterministicCommandTimeline({
+        playerCount: options.players,
+        currentFrame: 0,
+        channels: options.commandChannels,
+        validAssetRefs: options.validCommandAssetRefs,
+        validatePayload: options.validateCommandPayload,
+    });
+}
+function requireCommandTimeline(commandTimeline) {
+    if (commandTimeline === undefined) {
+        throw new Error('Deterministic authority server command timeline is not configured');
+    }
+    return commandTimeline;
+}
+function createAuthorityChecksums(runtime, commandTimeline) {
+    const checksums = runtime.checksums();
+    return {
+        ...checksums,
+        ...(commandTimeline === undefined ? {} : { commandTimelineChecksum: commandTimeline.checksum() }),
+    };
+}
+function replayAuthorityCertificationHistory(players, targetFrame, inputHistory, lifecycleEvents) {
+    const replayRuntime = createDeterministicLocalAuthorityRuntime(players);
+    const orderedEvents = [
+        ...lifecycleEvents.map((event, index) => ({ kind: 'lifecycle', frame: event.frame, index, event })),
+        ...inputHistory.map((input, index) => ({ kind: 'input', frame: input.frame, index, input })),
+    ].sort(compareReplayEvents);
+    let mismatches = 0;
+    for (const entry of orderedEvents) {
+        while (replayRuntime.state.frame < entry.frame) {
+            replayRuntime.step();
+        }
+        if (entry.kind === 'lifecycle') {
+            applyReplayLifecycleEvent(replayRuntime, entry.event);
+        }
+        else if (replayRuntime.submitInput(entry.input) !== entry.input.accepted) {
+            mismatches += 1;
+        }
+    }
+    while (replayRuntime.state.frame < targetFrame) {
+        replayRuntime.step();
+    }
+    const checksums = replayRuntime.checksums();
+    return {
+        mismatches,
+        replayedAuthorityChecksum: checksums.authorityChecksum,
+        replayedProjectionChecksum: checksums.authorityProjectionChecksum,
+    };
+}
+function applyReplayLifecycleEvent(replayRuntime, event) {
+    if (event.kind === 'lateJoin') {
+        replayRuntime.lateJoin(event.slot);
+        return;
+    }
+    if (event.kind === 'spectator') {
+        replayRuntime.addSpectator(event.slot);
+        return;
+    }
+    if (event.kind === 'disconnect') {
+        replayRuntime.disconnect(event.slot);
+        return;
+    }
+    replayRuntime.reconnect(event.slot);
+}
+function clientRole(options) {
+    if (options.spectator === true) {
+        return 'spectator';
+    }
+    if (options.bot === true) {
+        return 'bot';
+    }
+    return 'player';
+}
+function compareNumbers(left, right) {
+    return left - right;
+}
+function compareReplayEvents(left, right) {
+    return left.frame - right.frame || replayEventKindOrder(left.kind) - replayEventKindOrder(right.kind) || left.index - right.index;
+}
+function replayEventKindOrder(kind) {
+    return kind === 'lifecycle' ? 0 : 1;
+}
+function sameNumberList(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function assertClientSlot(players, slot) {
+    if (!Number.isInteger(slot) || slot < 0 || slot >= players) {
+        throw new Error(`Invalid deterministic multiplayer client slot ${slot}`);
+    }
+}

package/dist/navigation.d.ts

@@ -0,0 +1,91 @@
+export interface DeterministicNavNode {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly cost?: number;
+    readonly region?: string;
+}
+export interface DeterministicNavEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly cost?: number;
+    readonly offMesh?: boolean;
+    readonly bidirectional?: boolean;
+}
+export interface DeterministicNavRegion {
+    readonly id: string;
+    readonly enabled: boolean;
+}
+export interface DeterministicNavigationGraphSource {
+    readonly id: string;
+    readonly nodes: readonly DeterministicNavNode[];
+    readonly edges: readonly DeterministicNavEdge[];
+    readonly regions?: readonly DeterministicNavRegion[];
+}
+export interface CookedDeterministicNavigationGraph {
+    readonly id: string;
+    readonly nodes: readonly DeterministicNavNode[];
+    readonly edges: readonly DeterministicNavEdge[];
+    readonly regions: readonly DeterministicNavRegion[];
+    readonly bytes: string;
+    readonly hash: string;
+}
+export interface DeterministicPathQuery {
+    readonly start: string;
+    readonly goal: string;
+    readonly disabledRegionIds?: readonly string[];
+    readonly blockedNodeIds?: readonly string[];
+}
+export interface DeterministicPathResult {
+    readonly found: boolean;
+    readonly nodes: readonly string[];
+    readonly cost: number;
+    readonly visitedNodeCount: number;
+    readonly offMeshTraversals: number;
+    readonly pathHash: string;
+}
+export interface DeterministicFlowField {
+    readonly goal: string;
+    readonly nextByNodeId: Readonly<Record<string, string>>;
+    readonly hash: string;
+}
+export interface DeterministicTilemapSource {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+    readonly blocked?: readonly string[];
+    readonly costs?: Readonly<Record<string, number>>;
+    readonly portals?: Readonly<Record<string, string>>;
+}
+export interface DeterministicNavigationAgent {
+    readonly id: string;
+    readonly nodeId: string;
+    readonly targetNodeId: string;
+    readonly path?: readonly string[];
+    readonly pathIndex?: number;
+}
+export interface DeterministicNavigationStepOptions {
+    readonly frame: number;
+    readonly disabledRegionIds?: readonly string[];
+    readonly blockedNodeIds?: readonly string[];
+}
+export interface DeterministicNavigationStepResult {
+    readonly agents: readonly DeterministicNavigationAgent[];
+    readonly replans: number;
+    readonly avoidanceCorrections: number;
+    readonly offMeshTraversals: number;
+    readonly visitedNodeCount: number;
+    readonly reciprocalAvoidanceCorrections: number;
+    readonly agentChecksum: string;
+}
+export declare function cookDeterministicNavigationGraph(source: DeterministicNavigationGraphSource): CookedDeterministicNavigationGraph;
+export declare function findDeterministicPath(graph: CookedDeterministicNavigationGraph, query: DeterministicPathQuery): DeterministicPathResult;
+export declare function createDeterministicFlowField(graph: CookedDeterministicNavigationGraph, goal: string, options?: Omit<DeterministicPathQuery, 'start' | 'goal'>): DeterministicFlowField;
+export declare function smoothDeterministicPath(graph: CookedDeterministicNavigationGraph, path: readonly string[]): readonly string[];
+export declare function applyDeterministicReciprocalAvoidance(agents: readonly DeterministicNavigationAgent[]): {
+    readonly agents: readonly DeterministicNavigationAgent[];
+    readonly corrections: number;
+    readonly hash: string;
+};
+export declare function cookTilemapNavigationGraph(source: DeterministicTilemapSource): CookedDeterministicNavigationGraph;
+export declare function stepDeterministicNavigationAgents(graph: CookedDeterministicNavigationGraph, agents: readonly DeterministicNavigationAgent[], options: DeterministicNavigationStepOptions): DeterministicNavigationStepResult;