@woosh/meep-engine 2.156.0 → 2.157.0

package/src/engine/physics/ecs/RigidBodyFlags.d.ts

@@ -3,9 +3,12 @@
  *
  * - {@link IsSensor }: contacts are detected and events fired, but no impulses are
  *   applied. Useful for triggers.
- * - {@link LockRotX }/{@link LockRotY }/{@link LockRotZ }: the corresponding angular
- *   degree of freedom is fixed. Implemented by zeroing the matching inverse-inertia
- *   component during solve.
+ * - {@link LockRotX }/{@link LockRotY }/{@link LockRotZ }: the corresponding
+ *   BODY-LOCAL angular degree of freedom is fixed: the matching inverse-inertia
+ *   component is zeroed in the solver gather and in `applyImpulseAt`, so no
+ *   contact, joint, or user impulse can rotate the body about that local axis.
+ *   Locking does not cancel a pre-existing angular velocity about the axis —
+ *   zero `angularVelocity` yourself when locking a body mid-spin.
  * - {@link DisableSleep }: this body never enters the sleeping set. Bodies near it
  *   may still sleep when stable.
  * - {@link CCD }: opt-in continuous collision detection. After the solver, the

package/src/engine/physics/ecs/RigidBodyFlags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RigidBodyFlags.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/RigidBodyFlags.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;6BAiBU,MAAM"}
+{"version":3,"file":"RigidBodyFlags.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/RigidBodyFlags.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;6BAoBU,MAAM"}

package/src/engine/physics/ecs/RigidBodyFlags.js

