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

package/dist/offline-session.js

@@ -0,0 +1,367 @@
+import { canonicalize, cloneCanonical, decodeCanonicalBytes, defaultChecksum, encodeCanonicalBytes, } from './canonical.js';
+import { SyncplayError, invariant } from './errors.js';
+import { createDeterministicMath } from './math.js';
+import { DeterministicRandom } from './random.js';
+import { withRuntimeDeterminismGuards } from './runtime-guards.js';
+export function createOfflineSession(config) {
+    validateConfig(config);
+    const checksumInterval = config.checksumIntervalFrames ?? 1;
+    const snapshotBufferSize = config.snapshotBufferSize ?? 256;
+    const replayRecordingMode = config.replayRecordingMode ?? 'memory';
+    const randomSeed = config.randomSeed ?? 1;
+    const fixedFrameMs = 1000 / config.tickRate;
+    const math = createDeterministicMath();
+    const initialState = cloneCanonical(config.initialState);
+    const mutable = {
+        frame: 0,
+        accumulatedMs: 0,
+        state: cloneCanonical(initialState),
+        inputs: Array.from({ length: config.playerCount }, () => cloneInput(config, config.defaultInput)),
+        inputFlags: Array.from({ length: config.playerCount }, (_, slot) => defaultInputFlags(slot)),
+        random: new DeterministicRandom(randomSeed),
+        inputFrames: [],
+        commandFrames: [],
+        pendingCommandFrames: new Map(),
+        checksums: [],
+        snapshots: new Map(),
+        snapshotOrder: [],
+    };
+    let hydratedFromExternalSnapshot = false;
+    const session = {
+        get currentFrame() {
+            return mutable.frame;
+        },
+        schemaIdentity: {
+            inputSchemaId: config.inputSchemaId,
+            stateSchemaId: config.stateSchemaId,
+            deterministicVersion: config.deterministicVersion,
+        },
+        get accumulatedMs() {
+            return mutable.accumulatedMs;
+        },
+        setInput(slot, input) {
+            if (!Number.isInteger(slot) || slot < 0 || slot >= config.playerCount) {
+                throw new SyncplayError(`Input slot ${slot} is outside playerCount ${config.playerCount}`, {
+                    code: 'session.invalid-slot',
+                    frame: mutable.frame,
+                    slot,
+                });
+            }
+            mutable.inputs[slot] = cloneInput(config, input);
+            mutable.inputFlags[slot] = { ...mutable.inputFlags[slot], playerPresent: true, repeatedPrevious: false };
+        },
+        setInputFlags(slot, flags) {
+            if (!Number.isInteger(slot) || slot < 0 || slot >= config.playerCount) {
+                throw new SyncplayError(`Input flag slot ${slot} is outside playerCount ${config.playerCount}`, {
+                    code: 'session.invalid-slot',
+                    frame: mutable.frame,
+                    slot,
+                });
+            }
+            mutable.inputFlags[slot] = normalizeInputFlags(slot, { ...mutable.inputFlags[slot], ...flags });
+        },
+        recordCommands(commands) {
+            if (commands.length === 0) {
+                return;
+            }
+            const frameCommands = mutable.pendingCommandFrames.get(mutable.frame) ?? [];
+            for (const command of commands) {
+                frameCommands.push(canonicalize(config.canonicalizeCommand?.(command) ?? command));
+            }
+            mutable.pendingCommandFrames.set(mutable.frame, frameCommands);
+        },
+        update(deltaMs) {
+            if (!Number.isFinite(deltaMs) || deltaMs < 0) {
+                throw new SyncplayError('deltaMs must be a finite non-negative number', {
+                    code: 'session.invalid-delta',
+                    frame: mutable.frame,
+                });
+            }
+            const nextAccumulatedMs = mutable.accumulatedMs + deltaMs;
+            // The 1e-9 epsilon rescues products floating just under an integer, but
+            // can leave accumulatedMs a hair negative after the subtraction below —
+            // a subsequent near-zero delta would then floor to -1, skip a frame's
+            // worth of accumulator with no step, and break the >= 0 contract.
+            const framesToStep = Math.max(0, Math.floor((nextAccumulatedMs * config.tickRate + 1e-9) / 1000));
+            const maxCatchUpFrames = config.maxCatchUpFrames ?? 240;
+            if (framesToStep > maxCatchUpFrames) {
+                throw new SyncplayError(`deltaMs would require ${framesToStep} catch-up frames, above max ${maxCatchUpFrames}`, { code: 'session.catch-up-limit', frame: mutable.frame });
+            }
+            if (framesToStep === 0) {
+                mutable.accumulatedMs = nextAccumulatedMs;
+                return 0;
+            }
+            mutable.accumulatedMs = nextAccumulatedMs;
+            runFrames(config, mutable, checksumInterval, snapshotBufferSize, replayRecordingMode, math, framesToStep);
+            mutable.accumulatedMs = Math.max(0, mutable.accumulatedMs - framesToStep * fixedFrameMs);
+            return framesToStep;
+        },
+        stepFrames(count) {
+            if (!Number.isInteger(count) || count < 0) {
+                throw new SyncplayError('stepFrames count must be a non-negative integer', {
+                    code: 'session.invalid-frame-count',
+                    frame: mutable.frame,
+                });
+            }
+            runFrames(config, mutable, checksumInterval, snapshotBufferSize, replayRecordingMode, math, count);
+        },
+        getState() {
+            return cloneCanonical(mutable.state);
+        },
+        exportReplay() {
+            if (hydratedFromExternalSnapshot) {
+                // A hydrated session's history starts at the snapshot frame, not tick 0 —
+                // exporting would silently produce an unverifiable replay.
+                throw new SyncplayError('Replay export requires a session that started from tick 0', {
+                    code: 'session.replay-not-from-origin',
+                    frame: mutable.frame,
+                });
+            }
+            if (replayRecordingMode !== 'memory') {
+                throw new SyncplayError('Replay export requires replayRecordingMode="memory"', {
+                    code: 'session.replay-not-retained',
+                    frame: mutable.frame,
+                });
+            }
+            return {
+                formatVersion: 1,
+                deterministicVersion: config.deterministicVersion,
+                tickRate: config.tickRate,
+                playerCount: config.playerCount,
+                inputSchemaId: config.inputSchemaId,
+                stateSchemaId: config.stateSchemaId,
+                engineIdentityHash: config.engineIdentityHash ?? defaultChecksum({
+                    deterministicVersion: config.deterministicVersion,
+                    inputSchemaId: config.inputSchemaId,
+                    stateSchemaId: config.stateSchemaId,
+                }),
+                assetDbHash: config.assetDbHash ?? defaultChecksum('asset-db:none'),
+                configHash: config.configHash ?? defaultChecksum({
+                    tickRate: config.tickRate,
+                    playerCount: config.playerCount,
+                    checksumIntervalFrames: checksumInterval,
+                    snapshotBufferSize,
+                }),
+                metadata: config.replayMetadata ?? { package: 'rundot-syncplay' },
+                randomSeed,
+                initialState: canonicalize(config.canonicalizeState?.(initialState) ?? initialState),
+                inputFrames: mutable.inputFrames.map((inputFrame) => cloneReplayRecord(inputFrame)),
+                commandHistory: mutable.commandFrames.map((commandFrame) => cloneReplayRecord(commandFrame)),
+                checksums: mutable.checksums.map((checksum) => cloneReplayRecord(checksum)),
+                debugEvents: [
+                    ...mutable.commandFrames.map((commandFrame) => ({
+                        frame: commandFrame.frame,
+                        type: 'commands',
+                        payload: canonicalize({ count: commandFrame.commands.length }),
+                    })),
+                    ...mutable.checksums.map((checksum) => ({
+                        frame: checksum.frame,
+                        type: 'checksum',
+                        payload: canonicalize({ checksum: checksum.checksum }),
+                    })),
+                ],
+            };
+        },
+        getSnapshot(frame) {
+            const snapshot = mutable.snapshots.get(frame);
+            return snapshot === undefined ? undefined : cloneSnapshot(snapshot);
+        },
+        restoreToFrame(frame) {
+            const snapshot = mutable.snapshots.get(frame);
+            if (snapshot === undefined) {
+                throw new SyncplayError(`No snapshot exists for frame ${frame}`, {
+                    code: 'session.missing-snapshot',
+                    frame,
+                });
+            }
+            mutable.frame = snapshot.frame;
+            mutable.state = cloneCanonical(snapshot.state);
+            mutable.inputs = snapshot.inputs.map((input) => cloneInput(config, input));
+            mutable.inputFlags = Array.from({ length: config.playerCount }, (_, slot) => defaultInputFlags(slot));
+            mutable.random.restore({ state: snapshot.randomState });
+            mutable.accumulatedMs = 0;
+            mutable.inputFrames = mutable.inputFrames.filter((inputFrame) => inputFrame.frame < frame);
+            mutable.commandFrames = mutable.commandFrames.filter((commandFrame) => commandFrame.frame < frame);
+            mutable.pendingCommandFrames = new Map([...mutable.pendingCommandFrames.entries()].filter(([pendingFrame]) => pendingFrame < frame));
+            mutable.checksums = mutable.checksums.filter((checksum) => checksum.frame <= frame);
+            pruneSnapshotsAfterFrame(mutable, frame);
+        },
+        restoreSnapshot(snapshot) {
+            invariant(Number.isInteger(snapshot.frame) && snapshot.frame >= 0, 'External snapshot frame must be a non-negative integer', 'session.invalid-snapshot-frame');
+            invariant(snapshot.inputs.length === config.playerCount, 'External snapshot inputs must cover every player slot', 'session.invalid-snapshot-inputs');
+            mutable.frame = snapshot.frame;
+            mutable.state = deserializeState(config, snapshot.stateBytes);
+            mutable.inputs = snapshot.inputs.map((input) => cloneInput(config, input));
+            mutable.inputFlags = Array.from({ length: config.playerCount }, (_, slot) => defaultInputFlags(slot));
+            mutable.random.restore({ state: snapshot.randomState });
+            mutable.accumulatedMs = 0;
+            mutable.inputFrames = [];
+            mutable.commandFrames = [];
+            mutable.pendingCommandFrames = new Map();
+            mutable.checksums = [];
+            mutable.snapshots = new Map();
+            mutable.snapshotOrder = [];
+            hydratedFromExternalSnapshot = true;
+            recordSnapshot(config, mutable, snapshotBufferSize);
+        },
+        getSnapshotFrames() {
+            return [...mutable.snapshotOrder];
+        },
+    };
+    recordSnapshot(config, mutable, snapshotBufferSize);
+    return session;
+}
+function runFrames(config, mutable, checksumInterval, snapshotBufferSize, replayRecordingMode, math, count) {
+    for (let index = 0; index < count; index += 1) {
+        const frame = mutable.frame;
+        const commandFrame = readPendingCommandFrame(mutable, frame);
+        const commands = commandFrame?.commands ?? [];
+        const inputFlags = mutable.inputFlags.map((flags, slot) => normalizeInputFlags(slot, {
+            ...flags,
+            commandInput: commands.some((command) => commandTargetsSlot(command, slot)),
+        }));
+        const effectiveInputs = mutable.inputs.map((input, slot) => inputFlags[slot].playerPresent ? cloneInput(config, input) : cloneInput(config, config.defaultInput));
+        const inputFrame = {
+            frame,
+            inputs: effectiveInputs.map((input) => canonicalize(config.canonicalizeInput?.(input) ?? input)),
+            inputFlags,
+        };
+        config.onInputFrameRecorded?.(inputFrame);
+        if (replayRecordingMode === 'memory') {
+            mutable.inputFrames.push(inputFrame);
+        }
+        if (commandFrame !== undefined) {
+            config.onCommandFrameRecorded?.(commandFrame);
+            if (replayRecordingMode === 'memory') {
+                mutable.commandFrames.push(commandFrame);
+            }
+        }
+        const stepContext = {
+            frame,
+            dtTicks: 1,
+            random: mutable.random,
+            math,
+            commands,
+        };
+        mutable.state =
+            config.runtimeGuards === true
+                ? withRuntimeDeterminismGuards(frame, () => config.step(mutable.state, effectiveInputs, frame, stepContext))
+                : config.step(mutable.state, effectiveInputs, frame, stepContext);
+        mutable.frame += 1;
+        const checksum = getChecksum(config, mutable.state);
+        if (mutable.frame % checksumInterval === 0) {
+            const checksumRecord = { frame: mutable.frame, checksum };
+            config.onChecksumRecorded?.(checksumRecord);
+            if (replayRecordingMode === 'memory') {
+                mutable.checksums.push(checksumRecord);
+            }
+        }
+        recordSnapshot(config, mutable, snapshotBufferSize, checksum);
+        mutable.inputFlags = inputFlags.map((flags, slot) => ({ ...defaultInputFlags(slot), repeatedPrevious: flags.playerPresent }));
+    }
+}
+function readPendingCommandFrame(mutable, frame) {
+    const commands = mutable.pendingCommandFrames.get(frame);
+    mutable.pendingCommandFrames.delete(frame);
+    if (commands === undefined || commands.length === 0) {
+        return undefined;
+    }
+    return {
+        frame,
+        commands: commands.map((command) => cloneReplayRecord(command)),
+    };
+}
+function cloneReplayRecord(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function defaultInputFlags(slot) {
+    return {
+        slot,
+        playerPresent: true,
+        repeatedPrevious: false,
+        replacedByServer: false,
+        commandInput: false,
+    };
+}
+function normalizeInputFlags(slot, flags) {
+    return {
+        slot,
+        playerPresent: flags.playerPresent === true,
+        repeatedPrevious: flags.repeatedPrevious === true,
+        replacedByServer: flags.replacedByServer === true,
+        commandInput: flags.commandInput === true,
+    };
+}
+function commandTargetsSlot(command, slot) {
+    if (typeof command !== 'object' || command === null || Array.isArray(command)) {
+        return false;
+    }
+    const record = command;
+    return record.slot === slot;
+}
+function validateConfig(config) {
+    invariant([10, 20, 30, 60].includes(config.tickRate), 'tickRate must be one of 10, 20, 30, or 60', 'config.tick-rate');
+    invariant(Number.isInteger(config.playerCount) && config.playerCount >= 1 && config.playerCount <= 128, 'playerCount must be an integer between 1 and 128', 'config.player-count');
+    invariant(config.inputSchemaId.length > 0, 'inputSchemaId is required', 'config.input-schema');
+    invariant(config.stateSchemaId.length > 0, 'stateSchemaId is required', 'config.state-schema');
+    invariant(config.deterministicVersion.length > 0, 'deterministicVersion is required', 'config.version');
+    invariant(config.checksumIntervalFrames === undefined ||
+        (Number.isInteger(config.checksumIntervalFrames) && config.checksumIntervalFrames > 0), 'checksumIntervalFrames must be a positive integer', 'config.checksum-interval');
+    invariant(config.snapshotBufferSize === undefined ||
+        (Number.isInteger(config.snapshotBufferSize) && config.snapshotBufferSize >= 1), 'snapshotBufferSize must be a positive integer', 'config.snapshot-buffer');
+}
+function pruneSnapshotsAfterFrame(mutable, frame) {
+    mutable.snapshotOrder = mutable.snapshotOrder.filter((snapshotFrame) => {
+        if (snapshotFrame > frame) {
+            mutable.snapshots.delete(snapshotFrame);
+            return false;
+        }
+        return true;
+    });
+}
+function getChecksum(config, state) {
+    return String(config.checksum?.(state) ?? defaultChecksum(config.canonicalizeState?.(state) ?? state));
+}
+function cloneInput(config, input) {
+    return cloneCanonical(input);
+}
+function serializeState(config, state) {
+    return config.serializeState?.(state) ?? encodeCanonicalBytes(config.canonicalizeState?.(state) ?? state);
+}
+function deserializeState(config, bytes) {
+    return config.deserializeState?.(bytes) ?? decodeCanonicalBytes(bytes);
+}
+function recordSnapshot(config, mutable, snapshotBufferSize, checksum) {
+    const stateBytes = serializeState(config, mutable.state);
+    const snapshot = {
+        frame: mutable.frame,
+        inputs: mutable.inputs.map((input) => cloneInput(config, input)),
+        checksum: checksum ?? getChecksum(config, mutable.state),
+        state: deserializeState(config, stateBytes),
+        stateBytes,
+        randomState: mutable.random.snapshot().state,
+    };
+    const alreadyStored = mutable.snapshots.has(snapshot.frame);
+    mutable.snapshots.set(snapshot.frame, snapshot);
+    /* istanbul ignore else -- public session flow records at most one snapshot per frame. */
+    if (!alreadyStored) {
+        mutable.snapshotOrder.push(snapshot.frame);
+    }
+    while (mutable.snapshotOrder.length > snapshotBufferSize) {
+        const evictedFrame = mutable.snapshotOrder.shift();
+        /* istanbul ignore else -- shift cannot be undefined immediately after the length check above. */
+        if (evictedFrame !== undefined) {
+            mutable.snapshots.delete(evictedFrame);
+        }
+    }
+}
+function cloneSnapshot(snapshot) {
+    return {
+        frame: snapshot.frame,
+        inputs: snapshot.inputs.map((input) => cloneCanonical(input)),
+        checksum: snapshot.checksum,
+        state: cloneCanonical(snapshot.state),
+        stateBytes: new Uint8Array(snapshot.stateBytes),
+        randomState: snapshot.randomState,
+    };
+}

package/dist/pause-resume.d.ts

@@ -0,0 +1,48 @@
+import type { DeterministicStep } from './types.js';
+/**
+ * Pause/resume as an explicit deterministic state machine.
+ *
+ * Pause must be deterministic, so it rides the input stream: the controller
+ * wraps a game's step so that a rising edge on the designated pause-toggle
+ * input transitions running → paused (and back). Ticks still advance while
+ * paused — the wrapped sim becomes identity except for pause bookkeeping — so
+ * every peer, replay, and rollback observes the exact same pause window.
+ *
+ * The machine's state lives INSIDE the wrapped game state (`state.pause`), so
+ * it snapshots, rolls back, and re-simulates for free with the rest of the
+ * session state. All fields are canonical values.
+ *
+ * Semantics per tick:
+ * - A slot toggles on the RISING edge of `isPauseToggle` (holding the button
+ *   across ticks does not re-toggle).
+ * - Simultaneous rising edges accumulate: an odd number flips the status, an
+ *   even number cancels out (two players pausing on the same tick is a no-op).
+ * - A tick that transitions to `paused` is already paused (inner step skipped);
+ *   a tick that transitions to `running` already runs the inner step.
+ * - `pausedFrames` counts ticks the inner step was skipped; `toggleCount`
+ *   counts every rising edge observed.
+ */
+export type DeterministicPauseStatus = 'running' | 'paused';
+export interface DeterministicPauseState {
+    readonly status: DeterministicPauseStatus;
+    readonly pausedFrames: number;
+    readonly toggleCount: number;
+    /** Per-slot toggle-input level from the previous tick — the edge detector's memory. */
+    readonly toggleHeld: readonly boolean[];
+}
+export interface PauseWrappedState<GameState> {
+    readonly pause: DeterministicPauseState;
+    readonly game: GameState;
+}
+export interface PauseControllerOptions<GameState, Input> {
+    /** Whether this slot's input holds the pause toggle down this tick. */
+    readonly isPauseToggle: (input: Readonly<Input>, slot: number) => boolean;
+    /** The game step to wrap. */
+    readonly wrap: DeterministicStep<GameState, Input>;
+}
+export interface DeterministicPauseController<GameState, Input> {
+    wrapInitialState(gameState: GameState): PauseWrappedState<GameState>;
+    readonly step: DeterministicStep<PauseWrappedState<GameState>, Input>;
+    isPaused(state: Readonly<PauseWrappedState<GameState>>): boolean;
+}
+export declare function createPauseController<GameState, Input>(options: PauseControllerOptions<GameState, Input>): DeterministicPauseController<GameState, Input>;

package/dist/pause-resume.js

@@ -0,0 +1,40 @@
+export function createPauseController(options) {
+    const step = (state, inputs, frame, ctx) => {
+        const previousHeld = state.pause.toggleHeld;
+        let risingEdges = 0;
+        const toggleHeld = inputs.map((input, slot) => {
+            const held = options.isPauseToggle(input, slot) === true;
+            if (held && previousHeld[slot] !== true) {
+                risingEdges += 1;
+            }
+            return held;
+        });
+        const flips = risingEdges % 2 === 1;
+        const status = flips
+            ? state.pause.status === 'running' ? 'paused' : 'running'
+            : state.pause.status;
+        const toggleCount = state.pause.toggleCount + risingEdges;
+        if (status === 'paused') {
+            return {
+                pause: { status, pausedFrames: state.pause.pausedFrames + 1, toggleCount, toggleHeld },
+                game: state.game,
+            };
+        }
+        return {
+            pause: { status, pausedFrames: state.pause.pausedFrames, toggleCount, toggleHeld },
+            game: options.wrap(state.game, inputs, frame, ctx),
+        };
+    };
+    return {
+        wrapInitialState(gameState) {
+            return {
+                pause: { status: 'running', pausedFrames: 0, toggleCount: 0, toggleHeld: [] },
+                game: gameState,
+            };
+        },
+        step,
+        isPaused(state) {
+            return state.pause.status === 'paused';
+        },
+    };
+}

package/dist/physics-cert.d.ts

@@ -0,0 +1,40 @@
+export type PhysicsCertEngine = 'builtin-fixed' | 'rapier2d-compat';
+export type PhysicsCertShape = 'fixed-arena' | 'slot-load';
+export interface PhysicsCertOptions {
+    readonly engine: PhysicsCertEngine;
+    readonly shape: PhysicsCertShape;
+    readonly players: number;
+    readonly frames: number;
+    readonly seed: number;
+    readonly snapshotEvery: number;
+}
+export interface PhysicsCertResult {
+    readonly engine: PhysicsCertEngine;
+    readonly engineVersion: string;
+    readonly adapterVersion: string;
+    readonly shape: PhysicsCertShape;
+    readonly players: number;
+    readonly bodies: number;
+    readonly frames: number;
+    readonly snapshotEvery: number;
+    readonly seed: number;
+    readonly uninterruptedChecksum: string;
+    readonly restoredChecksum: string;
+    readonly collisionEvents: number;
+    readonly collisionEventsStable: boolean;
+    readonly queryOrderStable: boolean;
+    readonly snapshotHashStable: boolean;
+    readonly finalRestoreStable: boolean;
+    readonly stepMsP95: string;
+    readonly stepMsMax: string;
+    readonly snapshotMsP95: string;
+    readonly restoreMsP95: string;
+    readonly snapshotBytesP95: number;
+    readonly heapUsedBytes: number;
+    readonly knownIssueRapier910: 'not-applicable' | 'not-reproduced' | 'reproduced';
+    readonly packageName?: string;
+    readonly packageImportPath?: string;
+    readonly result: 'pass' | 'fail';
+}
+export declare function runPhysicsCert(options: PhysicsCertOptions): PhysicsCertResult;
+export declare function runRapierPhysicsCert(options: PhysicsCertOptions): Promise<PhysicsCertResult>;