@woosh/meep-engine 2.156.0 → 2.158.0

package/src/engine/physics/island/IslandBuilder.d.ts

@@ -1,6 +1,6 @@
 /**
- * Partitions this frame's awake dynamic bodies + touched non-sensor contacts
- * into connected components ("islands") via union-find. The solver iterates
+ * Partitions this frame's awake dynamic bodies + contacting non-sensor
+ * manifolds into connected components ("islands") via union-find. The solver iterates
  * each island independently (so impulses converge inside an island without
  * waiting for global passes) and the sleep test will eventually use island
  * granularity for atomic whole-island sleep.
@@ -20,7 +20,20 @@
  *    root of any component is the smallest body index of any of its members.
  *  - Islands are emitted sorted ascending by root index.
  *  - Bodies within an island are emitted sorted ascending by body index.
- *  - Contacts within an island are emitted sorted ascending by manifold slot id.
+ *  - Contacts within an island are emitted sorted by canonical ENTITY pair
+ *    `(min(entA, entB), max(entA, entB))` — NOT by manifold slot id. Slot ids
+ *    encode pair-discovery history (BVH traversal × awake-list order), which
+ *    two engines holding identical body state need not share; entity ids are
+ *    the cross-engine identity. Since the solver consumes contacts in this
+ *    order, solve order — and therefore the trajectory — is a function of
+ *    body state alone.
+ *
+ * Island ids themselves (and body order within an island, both index-based)
+ * may differ between two engines whose body slots were allocated in different
+ * historical order. That is deliberate: islands are disjoint and the solver's
+ * flat sweep writes zero deltas to shared static anchors, so cross-island
+ * order cannot affect outcomes; only WITHIN-island contact order can, and
+ * that is entity-keyed.
  *
  * Output layout is CSR-like — `body_offsets[i]..body_offsets[i+1]` indexes
  * into `body_data` for island `i`, similarly for contacts.
@@ -36,6 +49,33 @@ export class IslandBuilder {
      * @private
      */
     private static __body_is_sensor;
+    /**
+     * In-place insertion sort of `data[start..end)` (manifold slot ids) by the
+     * canonical entity pair `(min(entA, entB), max(entA, entB))` of each slot.
+     * One slot per pair, so the key is unique within a frame and the order is
+     * total. Insertion sort: island contact slices are small (tens), the
+     * comparator is two table reads, and there is nothing to allocate.
+     *
+     * @private
+     * @param {Uint32Array} data
+     * @param {number} start
+     * @param {number} end exclusive
+     * @param {BodyStorage} storage
+     * @param {ManifoldStore} manifolds
+     */
+    private static __sort_slots_by_entity_pair;
+    /**
+     * Smaller entity of a slot's body pair. Bodies of a contact emitted into
+     * an island are live (the slot passed `__island_of_slot`), so the entity
+     * lookups are valid this frame.
+     * @private
+     */
+    private static __slot_ent_lo;
+    /**
+     * Larger entity of a slot's body pair.
+     * @private
+     */
+    private static __slot_ent_hi;
     /**
      * Union-find parent table, indexed by body index (NOT packed id).
      * Sized to `storage.high_water_mark` at `build` time; reallocated by
@@ -129,8 +169,8 @@ export class IslandBuilder {
      */
     private __build_body_csr;
     /**
-     * Fill `contact_offsets` + `contact_data` with touched non-sensor manifold
-     * slot ids grouped by island. A contact belongs to its dynamic
+     * Fill `contact_offsets` + `contact_data` with contacting non-sensor
+     * manifold slot ids grouped by island. A contact belongs to its dynamic
      * participant's island (if both sides are dynamic they share an island
      * by construction). Static-vs-static contacts are skipped.
      * @private
@@ -139,9 +179,10 @@ export class IslandBuilder {
     /**
      * Resolve which island a manifold slot belongs to.
      *
-     * Returns `-1` if the manifold is not touched this frame, is a sensor
-     * pair, or both bodies are non-dynamic (static-static, which the solver
-     * wouldn't act on anyway).
+     * Returns `-1` if the manifold is not touched this frame, holds no
+     * contacts (fat-AABB proximity only — nothing for the solver), is a
+     * sensor pair, or both bodies are non-dynamic (static-static, which the
+     * solver wouldn't act on anyway).
      *
      * @private
      */

