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

package/dist/cjs/errors.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncplayError = void 0;
+exports.invariant = invariant;
+class SyncplayError extends Error {
+    code;
+    frame;
+    slot;
+    constructor(message, options) {
+        super(message);
+        this.name = 'SyncplayError';
+        this.code = options.code;
+        this.frame = options.frame;
+        this.slot = options.slot;
+    }
+}
+exports.SyncplayError = SyncplayError;
+function invariant(condition, message, code) {
+    if (!condition) {
+        throw new SyncplayError(message, { code });
+    }
+}

package/dist/cjs/events.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeterministicEventTimeline = createDeterministicEventTimeline;
+exports.runDeterministicEventKeywordFixture = runDeterministicEventKeywordFixture;
+exports.filterDeterministicEventsForPlayer = filterDeterministicEventsForPlayer;
+const canonical_js_1 = require("./canonical.js");
+const errors_js_1 = require("./errors.js");
+function createDeterministicEventTimeline() {
+    const records = [];
+    const emittedVerifiedOnly = new Set();
+    let nextSequence = 0;
+    return {
+        emitPredicted(eventId, frame, payload, options) {
+            validateEvent(eventId, frame);
+            const record = makeRecord(eventId, frame, nextSequence, payload, 'predicted', normalizeEmitOptions(options));
+            nextSequence += 1;
+            records.push(record);
+            return cloneEventRecord(record);
+        },
+        emitSynced(eventId, frame, payload, options) {
+            validateEvent(eventId, frame);
+            const record = makeRecord(eventId, frame, nextSequence, payload, 'synced', normalizeEmitOptions(options));
+            nextSequence += 1;
+            records.push(record);
+            return cloneEventRecord(record);
+        },
+        emitVerifiedOnly(eventId, frame, payload, options) {
+            validateEvent(eventId, frame);
+            const emitOptions = normalizeEmitOptions(options);
+            const key = emitOptions.dedupeKey ?? makeDedupeKey(eventId, frame, payload, emitOptions.notHashedKeys);
+            if (emittedVerifiedOnly.has(key)) {
+                throw new errors_js_1.SyncplayError(`Verified-only event ${eventId} already emitted for ${key}`, {
+                    code: 'events.duplicate-verified-only',
+                    frame,
+                });
+            }
+            emittedVerifiedOnly.add(key);
+            const record = makeRecord(eventId, frame, nextSequence, payload, 'verifiedOnly', { ...emitOptions, dedupeKey: key });
+            nextSequence += 1;
+            records.push(record);
+            return cloneEventRecord(record);
+        },
+        confirmThroughFrame(frame) {
+            validateFrame(frame);
+            const confirmed = [];
+            for (let index = 0; index < records.length; index += 1) {
+                const record = records[index];
+                if (record.predictionState === 'predicted' && record.frame <= frame) {
+                    const next = { ...record, predictionState: 'confirmed' };
+                    records[index] = next;
+                    confirmed.push(next);
+                }
+            }
+            return confirmed.map((record) => cloneEventRecord(record));
+        },
+        cancelFromFrame(frame) {
+            validateFrame(frame);
+            const canceled = [];
+            for (let index = 0; index < records.length; index += 1) {
+                const record = records[index];
+                if (record.predictionState === 'predicted' && record.frame >= frame) {
+                    const next = { ...record, predictionState: 'canceled' };
+                    records[index] = next;
+                    canceled.push(next);
+                }
+            }
+            return canceled.map((record) => cloneEventRecord(record));
+        },
+        records() {
+            return records.map((record) => cloneEventRecord(record));
+        },
+    };
+}
+function runDeterministicEventKeywordFixture() {
+    const first = runEventKeywordScenario();
+    const restored = runEventKeywordScenario();
+    const checksum = (0, canonical_js_1.defaultChecksum)(first);
+    const restoredChecksum = (0, canonical_js_1.defaultChecksum)(restored);
+    return {
+        checksum,
+        restoredChecksum,
+        rollbackEquivalent: checksum === restoredChecksum,
+        syncedEvents: first.records.filter((record) => record.predictionState === 'synced').length,
+        confirmedEvents: first.records.filter((record) => record.predictionState === 'confirmed').length,
+        canceledEvents: first.records.filter((record) => record.predictionState === 'canceled').length,
+        verifiedOnlyEvents: first.records.filter((record) => record.predictionState === 'verifiedOnly').length,
+        notHashedDuplicateRejected: first.notHashedDuplicateRejected,
+        notHashedDedupeStable: first.notHashedDedupeStable,
+        syncedSurvivedConfirmCancel: first.syncedSurvivedConfirmCancel,
+        localEvents: first.localPlayerRecords.length,
+        remoteEvents: first.remotePlayerRecords.length,
+        localRemoteDispatchStable: (0, canonical_js_1.defaultChecksum)(first.localPlayerRecords) === (0, canonical_js_1.defaultChecksum)(restored.localPlayerRecords)
+            && (0, canonical_js_1.defaultChecksum)(first.remotePlayerRecords) === (0, canonical_js_1.defaultChecksum)(restored.remotePlayerRecords),
+    };
+}
+function filterDeterministicEventsForPlayer(records, localSlot) {
+    if (!Number.isInteger(localSlot) || localSlot < 0) {
+        throw new errors_js_1.SyncplayError('Local event player slot must be a non-negative integer', {
+            code: 'events.local-slot',
+            slot: localSlot,
+        });
+    }
+    return records.filter((record) => shouldDispatchRecordToPlayer(record, localSlot)).map((record) => cloneEventRecord(record));
+}
+function runEventKeywordScenario() {
+    const timeline = createDeterministicEventTimeline();
+    timeline.emitPredicted('dash', 2, { slot: 0 }, { deliveryScope: 'local', playerSlot: 0 });
+    timeline.emitPredicted('remote.dash', 2, { slot: 0 }, { deliveryScope: 'remote', playerSlot: 0 });
+    const synced = timeline.emitSynced('spawn.synced', 2, { slot: 1, cosmetic: 'spark' }, { notHashedKeys: ['cosmetic'] });
+    const verified = timeline.emitVerifiedOnly('score', 3, { slot: 1, cosmetic: 'spark' }, { notHashedKeys: ['cosmetic'] });
+    let duplicateRejected = false;
+    try {
+        timeline.emitVerifiedOnly('score', 3, { slot: 1, cosmetic: 'smoke' }, { notHashedKeys: ['cosmetic'] });
+    }
+    catch (error) {
+        duplicateRejected = error instanceof errors_js_1.SyncplayError;
+    }
+    timeline.confirmThroughFrame(2);
+    timeline.emitPredicted('late.predicted', 5, { slot: 2 });
+    timeline.cancelFromFrame(4);
+    const records = timeline.records();
+    return {
+        records,
+        localPlayerRecords: filterDeterministicEventsForPlayer(records, 0),
+        remotePlayerRecords: filterDeterministicEventsForPlayer(records, 1),
+        notHashedDuplicateRejected: duplicateRejected,
+        notHashedDedupeStable: verified.dedupeKey === `score:3:${(0, canonical_js_1.defaultChecksum)({ slot: 1 })}`,
+        syncedSurvivedConfirmCancel: records.some((record) => record.sequence === synced.sequence && record.predictionState === 'synced'),
+    };
+}
+function makeRecord(eventId, frame, sequence, payload, predictionState, options) {
+    return {
+        eventId,
+        frame,
+        sequence,
+        payload: (0, canonical_js_1.cloneCanonical)(payload),
+        predictionState,
+        dedupeKey: options.dedupeKey ?? makeDedupeKey(eventId, frame, payload, options.notHashedKeys),
+        notHashedKeys: [...(options.notHashedKeys ?? [])].sort(compareStrings),
+        deliveryScope: options.deliveryScope ?? 'all',
+        playerSlot: options.playerSlot,
+    };
+}
+function cloneEventRecord(record) {
+    return {
+        eventId: record.eventId,
+        frame: record.frame,
+        sequence: record.sequence,
+        payload: (0, canonical_js_1.cloneCanonical)(record.payload),
+        predictionState: record.predictionState,
+        dedupeKey: record.dedupeKey,
+        notHashedKeys: [...record.notHashedKeys],
+        deliveryScope: record.deliveryScope,
+        playerSlot: record.playerSlot,
+    };
+}
+function normalizeEmitOptions(options) {
+    if (options === undefined) {
+        return {};
+    }
+    if (typeof options === 'string') {
+        return { dedupeKey: options };
+    }
+    if (options.deliveryScope !== undefined && options.deliveryScope !== 'all' && options.deliveryScope !== 'local' && options.deliveryScope !== 'remote') {
+        throw new errors_js_1.SyncplayError(`Unsupported event delivery scope ${options.deliveryScope}`, {
+            code: 'events.delivery-scope',
+        });
+    }
+    if (options.playerSlot !== undefined &&
+        (!Number.isInteger(options.playerSlot) || options.playerSlot < 0)) {
+        throw new errors_js_1.SyncplayError('Event playerSlot must be a non-negative integer', {
+            code: 'events.player-slot',
+            slot: options.playerSlot,
+        });
+    }
+    return {
+        dedupeKey: options.dedupeKey,
+        notHashedKeys: options.notHashedKeys === undefined ? undefined : [...options.notHashedKeys].sort(compareStrings),
+        deliveryScope: options.deliveryScope ?? 'all',
+        playerSlot: options.playerSlot,
+    };
+}
+function shouldDispatchRecordToPlayer(record, localSlot) {
+    const scope = record.deliveryScope ?? 'all';
+    if (scope === 'all') {
+        return true;
+    }
+    if (scope !== 'local' && scope !== 'remote') {
+        throw new errors_js_1.SyncplayError(`Unsupported event delivery scope ${scope}`, {
+            code: 'events.delivery-scope',
+        });
+    }
+    if (record.playerSlot === undefined) {
+        throw new errors_js_1.SyncplayError(`Event ${record.eventId} is missing playerSlot for ${scope} delivery`, {
+            code: 'events.player-slot',
+            frame: record.frame,
+        });
+    }
+    if (!Number.isInteger(record.playerSlot) || record.playerSlot < 0) {
+        throw new errors_js_1.SyncplayError('Event playerSlot must be a non-negative integer', {
+            code: 'events.player-slot',
+            frame: record.frame,
+            slot: record.playerSlot,
+        });
+    }
+    return scope === 'local' ? record.playerSlot === localSlot : record.playerSlot !== localSlot;
+}
+function makeDedupeKey(eventId, frame, payload, notHashedKeys = []) {
+    return `${eventId}:${frame}:${(0, canonical_js_1.defaultChecksum)(stripNotHashedPayloadKeys(payload, notHashedKeys))}`;
+}
+function stripNotHashedPayloadKeys(payload, notHashedKeys) {
+    if (notHashedKeys.length === 0 || payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+        return payload;
+    }
+    const ignored = new Set(notHashedKeys);
+    const source = payload;
+    const stripped = {};
+    for (const key of stableRecordKeys(source)) {
+        if (!ignored.has(key)) {
+            stripped[key] = source[key];
+        }
+    }
+    return stripped;
+}
+function validateEvent(eventId, frame) {
+    if (eventId.length === 0) {
+        throw new errors_js_1.SyncplayError('eventId is required', { code: 'events.event-id' });
+    }
+    (0, canonical_js_1.canonicalStringify)(eventId);
+    validateFrame(frame);
+}
+function validateFrame(frame) {
+    if (!Number.isInteger(frame) || frame < 0) {
+        throw new errors_js_1.SyncplayError('Event frame must be a non-negative integer', {
+            code: 'events.frame',
+            frame,
+        });
+    }
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function stableRecordKeys(record) {
+    return Reflect.ownKeys(record)
+        .filter((key) => typeof key === 'string')
+        .sort(compareStrings);
+}

package/dist/cjs/examples/counter-duel.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.counterDuelDefaultInput = void 0;
+exports.createCounterDuelSession = createCounterDuelSession;
+exports.runCounterDuelExample = runCounterDuelExample;
+exports.verifyCounterDuelReplay = verifyCounterDuelReplay;
+exports.makeCounterDuelInput = makeCounterDuelInput;
+const canonical_js_1 = require("../canonical.js");
+const events_js_1 = require("../events.js");
+const offline_session_js_1 = require("../offline-session.js");
+const random_js_1 = require("../random.js");
+const replay_js_1 = require("../replay.js");
+exports.counterDuelDefaultInput = {
+    attack: false,
+    targetSlot: 0,
+};
+function createCounterDuelSession(players, seed, options = {}) {
+    return (0, offline_session_js_1.createOfflineSession)({
+        tickRate: 30,
+        playerCount: players,
+        initialState: createInitialCounterDuelState(players),
+        step: counterDuelStep,
+        defaultInput: exports.counterDuelDefaultInput,
+        inputSchemaId: 'counter-duel-input/v1',
+        stateSchemaId: 'counter-duel-state/v1',
+        deterministicVersion: 'counter-duel@1',
+        randomSeed: seed,
+        snapshotBufferSize: options.snapshotBufferSize,
+        replayRecordingMode: options.replayRecordingMode,
+    });
+}
+function runCounterDuelExample(options) {
+    validateCounterDuelOptions(options);
+    const session = createCounterDuelSession(options.players, options.seed);
+    const inputRandom = new random_js_1.DeterministicRandom(options.seed);
+    const eventTimeline = (0, events_js_1.createDeterministicEventTimeline)();
+    for (let frame = 0; frame < options.frames; frame += 1) {
+        const previousState = session.getState();
+        const frameInputs = Array.from({ length: options.players }, (_, slot) => makeCounterDuelInput(inputRandom, options.players, slot));
+        for (let slot = 0; slot < options.players; slot += 1) {
+            session.setInput(slot, frameInputs[slot]);
+        }
+        session.stepFrames(1);
+        const nextState = session.getState();
+        for (let slot = 0; slot < options.players; slot += 1) {
+            if (frameInputs[slot].attack && previousState.cooldown[slot] === 0) {
+                const target = normalizeTarget(frameInputs[slot].targetSlot, options.players, slot);
+                eventTimeline.emitVerifiedOnly('counter-duel.hit', nextState.frame, {
+                    attacker: slot,
+                    target,
+                    score: nextState.score[slot],
+                });
+            }
+        }
+    }
+    const replay = session.exportReplay();
+    if (options.verify === true) {
+        verifyCounterDuelReplay(replay);
+    }
+    const finalChecksum = replay.checksums.at(-1)?.checksum ?? (0, canonical_js_1.defaultChecksum)(session.getState());
+    return {
+        frames: options.frames,
+        players: options.players,
+        events: eventTimeline.records().length,
+        replayChecksums: replay.checksums.length,
+        finalChecksum,
+        verified: options.verify === true,
+        result: 'pass',
+        replay,
+        eventTimeline: eventTimeline.records(),
+    };
+}
+function verifyCounterDuelReplay(replay) {
+    const result = (0, replay_js_1.verifyReplay)({
+        replay,
+        step: counterDuelStep,
+        defaultInput: exports.counterDuelDefaultInput,
+        inputSchemaId: 'counter-duel-input/v1',
+        stateSchemaId: 'counter-duel-state/v1',
+        deterministicVersion: 'counter-duel@1',
+        hydrateInput: hydrateCounterDuelInput,
+    });
+    if (result.mismatches !== 0) {
+        throw new Error(`Counter Duel replay mismatch: ${result.mismatches}`);
+    }
+}
+function createInitialCounterDuelState(players) {
+    return {
+        frame: 0,
+        health: Array.from({ length: players }, () => 3),
+        score: Array.from({ length: players }, () => 0),
+        cooldown: Array.from({ length: players }, () => 0),
+    };
+}
+function counterDuelStep(state, inputs) {
+    const health = [...state.health];
+    const score = [...state.score];
+    const cooldown = state.cooldown.map((value) => Math.max(0, value - 1));
+    for (let slot = 0; slot < inputs.length; slot += 1) {
+        const input = inputs[slot];
+        if (!input.attack || cooldown[slot] > 0) {
+            continue;
+        }
+        const target = normalizeTarget(input.targetSlot, inputs.length, slot);
+        health[target] -= 1;
+        cooldown[slot] = 12;
+        if (health[target] <= 0) {
+            score[slot] += 1;
+            health[target] = 3;
+        }
+    }
+    return {
+        frame: state.frame + 1,
+        health,
+        score,
+        cooldown,
+    };
+}
+function makeCounterDuelInput(random, players, slot) {
+    const attackRoll = random.nextInt(0, 99);
+    return {
+        attack: attackRoll < 15,
+        targetSlot: findLastTarget(slot, players),
+    };
+}
+function findLastTarget(slot, players) {
+    return (slot + 1) % players;
+}
+function normalizeTarget(targetSlot, players, selfSlot) {
+    if (!Number.isInteger(targetSlot) || targetSlot < 0 || targetSlot >= players || targetSlot === selfSlot) {
+        return (selfSlot + 1) % players;
+    }
+    return targetSlot;
+}
+function hydrateCounterDuelInput(recordedInput) {
+    if (recordedInput === null ||
+        typeof recordedInput !== 'object' ||
+        typeof recordedInput.attack !== 'boolean' ||
+        typeof recordedInput.targetSlot !== 'number') {
+        throw new Error('Invalid Counter Duel replay input');
+    }
+    return {
+        attack: recordedInput.attack,
+        targetSlot: recordedInput.targetSlot,
+    };
+}
+function validateCounterDuelOptions(options) {
+    if (!Number.isInteger(options.players) || options.players < 2 || options.players > 8) {
+        throw new Error('Counter Duel requires 2 to 8 players');
+    }
+    if (!Number.isInteger(options.frames) || options.frames < 1) {
+        throw new Error('Counter Duel requires at least one frame');
+    }
+    if (!Number.isInteger(options.seed)) {
+        throw new Error('Counter Duel seed must be an integer');
+    }
+}