@series-inc/rundot-syncplay 5.23.0 → 5.24.0-beta.1

package/dist/cjs/networked-client.js

@@ -6,6 +6,7 @@ const errors_js_1 = require("./errors.js");
 const local_authority_wire_js_1 = require("./local-authority-wire.js");
 const session_snapshot_js_1 = require("./session-snapshot.js");
 const session_wire_js_1 = require("./session-wire.js");
+const secret_client_js_1 = require("./secret-client.js");
 const DEFAULT_MSG_TYPE = 'rdm';
 const DEFAULT_MAX_PREDICTION = 8;
 const DEFAULT_CHECKSUM_CADENCE_TICKS = 120;
@@ -82,6 +83,9 @@ function createNetworkedSyncplayClient(options) {
     const ownInputs = new Map();
     const confirmed = new Map();
     let lastConfirmedBySlot = [];
+    let confirmationQueue;
+    let secretFailure;
+    let secrets;
     // M5.5 snapshot late-join state: identities from session-start (descriptor)
     // and the session config (schema), the donor upload queue, and the joiner's
     // transfer collector.
@@ -147,12 +151,25 @@ function createNetworkedSyncplayClient(options) {
         }
         else if (message.kind === 'confirmed-input') {
             observeAuthorityTick(message.authorityTick, wallClock());
-            applyConfirmedFrames(message.frames);
+            receiveConfirmedFrames(message.frames);
         }
         else if (message.kind === 'time-sync-pong') {
             handleTimeSyncPong(message.nonce, message.authorityTick);
         }
     });