package/src/engine/physics/island/IslandBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAyFI;;;;;OAKG;IACH,gCAOC;IAnGG;;;;;OAKG;IACH,QAFU,WAAW,CAEY;IAEjC;;;;OAIG;IACH,gBAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,cAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,cAFU,WAAW,CAEiB;IAEtC;;;;OAIG;IACH,WAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;;OAKG;IACH,iBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,cAFU,WAAW,CAEkB;IAEvC;;;OAGG;IACH,eAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,yBAA0C;IAE1C;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;OAIG;IACH,kBAAmC;IAkBvC;;;;;;;;;;;OAWG;IACH,8DANW,WAAW,uBACX,OAAO,UACP,OAAO,QAgGjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BAwCC;IAED;;;;;;;;OAQG;IACH,yBAqBC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}
+{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAyFI;;;;;OAKG;IACH,gCAOC;IA0ND;;;;;;;;;;;;;OAaG;IACH,2CAmBC;IAED;;;;;OAKG;IACH,6BAIC;IAED;;;OAGG;IACH,6BAIC;IApXG;;;;;OAKG;IACH,QAFU,WAAW,CAEY;IAEjC;;;;OAIG;IACH,gBAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,cAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,cAFU,WAAW,CAEiB;IAEtC;;;;OAIG;IACH,WAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;;OAKG;IACH,iBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,cAFU,WAAW,CAEkB;IAEvC;;;OAGG;IACH,eAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,yBAA0C;IAE1C;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;OAIG;IACH,kBAAmC;IAkBvC;;;;;;;;;;;OAWG;IACH,8DANW,WAAW,uBACX,OAAO,UACP,OAAO,QAqGjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BA0CC;IA2DD;;;;;;;;;OASG;IACH,yBAsBC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}

package/src/engine/physics/island/IslandBuilder.js

@@ -3,11 +3,11 @@ import { body_id_index } from "../body/BodyStorage.js";
 import { BodyKind } from "../ecs/BodyKind.js";
 import { is_sensor } from "../ecs/is_sensor.js";
 import { JOINT_WORLD } from "../ecs/Joint.js";
-import { uf_find, uf_init, uf_union } from "./union_find.js";
+import { uf_find, uf_init, uf_union } from "../../../core/collection/union-find/union_find.js";
 
 /**
- * Partitions this frame's awake dynamic bodies + touched non-sensor contacts
- * into connected components ("islands") via union-find. The solver iterates
+ * Partitions this frame's awake dynamic bodies + contacting non-sensor
+ * manifolds into connected components ("islands") via union-find. The solver iterates
  * each island independently (so impulses converge inside an island without
  * waiting for global passes) and the sleep test will eventually use island
  * granularity for atomic whole-island sleep.
@@ -27,7 +27,20 @@ import { uf_find, uf_init, uf_union } from "./union_find.js";
  *    root of any component is the smallest body index of any of its members.
  *  - Islands are emitted sorted ascending by root index.
  *  - Bodies within an island are emitted sorted ascending by body index.
- *  - Contacts within an island are emitted sorted ascending by manifold slot id.
+ *  - Contacts within an island are emitted sorted by canonical ENTITY pair
+ *    `(min(entA, entB), max(entA, entB))` — NOT by manifold slot id. Slot ids
+ *    encode pair-discovery history (BVH traversal × awake-list order), which
+ *    two engines holding identical body state need not share; entity ids are
+ *    the cross-engine identity. Since the solver consumes contacts in this
+ *    order, solve order — and therefore the trajectory — is a function of
+ *    body state alone.
+ *
+ * Island ids themselves (and body order within an island, both index-based)
+ * may differ between two engines whose body slots were allocated in different
+ * historical order. That is deliberate: islands are disjoint and the solver's
+ * flat sweep writes zero deltas to shared static anchors, so cross-island
+ * order cannot affect outcomes; only WITHIN-island contact order can, and
+ * that is entity-keyed.
  *
  * Output layout is CSR-like — `body_offsets[i]..body_offsets[i+1]` indexes
  * into `body_data` for island `i`, similarly for contacts.
@@ -158,11 +171,16 @@ export class IslandBuilder {
         const parent = this.parent;
         uf_init(parent, hwm);
 
-        // --- Pass 1: union dynamic-dynamic pairs from touched non-sensor manifolds.
+        // --- Pass 1: union dynamic-dynamic pairs from CONTACTING non-sensor
+        //     manifolds. The contact_count gate matters: a touched slot with
+        //     zero contacts is mere fat-AABB proximity — unioning on it would
+        //     couple hovering neighbours into one island (and a single moving
+        //     body within ~10 cm would then hold a whole resting pile awake).
         const live_count = manifolds.count;
         for (let i = 0; i < live_count; i++) {
             const slot = manifolds.live_at(i);
             if (!manifolds.is_touched(slot)) continue;
+            if (manifolds.contact_count(slot) === 0) continue;
             const idxA = body_id_index(manifolds.bodyA(slot));
             const idxB = body_id_index(manifolds.bodyB(slot));
             const rbA = bodies[idxA];
@@ -242,7 +260,7 @@ export class IslandBuilder {
         }
 
         this.__build_body_csr(storage, bodies, awake_count, root_count);
-        this.__build_contact_csr(manifolds, bodies, body_collider_lists, root_count);
+        this.__build_contact_csr(storage, manifolds, bodies, body_collider_lists, root_count);
     }
 
     /**
@@ -300,13 +318,13 @@ export class IslandBuilder {
     }
 
     /**
-     * Fill `contact_offsets` + `contact_data` with touched non-sensor manifold
-     * slot ids grouped by island. A contact belongs to its dynamic
+     * Fill `contact_offsets` + `contact_data` with contacting non-sensor
+     * manifold slot ids grouped by island. A contact belongs to its dynamic
      * participant's island (if both sides are dynamic they share an island
      * by construction). Static-vs-static contacts are skipped.
      * @private
      */
