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

package/dist/multiclient-authority.d.ts

@@ -0,0 +1,30 @@
+export interface DeterministicMulticlientAuthorityFixtureResult {
+    readonly checksum: string;
+    readonly players: number;
+    readonly frames: number;
+    readonly predictedClientRunners: number;
+    readonly authoritySnapshotsDelivered: number;
+    readonly predictionMismatches: number;
+    readonly correctionsApplied: number;
+    readonly resimulatedFrames: number;
+    readonly convergedSnapshots: number;
+    readonly rollbackDepthP95: number;
+    readonly rollbackDepthMax: number;
+    readonly finalAuthorityProjection: number;
+    readonly finalClientProjectionChecksum: string;
+    readonly convergence: boolean;
+    readonly allClientsReachedFinalAuthorityFrame: boolean;
+    readonly runtimeBackedClients: number;
+    readonly runtimeBackedFrames: number;
+    readonly runtimeBackedAuthoritySnapshots: number;
+    readonly runtimeBackedPredictionMismatches: number;
+    readonly runtimeBackedCorrectionsApplied: number;
+    readonly runtimeBackedResimulatedFrames: number;
+    readonly runtimeBackedReplayVerifiedClients: number;
+    readonly runtimeBackedAuthorityChecksum: string;
+    readonly runtimeBackedClientChecksum: string;
+    readonly runtimeBackedConvergence: boolean;
+    readonly p95FrameCost: number;
+    readonly p99FrameCost: number;
+}
+export declare function runDeterministicMulticlientAuthorityFixture(players: number, frames: number, seed: number): DeterministicMulticlientAuthorityFixtureResult;

package/dist/multiclient-authority.js

