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

package/dist/cjs/offline-session.js

@@ -0,0 +1,370 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOfflineSession = createOfflineSession;
+const canonical_js_1 = require("./canonical.js");
+const errors_js_1 = require("./errors.js");
+const math_js_1 = require("./math.js");
+const random_js_1 = require("./random.js");
+const runtime_guards_js_1 = require("./runtime-guards.js");
+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 = (0, math_js_1.createDeterministicMath)();
+    const initialState = (0, canonical_js_1.cloneCanonical)(config.initialState);
+    const mutable = {
+        frame: 0,
+        accumulatedMs: 0,
+        state: (0, canonical_js_1.cloneCanonical)(initialState),
+        inputs: Array.from({ length: config.playerCount }, () => cloneInput(config, config.defaultInput)),
+        inputFlags: Array.from({ length: config.playerCount }, (_, slot) => defaultInputFlags(slot)),
+        random: new random_js_1.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 errors_js_1.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 errors_js_1.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((0, canonical_js_1.canonicalize)(config.canonicalizeCommand?.(command) ?? command));
+            }
+            mutable.pendingCommandFrames.set(mutable.frame, frameCommands);
+        },
+        update(deltaMs) {
+            if (!Number.isFinite(deltaMs) || deltaMs < 0) {
+                throw new errors_js_1.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 errors_js_1.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 errors_js_1.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 (0, canonical_js_1.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 errors_js_1.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 errors_js_1.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 ?? (0, canonical_js_1.defaultChecksum)({
+                    deterministicVersion: config.deterministicVersion,
+                    inputSchemaId: config.inputSchemaId,
+                    stateSchemaId: config.stateSchemaId,
+                }),
+                assetDbHash: config.assetDbHash ?? (0, canonical_js_1.defaultChecksum)('asset-db:none'),
+                configHash: config.configHash ?? (0, canonical_js_1.defaultChecksum)({
+                    tickRate: config.tickRate,
+                    playerCount: config.playerCount,
+                    checksumIntervalFrames: checksumInterval,
+                    snapshotBufferSize,
+                }),
+                metadata: config.replayMetadata ?? { package: 'rundot-syncplay' },
+                randomSeed,
+                initialState: (0, canonical_js_1.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: (0, canonical_js_1.canonicalize)({ count: commandFrame.commands.length }),
+                    })),
+                    ...mutable.checksums.map((checksum) => ({
+                        frame: checksum.frame,
+                        type: 'checksum',
+                        payload: (0, canonical_js_1.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 errors_js_1.SyncplayError(`No snapshot exists for frame ${frame}`, {
+                    code: 'session.missing-snapshot',
+                    frame,
+                });
+            }
+            mutable.frame = snapshot.frame;
+            mutable.state = (0, canonical_js_1.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) {
+            (0, errors_js_1.invariant)(Number.isInteger(snapshot.frame) && snapshot.frame >= 0, 'External snapshot frame must be a non-negative integer', 'session.invalid-snapshot-frame');
+            (0, errors_js_1.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) => (0, canonical_js_1.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
+                ? (0, runtime_guards_js_1.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) {
+    (0, errors_js_1.invariant)([10, 20, 30, 60].includes(config.tickRate), 'tickRate must be one of 10, 20, 30, or 60', 'config.tick-rate');
+    (0, errors_js_1.invariant)(Number.isInteger(config.playerCount) && config.playerCount >= 1 && config.playerCount <= 128, 'playerCount must be an integer between 1 and 128', 'config.player-count');
+    (0, errors_js_1.invariant)(config.inputSchemaId.length > 0, 'inputSchemaId is required', 'config.input-schema');
+    (0, errors_js_1.invariant)(config.stateSchemaId.length > 0, 'stateSchemaId is required', 'config.state-schema');
+    (0, errors_js_1.invariant)(config.deterministicVersion.length > 0, 'deterministicVersion is required', 'config.version');
+    (0, errors_js_1.invariant)(config.checksumIntervalFrames === undefined ||
+        (Number.isInteger(config.checksumIntervalFrames) && config.checksumIntervalFrames > 0), 'checksumIntervalFrames must be a positive integer', 'config.checksum-interval');
+    (0, errors_js_1.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) ?? (0, canonical_js_1.defaultChecksum)(config.canonicalizeState?.(state) ?? state));
+}
+function cloneInput(config, input) {
+    return (0, canonical_js_1.cloneCanonical)(input);
+}
+function serializeState(config, state) {
+    return config.serializeState?.(state) ?? (0, canonical_js_1.encodeCanonicalBytes)(config.canonicalizeState?.(state) ?? state);
+}
+function deserializeState(config, bytes) {
+    return config.deserializeState?.(bytes) ?? (0, canonical_js_1.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) => (0, canonical_js_1.cloneCanonical)(input)),
+        checksum: snapshot.checksum,
+        state: (0, canonical_js_1.cloneCanonical)(snapshot.state),
+        stateBytes: new Uint8Array(snapshot.stateBytes),
+        randomState: snapshot.randomState,
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/pause-resume.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPauseController = createPauseController;
+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';
+        },
+    };
+}