@woosh/meep-engine 2.139.0 → 2.140.0

package/src/engine/physics/contact/ManifoldStore.d.ts

@@ -9,21 +9,30 @@ export const MAX_CONTACTS_PER_MANIFOLD: number;
  * Per-contact field stride in the data Float64Array.
  *
  * Layout per contact (all world-space):
- *   0..2  : world_a   (contact point on body A's surface)
- *   3..5  : world_b   (contact point on body B's surface)
- *   6..8  : normal_w  (from B toward A)
- *   9     : depth     (positive = penetration, negative = speculative gap)
- *   10    : j_n       (accumulated normal impulse, warm-start)
- *   11    : j_t1      (accumulated tangent impulse, axis 1)
- *   12    : j_t2      (accumulated tangent impulse, axis 2)
+ *   0..2  : world_a    (contact point on body A's surface)
+ *   3..5  : world_b    (contact point on body B's surface)
+ *   6..8  : normal_w   (from B toward A)
+ *   9     : depth      (positive = penetration, negative = speculative gap)
+ *   10    : j_n        (accumulated normal impulse, warm-start)
+ *   11    : j_t1       (accumulated tangent impulse, axis 1)
+ *   12    : j_t2       (accumulated tangent impulse, axis 2)
+ *   13    : feature_id (uint32 packed as f64 — stable cross-frame ID of the
+ *                       geometric feature pair that produced this contact;
+ *                       0 means "no info, fall back to position matching")
  *
  * Solver uses `(world_a + world_b) * 0.5` as the application point; storing
- * both surface points keeps the door open for richer warm-start matching
- * across frames in a follow-up slice.
+ * both surface points enables the per-frame warm-start matcher in the
+ * narrowphase to compare contact-point positions when feature_id is 0.
  *
  * @type {number}
  */
 export const CONTACT_STRIDE: number;
+/**
+ * Per-contact feature_id offset within {@link CONTACT_STRIDE}.
+ * Exposed for the narrowphase matcher; solver code does not read this.
+ * @type {number}
+ */
+export const CONTACT_FEATURE_ID_OFFSET: number;
 /**
  * Per-slot Float64 stride: room for {@link MAX_CONTACTS_PER_MANIFOLD} contacts.
  * @type {number}
@@ -65,6 +74,7 @@ export class ManifoldStore {
     __high_water: number;
     __data: Float64Array;
     __meta: Uint32Array;
+    __slot_axis: Float64Array;
     __pair_index: PairUint32Map;
     __live_slots: Uint32Array;
     __live_pos: Int32Array;
@@ -137,10 +147,31 @@ export class ManifoldStore {
      * @param {number} slot
      */
     clear_contacts(slot: number): void;
+    /**
+     * Reset the contact count to zero so the next `set_contact(slot, 0, …)`
+     * lands at index 0, but DO NOT zero the data slab. Warm-start impulses
+     * (`j_n`, `j_t1`, `j_t2`) at each contact slot survive — the subsequent
+     * `set_contact` calls only overwrite the first 10 floats (position,
+     * normal, depth) per contact.
+     *
+     * Use this when narrowphase determines the pair still has overlap and
+     * is about to refill the slot with the new frame's contacts. Use
+     * {@link clear_contacts} instead when the pair has genuinely separated
+     * and the cached impulses should be evicted.
+     *
+     * @param {number} slot
+     */
+    begin_refill(slot: number): void;
     /**
      * Write a contact point into a slot. Increments contact_count if `idx`
      * exceeds the current count.
      *
+     * Writes geometry (offsets 0..9) and the feature_id at offset 13.
+     * Deliberately does NOT touch the warm-start impulse fields (offsets
+     * 10..12) — the narrowphase match-and-merge pass uses this to refill
+     * a slot while preserving the cached impulses that the solver's
+     * warm-start needs.
+     *
      * @param {number} slot
      * @param {number} idx contact index in `[0, MAX_CONTACTS_PER_MANIFOLD)`
      * @param {number} lax
@@ -153,8 +184,35 @@ export class ManifoldStore {
      * @param {number} ny
      * @param {number} nz
      * @param {number} depth
+     * @param {number} feature_id stable cross-frame identifier of the
+     *   geometric feature pair that produced this contact; 0 means
+     *   "no info, fall back to position matching"
      */
-    set_contact(slot: number, idx: number, lax: number, lay: number, laz: number, lbx: number, lby: number, lbz: number, nx: number, ny: number, nz: number, depth: number): void;
+    set_contact(slot: number, idx: number, lax: number, lay: number, laz: number, lbx: number, lby: number, lbz: number, nx: number, ny: number, nz: number, depth: number, feature_id?: number): void;
+    /**
+     * Zero the warm-start impulse fields (j_n, j_t1, j_t2) for one contact
+     * index inside a slot. Called by the narrowphase match-and-merge pass
+     * after writing a candidate that did NOT match any prior-frame contact:
+     * the geometry at this index is "new" and inheriting impulses from
+     * whatever happened to be cached at this index last frame would
+     * destabilise the solver.
+     *
+     * Distinct from {@link clear_contacts} (which wipes the entire slot's
+     * data slab including geometry) — `clear_impulses` only touches the
+     * three impulse fields at one contact index, leaving the geometric
+     * fields and feature_id intact.
+     *
+     * @param {number} slot
+     * @param {number} idx
+     */
+    clear_impulses(slot: number, idx: number): void;
+    /**
+     * Read the feature_id stored at one contact within a slot.
+     * @param {number} slot
+     * @param {number} idx
+     * @returns {number}
+     */
+    feature_id_of(slot: number, idx: number): number;
     /**
      * Read a contact point. Writes 10 floats: lax, lay, laz, lbx, lby, lbz, nx, ny, nz, depth.
      * @param {number} slot
@@ -184,6 +242,21 @@ export class ManifoldStore {
      * @returns {Float64Array}
      */
     get data_buffer(): Float64Array;
+    /**
+     * Per-slot cached GJK separating axis buffer. Hot-path GJK callers
+     * pass this together with {@link slot_axis_offset} to
+     * `gjk_with_axis(...)` so the cached axis seeds the next iteration.
+     * Buffer identity is stable until grow.
+     * @returns {Float64Array}
+     */
+    get slot_axis_buffer(): Float64Array;
+    /**
+     * Float offset into {@link slot_axis_buffer} where this slot's
+     * cached axis lives (3 floats: x, y, z).
+     * @param {number} slot
+     * @returns {number}
+     */
+    slot_axis_offset(slot: number): number;
     /**
      * Word offset into {@link data_buffer} where the first contact of `slot`
      * begins. Subsequent contacts within the slot are at

package/src/engine/physics/contact/ManifoldStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ManifoldStore.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/contact/ManifoldStore.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;;GAiBG;AACH,6BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,+BAFU,MAAM,CAE2D;AAyB3E;;;GAGG;AACH,mCAFU,MAAM,CAEuB;AAIvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;OAEG;IACH,+BAFW,MAAM,EAqBhB;IAjBG,mBAA+C;IAC/C,qBAAqB;IAErB,qBAAkE;IAClE,oBAAiE;IAEjE,4BAA0D;IAG1D,0BAAoD;IACpD,uBAAiD;IAEjD,qBAAqB;IAGrB,yBAAmD;IACnD,qBAAqB;IAGzB;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;;;OAOG;IACH,UAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;OAQG;IACH,aAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAwBlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qBAFW,MAAM,QAQhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,kBAbW,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,SACN,MAAM,QAqBhB;IAED;;;;;;OAMG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,cACrB,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,oBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,sBA6BC;IAED;;;OAGG;IACH,wBAcC;IAED;;;OAGG;IACH,uBAkBC;IAED;;OAEG;IACH,eA8BC;IAED;;;OAGG;IACH,oBAaC;IAED;;;OAGG;IACH,mBAqBC;CACJ;8BAjfqD,2CAA2C"}
+{"version":3,"file":"ManifoldStore.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/contact/ManifoldStore.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,6BAFU,MAAM,CAEiB;AAEjC;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,+BAFU,MAAM,CAE2D;AAyB3E;;;GAGG;AACH,mCAFU,MAAM,CAEuB;AAIvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;OAEG;IACH,+BAFW,MAAM,EA6BhB;IAzBG,mBAA+C;IAC/C,qBAAqB;IAErB,qBAAkE;IAClE,oBAAiE;IAQjE,0BAAwD;IAExD,4BAA0D;IAG1D,0BAAoD;IACpD,uBAAiD;IAEjD,qBAAqB;IAGrB,yBAAmD;IACnD,qBAAqB;IAGzB;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;;;OAOG;IACH,UAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;OAQG;IACH,aAJW,MAAM,OACN,MAAM,GACJ,MAAM,CA+BlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qBAFW,MAAM,QAQhB;IAED;;;;;;;;;;;;;OAaG;IACH,mBAFW,MAAM,QAKhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAhBW,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,SACN,MAAM,eACN,MAAM,QAwBhB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,MAAM,OACN,MAAM,QAOhB;IAED;;;;;OAKG;IACH,oBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,cACrB,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,oBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,qCAEC;IAED;;;;;OAKG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,sBA6BC;IAED;;;OAGG;IACH,wBAcC;IAED;;;OAGG;IACH,uBAkBC;IAED;;OAEG;IACH,eA+BC;IAED;;;OAGG;IACH,oBAaC;IAED;;;OAGG;IACH,mBAqBC;CACJ;8BA9lBqD,2CAA2C"}