@@ -0,0 +1,305 @@
+import { defaultChecksum } from './canonical.js';
+import { createDeterministicFrameRuntime, } from './engine-runtime.js';
+const projectionModulo = 2_147_483_647;
+export function runDeterministicMulticlientAuthorityFixture(players, frames, seed) {
+    const authorityHistory = new Array(frames + 1).fill(0);
+    const authorityDeltas = new Array(frames).fill(0);
+    const clientStates = new Array(players).fill(0);
+    const clientHistories = Array.from({ length: players }, () => new Array(frames + 1).fill(0));
+    const clientPredictedDeltas = Array.from({ length: players }, () => new Array(frames).fill(0));
+    const lastAuthorityFrameByClient = new Array(players).fill(0);
+    const rollbackDepths = [];
+    const frameCosts = [];
+    let authorityState = 0;
+    let authoritySnapshotsDelivered = 0;
+    let predictionMismatches = 0;
+    let correctionsApplied = 0;
+    let resimulatedFrames = 0;
+    let convergedSnapshots = 0;
+    for (let frame = 0; frame < frames; frame += 1) {
+        const authorityDelta = authorityFrameDelta(players, frame, seed);
+        authorityDeltas[frame] = authorityDelta;
+        authorityState = addProjection(authorityState, authorityDelta);
+        authorityHistory[frame + 1] = authorityState;
+        for (let slot = 0; slot < players; slot += 1) {
+            const predictedDelta = addProjection(authorityDelta, predictionError(slot, frame, seed));
+            clientPredictedDeltas[slot][frame] = predictedDelta;
+            clientStates[slot] = addProjection(clientStates[slot], predictedDelta);
+            clientHistories[slot][frame + 1] = clientStates[slot];
+        }
+        const currentFrameExclusive = frame + 1;
+        for (let slot = 0; slot < players; slot += 1) {
+            const confirmedFrame = currentFrameExclusive - snapshotDelay(slot, frame);
+            if (confirmedFrame > lastAuthorityFrameByClient[slot]) {
+                for (let frameToApply = lastAuthorityFrameByClient[slot] + 1; frameToApply <= confirmedFrame; frameToApply += 1) {
+                    const applied = applyClientAuthoritySnapshot({
+                        slot,
+                        confirmedFrame: frameToApply,
+                        currentFrameExclusive,
+                        authorityHistory,
+                        clientStates,
+                        clientHistories,
+                        clientPredictedDeltas,
+                    });
+                    authoritySnapshotsDelivered += 1;
+                    lastAuthorityFrameByClient[slot] = frameToApply;
+                    if (applied.rollbackDepth === 0) {
+                        convergedSnapshots += 1;
+                    }
+                    else {
+                        predictionMismatches += 1;
+                        correctionsApplied += 1;
+                        resimulatedFrames += applied.resimulatedFrames;
+                        rollbackDepths.push(applied.rollbackDepth);
+                    }
+                }
+            }
+        }
+        frameCosts.push((players + authoritySnapshotsDelivered + correctionsApplied) / 100_000);
+    }
+    for (let slot = 0; slot < players; slot += 1) {
+        for (let confirmedFrame = lastAuthorityFrameByClient[slot] + 1; confirmedFrame <= frames; confirmedFrame += 1) {
+            const applied = applyClientAuthoritySnapshot({
+                slot,
+                confirmedFrame,
+                currentFrameExclusive: frames,
+                authorityHistory,
+                clientStates,
+                clientHistories,
+                clientPredictedDeltas,
+            });
+            authoritySnapshotsDelivered += 1;
+            lastAuthorityFrameByClient[slot] = confirmedFrame;
+            if (applied.rollbackDepth === 0) {
+                convergedSnapshots += 1;
+            }
+            else {
+                predictionMismatches += 1;
+                correctionsApplied += 1;
+                resimulatedFrames += applied.resimulatedFrames;
+                rollbackDepths.push(applied.rollbackDepth);
+            }
+        }
+    }
+    const finalAuthorityProjection = authorityHistory[frames];
+    const finalClientProjectionChecksum = defaultChecksum(clientStates);
+    const convergence = clientStates.every((state) => state === finalAuthorityProjection);
+    const allClientsReachedFinalAuthorityFrame = lastAuthorityFrameByClient.every((frame) => frame === frames);
+    const runtimeBacked = runRuntimeBackedMulticlientAuthorityFixture(players, frames, seed);
+    const metrics = {
+        players,
+        frames,
+        predictedClientRunners: players,
+        authoritySnapshotsDelivered,
+        predictionMismatches,
+        correctionsApplied,
+        resimulatedFrames,
+        convergedSnapshots,
+        rollbackDepthP95: percentile(rollbackDepths, 95),
+        rollbackDepthMax: rollbackDepths.length === 0 ? 0 : Math.max(...rollbackDepths),
+        finalAuthorityProjection,
+        finalClientProjectionChecksum,
+        convergence,
+        allClientsReachedFinalAuthorityFrame,
+        runtimeBackedClients: runtimeBacked.clients,
+        runtimeBackedFrames: runtimeBacked.frames,
+        runtimeBackedAuthoritySnapshots: runtimeBacked.authoritySnapshots,
+        runtimeBackedPredictionMismatches: runtimeBacked.predictionMismatches,
+        runtimeBackedCorrectionsApplied: runtimeBacked.correctionsApplied,
+        runtimeBackedResimulatedFrames: runtimeBacked.resimulatedFrames,
+        runtimeBackedReplayVerifiedClients: runtimeBacked.replayVerifiedClients,
+        runtimeBackedAuthorityChecksum: runtimeBacked.authorityChecksum,
+        runtimeBackedClientChecksum: runtimeBacked.clientChecksum,
+        runtimeBackedConvergence: runtimeBacked.convergence,
+        p95FrameCost: percentile(frameCosts, 95),
+        p99FrameCost: percentile(frameCosts, 99),
+    };
+    return {
+        ...metrics,
+        checksum: defaultChecksum(metrics),
+    };
+}
+function runRuntimeBackedMulticlientAuthorityFixture(players, frames, seed) {
+    const descriptor = createRuntimeBackedAuthorityDescriptor();
+    const systems = createRuntimeBackedAuthoritySystems();
+    const authority = createDeterministicFrameRuntime(descriptor, seed);
+    const clients = Array.from({ length: players }, () => createDeterministicFrameRuntime(descriptor, seed));
+    initializeRuntimeBackedProjection(authority);
+    for (const client of clients) {
+        initializeRuntimeBackedProjection(client);
+    }
+    const lastAuthorityFrameByClient = new Array(players).fill(0);
+    const clientSnapshotHistory = clients.map((client) => [client.snapshot()]);
+    const clientPredictedDeltas = clients.map(() => new Array(frames).fill(0));
+    const authoritySnapshots = [authority.snapshot()];
+    let authoritySnapshotsDelivered = 0;
+    let predictionMismatches = 0;
+    let correctionsApplied = 0;
+    let resimulatedFrames = 0;
+    for (let frame = 0; frame < frames; frame += 1) {
+        const authorityDelta = authorityFrameDelta(players, frame, seed);
+        stepRuntimeBackedAuthority(authority, systems, authorityDelta);
+        authoritySnapshots[frame + 1] = authority.snapshot();
+        for (let slot = 0; slot < players; slot += 1) {
+            const predictedDelta = addProjection(authorityDelta, predictionError(slot, frame, seed));
+            clientPredictedDeltas[slot][frame] = predictedDelta;
+            stepRuntimeBackedAuthority(clients[slot], systems, predictedDelta);
+            clientSnapshotHistory[slot][frame + 1] = clients[slot].snapshot();
+        }
+        const currentFrameExclusive = frame + 1;
+        for (let slot = 0; slot < players; slot += 1) {
+            const confirmedFrame = currentFrameExclusive - snapshotDelay(slot, frame);
+            if (confirmedFrame > 0 && confirmedFrame % 16 === 0) {
+                const authoritySnapshot = authoritySnapshots[confirmedFrame];
+                authoritySnapshotsDelivered += 1;
+                lastAuthorityFrameByClient[slot] = confirmedFrame;
+                const applied = applyRuntimeBackedAuthoritySnapshot({
+                    client: clients[slot],
+                    systems,
+                    authoritySnapshot,
+                    confirmedFrame,
+                    currentFrameExclusive,
+                    clientSnapshotHistory: clientSnapshotHistory[slot],
+                    clientPredictedDeltas: clientPredictedDeltas[slot],
+                });
+                if (applied.mismatch) {
+                    predictionMismatches += 1;
+                    correctionsApplied += 1;
+                    resimulatedFrames += applied.resimulatedFrames;
+                }
+            }
+        }
+    }
+    for (let slot = 0; slot < players; slot += 1) {
+        for (let confirmedFrame = lastAuthorityFrameByClient[slot] + 1; confirmedFrame <= frames; confirmedFrame += 1) {
+            const authoritySnapshot = authoritySnapshots[confirmedFrame];
+            authoritySnapshotsDelivered += 1;
+            lastAuthorityFrameByClient[slot] = confirmedFrame;
+            const applied = applyRuntimeBackedAuthoritySnapshot({
+                client: clients[slot],
+                systems,
+                authoritySnapshot,
+                confirmedFrame,
+                currentFrameExclusive: frames,
+                clientSnapshotHistory: clientSnapshotHistory[slot],
+                clientPredictedDeltas: clientPredictedDeltas[slot],
+            });
+            if (applied.mismatch) {
+                predictionMismatches += 1;
+                correctionsApplied += 1;
+                resimulatedFrames += applied.resimulatedFrames;
+            }
+        }
+    }
+    const finalAuthoritySnapshot = authority.snapshot();
+    const clientChecksums = clients.map((client) => client.snapshot().checksum);
+    const replayVerifiedClients = clientChecksums.filter((checksum) => checksum === finalAuthoritySnapshot.checksum).length;
+    return {
+        clients: players,
+        frames,
+        authoritySnapshots: authoritySnapshotsDelivered,
+        predictionMismatches,
+        correctionsApplied,
+        resimulatedFrames,
+        replayVerifiedClients,
+        authorityChecksum: finalAuthoritySnapshot.checksum,
+        clientChecksum: defaultChecksum(clientChecksums),
+        convergence: replayVerifiedClients === players,
+    };
+}
+function applyRuntimeBackedAuthoritySnapshot(options) {
+    const clientSnapshot = options.clientSnapshotHistory[options.confirmedFrame];
+    if (clientSnapshot?.checksum === options.authoritySnapshot.checksum) {
+        return { mismatch: false, resimulatedFrames: 0 };
+    }
+    options.client.restore(options.authoritySnapshot);
+    options.clientSnapshotHistory[options.confirmedFrame] = options.client.snapshot();
+    let resimulatedFrames = 0;
+    for (let resimFrame = options.confirmedFrame; resimFrame < options.currentFrameExclusive; resimFrame += 1) {
+        stepRuntimeBackedAuthority(options.client, options.systems, options.clientPredictedDeltas[resimFrame]);
+        options.clientSnapshotHistory[resimFrame + 1] = options.client.snapshot();
+        resimulatedFrames += 1;
+    }
+    return { mismatch: true, resimulatedFrames };
+}
+function createRuntimeBackedAuthorityDescriptor() {
+    return {
+        id: 'runtime-backed-multiclient-authority',
+        tickRate: 60,
+        components: [
+            { id: 'projection', singleton: true, fields: [{ name: 'value', kind: 'int', defaultValue: 0 }] },
+            { id: 'frameInput', singleton: true, fields: [{ name: 'delta', kind: 'int', defaultValue: 0 }] },
+        ],
+        systems: [{ id: 'simulate', group: 'simulation', order: 0 }],
+    };
+}
+function createRuntimeBackedAuthoritySystems() {
+    return {
+        simulate(ctx) {
+            const projection = ctx.getSingleton('projection');
+            const input = ctx.getSingleton('frameInput');
+            ctx.setSingleton('projection', { value: addProjection(Number(projection.value), Number(input.delta)) });
+            ctx.setSingleton('frameInput', { delta: 0 });
+        },
+    };
+}
+function stepRuntimeBackedAuthority(runtime, systems, delta) {
+    runtime.setSingleton('frameInput', { delta });
+    runtime.step(systems);
+}
+function initializeRuntimeBackedProjection(runtime) {
+    runtime.setSingleton('projection', { value: 0 });
+    runtime.setSingleton('frameInput', { delta: 0 });
+}
+function applyClientAuthoritySnapshot(options) {
+    const expected = options.authorityHistory[options.confirmedFrame];
+    const history = options.clientHistories[options.slot];
+    if (history[options.confirmedFrame] === expected) {
+        return { rollbackDepth: 0, resimulatedFrames: 0 };
+    }
+    let state = expected;
+    history[options.confirmedFrame] = state;
+    let resimulatedFrames = 0;
+    for (let frame = options.confirmedFrame; frame < options.currentFrameExclusive; frame += 1) {
+        state = addProjection(state, options.clientPredictedDeltas[options.slot][frame]);
+        history[frame + 1] = state;
+        resimulatedFrames += 1;
+    }
+    options.clientStates[options.slot] = state;
+    return {
+        rollbackDepth: options.currentFrameExclusive - options.confirmedFrame,
+        resimulatedFrames,
+    };
+}
+function authorityFrameDelta(players, frame, seed) {
+    let delta = 0;
+    for (let slot = 0; slot < players; slot += 1) {
+        const value = ((seed + frame * 17 + slot * 13) % 19) - 9;
+        delta = addProjection(delta, value * (slot + 1));
+    }
+    return delta;
+}
+function predictionError(slot, frame, seed) {
+    if ((seed + slot * 3 + frame * 5) % 11 === 0) {
+        return slot + 1;
+    }
+    if ((seed + slot + frame * 7) % 17 === 0) {
+        return -slot - 1;
+    }
+    return 0;
+}
+function snapshotDelay(slot, frame) {
+    return 2 + ((slot + frame) % 5);
+}
+function addProjection(left, right) {
+    const sum = (left + right) % projectionModulo;
+    return sum < 0 ? sum + projectionModulo : sum;
+}
+function percentile(values, percentileValue) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((left, right) => left - right);
+    const index = Math.min(sorted.length - 1, Math.floor((percentileValue / 100) * sorted.length));
+    return sorted[index];
+}