+    // Attach the public channel first: both channels may have buffered their
+    // join-time greetings, and secret-start is bound to the slot established by
+    // session-start. Flushing the private channel first would reject an honest
+    // greeting against the initial slot -1.
+    secrets = (0, secret_client_js_1.createSyncplaySecretsClient)({
+        transport: options.transport,
+        connection: () => ({
+            playerId: options.playerId ?? options.transport.playerId,
+            slot,
+            role,
+        }),
+        ...(options.secretCrypto === undefined ? {} : { crypto: options.secretCrypto }),
+    });
     // ── G1: authority-clock estimation + drift-corrected timescale ──
     function handleTimeSyncPong(nonce, authorityTick) {
         const sentAtMs = pendingPings.get(nonce);
@@ -278,7 +295,7 @@ function createNetworkedSyncplayClient(options) {
     function inputForSlot(targetSlot, tick) {
         const conf = confirmed.get(tick);
         if (conf !== undefined) {
-            return conf[targetSlot];
+            return conf.inputs[targetSlot];
         }
         if (targetSlot === slot) {
             // Scheduled by the cursor (possibly delay-shifted). A tick with no
@@ -323,7 +340,8 @@ function createNetworkedSyncplayClient(options) {
             inputs.push(encoded);
             active.setInput(s, decodeInputSafe(encoded));
         }
-        timeline[tick] = inputs;
+        timeline[tick] = { inputs, commands: [] };
+        active.recordCommands([]);
         active.stepFrames(1);
         predictedThrough = tick + 1;
     }
@@ -340,11 +358,15 @@ function createNetworkedSyncplayClient(options) {
                 inputs.push(encoded);
                 active.setInput(s, decodeInputSafe(encoded));
             }
-            timeline[tick] = inputs;
+            const commands = confirmed.get(tick)?.commands ?? [];
+            timeline[tick] = { inputs, commands };
+            active.recordCommands(commands);
             active.stepFrames(1);
         }
     }
     function pump() {
+        if (secretFailure)
+            throw secretFailure;
         if (session === undefined) {
             return;
         }
@@ -354,6 +376,8 @@ function createNetworkedSyncplayClient(options) {
         }
     }
     function pumpPaced(nowMs) {
+        if (secretFailure)
+            throw secretFailure;
         flushOutgoingTransfer();
         maybeSendPing(nowMs);
         if (session === undefined || frameMs <= 0) {
@@ -394,20 +418,43 @@ function createNetworkedSyncplayClient(options) {
             return '';
         }
         active.restoreToFrame(frame);
-        return String((0, canonical_js_1.defaultChecksum)(active.getState()));
+        return active.getWireStateChecksum(frame);
+    }
+    function receiveConfirmedFrames(frames) {
+        const containsSecretCommands = frames.some((frame) => (frame.commands ?? []).some((command) => (command !== null && typeof command === 'object' && !Array.isArray(command)
+            && typeof command.kind === 'string'
+            && command.kind.startsWith('syncplay.'))));
+        if (!containsSecretCommands && confirmationQueue === undefined) {
+            applyConfirmedFrames(frames);
+            return;
+        }
+        const prior = confirmationQueue ?? Promise.resolve();
+        const next = prior.then(async () => {
+            for (const frame of frames)
+                await secrets.acceptConfirmedCommands(frame.commands ?? []);
+            applyConfirmedFrames(frames);
+        });
+        confirmationQueue = next;
+        void next.catch((error) => {
+            secretFailure = error instanceof Error ? error : new Error('signature-invalid');
+        }).finally(() => {
+            if (confirmationQueue === next)
+                confirmationQueue = undefined;
+        });
     }
     function applyConfirmedFrames(frames) {
         for (const frame of frames) {
             if (frame.tick > appliedThrough) {
-                confirmed.set(frame.tick, frame.inputs);
+                confirmed.set(frame.tick, { inputs: frame.inputs, commands: frame.commands ?? [] });
             }
         }
         while (confirmed.has(appliedThrough + 1)) {
             const tick = appliedThrough + 1;
-            const confInputs = confirmed.get(tick);
-            const predInputs = timeline[tick];
-            if (predInputs === undefined || (0, canonical_js_1.canonicalStringify)(confInputs) !== (0, canonical_js_1.canonicalStringify)(predInputs)) {
-                timeline[tick] = confInputs.slice();
+            const confFrame = confirmed.get(tick);
+            const confInputs = confFrame.inputs;
+            const predFrame = timeline[tick];
+            if (predFrame === undefined || (0, canonical_js_1.canonicalStringify)(confFrame) !== (0, canonical_js_1.canonicalStringify)(predFrame)) {
+                timeline[tick] = { inputs: confInputs.slice(), commands: confFrame.commands };
                 if (predictedThrough > tick) {
                     // Rollback: we had already predicted this tick and the confirmed inputs differ.
                     rollbacks += 1;
@@ -457,9 +504,9 @@ function createNetworkedSyncplayClient(options) {
     /**
      * Report the confirmed-state checksum at `tick`, read from the rolling
      * snapshot buffer — NOT via restoreToFrame, which would rewind the live
-     * session out from under prediction. Buffer state is the serialize
-     * round-trip of the live state, i.e. exactly what a snapshot joiner will
-     * hydrate, so quorum comparisons are round-trip-consistent by construction.
+     * session out from under prediction. Quorum consistency comes from the wire
+     * checksum's full-state serialize/deserialize round-trip; synctest's codec
+     * phase verifies that round-trip is canonical on every retained frame.
      * Ticks that fell out of the buffer are skipped (the client simply is not
      * donor-eligible for them).
      */
@@ -469,7 +516,7 @@ function createNetworkedSyncplayClient(options) {
         if (active === undefined || tick < 0 || role === 'spectator') {
             return;
         }
-        const snapshot = active.getSnapshot(tick + 1);
+        const snapshot = active.peekSnapshot(tick + 1);
         if (snapshot === undefined) {
             return;
         }
@@ -477,7 +524,7 @@ function createNetworkedSyncplayClient(options) {
             kind: 'checksum-report',
             slot,
             tick,
-            checksum: (0, canonical_js_1.defaultChecksum)(snapshot.state),
+            checksum: active.getWireStateChecksum(snapshot.frame),
         }));
         reportedTicks.push(tick);
         if (reportedTicks.length > REPORTED_TICKS_RETAINED) {
@@ -531,8 +578,8 @@ function createNetworkedSyncplayClient(options) {
         const minTick = minFrame - 1;
         const candidates = reportedTicks.filter((tick) => tick >= minTick).sort((a, b) => a - b);
         for (const tick of candidates) {
-            const snapshot = active.getSnapshot(tick + 1);
-            const confirmedAtTick = timeline[tick];
+            const snapshot = active.peekSnapshot(tick + 1);
+            const confirmedAtTick = timeline[tick]?.inputs;
             if (snapshot === undefined || confirmedAtTick === undefined) {
                 continue;
             }
@@ -540,9 +587,9 @@ function createNetworkedSyncplayClient(options) {
                 v: 1,
                 tick,
                 sessionFrame: tick + 1,
-                stateBytes: (0, session_snapshot_js_1.bytesToBase64)(snapshot.stateBytes),
+                stateBytes: (0, session_snapshot_js_1.bytesToBase64)(active.getSnapshotBytes(snapshot.frame)),
                 randomState: snapshot.randomState,
-                stateChecksum: (0, canonical_js_1.defaultChecksum)(snapshot.state),
+                stateChecksum: active.getWireStateChecksum(snapshot.frame),
                 confirmedInputs: confirmedAtTick.map((input) => (0, canonical_js_1.cloneCanonical)(input)),
             });
             donorTransferCounter += 1;
@@ -613,6 +660,8 @@ function createNetworkedSyncplayClient(options) {
             randomState: snapshot.randomState,
             inputs: snapshot.confirmedInputs.map((input) => decodeInputSafe(input)),
         });
+        // The active state was just deserialized, so this is already the same
+        // round-tripped full-state basis used by the donor's wire checksum.
         const actualChecksum = (0, canonical_js_1.defaultChecksum)(active.getState());
         if (actualChecksum !== snapshot.stateChecksum) {
             throw new errors_js_1.SyncplayError('Hydrated snapshot state does not match its declared checksum', {
@@ -627,7 +676,7 @@ function createNetworkedSyncplayClient(options) {
         ownScheduleCursor = Math.max(ownScheduleCursor, snapshot.tick + 1);
         lastConfirmedBySlot = snapshot.confirmedInputs.map((input) => (0, canonical_js_1.cloneCanonical)(input));
         timeline.length = 0;
-        timeline[snapshot.tick] = lastConfirmedBySlot.slice();
+        timeline[snapshot.tick] = { inputs: lastConfirmedBySlot.slice(), commands: [] };
         for (const key of [...ownInputs.keys()]) {
             if (key <= snapshot.tick)
                 ownInputs.delete(key);
@@ -669,6 +718,7 @@ function createNetworkedSyncplayClient(options) {
                 maxRollbackDepth,
             };
         },
+        secrets,
         whenReady() {
             return readyPromise;
         },

package/dist/cjs/node.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stableEngineParityJson = exports.runEngineParitySuite = exports.explainEngineParityFixture = exports.runChaosCertificationSuite = exports.explainChaosFixture = exports.startLocalWebSocketProtocolServer = exports.runLocalWebSocketAdapterTest = exports.runNetworkedInputAuthoritySpike = exports.defaultNetworkedInputAuthoritySpikeOptions = exports.verifyReplayScoreAgainstTrustedRuntime = exports.verifyReplay = exports.createSyncplaySession = exports.createOfflineSession = void 0;
+exports.cookConvexDecomposition = exports.assertCookedColliderIsRuntimeValid = exports.stableEngineParityJson = exports.runEngineParitySuite = exports.explainEngineParityFixture = exports.runChaosCertificationSuite = exports.explainChaosFixture = exports.startLocalWebSocketProtocolServer = exports.runLocalWebSocketAdapterTest = exports.runNetworkedInputAuthoritySpike = exports.defaultNetworkedInputAuthoritySpikeOptions = exports.verifySyncplaySignedReceipt = exports.verifyMerkleProof = exports.verifyHashChainReveal = exports.signedReceiptBytes = exports.sha256Bytes = exports.merkleProof = exports.merkleNodeHash = exports.merkleLeafHash = exports.hexToBytes = exports.createBrowserSyncplaySecretCrypto = exports.constantTimeEqual = exports.concatBytes = exports.bytesToHex = exports.buildMerkleTree = exports.verifyReplayScoreAgainstTrustedRuntime = exports.verifyReplay = exports.createSyncplaySession = exports.createOfflineSession = void 0;
 __exportStar(require("./multiplayer-service.js"), exports);
 __exportStar(require("./input-authority.js"), exports);
 __exportStar(require("./local-authority-wire.js"), exports);
@@ -35,6 +35,24 @@ var replay_bundle_js_1 = require("./replay-bundle.js");
 Object.defineProperty(exports, "verifyReplayScoreAgainstTrustedRuntime", { enumerable: true, get: function () { return replay_bundle_js_1.verifyReplayScoreAgainstTrustedRuntime; } });
 __exportStar(require("./match-log.js"), exports);
 __exportStar(require("./authority-room.js"), exports);
+__exportStar(require("./secret-config.js"), exports);
+__exportStar(require("./secret-protocol.js"), exports);
+var secret_crypto_js_1 = require("./secret-crypto.js");
+Object.defineProperty(exports, "buildMerkleTree", { enumerable: true, get: function () { return secret_crypto_js_1.buildMerkleTree; } });
+Object.defineProperty(exports, "bytesToHex", { enumerable: true, get: function () { return secret_crypto_js_1.bytesToHex; } });
+Object.defineProperty(exports, "concatBytes", { enumerable: true, get: function () { return secret_crypto_js_1.concatBytes; } });
+Object.defineProperty(exports, "constantTimeEqual", { enumerable: true, get: function () { return secret_crypto_js_1.constantTimeEqual; } });
+Object.defineProperty(exports, "createBrowserSyncplaySecretCrypto", { enumerable: true, get: function () { return secret_crypto_js_1.createBrowserSyncplaySecretCrypto; } });
+Object.defineProperty(exports, "hexToBytes", { enumerable: true, get: function () { return secret_crypto_js_1.hexToBytes; } });
+Object.defineProperty(exports, "merkleLeafHash", { enumerable: true, get: function () { return secret_crypto_js_1.merkleLeafHash; } });
+Object.defineProperty(exports, "merkleNodeHash", { enumerable: true, get: function () { return secret_crypto_js_1.merkleNodeHash; } });
+Object.defineProperty(exports, "merkleProof", { enumerable: true, get: function () { return secret_crypto_js_1.merkleProof; } });
+Object.defineProperty(exports, "sha256Bytes", { enumerable: true, get: function () { return secret_crypto_js_1.sha256Bytes; } });
+Object.defineProperty(exports, "signedReceiptBytes", { enumerable: true, get: function () { return secret_crypto_js_1.signedReceiptBytes; } });
+Object.defineProperty(exports, "verifyHashChainReveal", { enumerable: true, get: function () { return secret_crypto_js_1.verifyHashChainReveal; } });
+Object.defineProperty(exports, "verifyMerkleProof", { enumerable: true, get: function () { return secret_crypto_js_1.verifyMerkleProof; } });
+Object.defineProperty(exports, "verifySyncplaySignedReceipt", { enumerable: true, get: function () { return secret_crypto_js_1.verifySyncplaySignedReceipt; } });
+__exportStar(require("./secret-authority.js"), exports);
 __exportStar(require("./ws-frame.js"), exports);
 var networked_input_authority_js_1 = require("./networked-input-authority.js");
 Object.defineProperty(exports, "defaultNetworkedInputAuthoritySpikeOptions", { enumerable: true, get: function () { return networked_input_authority_js_1.defaultNetworkedInputAuthoritySpikeOptions; } });
@@ -49,3 +67,7 @@ var engine_parity_js_1 = require("./engine-parity.js");
 Object.defineProperty(exports, "explainEngineParityFixture", { enumerable: true, get: function () { return engine_parity_js_1.explainEngineParityFixture; } });
 Object.defineProperty(exports, "runEngineParitySuite", { enumerable: true, get: function () { return engine_parity_js_1.runEngineParitySuite; } });
 Object.defineProperty(exports, "stableEngineParityJson", { enumerable: true, get: function () { return engine_parity_js_1.stableEngineParityJson; } });
+// Offline collider cooking — build-time only, never part of a simulation step.
+var collider_cooking_js_1 = require("./collider-cooking.js");
+Object.defineProperty(exports, "assertCookedColliderIsRuntimeValid", { enumerable: true, get: function () { return collider_cooking_js_1.assertCookedColliderIsRuntimeValid; } });
+Object.defineProperty(exports, "cookConvexDecomposition", { enumerable: true, get: function () { return collider_cooking_js_1.cookConvexDecomposition; } });

package/dist/cjs/offline-session.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createOfflineSession = createOfflineSession;
 const canonical_js_1 = require("./canonical.js");
+const checksum_basis_js_1 = require("./checksum-basis.js");
 const errors_js_1 = require("./errors.js");
 const math_js_1 = require("./math.js");
 const random_js_1 = require("./random.js");
@@ -14,6 +15,8 @@ function createOfflineSession(config) {
     const randomSeed = config.randomSeed ?? 1;
     const fixedFrameMs = 1000 / config.tickRate;
     const math = (0, math_js_1.createDeterministicMath)();
+    // LOAD-BEARING: these two clones make frame-0 reference retention private to
+    // each session and insulate exportReplay's initialState.
     const initialState = (0, canonical_js_1.cloneCanonical)(config.initialState);
     const mutable = {
         frame: 0,
@@ -165,20 +168,39 @@ function createOfflineSession(config) {
                 ],
             };
         },
+        peekSnapshot(frame) {
+            return mutable.snapshots.get(frame);
+        },
         getSnapshot(frame) {
             const snapshot = mutable.snapshots.get(frame);
             return snapshot === undefined ? undefined : cloneSnapshot(snapshot);
         },
+        getSnapshotBytes(frame) {
+            return (0, checksum_basis_js_1.serializeStateWith)(config, requireSnapshot(mutable, frame).state);
+        },
+        exportExternalSnapshot(frame) {
+            const snapshot = requireSnapshot(mutable, frame);
+            return {
+                frame: snapshot.frame,
+                stateBytes: (0, checksum_basis_js_1.serializeStateWith)(config, snapshot.state),
+                randomState: snapshot.randomState,
+                inputs: snapshot.inputs.map((input) => cloneInput(config, input)),
+            };
+        },
+        getRecordedChecksum(frame) {
+            return requireSnapshot(mutable, frame).checksum;
+        },
+        computeRecordedChecksum(frame) {
+            const snapshot = requireSnapshot(mutable, frame);
+            return snapshot.checksum ?? getChecksum(config, snapshot.state);
+        },
+        getWireStateChecksum(frame) {
+            return (0, checksum_basis_js_1.computeWireStateChecksum)(config, requireSnapshot(mutable, frame).state);
+        },
         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,
-                });
-            }
+            const snapshot = requireSnapshot(mutable, frame);
             mutable.frame = snapshot.frame;
-            mutable.state = (0, canonical_js_1.cloneCanonical)(snapshot.state);
+            mutable.state = 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 });
@@ -193,7 +215,7 @@ function createOfflineSession(config) {
             (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.state = (0, checksum_basis_js_1.deserializeStateWith)(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 });
@@ -205,13 +227,16 @@ function createOfflineSession(config) {
             mutable.snapshots = new Map();
             mutable.snapshotOrder = [];
             hydratedFromExternalSnapshot = true;
-            recordSnapshot(config, mutable, snapshotBufferSize);
+            const hydratedChecksum = mutable.frame % checksumInterval === 0
+                ? getChecksum(config, mutable.state)
+                : undefined;
+            recordSnapshot(config, mutable, snapshotBufferSize, hydratedChecksum);
         },
         getSnapshotFrames() {
             return [...mutable.snapshotOrder];
         },
     };
-    recordSnapshot(config, mutable, snapshotBufferSize);
+    recordSnapshot(config, mutable, snapshotBufferSize, getChecksum(config, mutable.state));
     return session;
 }
 function runFrames(config, mutable, checksumInterval, snapshotBufferSize, replayRecordingMode, math, count) {
@@ -251,8 +276,10 @@ function runFrames(config, mutable, checksumInterval, snapshotBufferSize, replay
                 ? (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 checksum = mutable.frame % checksumInterval === 0
+            ? getChecksum(config, mutable.state)
+            : undefined;
+        if (checksum !== undefined) {
             const checksumRecord = { frame: mutable.frame, checksum };
             config.onChecksumRecorded?.(checksumRecord);
             if (replayRecordingMode === 'memory') {
@@ -322,26 +349,28 @@ function pruneSnapshotsAfterFrame(mutable, frame) {
         return true;
     });
 }
+function requireSnapshot(mutable, 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,
+        });
+    }
+    return snapshot;
+}
 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,
+        checksum,
+        state: mutable.state,
         randomState: mutable.random.snapshot().state,
     };
     const alreadyStored = mutable.snapshots.has(snapshot.frame);
@@ -364,7 +393,6 @@ function cloneSnapshot(snapshot) {
         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/physics-cert.js

@@ -62,7 +62,7 @@ function runPhysicsCert(options) {
         snapshotHashStable;
     return {
         engine: options.engine,
-        engineVersion: options.engine === 'builtin-rigid' ? 'builtin-rigid@1' : 'builtin-fixed@1',
+        engineVersion: options.engine === 'builtin-rigid' ? 'builtin-rigid@2' : 'builtin-fixed@1',
         adapterVersion: 'physics-cert@1',
         shape: options.shape,
         players: options.players,
@@ -319,13 +319,18 @@ function buildRigidArena(options) {
         // hinge door
         bodies.push({ id: `frame-${slot}`, kind: 'static', x: baseX + 3, y: 2, z: 0, vx: 0, vy: 0, vz: 0, shape: { type: 'box', halfX: 0.1, halfY: 0.5, halfZ: 0.5 }, layer: 1, mask: 1 });
         bodies.push({ id: `door-${slot}`, kind: 'dynamic', x: baseX + 4, y: 2, z: 0, vx: 0, vy: 0, vz: 0, mass: 1, orientation: ident, angularVel: { x: 0, y: 0, z: 0 }, shape: { type: 'box', halfX: 1, halfY: 0.5, halfZ: 0.1 }, layer: 1, mask: 1 });
-        joints.push({ id: `hinge-${slot}`, type: 'hinge', a: `frame-${slot}`, b: `door-${slot}`, anchorA: { x: 0, y: 0, z: 0 }, anchorB: { x: -1, y: 0, z: 0 }, axisA: { x: 0, y: 1, z: 0 }, motorSpeed: 0.02, maxMotorTorque: 50 });
+        joints.push({ id: `hinge-${slot}`, type: 'hinge', a: `frame-${slot}`, b: `door-${slot}`, anchorA: { x: 0, y: 0, z: 0 }, anchorB: { x: -1, y: 0, z: 0 }, axisA: { x: 0, y: 1, z: 0 }, motorSpeed: 0.02, maxMotorTorque: 50, disableCollision: true });
         // grab-target box
         bodies.push({ id: `grab-${slot}`, kind: 'dynamic', x: baseX + 6, y: 3, z: 0, vx: 0, vy: 0, vz: 0, mass: 1, orientation: ident, angularVel: { x: 0, y: 0, z: 0 }, shape: { type: 'box', halfX: 0.5, halfY: 0.5, halfZ: 0.5 }, layer: 1, mask: 1 });
         joints.push({ id: `carry-${slot}`, type: 'grab', body: `grab-${slot}`, anchor: { x: 0, y: 0, z: 0 }, targetX: baseX + 6, targetY: 4, targetZ: 0, maxForce: 20 });
         // ccd projectile toward a thin wall
         bodies.push({ id: `wall-${slot}`, kind: 'static', x: baseX + 9, y: 2, z: 0, vx: 0, vy: 0, vz: 0, shape: { type: 'box', halfX: 0.05, halfY: 2, halfZ: 2 }, layer: 1, mask: 1 });
-        bodies.push({ id: `bullet-${slot}`, kind: 'dynamic', x: baseX - 20, y: 2, z: 0, vx: 60, vy: 0, vz: 0, mass: 1, orientation: ident, angularVel: { x: 0, y: 0, z: 0 }, ccd: true, linearDamping: 1, angularDamping: 1, shape: { type: 'box', halfX: 0.2, halfY: 0.2, halfZ: 0.2 }, layer: 1, mask: 1 });
+        // vx 8 tunnels the 0.1-thick wall per step without CCD, so this exercises the
+        // exact-TOI ccd path while staying a settling-scale impact the convergence gate can
+        // reach. The extreme-speed case (vx 60 into a stack) is finiteness/determinism-tested
+        // in physics3d-ccd.test.ts — a physical punch-through does not re-settle, so it cannot
+        // live in a convergence budget.
+        bodies.push({ id: `bullet-${slot}`, kind: 'dynamic', x: baseX - 20, y: 2, z: 0, vx: 8, vy: 0, vz: 0, mass: 1, orientation: ident, angularVel: { x: 0, y: 0, z: 0 }, ccd: true, linearDamping: 1, angularDamping: 1, shape: { type: 'box', halfX: 0.2, halfY: 0.2, halfZ: 0.2 }, layer: 1, mask: 1 });
         // soft spring: bob hung 2 below a static anchor, restLength 1 → oscillates and settles
         bodies.push({ id: `spring-anchor-${slot}`, kind: 'static', x: baseX + 2, y: 6, z: 3, vx: 0, vy: 0, vz: 0, shape: { type: 'box', halfX: 0.1, halfY: 0.1, halfZ: 0.1 }, layer: 2, mask: 2 });
         bodies.push({ id: `spring-bob-${slot}`, kind: 'dynamic', x: baseX + 2, y: 4, z: 3, vx: 0, vy: 0, vz: 0, mass: 1, orientation: ident, angularVel: { x: 0, y: 0, z: 0 }, shape: { type: 'box', halfX: 0.3, halfY: 0.3, halfZ: 0.3 }, layer: 2, mask: 2 });

package/dist/cjs/physics3d-heightfield.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.heightfieldLocalBounds = heightfieldLocalBounds;
+exports.heightfieldLocalTriangles = heightfieldLocalTriangles;
+function heightfieldLocalBounds(shape) {
+    let minHeight = shape.heights[0];
+    let maxHeight = shape.heights[0];
+    for (const height of shape.heights) {
+        minHeight = Math.min(minHeight, height);
+        maxHeight = Math.max(maxHeight, height);
+    }
+    return {
+        minX: 0,
+        maxX: (shape.columns - 1) * shape.scale.x,
+        minY: minHeight * shape.scale.y,
+        maxY: maxHeight * shape.scale.y,
+        minZ: 0,
+        maxZ: (shape.rows - 1) * shape.scale.z,
+    };
+}
+function vertex(shape, column, row) {
+    return {
+        x: column * shape.scale.x,
+        y: shape.heights[row * shape.columns + column] * shape.scale.y,
+        z: row * shape.scale.z,
+    };
+}
+function heightfieldLocalTriangles(shape, bounds) {
+    const minColumn = bounds === undefined ? 0 : Math.max(0, Math.floor(bounds.minX / shape.scale.x));
+    const maxColumn = bounds === undefined
+        ? shape.columns - 2
+        : Math.min(shape.columns - 2, Math.ceil(bounds.maxX / shape.scale.x));
+    const minRow = bounds === undefined ? 0 : Math.max(0, Math.floor(bounds.minZ / shape.scale.z));
+    const maxRow = bounds === undefined
+        ? shape.rows - 2
+        : Math.min(shape.rows - 2, Math.ceil(bounds.maxZ / shape.scale.z));
+    if (minColumn > maxColumn || minRow > maxRow) {
+        return [];
+    }
+    const triangles = [];
+    for (let row = minRow; row <= maxRow; row += 1) {
+        for (let column = minColumn; column <= maxColumn; column += 1) {
+            const a = vertex(shape, column, row);
+            const b = vertex(shape, column, row + 1);
+            const c = vertex(shape, column + 1, row);
+            const d = vertex(shape, column + 1, row + 1);
+            triangles.push([a, b, c], [d, c, b]);
+        }
+    }
+    return triangles;
+}