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

package/dist/cjs/input-timeline.js

@@ -0,0 +1,418 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeterministicInputTimelineFixture = runDeterministicInputTimelineFixture;
+exports.evaluateDeterministicInputTimelineResult = evaluateDeterministicInputTimelineResult;
+exports.accumulateDeterministicInputTimelineState = accumulateDeterministicInputTimelineState;
+exports.sortDeterministicInputTimelineFlags = sortDeterministicInputTimelineFlags;
+const canonical_js_1 = require("./canonical.js");
+const local_authority_js_1 = require("./local-authority.js");
+const random_js_1 = require("./random.js");
+const deterministic_session_js_1 = require("./deterministic-session.js");
+function runDeterministicInputTimelineFixture(options) {
+    validateInputTimelineOptions(options);
+    const descriptor = createInputTimelineDescriptor();
+    const systems = createInputTimelineSystems();
+    const session = (0, deterministic_session_js_1.createDeterministicSessionCore)({
+        players: options.players,
+        descriptor,
+        systems,
+        seed: options.seed,
+        mapInputsToSingleton,
+    });
+    const random = new random_js_1.DeterministicRandom(options.seed);
+    const lateJoinSlot = options.players - 1;
+    const spectatorSlot = 0;
+    const botSlot = 1;
+    const absentSlot = 2;
+    const transientSlot = 3;
+    const lateJoinFrame = Math.max(1, Math.floor(options.frames / 4));
+    const removeFrame = Math.max(1, Math.floor(options.frames / 3));
+    const readdFrame = Math.min(options.frames - 1, Math.max(removeFrame + 1, Math.floor(options.frames / 2)));
+    const lastRepeatableValue = Array.from({ length: options.players }, () => 0);
+    const hasRepeatableValue = Array.from({ length: options.players }, () => false);
+    const rows = [];
+    for (let slot = 0; slot < options.players; slot += 1) {
+        session.joinAsSpectator(slot, `actor-${slot}`, 0);
+        if (slot !== spectatorSlot && slot !== absentSlot && slot !== lateJoinSlot) {
+            session.addPlayer(slot, `actor-${slot}`, 0);
+        }
+    }
+    for (let frame = 0; frame < options.frames; frame += 1) {
+        if (frame === lateJoinFrame) {
+            session.addPlayer(lateJoinSlot, `actor-${lateJoinSlot}`, frame);
+        }
+        if (frame === removeFrame) {
+            session.removePlayer(transientSlot, `actor-${transientSlot}`, frame);
+        }
+        if (frame === readdFrame) {
+            session.addPlayer(transientSlot, `actor-${transientSlot}`, frame);
+        }
+        const pendingRows = [];
+        for (let slot = 0; slot < options.players; slot += 1) {
+            const slotState = classifySlot(frame, slot, {
+                spectatorSlot,
+                botSlot,
+                absentSlot,
+                transientSlot,
+                lateJoinSlot,
+                lateJoinFrame,
+                removeFrame,
+                readdFrame,
+            });
+            if (!slotState.active) {
+                session.replaceInput({ frame, slot, value: 0, flags: ['player-not-present'] });
+                pendingRows.push({
+                    frame,
+                    slot,
+                    lane: slotState.lane,
+                    prediction: 'none',
+                    verification: 'absent',
+                    correction: 'none',
+                    predictedValue: 0,
+                    verifiedValue: 0,
+                    flags: ['player-not-present'],
+                });
+                continue;
+            }
+            const predictedPolicy = shouldSubmitExplicitPrediction(frame, slot, options.seed) ? 'explicit' : fallbackPolicy(hasRepeatableValue[slot]);
+            const predictedValue = predictedPolicy === 'explicit'
+                ? random.nextInt(-8, 8)
+                : predictedPolicy === 'repeat-last'
+                    ? lastRepeatableValue[slot]
+                    : 0;
+            const predictedFlags = inputFlags(frame, slot, options.seed);
+            if (predictedPolicy === 'explicit') {
+                session.submitPredictedInput({ frame, slot, value: predictedValue, flags: predictedFlags });
+            }
+            const replacement = shouldReplaceInput(frame, slot, options.seed);
+            const verifiedValue = replacement
+                ? (hasRepeatableValue[slot] ? lastRepeatableValue[slot] : 0)
+                : predictedValue + shouldLateFill(frame, slot, options.seed);
+            const verifiedFlags = replacement
+                ? sortDeterministicInputTimelineFlags(['replaced-by-server', ...(hasRepeatableValue[slot] ? ['repeatable'] : [])])
+                : predictedFlags;
+            pendingRows.push({
+                frame,
+                slot,
+                lane: slotState.lane,
+                prediction: predictedPolicy,
+                verification: replacement ? 'replacement' : 'confirmed',
+                correction: correctionFor(predictedPolicy, predictedValue, verifiedValue),
+                predictedValue,
+                verifiedValue,
+                flags: verifiedFlags,
+            });
+        }
+        session.predictTo(frame + 1);
+        for (const row of pendingRows) {
+            if (row.verification === 'absent') {
+                continue;
+            }
+            const input = {
+                frame: row.frame,
+                slot: row.slot,
+                value: row.verifiedValue,
+                flags: row.flags,
+            };
+            if (row.verification === 'replacement') {
+                session.replaceInput(input);
+            }
+            else {
+                session.confirmInput(input);
+            }
+            if (row.flags.includes('repeatable')) {
+                hasRepeatableValue[row.slot] = true;
+                lastRepeatableValue[row.slot] = row.verifiedValue;
+            }
+        }
+        session.advanceVerifiedTo(frame + 1);
+        rows.push(...pendingRows);
+    }
+    const replay = session.exportReplay();
+    const replayVerification = (0, deterministic_session_js_1.verifyDeterministicSessionRuntimeReplay)(replay, {
+        players: options.players,
+        descriptor,
+        systems,
+        seed: options.seed,
+        mapInputsToSingleton,
+    });
+    const counts = countRows(rows);
+    const negativeCases = runInputTimelineNegativeCases(options.players);
+    const rowHash = (0, canonical_js_1.defaultChecksum)(rows);
+    const invariants = {
+        allFramesCovered: counts.frames === options.frames,
+        allSlotsCovered: counts.slots === options.players,
+        rowCountStable: rows.length === options.frames * options.players,
+        orderStable: rows.every((row, index) => index === 0 || compareRows(rows[index - 1], row) <= 0),
+        explicitPredictionCovered: counts.explicitPredictions > 0,
+        neutralPredictionCovered: counts.neutralPredictions > 0,
+        repeatLastPredictionCovered: counts.repeatLastPredictions > 0,
+        confirmedCovered: counts.confirmed > 0,
+        replacementCovered: counts.replacements > 0,
+        absentCovered: counts.absent > 0,
+        botCovered: counts.bot > 0,
+        lateJoinCovered: counts.lateJoin > 0,
+        lateFillCovered: counts.lateFill > 0,
+        rollbackTriggeredCovered: counts.rollbackTriggered > 0,
+        replayVerified: replayVerification.result === 'pass',
+        inactivePredictionRejected: negativeCases.inactivePredictionRejected,
+        malformedValueRejected: negativeCases.malformedValueRejected,
+        duplicateIngressRejected: negativeCases.duplicateIngressRejected,
+        duplicateAfterRestoreRejected: negativeCases.duplicateAfterRestoreRejected,
+        futureIngressRejected: negativeCases.futureIngressRejected,
+        staleIngressRejected: negativeCases.staleIngressRejected,
+        spectatorIngressRejected: negativeCases.spectatorIngressRejected,
+        badSenderRejected: negativeCases.badSenderRejected,
+    };
+    const invariantChecks = [
+        invariants.allFramesCovered,
+        invariants.allSlotsCovered,
+        invariants.rowCountStable,
+        invariants.orderStable,
+        invariants.explicitPredictionCovered,
+        invariants.neutralPredictionCovered,
+        invariants.repeatLastPredictionCovered,
+        invariants.confirmedCovered,
+        invariants.replacementCovered,
+        invariants.absentCovered,
+        invariants.botCovered,
+        invariants.lateJoinCovered,
+        invariants.lateFillCovered,
+        invariants.rollbackTriggeredCovered,
+        invariants.replayVerified,
+        invariants.inactivePredictionRejected,
+        invariants.malformedValueRejected,
+        invariants.duplicateIngressRejected,
+        invariants.duplicateAfterRestoreRejected,
+        invariants.futureIngressRejected,
+        invariants.staleIngressRejected,
+        invariants.spectatorIngressRejected,
+        invariants.badSenderRejected,
+    ];
+    const result = evaluateDeterministicInputTimelineResult(invariantChecks);
+    const sampleLimit = options.sampleLimit ?? 64;
+    const reportWithoutChecksum = {
+        schemaVersion: 1,
+        kind: 'deterministic-input-timeline',
+        result,
+        players: options.players,
+        frames: options.frames,
+        seed: options.seed,
+        rowCount: rows.length,
+        rowHash,
+        sampledRows: rows.slice(0, sampleLimit),
+        ...(options.includeRows === true ? { rows } : {}),
+        counts,
+        negativeCases,
+        replayVerified: replayVerification.result === 'pass',
+        replayChecksum: replayVerification.replayChecksum,
+        finalVerifiedChecksum: replay.finalVerifiedChecksum,
+        invariants,
+    };
+    return {
+        ...reportWithoutChecksum,
+        checksum: (0, canonical_js_1.defaultChecksum)(reportWithoutChecksum),
+    };
+}
+function createInputTimelineDescriptor() {
+    return {
+        id: 'input-timeline-fixture',
+        tickRate: 60,
+        components: [
+            { id: 'sessionInput', singleton: true, fields: [
+                    { name: 'sum', kind: 'int', defaultValue: 0 },
+                    { name: 'active', kind: 'int', defaultValue: 0 },
+                ] },
+            { id: 'sessionState', singleton: true, fields: [
+                    { name: 'sum', kind: 'int', defaultValue: 0 },
+                    { name: 'frames', kind: 'int', defaultValue: 0 },
+                    { name: 'activeInputs', kind: 'int', defaultValue: 0 },
+                ] },
+        ],
+        systems: [{ id: 'input-timeline-step', group: 'simulation', order: 0 }],
+    };
+}
+function createInputTimelineSystems() {
+    return {
+        'input-timeline-step'(ctx) {
+            const input = ctx.getSingleton('sessionInput');
+            const state = (ctx.getSingleton('sessionState') ?? { sum: 0, frames: 0, activeInputs: 0 });
+            ctx.setSingleton('sessionState', accumulateDeterministicInputTimelineState(state, input));
+        },
+    };
+}
+function evaluateDeterministicInputTimelineResult(invariantChecks) {
+    return invariantChecks.every((value) => value) ? 'pass' : 'fail';
+}
+function accumulateDeterministicInputTimelineState(state, input) {
+    return {
+        sum: Number(state.sum ?? 0) + Number(input.sum ?? 0),
+        frames: Number(state.frames ?? 0) + 1,
+        activeInputs: Number(state.activeInputs ?? 0) + Number(input.active ?? 0),
+    };
+}
+function mapInputsToSingleton(_frame, inputs) {
+    return {
+        sum: inputs.reduce((sum, input) => sum + input.value, 0),
+        active: inputs.length,
+    };
+}
+function classifySlot(frame, slot, config) {
+    if (slot === config.spectatorSlot) {
+        return { lane: 'spectator', active: false };
+    }
+    if (slot === config.absentSlot) {
+        return { lane: 'absent', active: false };
+    }
+    if (slot === config.lateJoinSlot && frame < config.lateJoinFrame) {
+        return { lane: 'late-join', active: false };
+    }
+    if (slot === config.transientSlot && frame >= config.removeFrame && frame < config.readdFrame) {
+        return { lane: 'absent', active: false };
+    }
+    if (slot === config.botSlot) {
+        return { lane: 'bot', active: true };
+    }
+    return { lane: 'human', active: true };
+}
+function shouldSubmitExplicitPrediction(frame, slot, seed) {
+    return (frame + slot + seed) % 11 !== 0;
+}
+function shouldReplaceInput(frame, slot, seed) {
+    return (frame * 3 + slot + seed) % 17 === 0;
+}
+function shouldLateFill(frame, slot, seed) {
+    return (frame + slot + seed) % 5 === 0 ? 1 : 0;
+}
+function inputFlags(frame, slot, seed) {
+    const flags = [];
+    if ((frame + slot + seed) % 7 === 0) {
+        flags.push('repeatable');
+    }
+    if ((frame + slot + seed) % 13 === 0) {
+        flags.push('command');
+    }
+    return sortDeterministicInputTimelineFlags(flags);
+}
+function fallbackPolicy(hasRepeatable) {
+    return hasRepeatable ? 'repeat-last' : 'neutral';
+}
+function correctionFor(prediction, predictedValue, verifiedValue) {
+    if (prediction === 'none' || predictedValue === verifiedValue) {
+        return 'none';
+    }
+    return prediction === 'explicit' ? 'late-fill' : 'rollback-triggered';
+}
+function sortDeterministicInputTimelineFlags(flags) {
+    return [...new Set(flags)].sort(compareStrings);
+}
+function countRows(rows) {
+    const frames = new Set();
+    const slots = new Set();
+    const counts = {
+        rows: rows.length,
+        frames: 0,
+        slots: 0,
+        explicitPredictions: 0,
+        neutralPredictions: 0,
+        repeatLastPredictions: 0,
+        confirmed: 0,
+        replacements: 0,
+        absent: 0,
+        bot: 0,
+        lateJoin: 0,
+        lateFill: 0,
+        rollbackTriggered: 0,
+    };
+    for (const row of rows) {
+        frames.add(row.frame);
+        slots.add(row.slot);
+        counts.explicitPredictions += row.prediction === 'explicit' ? 1 : 0;
+        counts.neutralPredictions += row.prediction === 'neutral' ? 1 : 0;
+        counts.repeatLastPredictions += row.prediction === 'repeat-last' ? 1 : 0;
+        counts.confirmed += row.verification === 'confirmed' ? 1 : 0;
+        counts.replacements += row.verification === 'replacement' ? 1 : 0;
+        counts.absent += row.verification === 'absent' ? 1 : 0;
+        counts.bot += row.lane === 'bot' ? 1 : 0;
+        counts.lateJoin += row.lane === 'late-join' ? 1 : 0;
+        counts.lateFill += row.correction === 'late-fill' ? 1 : 0;
+        counts.rollbackTriggered += row.correction === 'rollback-triggered' ? 1 : 0;
+    }
+    counts.frames = frames.size;
+    counts.slots = slots.size;
+    return counts;
+}
+function runInputTimelineNegativeCases(players) {
+    const descriptor = createInputTimelineDescriptor();
+    const systems = createInputTimelineSystems();
+    const session = (0, deterministic_session_js_1.createDeterministicSessionCore)({ players, descriptor, systems, seed: 19, mapInputsToSingleton });
+    session.joinAsSpectator(0, 'actor-0', 0);
+    const inactivePredictionRejected = throws(() => session.submitPredictedInput({ frame: 0, slot: 0, value: 1 }));
+    session.addPlayer(1, 'actor-1', 0);
+    const validPredictionAccepted = !throws(() => session.submitPredictedInput({ frame: 0, slot: 1, value: 1 }));
+    const malformedValueRejected = throws(() => session.submitPredictedInput({ frame: 0, slot: 1, value: 1.5 }));
+    const runtime = (0, local_authority_js_1.createDeterministicLocalAuthorityRuntime)(players, { maxFrameLead: 4 });
+    const firstAccepted = runtime.submitInput({ slot: 1, frame: 0, value: 7, inputId: 'input:slot-1:frame-0' });
+    const duplicateIngressRejected = firstAccepted && !runtime.submitInput({ slot: 1, frame: 0, value: 7, inputId: 'input:slot-1:frame-0' });
+    const futureIngressRejected = !runtime.submitInput({ slot: 1, frame: 99, value: 1 });
+    runtime.step();
+    runtime.step();
+    const staleIngressRejected = !runtime.submitInput({ slot: 1, frame: 0, value: 1, inputId: 'input:stale' });
+    runtime.addSpectator(2);
+    const spectatorIngressRejected = !runtime.submitInput({ slot: 2, frame: runtime.state.frame, value: 3 });
+    const badSenderRejected = !runtime.submitInput({ slot: 1, senderSlot: 2, frame: runtime.state.frame, value: 3 });
+    const restoreSource = (0, local_authority_js_1.createDeterministicLocalAuthorityRuntime)(players, { maxFrameLead: 4 });
+    const restoreAccepted = restoreSource.submitInput({ slot: 1, frame: 0, value: 5, inputId: 'input:persisted' });
+    const snapshot = restoreSource.snapshot();
+    const restored = (0, local_authority_js_1.createDeterministicLocalAuthorityRuntime)(players, { maxFrameLead: 4 });
+    restored.restore(snapshot);
+    const duplicateAfterRestoreRejected = restoreAccepted && !restored.submitInput({ slot: 1, frame: 0, value: 5, inputId: 'input:persisted' });
+    return {
+        validPredictionAccepted,
+        inactivePredictionRejected,
+        malformedValueRejected,
+        duplicateIngressRejected,
+        duplicateAfterRestoreRejected,
+        futureIngressRejected,
+        staleIngressRejected,
+        spectatorIngressRejected,
+        badSenderRejected,
+    };
+}
+function compareRows(left, right) {
+    return left.frame - right.frame || left.slot - right.slot;
+}
+function compareStrings(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    /* istanbul ignore else -- input timeline flag sorting de-duplicates before comparing. */
+    if (left > right) {
+        return 1;
+    }
+    /* istanbul ignore next -- stable flag sorting receives de-duplicated flag strings. */
+    return 0;
+}
+function throws(action) {
+    try {
+        action();
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function validateInputTimelineOptions(options) {
+    if (!Number.isInteger(options.players) || options.players < 16 || options.players > 128) {
+        throw new Error('input timeline players must be an integer between 16 and 128');
+    }
+    if (!Number.isInteger(options.frames) || options.frames < 96) {
+        throw new Error('input timeline frames must be an integer >= 96');
+    }
+    if (!Number.isInteger(options.seed)) {
+        throw new Error('input timeline seed must be an integer');
+    }
+    if (options.sampleLimit !== undefined && (!Number.isInteger(options.sampleLimit) || options.sampleLimit < 0)) {
+        throw new Error('input timeline sampleLimit must be a non-negative integer');
+    }
+}

package/dist/cjs/instant-replay.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInstantReplay = runInstantReplay;
+exports.createInstantReplayRunner = createInstantReplayRunner;
+const errors_js_1 = require("./errors.js");
+const offline_session_js_1 = require("./offline-session.js");
+function runInstantReplay(options) {
+    const session = options.createSession();
+    session.restoreSnapshot(options.snapshot);
+    let expectedFrame = options.snapshot.frame;
+    for (const inputFrame of options.inputs) {
+        if (inputFrame.frame !== expectedFrame) {
+            throw new errors_js_1.SyncplayError(`Instant replay inputs must be contiguous from snapshot frame ${options.snapshot.frame}: expected frame ${expectedFrame}, got ${inputFrame.frame}`, { code: 'instant-replay.non-contiguous-inputs', frame: inputFrame.frame });
+        }
+        for (let slot = 0; slot < inputFrame.inputs.length; slot += 1) {
+            const recorded = inputFrame.inputs[slot];
+            // NOT `??`: a decoder returning null (the canonical neutral) must win
+            // over the raw recorded value (adversarial-review LOW).
+            session.setInput(slot, options.decodeInput !== undefined ? options.decodeInput(recorded, slot) : recorded);
+        }
+        session.stepFrames(1);
+        options.onFrame(session.getState(), session.currentFrame);
+        expectedFrame += 1;
+    }
+    const finalSnapshot = session.getSnapshot(session.currentFrame);
+    /* istanbul ignore if -- the session records a snapshot on every stepped frame. */
+    if (finalSnapshot === undefined) {
+        throw new errors_js_1.SyncplayError('Instant replay session has no snapshot at its final frame', {
+            code: 'instant-replay.missing-final-snapshot',
+            frame: session.currentFrame,
+        });
+    }
+    return { framesPlayed: options.inputs.length, finalChecksum: finalSnapshot.checksum };
+}
+/**
+ * Binds a session config to a replay window. Each `run` simulates on a fresh
+ * throwaway session with replay recording off, a single-frame snapshot buffer,
+ * and the config's recording callbacks stripped — so a killcam never leaks
+ * events into the live game's observers and stays allocation-light.
+ */
+function createInstantReplayRunner(config, options) {
+    (0, errors_js_1.invariant)(Number.isInteger(options.window) && options.window >= 1, 'Instant replay window must be a positive integer', 'instant-replay.invalid-window');
+    const replayConfig = {
+        ...config,
+        replayRecordingMode: 'none',
+        snapshotBufferSize: 1,
+        onInputFrameRecorded: undefined,
+        onCommandFrameRecorded: undefined,
+        onChecksumRecorded: undefined,
+    };
+    return {
+        window: options.window,
+        run(runOptions) {
+            if (runOptions.inputs.length > options.window) {
+                throw new errors_js_1.SyncplayError(`Instant replay covers ${runOptions.inputs.length} ticks, above window ${options.window}`, { code: 'instant-replay.window-exceeded', frame: runOptions.snapshot.frame });
+            }
+            return runInstantReplay({
+                createSession: () => (0, offline_session_js_1.createOfflineSession)(replayConfig),
+                snapshot: runOptions.snapshot,
+                inputs: runOptions.inputs,
+                decodeInput: runOptions.decodeInput,
+                onFrame: runOptions.onFrame,
+            });
+        },
+    };
+}