package/dist/multiplayer-service.d.ts

@@ -0,0 +1,153 @@
+import { type CanonicalValue } from './canonical.js';
+import { type DeterministicCommandChannelDescriptor, type DeterministicCommandTimelineSnapshot, type DeterministicPlayerCommand, type DeterministicRejectedCommand } from './commands.js';
+import { type DeterministicLocalAuthorityRuntimeOptions, type DeterministicLocalAuthorityRuntimeSnapshot, type DeterministicLocalAuthorityState } from './local-authority.js';
+import { deterministicLocalAuthorityWireProtocol } from './local-authority-wire.js';
+export interface DeterministicAuthorityServerOptions extends DeterministicLocalAuthorityRuntimeOptions {
+    readonly players: number;
+    readonly commandChannels?: readonly DeterministicCommandChannelDescriptor[];
+    readonly validCommandAssetRefs?: readonly string[];
+    readonly validateCommandPayload?: (command: DeterministicPlayerCommand) => boolean;
+}
+export interface DeterministicAuthorityClientOptions {
+    readonly slot: number;
+    readonly spectator?: boolean;
+    readonly bot?: boolean;
+    readonly lateJoin?: boolean;
+}
+export interface SyncplayInput {
+    readonly frame: number;
+    readonly value: number;
+    readonly data?: CanonicalValue;
+    readonly delay?: number;
+    readonly inputId?: string;
+}
+export interface SyncplaySubmitResult {
+    readonly accepted: boolean;
+    readonly slot: number;
+    readonly frame: number;
+}
+export type SyncplayClientRole = 'player' | 'spectator' | 'bot';
+export interface SyncplayLifecycleResult {
+    readonly slot: number;
+    readonly frame: number;
+}
+export interface SyncplayCommand {
+    readonly id: string;
+    readonly frame: number;
+    readonly channelId: string;
+    readonly payload: CanonicalValue;
+    readonly predicted?: boolean;
+    readonly slot?: number;
+}
+export interface SyncplayCommandSubmitResult {
+    readonly accepted: boolean;
+    readonly slot: number;
+    readonly frame: number;
+    readonly commandId: string;
+    readonly rejectionReason?: DeterministicRejectedCommand['reason'];
+}
+export interface SyncplayCommandPollOptions {
+    readonly slot?: number;
+    readonly channelId?: string;
+}
+export interface DeterministicAuthorityChecksums {
+    readonly authorityChecksum: string;
+    readonly clientChecksum: string;
+    readonly authorityProjectionChecksum: string;
+    readonly clientProjectionChecksum: string;
+    readonly convergence: boolean;
+    readonly commandChecksum: string;
+    readonly commandTimelineChecksum?: string;
+}
+export interface DeterministicAuthorityRecordedInput {
+    readonly accepted: boolean;
+    readonly slot: number;
+    readonly senderSlot?: number;
+    readonly frame: number;
+    readonly value: number;
+    readonly data?: CanonicalValue;
+    readonly delay?: number;
+    readonly inputId?: string;
+}
+export interface DeterministicAuthorityLifecycleEvent {
+    readonly kind: 'lateJoin' | 'spectator' | 'disconnect' | 'reconnect';
+    readonly slot: number;
+    readonly frame: number;
+}
+export interface DeterministicAuthorityReplayEvidence {
+    readonly mismatches: number;
+    readonly replayedAuthorityChecksum: string;
+    readonly replayedProjectionChecksum: string;
+}
+export interface DeterministicAuthorityCertificationArtifact {
+    readonly schemaVersion: 1;
+    readonly result: 'pass' | 'fail';
+    readonly protocol: typeof deterministicLocalAuthorityWireProtocol;
+    readonly players: number;
+    readonly frame: number;
+    readonly replayMismatches: number;
+    readonly botSlots: readonly number[];
+    readonly lateJoinSlots: readonly number[];
+    readonly spectatorSlots: readonly number[];
+    readonly inputHistory: readonly DeterministicAuthorityRecordedInput[];
+    readonly lifecycleEvents: readonly DeterministicAuthorityLifecycleEvent[];
+    readonly replay: DeterministicAuthorityReplayEvidence;
+    readonly snapshotChecksum: string;
+    readonly commandSnapshotChecksum?: string;
+    readonly checksums: DeterministicAuthorityChecksums;
+    readonly snapshot: DeterministicLocalAuthorityRuntimeSnapshot;
+    readonly commandSnapshot?: DeterministicCommandTimelineSnapshot;
+}
+export interface DeterministicAuthorityCertificationVerification {
+    readonly result: 'pass' | 'fail';
+    readonly diagnostics: readonly string[];
+    readonly replayMismatches: number;
+    readonly convergence: boolean;
+}
+export interface SyncplayClientConnection {
+    readonly slot: number;
+    readonly role: SyncplayClientRole;
+    submitInput(input: SyncplayInput): SyncplaySubmitResult;
+    submitCommand(command: SyncplayCommand): SyncplayCommandSubmitResult;
+    pollCommands(frame: number, options?: SyncplayCommandPollOptions): readonly DeterministicPlayerCommand[];
+    commandSnapshot(): DeterministicCommandTimelineSnapshot;
+    lateJoin(): SyncplayLifecycleResult;
+    disconnect(): void;
+    reconnect(): void;
+    snapshot(): DeterministicLocalAuthorityRuntimeSnapshot;
+    checksums(): DeterministicAuthorityChecksums;
+    exportCertificationArtifact(): DeterministicAuthorityCertificationArtifact;
+}
+export interface SyncplayClient {
+    readonly slot: number;
+    readonly role: SyncplayClientRole;
+    submitInput(input: SyncplayInput): SyncplaySubmitResult;
+    submitCommand(command: SyncplayCommand): SyncplayCommandSubmitResult;
+    pollCommands(frame: number, options?: SyncplayCommandPollOptions): readonly DeterministicPlayerCommand[];
+    commandSnapshot(): DeterministicCommandTimelineSnapshot;
+    lateJoin(): SyncplayLifecycleResult;
+    disconnect(): void;
+    reconnect(): void;
+    snapshot(): DeterministicLocalAuthorityRuntimeSnapshot;
+    checksums(): DeterministicAuthorityChecksums;
+    exportCertificationArtifact(): DeterministicAuthorityCertificationArtifact;
+}
+export interface DeterministicAuthorityServer {
+    readonly protocol: typeof deterministicLocalAuthorityWireProtocol;
+    readonly players: number;
+    readonly botSlots: readonly number[];
+    readonly state: DeterministicLocalAuthorityState;
+    connectClient(options: DeterministicAuthorityClientOptions): SyncplayClientConnection;
+    stepFrames(count: number): void;
+    pollCommands(frame: number, options?: SyncplayCommandPollOptions): readonly DeterministicPlayerCommand[];
+    commandSnapshot(): DeterministicCommandTimelineSnapshot;
+    snapshot(): DeterministicLocalAuthorityRuntimeSnapshot;
+    checksums(): DeterministicAuthorityChecksums;
+    exportCertificationArtifact(): DeterministicAuthorityCertificationArtifact;
+    close(): void;
+}
+export declare function createDeterministicAuthorityServer(options: DeterministicAuthorityServerOptions): DeterministicAuthorityServer;
+export declare function createSyncplayClient(options: {
+    readonly connection: SyncplayClientConnection;
+}): SyncplayClient;
+export declare function verifyDeterministicAuthorityCertificationArtifact(artifact: DeterministicAuthorityCertificationArtifact): DeterministicAuthorityCertificationVerification;