-    __build_contact_csr(manifolds, bodies, body_collider_lists, island_count) {
+    __build_contact_csr(storage, manifolds, bodies, body_collider_lists, island_count) {
         const offsets = this.contact_offsets;
         for (let i = 0; i <= island_count; i++) offsets[i] = 0;
 
@@ -338,27 +356,88 @@ export class IslandBuilder {
             data[cursors[isl]++] = slot;
         }
 
-        // Sort each island's contact slice ascending by slot id.
+        // Sort each island's contact slice by canonical entity pair — the
+        // determinism contract's "solve order is a function of body state"
+        // clause. See the class doc.
         for (let i = 0; i < island_count; i++) {
             const start = offsets[i];
             const end = offsets[i + 1];
             if (end - start > 1) {
-                data.subarray(start, end).sort();
+                IslandBuilder.__sort_slots_by_entity_pair(data, start, end, storage, manifolds);
+            }
+        }
+    }
+
+    /**
+     * In-place insertion sort of `data[start..end)` (manifold slot ids) by the
+     * canonical entity pair `(min(entA, entB), max(entA, entB))` of each slot.
+     * One slot per pair, so the key is unique within a frame and the order is
+     * total. Insertion sort: island contact slices are small (tens), the
+     * comparator is two table reads, and there is nothing to allocate.
+     *
+     * @private
+     * @param {Uint32Array} data
+     * @param {number} start
+     * @param {number} end exclusive
+     * @param {BodyStorage} storage
+     * @param {ManifoldStore} manifolds
+     */
+    static __sort_slots_by_entity_pair(data, start, end, storage, manifolds) {
+        for (let i = start + 1; i < end; i++) {
+            const slot = data[i];
+            const lo = IslandBuilder.__slot_ent_lo(slot, storage, manifolds);
+            const hi = IslandBuilder.__slot_ent_hi(slot, storage, manifolds);
+            let j = i - 1;
+            while (j >= start) {
+                const other = data[j];
+                const o_lo = IslandBuilder.__slot_ent_lo(other, storage, manifolds);
+                if (o_lo < lo) break;
+                if (o_lo === lo) {
+                    const o_hi = IslandBuilder.__slot_ent_hi(other, storage, manifolds);
+                    if (o_hi <= hi) break;
+                }
+                data[j + 1] = other;
+                j--;
             }
+            data[j + 1] = slot;
         }
     }
 
+    /**
+     * Smaller entity of a slot's body pair. Bodies of a contact emitted into
+     * an island are live (the slot passed `__island_of_slot`), so the entity
+     * lookups are valid this frame.
+     * @private
+     */
+    static __slot_ent_lo(slot, storage, manifolds) {
+        const ea = storage.entity_at(body_id_index(manifolds.bodyA(slot)));
+        const eb = storage.entity_at(body_id_index(manifolds.bodyB(slot)));
+        return ea < eb ? ea : eb;
+    }
+
+    /**
+     * Larger entity of a slot's body pair.
+     * @private
+     */
+    static __slot_ent_hi(slot, storage, manifolds) {
+        const ea = storage.entity_at(body_id_index(manifolds.bodyA(slot)));
+        const eb = storage.entity_at(body_id_index(manifolds.bodyB(slot)));
+        return ea > eb ? ea : eb;
+    }
+
     /**
      * Resolve which island a manifold slot belongs to.
      *
-     * Returns `-1` if the manifold is not touched this frame, is a sensor
-     * pair, or both bodies are non-dynamic (static-static, which the solver
-     * wouldn't act on anyway).
+     * Returns `-1` if the manifold is not touched this frame, holds no
+     * contacts (fat-AABB proximity only — nothing for the solver), is a
+     * sensor pair, or both bodies are non-dynamic (static-static, which the
+     * solver wouldn't act on anyway).
      *
      * @private
      */
     __island_of_slot(manifolds, slot, bodies, body_collider_lists) {
         if (!manifolds.is_touched(slot)) return -1;
+        if (manifolds.contact_count(slot) === 0) return -1;
         const idxA = body_id_index(manifolds.bodyA(slot));
         const idxB = body_id_index(manifolds.bodyB(slot));
         const rbA = bodies[idxA];

package/src/engine/physics/narrowphase/box_box_manifold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AAiHA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAghBnB;AArlBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}
+{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AA6JA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA8enB;AA9lBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}