@@ -1,28 +1,31 @@
-/**
- * Bit-flags carried on {@link RigidBody}.
- *
- * - {@link IsSensor}: contacts are detected and events fired, but no impulses are
- *   applied. Useful for triggers.
- * - {@link LockRotX}/{@link LockRotY}/{@link LockRotZ}: the corresponding angular
- *   degree of freedom is fixed. Implemented by zeroing the matching inverse-inertia
- *   component during solve.
- * - {@link DisableSleep}: this body never enters the sleeping set. Bodies near it
- *   may still sleep when stable.
- * - {@link CCD}: opt-in continuous collision detection. After the solver, the
- *   body's net step translation is shape-cast against the broadphase and the
- *   body is stopped at the first blocker, so a fast mover can't tunnel through
- *   thin geometry between discrete steps. Off by default — it costs one swept
- *   query per fast-moving flagged body per step. See `ccd/linear_sweep.js`.
- *
- * @readonly
- * @enum {number}
- */
-export const RigidBodyFlags = {
-    None: 0,
-    IsSensor: 1,
-    LockRotX: 2,
-    LockRotY: 4,
-    LockRotZ: 8,
-    DisableSleep: 16,
-    CCD: 32,
-};
+/**
+ * Bit-flags carried on {@link RigidBody}.
+ *
+ * - {@link IsSensor}: contacts are detected and events fired, but no impulses are
+ *   applied. Useful for triggers.
+ * - {@link LockRotX}/{@link LockRotY}/{@link LockRotZ}: the corresponding
+ *   BODY-LOCAL angular degree of freedom is fixed: the matching inverse-inertia
+ *   component is zeroed in the solver gather and in `applyImpulseAt`, so no
+ *   contact, joint, or user impulse can rotate the body about that local axis.
+ *   Locking does not cancel a pre-existing angular velocity about the axis —
+ *   zero `angularVelocity` yourself when locking a body mid-spin.
+ * - {@link DisableSleep}: this body never enters the sleeping set. Bodies near it
+ *   may still sleep when stable.
+ * - {@link CCD}: opt-in continuous collision detection. After the solver, the
+ *   body's net step translation is shape-cast against the broadphase and the
+ *   body is stopped at the first blocker, so a fast mover can't tunnel through
+ *   thin geometry between discrete steps. Off by default — it costs one swept
+ *   query per fast-moving flagged body per step. See `ccd/linear_sweep.js`.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const RigidBodyFlags = {
+    None: 0,
+    IsSensor: 1,
+    LockRotX: 2,
+    LockRotY: 4,
+    LockRotZ: 8,
+    DisableSleep: 16,
+    CCD: 32,
+};

package/src/engine/physics/ecs/RigidBodySerializationAdapter.d.ts

@@ -1,10 +1,18 @@
 /**
  * Binary serialization for {@link RigidBody}.
  *
- * Only the configurable / persistent fields are written. Transient runtime state
- * (`_bodyId`, `sleepState`, accumulated force/torque) is owned by the
- * {@link PhysicsSystem} and recomputed on link — serialising it would tie the
- * stream to a particular world instance.
+ * Only the persistent fields are written. World-instance-tied runtime state
+ * (`_bodyId`, sleep-group links, accumulated force/torque — the accumulators
+ * are consumed within the tick and are zero at any step boundary) is owned by
+ * the {@link PhysicsSystem} and recomputed on link.
+ *
+ * v1 adds `sleepState` + `sleep_timer`: sleep progress is BODY state, not
+ * world state. A reconstructed world (snapshot restore, replicated late-join)
+ * must restore sleeping bodies asleep and half-drowsy bodies half-drowsy, or
+ * it wakes/sleeps on a different schedule than the original and diverges —
+ * the reconstruction-determinism contract. {@link PhysicsSystem#link} honours
+ * the restored value. v0 streams upgrade via
+ * {@link RigidBodySerializationUpgrader_0_1}.
  */
 export class RigidBodySerializationAdapter extends BinaryClassSerializationAdapter<any> {
     constructor();

package/src/engine/physics/ecs/RigidBodySerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RigidBodySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/RigidBodySerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH;;IAEI,wBAAkB;IAClB,gBAAY;IAEZ;;;;OAIG;IACH,uCAFW,SAAS,QA0BnB;IAED;;;;OAIG;IACH,yCAFW,SAAS,QAiCnB;CACJ;gDApF+C,6DAA6D;0BACnF,gBAAgB"}
+{"version":3,"file":"RigidBodySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/RigidBodySerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH;;IAEI,wBAAkB;IAClB,gBAAY;IAEZ;;;;OAIG;IACH,uCAFW,SAAS,QA6BnB;IAED;;;;OAIG;IACH,yCAFW,SAAS,QAoCnB;CACJ;gDAlG+C,6DAA6D;0BACnF,gBAAgB"}

package/src/engine/physics/ecs/RigidBodySerializationAdapter.js

@@ -4,15 +4,23 @@ import { RigidBody } from "./RigidBody.js";
 /**
  * Binary serialization for {@link RigidBody}.
  *
- * Only the configurable / persistent fields are written. Transient runtime state
- * (`_bodyId`, `sleepState`, accumulated force/torque) is owned by the
- * {@link PhysicsSystem} and recomputed on link — serialising it would tie the
- * stream to a particular world instance.
+ * Only the persistent fields are written. World-instance-tied runtime state
+ * (`_bodyId`, sleep-group links, accumulated force/torque — the accumulators
+ * are consumed within the tick and are zero at any step boundary) is owned by
+ * the {@link PhysicsSystem} and recomputed on link.
+ *
+ * v1 adds `sleepState` + `sleep_timer`: sleep progress is BODY state, not
+ * world state. A reconstructed world (snapshot restore, replicated late-join)
+ * must restore sleeping bodies asleep and half-drowsy bodies half-drowsy, or
+ * it wakes/sleeps on a different schedule than the original and diverges —
+ * the reconstruction-determinism contract. {@link PhysicsSystem#link} honours
+ * the restored value. v0 streams upgrade via
+ * {@link RigidBodySerializationUpgrader_0_1}.
  */
 export class RigidBodySerializationAdapter extends BinaryClassSerializationAdapter {
 
     klass = RigidBody;
-    version = 0;
+    version = 1;
 
     /**
      *
@@ -43,6 +51,9 @@ export class RigidBodySerializationAdapter extends BinaryClassSerializationAdapt
         buffer.writeUint32(value.layer >>> 0);
         buffer.writeUint32(value.mask >>> 0);
         buffer.writeUint32(value.flags >>> 0);
+
+        buffer.writeUint8(value.sleepState);
+        buffer.writeFloat64(value.sleep_timer);
     }
 
     /**
@@ -81,5 +92,8 @@ export class RigidBodySerializationAdapter extends BinaryClassSerializationAdapt
         value.layer = buffer.readUint32() | 0;
         value.mask = buffer.readUint32() | 0;
         value.flags = buffer.readUint32() | 0;
+
+        value.sleepState = buffer.readUint8();
+        value.sleep_timer = buffer.readFloat64();
     }
 }

package/src/engine/physics/ecs/RigidBodySerializationUpgrader_0_1.d.ts

@@ -0,0 +1,10 @@
+/**
+ * v0 → v1: appends the sleep fields (`sleepState`, `sleep_timer`) that v1 of
+ * {@link RigidBodySerializationAdapter} persists. A v0 stream predates sleep
+ * persistence, so its bodies restore awake with a zero timer — exactly the
+ * pre-upgrade behaviour.
+ */
+export class RigidBodySerializationUpgrader_0_1 extends BinaryClassUpgrader {
+}
+import { BinaryClassUpgrader } from "../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=RigidBodySerializationUpgrader_0_1.d.ts.map

package/src/engine/physics/ecs/RigidBodySerializationUpgrader_0_1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RigidBodySerializationUpgrader_0_1.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/RigidBodySerializationUpgrader_0_1.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;CA4BC;oCApCmC,iDAAiD"}

package/src/engine/physics/ecs/RigidBodySerializationUpgrader_0_1.js

@@ -0,0 +1,37 @@
+import { BinaryClassUpgrader } from "../../ecs/storage/binary/BinaryClassUpgrader.js";
+
+/**
+ * v0 → v1: appends the sleep fields (`sleepState`, `sleep_timer`) that v1 of
+ * {@link RigidBodySerializationAdapter} persists. A v0 stream predates sleep
+ * persistence, so its bodies restore awake with a zero timer — exactly the
+ * pre-upgrade behaviour.
+ */
+export class RigidBodySerializationUpgrader_0_1 extends BinaryClassUpgrader {
+
+    __startVersion = 0;
+    __targetVersion = 1;
+
+    /**
+     *
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source, target) {
+        // v0 layout: kind u8, then 13 f64 (linearVelocity ×3,
+        // angularVelocity ×3, mass, inverseInertiaLocal ×3, linearDamping,
+        // angularDamping, gravityScale), then 3 u32 (layer, mask, flags).
+        target.writeUint8(source.readUint8());
+
+        for (let i = 0; i < 13; i++) {
+            target.writeFloat64(source.readFloat64());
+        }
+
+        target.writeUint32(source.readUint32());
+        target.writeUint32(source.readUint32());
+        target.writeUint32(source.readUint32());
+
+        // New in v1: sleepState (Awake = 0), sleep_timer.
+        target.writeUint8(0);
+        target.writeFloat64(0);
+    }
+}

package/src/engine/physics/ecs/find_non_finite_physics_state.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Dev-build tripwire: scan post-step physics state for non-finite values
+ * (NaN / ±Infinity) and describe the first offender, or return "" when clean.
+ *
+ * Called from `PhysicsSystem.fixedUpdate` behind an `assert.*` call (compiled
+ * out of production bundles), so the O(awake bodies + live contacts) sweep
+ * costs nothing in prod. The sweep exists because a NaN that enters the
+ * pipeline is self-concealing: NaN fails every comparison, so it passes depth
+ * early-outs, wins "deepest candidate" reductions (`min_d2` stays Infinity),
+ * and never satisfies the sleep test — it propagates silently instead of
+ * failing loudly at the source.
+ *
+ * Coverage:
+ *   - every AWAKE body's linear/angular velocity and Transform pose. Sleeping
+ *     bodies froze with state this sweep already validated (a non-finite
+ *     velocity can never pass the sleep threshold comparison), so awake-only
+ *     is exhaustive across steps.
+ *   - every live manifold slot's contact lanes (geometry, depth, feature id,
+ *     impulses, material) for its current `contact_count`.
+ *
+ * @param {PhysicsSystem} system
+ * @returns {string} "" when clean, else a description of the first non-finite value
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function find_non_finite_physics_state(system: PhysicsSystem): string;
+//# sourceMappingURL=find_non_finite_physics_state.d.ts.map

package/src/engine/physics/ecs/find_non_finite_physics_state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find_non_finite_physics_state.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/find_non_finite_physics_state.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,sEALa,MAAM,CAoDlB"}

package/src/engine/physics/ecs/find_non_finite_physics_state.js

@@ -0,0 +1,76 @@
+import { CONTACT_STRIDE } from "../contact/ManifoldStore.js";
+
+/**
+ * Dev-build tripwire: scan post-step physics state for non-finite values
+ * (NaN / ±Infinity) and describe the first offender, or return "" when clean.
+ *
+ * Called from `PhysicsSystem.fixedUpdate` behind an `assert.*` call (compiled
+ * out of production bundles), so the O(awake bodies + live contacts) sweep
+ * costs nothing in prod. The sweep exists because a NaN that enters the
+ * pipeline is self-concealing: NaN fails every comparison, so it passes depth
+ * early-outs, wins "deepest candidate" reductions (`min_d2` stays Infinity),
+ * and never satisfies the sleep test — it propagates silently instead of
+ * failing loudly at the source.
+ *
+ * Coverage:
+ *   - every AWAKE body's linear/angular velocity and Transform pose. Sleeping
+ *     bodies froze with state this sweep already validated (a non-finite
+ *     velocity can never pass the sleep threshold comparison), so awake-only
+ *     is exhaustive across steps.
+ *   - every live manifold slot's contact lanes (geometry, depth, feature id,
+ *     impulses, material) for its current `contact_count`.
+ *
+ * @param {PhysicsSystem} system
+ * @returns {string} "" when clean, else a description of the first non-finite value
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function find_non_finite_physics_state(system) {
+    const storage = system.storage;
+    const bodies = system.__bodies;
+    const transforms = system.__transforms;
+
+    const awake = storage.awake_count;
+    for (let i = 0; i < awake; i++) {
+        const idx = storage.awake_at(i);
+        const rb = bodies[idx];
+        const tr = transforms[idx];
+
+        const lv = rb.linearVelocity;
+        if (!Number.isFinite(lv[0] + lv[1] + lv[2])) {
+            return `body[${idx}].linearVelocity = (${lv[0]}, ${lv[1]}, ${lv[2]})`;
+        }
+        const av = rb.angularVelocity;
+        if (!Number.isFinite(av[0] + av[1] + av[2])) {
+            return `body[${idx}].angularVelocity = (${av[0]}, ${av[1]}, ${av[2]})`;
+        }
+
+        const p = tr.position;
+        if (!Number.isFinite(p.x + p.y + p.z)) {
+            return `body[${idx}].position = (${p.x}, ${p.y}, ${p.z})`;
+        }
+        const q = tr.rotation;
+        if (!Number.isFinite(q.x + q.y + q.z + q.w)) {
+            return `body[${idx}].rotation = (${q.x}, ${q.y}, ${q.z}, ${q.w})`;
+        }
+    }
+
+    const manifolds = system.manifolds;
+    const data = manifolds.data_buffer;
+    const live = manifolds.count;
+    for (let i = 0; i < live; i++) {
+        const slot = manifolds.live_at(i);
+        const lanes = manifolds.contact_count(slot) * CONTACT_STRIDE;
+        const off = manifolds.slot_data_offset(slot);
+        for (let k = 0; k < lanes; k++) {
+            const v = data[off + k];
+            if (!Number.isFinite(v)) {
+                return `manifold slot ${slot} (bodies ${manifolds.bodyA(slot)}/${manifolds.bodyB(slot)})`
+                    + ` contact ${(k / CONTACT_STRIDE) | 0} lane ${k % CONTACT_STRIDE} = ${v}`;
+            }
+        }
+    }
+
+    return "";
+}

package/src/engine/physics/events/ContactEventBuffer.d.ts

@@ -43,5 +43,16 @@ export class ContactEventBuffer {
     entityA_at(i: any): number;
     entityB_at(i: any): number;
     slot_at(i: any): number;
+    /**
+     * Sort events in place by `(entityA, entityB, kind)` ascending. The diff
+     * pass emits in manifold live-slot order — slot ALLOCATION history, which
+     * two engines holding identical body state need not share — so consumers
+     * (the dispatch pass → gameplay) must see a state-derived order instead.
+     * One event per pair per frame makes the entity pair a unique key; the
+     * kind tie-break only matters for records carrying `-1` (freed-body)
+     * entities. In-place insertion sort over the 4-int records: event counts
+     * are small and per-frame, and there is nothing to allocate.
+     */
+    sort_canonical(): void;
 }
 //# sourceMappingURL=ContactEventBuffer.d.ts.map

package/src/engine/physics/events/ContactEventBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContactEventBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/events/ContactEventBuffer.js"],"names":[],"mappings":";;;+BAGU,MAAM;;;;;;AAoBhB;;;;;;;;;;;GAWG;AACH;IACI;;OAEG;IACH,+BAFW,MAAM,EAOhB;IAJG,mBAA+C;IAC/C,gBAAgB;IAEhB,mBAA4D;IAGhE;;OAEG;IACH,oBAEC;IAED,cAEC;IAED;;;;;OAKG;IACH,WALW,gBAAgB,GAAC,MAAM,WACvB,MAAM,WACN,MAAM,QACN,MAAM,QAgBhB;IAED,wBAAoD;IACpD,2BAA2D;IAC3D,2BAA2D;IAC3D,wBAAwD;CAC3D"}
+{"version":3,"file":"ContactEventBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/events/ContactEventBuffer.js"],"names":[],"mappings":";;;+BAGU,MAAM;;;;;;AAoBhB;;;;;;;;;;;GAWG;AACH;IACI;;OAEG;IACH,+BAFW,MAAM,EAOhB;IAJG,mBAA+C;IAC/C,gBAAgB;IAEhB,mBAA4D;IAGhE;;OAEG;IACH,oBAEC;IAED,cAEC;IAED;;;;;OAKG;IACH,WALW,gBAAgB,GAAC,MAAM,WACvB,MAAM,WACN,MAAM,QACN,MAAM,QAgBhB;IAED,wBAAoD;IACpD,2BAA2D;IAC3D,2BAA2D;IAC3D,wBAAwD;IAExD;;;;;;;;;OASG;IACH,uBA4BC;CACJ"}

package/src/engine/physics/events/ContactEventBuffer.js

@@ -81,4 +81,44 @@ export class ContactEventBuffer {
     entityA_at(i) { return this.__data[i * EVENT_STRIDE + 1]; }
     entityB_at(i) { return this.__data[i * EVENT_STRIDE + 2]; }
     slot_at(i) { return this.__data[i * EVENT_STRIDE + 3]; }
+
+    /**
+     * Sort events in place by `(entityA, entityB, kind)` ascending. The diff
+     * pass emits in manifold live-slot order — slot ALLOCATION history, which
+     * two engines holding identical body state need not share — so consumers
+     * (the dispatch pass → gameplay) must see a state-derived order instead.
+     * One event per pair per frame makes the entity pair a unique key; the
+     * kind tie-break only matters for records carrying `-1` (freed-body)
+     * entities. In-place insertion sort over the 4-int records: event counts
+     * are small and per-frame, and there is nothing to allocate.
+     */
+    sort_canonical() {
+        const d = this.__data;
+        const n = this.__count;
+        for (let i = 1; i < n; i++) {
+            const off = i * EVENT_STRIDE;
+            const k = d[off], ea = d[off + 1], eb = d[off + 2], sl = d[off + 3];
+            let j = i - 1;
+            while (j >= 0) {
+                const joff = j * EVENT_STRIDE;
+                const jea = d[joff + 1];
+                if (jea < ea) break;
+                if (jea === ea) {
+                    const jeb = d[joff + 2];
+                    if (jeb < eb) break;
+                    if (jeb === eb && d[joff] <= k) break;
+                }
+                d[joff + EVENT_STRIDE] = d[joff];
+                d[joff + EVENT_STRIDE + 1] = jea;
+                d[joff + EVENT_STRIDE + 2] = d[joff + 2];
+                d[joff + EVENT_STRIDE + 3] = d[joff + 3];
+                j--;
+            }
+            const dest = (j + 1) * EVENT_STRIDE;
+            d[dest] = k;
+            d[dest + 1] = ea;
+            d[dest + 2] = eb;
+            d[dest + 3] = sl;
+        }
+    }
 }

package/src/engine/physics/events/diff_manifolds.d.ts

@@ -1,21 +1,38 @@
 /**
  * Walk every live manifold and produce a contact event for each pair whose
- * touched state changed (or persisted) since the previous step:
+ * CONTACT state changed (or persisted) since the previous step:
  *
- *   touched + !prev_touched  → ContactBegin
- *   touched +  prev_touched  → ContactStay
- *   !touched + prev_touched  → ContactEnd
- *   !touched + !prev_touched → no event (slot is about to be evicted by
- *                              advance_frame's grace counter)
+ *   has_contacts + !had_contacts  → ContactBegin
+ *   has_contacts +  had_contacts  → ContactStay
+ *   !has_contacts + had_contacts  → ContactEnd
+ *   !has_contacts + !had_contacts → no event
  *
- * MUST be called BEFORE {@link ManifoldStore#advance_frame} so the touched
- * bits still reflect the just-finished step.
+ * "has contacts" means the slot holds narrowphase contacts THIS frame
+ * (`contact_count > 0`) for a pair the broadphase touched; a pair that is
+ * merely inside the other's fat AABB (touched, zero contacts) produces no
+ * events — proximity is not contact. For an UNTOUCHED slot the stored
+ * contacts are stale (the pair left broadphase range or a body was removed),
+ * so it counts as contact-less and fires End once if it had contacts.
  *
- * Output is in slot-iteration order, which matches the deterministic
- * insertion order of slots in the dense live list. That's stable for a given
- * input sequence; not the same as `(idA, idB)` lex order, which would
- * require a sort. For v1 callers want stable-replay determinism rather than
- * any specific external order, so we don't sort.
+ * DORMANT pairs ({@link ManifoldStore#is_dormant}: both bodies alive and
+ * asleep) are skipped entirely: a stack falling asleep emits no End, and
+ * waking resumes with Stay — the events track physical contact, which never
+ * changed while the pair slept.
+ *
+ * MUST be called BEFORE {@link ManifoldStore#advance_frame} so the touched /
+ * had-contacts bits still reflect the just-finished step.
+ *
+ * Output is ENTITY-CANONICAL, both per event and across the buffer: each
+ * event's `(entityA, entityB)` is the pair's `(min, max)` by entity id —
+ * NOT the manifold's A/B, which follows packed-body-id order, i.e. slot
+ * allocation history — and the buffer is sorted by that key. Gameplay
+ * consumes these events through the action log, so both the pair identity
+ * and the within-frame delivery order must be derivable from body state
+ * alone: two engines holding identical bodies (same entities) emit
+ * identical event sequences regardless of how their manifold slots were
+ * allocated. The dispatch pass mirrors the contact normal whenever the
+ * canonicalization swapped the pair, preserving the "normal points from
+ * entityB toward entityA" payload convention.
  *
  * @param {ManifoldStore} manifolds
  * @param {BodyStorage} storage

package/src/engine/physics/events/diff_manifolds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff_manifolds.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/events/diff_manifolds.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qHAuBC"}
+{"version":3,"file":"diff_manifolds.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/events/diff_manifolds.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qHA2CC"}

package/src/engine/physics/events/diff_manifolds.js

@@ -1,50 +1,87 @@
-import { body_id_index } from "../body/BodyStorage.js";
-import { ContactEventKind } from "./ContactEventBuffer.js";
-
-/**
- * Walk every live manifold and produce a contact event for each pair whose
- * touched state changed (or persisted) since the previous step:
- *
- *   touched + !prev_touched  → ContactBegin
- *   touched +  prev_touched  → ContactStay
- *   !touched + prev_touched  → ContactEnd
- *   !touched + !prev_touched → no event (slot is about to be evicted by
- *                              advance_frame's grace counter)
- *
- * MUST be called BEFORE {@link ManifoldStore#advance_frame} so the touched
- * bits still reflect the just-finished step.
- *
- * Output is in slot-iteration order, which matches the deterministic
- * insertion order of slots in the dense live list. That's stable for a given
- * input sequence; not the same as `(idA, idB)` lex order, which would
- * require a sort. For v1 callers want stable-replay determinism rather than
- * any specific external order, so we don't sort.
- *
- * @param {ManifoldStore} manifolds
- * @param {BodyStorage} storage
- * @param {ContactEventBuffer} out_events cleared and refilled
- */
-export function diff_manifolds(manifolds, storage, out_events) {
-    out_events.clear();
-
-    const live_count = manifolds.count;
-    for (let i = 0; i < live_count; i++) {
-        const slot = manifolds.live_at(i);
-        const touched = manifolds.is_touched(slot);
-        const prev = manifolds.was_touched_prev(slot);
-
-        if (!touched && !prev) continue;
-
-        let kind;
-        if (touched && !prev)       kind = ContactEventKind.Begin;
-        else if (touched && prev)   kind = ContactEventKind.Stay;
-        else                        kind = ContactEventKind.End;
-
-        const idA = manifolds.bodyA(slot);
-        const idB = manifolds.bodyB(slot);
-        const entA = storage.entity_at(body_id_index(idA));
-        const entB = storage.entity_at(body_id_index(idB));
-
-        out_events.push(kind, entA, entB, slot);
-    }
-}
+import { body_id_index } from "../body/BodyStorage.js";
+import { ContactEventKind } from "./ContactEventBuffer.js";
+
+/**
+ * Walk every live manifold and produce a contact event for each pair whose
+ * CONTACT state changed (or persisted) since the previous step:
+ *
+ *   has_contacts + !had_contacts  → ContactBegin
+ *   has_contacts +  had_contacts  → ContactStay
+ *   !has_contacts + had_contacts  → ContactEnd
+ *   !has_contacts + !had_contacts → no event
+ *
+ * "has contacts" means the slot holds narrowphase contacts THIS frame
+ * (`contact_count > 0`) for a pair the broadphase touched; a pair that is
+ * merely inside the other's fat AABB (touched, zero contacts) produces no
+ * events — proximity is not contact. For an UNTOUCHED slot the stored
+ * contacts are stale (the pair left broadphase range or a body was removed),
+ * so it counts as contact-less and fires End once if it had contacts.
+ *
+ * DORMANT pairs ({@link ManifoldStore#is_dormant}: both bodies alive and
+ * asleep) are skipped entirely: a stack falling asleep emits no End, and
+ * waking resumes with Stay — the events track physical contact, which never
+ * changed while the pair slept.
+ *
+ * MUST be called BEFORE {@link ManifoldStore#advance_frame} so the touched /
+ * had-contacts bits still reflect the just-finished step.
+ *
+ * Output is ENTITY-CANONICAL, both per event and across the buffer: each
+ * event's `(entityA, entityB)` is the pair's `(min, max)` by entity id —
+ * NOT the manifold's A/B, which follows packed-body-id order, i.e. slot
+ * allocation history — and the buffer is sorted by that key. Gameplay
+ * consumes these events through the action log, so both the pair identity
+ * and the within-frame delivery order must be derivable from body state
+ * alone: two engines holding identical bodies (same entities) emit
+ * identical event sequences regardless of how their manifold slots were
+ * allocated. The dispatch pass mirrors the contact normal whenever the
+ * canonicalization swapped the pair, preserving the "normal points from
+ * entityB toward entityA" payload convention.
+ *
+ * @param {ManifoldStore} manifolds
+ * @param {BodyStorage} storage
+ * @param {ContactEventBuffer} out_events cleared and refilled
+ */
+export function diff_manifolds(manifolds, storage, out_events) {
+    out_events.clear();
+
+    const live_count = manifolds.count;
+    for (let i = 0; i < live_count; i++) {
+        const slot = manifolds.live_at(i);
+        const had = manifolds.had_contacts_prev(slot);
+
+        let has;
+        if (manifolds.is_touched(slot)) {
+            has = manifolds.contact_count(slot) > 0;
+        } else if (manifolds.is_dormant(slot, storage)) {
+            continue; // frozen with its sleeping bodies — no transitions to report
+        } else {
+            has = false; // out of broadphase range / body removed → contacts are stale
+        }
+
+        if (!has && !had) continue;
+
+        let kind;
+        if (has && !had)       kind = ContactEventKind.Begin;
+        else if (has && had)   kind = ContactEventKind.Stay;
+        else                   kind = ContactEventKind.End;
+
+        const idA = manifolds.bodyA(slot);
+        const idB = manifolds.bodyB(slot);
+        // Resolve entities through the packed id's GENERATION, not the bare
+        // index: the body pool reuses the lowest index first, so a despawn +
+        // respawn inside the manifold grace window would otherwise attribute
+        // the dead pair's event to the unrelated new occupant of the slot.
+        // The event buffer documents -1 as "body no longer exists".
+        const entA = storage.is_valid(idA) ? storage.entity_at(body_id_index(idA)) : -1;
+        const entB = storage.is_valid(idB) ? storage.entity_at(body_id_index(idB)) : -1;
+
+        // Entity-canonical pair order (min, max) — see the header.
+        if (entA <= entB) {
+            out_events.push(kind, entA, entB, slot);
+        } else {
+            out_events.push(kind, entB, entA, slot);
+        }
+    }
+
+    out_events.sort_canonical();
+}