@woosh/meep-engine 3.37.0 → 3.39.0

package/src/engine/physics/inertia/world_inverse_inertia.js

@@ -26,7 +26,8 @@
  * @param {number[]|Float64Array} inv_inertia_local
  *        Body-frame inverse inertia diagonal, `[x, y, z]` (typically `rb.inverseInertiaLocal`).
  * @param {number[]|Float64Array} rotation
- *        Body orientation as a unit quaternion, `[x, y, z, w]` (typically `transform.rotation`).
+ *        Body orientation as a unit quaternion, `[x, y, z, w]`. Not a Transform64's `rotation`, which
+ *        allocates a view on every read: hand its `rotation_x..w` to {@link world_inverse_inertia_apply_raw}.
  * @param {number} vx
  * @param {number} vy
  * @param {number} vz
@@ -49,28 +50,6 @@ export function world_inverse_inertia_apply(
     );
 }
 
-/**
- * Raw-float counterpart of {@link world_inverse_inertia_apply}: the same
- * `I_w⁻¹ = R · diag · R^T` application, with the inverse-inertia diagonal and
- * orientation quaternion passed as scalars rather than read off
- * three- / four-element arrays. The data-oriented contact / joint solver
- * reads these straight out of its `SolverBodyState` typed array, avoiding the
- * per-impulse object dereference on the hot path. The arithmetic is identical
- * to the object version (same operation order), so results are bit-identical.
- *
- * @param {number[]|Float64Array} result length >= 3
- * @param {number} result_offset
- * @param {number} ix
- * @param {number} iy
- * @param {number} iz Body-frame inverse inertia diagonal.
- * @param {number} qx
- * @param {number} qy
- * @param {number} qz
- * @param {number} qw Body orientation as a unit quaternion.
- * @param {number} vx
- * @param {number} vy
- * @param {number} vz
- */
 /**
  * Quadratic-form contribution of one body to a unit-axis velocity
  * constraint's effective mass: `(r × axis)ᵀ · I_w⁻¹ · (r × axis)`, where `r`
@@ -81,7 +60,8 @@ export function world_inverse_inertia_apply(
  * raycast-vehicle's component path — each previously inlined the cross
  * product + {@link world_inverse_inertia_apply_raw} + dot themselves.
  * Identical operation order in every caller keeps the paths bit-identical
- * (the determinism contract).
+ * (the determinism contract): the arithmetic is
+ * {@link angular_effective_mass_array}'s, which this packs its scalars for.
  *
  * @param {number} ix
  * @param {number} iy
@@ -106,21 +86,159 @@ export function angular_effective_mass_raw(
     ax, ay, az,
     scratch
 ) {
+    const inputs = mass_inputs;
+
+    inputs[0] = ix;
+    inputs[1] = iy;
+    inputs[2] = iz;
+    inputs[3] = qx;
+    inputs[4] = qy;
+    inputs[5] = qz;
+    inputs[6] = qw;
+    inputs[7] = rx;
+    inputs[8] = ry;
+    inputs[9] = rz;
+    inputs[10] = ax;
+    inputs[11] = ay;
+    inputs[12] = az;
+
+    angular_effective_mass_array(mass_result, 0, inputs, 0, inputs, 3, inputs, 7, inputs, 10, scratch);
+
+    return mass_result[0];
+}
+
+/** Where {@link angular_effective_mass_raw} packs its scalars: diagonal, quaternion, lever, axis. */
+const mass_inputs = new Float64Array(13);
+/** Where {@link angular_effective_mass_raw} has its result written. */
+const mass_result = new Float64Array(1);
+
+/**
+ * {@link angular_effective_mass_raw} with every input read from an array and the result written to
+ * `result[result_offset]`: nothing crosses the call as a number, for the reason
+ * {@link world_inverse_inertia_apply_array} gives (a returned number is boxed as well).
+ *
+ * @param {number[]|Float64Array} result
+ * @param {number} result_offset
+ * @param {number[]|Float64Array} inv_inertia body-frame inverse inertia diagonal
+ * @param {number} inv_inertia_offset
+ * @param {number[]|Float64Array} rotation body orientation, a unit quaternion `[x, y, z, w]`
+ * @param {number} rotation_offset
+ * @param {number[]|Float64Array} lever body-relative application point
+ * @param {number} lever_offset
+ * @param {number[]|Float64Array} axis unit constraint axis
+ * @param {number} axis_offset
+ * @param {number[]|Float64Array} scratch length >= 3, clobbered
+ */
+export function angular_effective_mass_array(
+    result, result_offset,
+    inv_inertia, inv_inertia_offset,
+    rotation, rotation_offset,
+    lever, lever_offset,
+    axis, axis_offset,
+    scratch
+) {
+    const rx = lever[lever_offset];
+    const ry = lever[lever_offset + 1];
+    const rz = lever[lever_offset + 2];
+
+    const ax = axis[axis_offset];
+    const ay = axis[axis_offset + 1];
+    const az = axis[axis_offset + 2];
+
     const cx = ry * az - rz * ay;
     const cy = rz * ax - rx * az;
     const cz = rx * ay - ry * ax;
 
-    world_inverse_inertia_apply_raw(scratch, 0, ix, iy, iz, qx, qy, qz, qw, cx, cy, cz);
+    scratch[0] = cx;
+    scratch[1] = cy;
+    scratch[2] = cz;
 
-    return cx * scratch[0] + cy * scratch[1] + cz * scratch[2];
+    world_inverse_inertia_apply_array(scratch, 0, inv_inertia, inv_inertia_offset, rotation, rotation_offset, scratch, 0);
+
+    result[result_offset] = cx * scratch[0] + cy * scratch[1] + cz * scratch[2];
 }
 
+/** Where {@link world_inverse_inertia_apply_raw} packs its scalars: diagonal, quaternion, vector. */
+const raw_inputs = new Float64Array(10);
+
+/**
+ * Raw-float counterpart of {@link world_inverse_inertia_apply}: the same
+ * `I_w⁻¹ = R · diag · R^T` application, with the inverse-inertia diagonal and
+ * orientation quaternion passed as scalars rather than read off
+ * three- / four-element arrays. The arithmetic is {@link world_inverse_inertia_apply_array}'s,
+ * so results are bit-identical across every form.
+ *
+ * Packs its scalars into a module buffer and hands that to the array form. Small enough for V8 to
+ * inline, so a caller that inlines it passes nothing boxed; the array form it calls takes no doubles.
+ *
+ * @param {number[]|Float64Array} result length >= 3
+ * @param {number} result_offset
+ * @param {number} ix
+ * @param {number} iy
+ * @param {number} iz Body-frame inverse inertia diagonal.
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw Body orientation as a unit quaternion.
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ */
 export function world_inverse_inertia_apply_raw(
     result, result_offset,
     ix, iy, iz,
     qx, qy, qz, qw,
     vx, vy, vz
 ) {
+    const inputs = raw_inputs;
+
+    inputs[0] = ix;
+    inputs[1] = iy;
+    inputs[2] = iz;
+    inputs[3] = qx;
+    inputs[4] = qy;
+    inputs[5] = qz;
+    inputs[6] = qw;
+    inputs[7] = vx;
+    inputs[8] = vy;
+    inputs[9] = vz;
+
+    world_inverse_inertia_apply_array(result, result_offset, inputs, 0, inputs, 3, inputs, 7);
+}
+
+/**
+ * {@link world_inverse_inertia_apply_raw} with every input read from an array: the body-frame
+ * inverse-inertia diagonal from `inv_inertia[inv_inertia_offset ..+2]`, the orientation (a unit
+ * quaternion) from `rotation[rotation_offset ..+3]` and the vector from `v[v_offset ..+2]`. Every input
+ * is read before the result is written, so `result` may be `v`: the vector is transformed in place.
+ *
+ * The form for hot loops, and the one place the math lives. Its bytecode is past what V8 will inline,
+ * so a call to it is a real call, and a real call boxes each double argument into a new heap number:
+ * ten a call, through the scalar form, once per impulse per solver iteration. Arrays and offsets cross
+ * a call as they are.
+ *
+ * @param {number[]|Float64Array} result length >= result_offset + 3
+ * @param {number} result_offset
+ * @param {number[]|Float64Array} inv_inertia body-frame inverse inertia diagonal
+ * @param {number} inv_inertia_offset
+ * @param {number[]|Float64Array} rotation body orientation, a unit quaternion `[x, y, z, w]`
+ * @param {number} rotation_offset
+ * @param {number[]|Float64Array} v the world-space vector
+ * @param {number} v_offset
+ */
+export function world_inverse_inertia_apply_array(
+    result, result_offset,
+    inv_inertia, inv_inertia_offset,
+    rotation, rotation_offset,
+    v, v_offset
+) {
+    const ix = inv_inertia[inv_inertia_offset];
+    const iy = inv_inertia[inv_inertia_offset + 1];
+    const iz = inv_inertia[inv_inertia_offset + 2];
+
+    const vx = v[v_offset];
+    const vy = v[v_offset + 1];
+    const vz = v[v_offset + 2];
 
     if (ix === iy && iy === iz) {
         // Isotropic — rotation cancels.
@@ -130,6 +248,11 @@ export function world_inverse_inertia_apply_raw(
         return;
     }
 
+    const qx = rotation[rotation_offset];
+    const qy = rotation[rotation_offset + 1];
+    const qz = rotation[rotation_offset + 2];
+    const qw = rotation[rotation_offset + 3];
+
     // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
     // quaternion (-qx, -qy, -qz, qw). Inlined for V8 inliner — see
     // PosedShape3D.support and core/geom/vec3/v3_quat3_apply_inverse.js

package/src/engine/physics/integration/integrate_position.d.ts

@@ -3,22 +3,25 @@
  * current linear and angular velocity over a step `dt`. Static bodies are
  * not touched.
  *
- * The trailing six arguments are the body's *pseudo-velocity*: the
- * position-pass output from the constraint solver (Catto split-impulse).
- * Pseudo-velocity exists only inside the step — it's folded into the
- * integration so the position update reflects depth correction, then
+ * `pseudo[pseudo_offset ..+5]` is the body's *pseudo-velocity*, linear then
+ * angular: the position-pass output from the constraint solver (Catto
+ * split-impulse). Pseudo-velocity exists only inside the step — it's folded
+ * into the integration so the position update reflects depth correction, then
  * implicitly discarded. The body's persistent `linearVelocity` /
  * `angularVelocity` (which carry restitution + warm-start across steps)
- * are never contaminated by it.
+ * are never contaminated by it. It is read from the array rather than passed
+ * as six numbers: this is not inlined into the step's loop, and a call that is
+ * not inlined boxes each number passed to it, per body per substep.
  *
- * Callers with no position-pass output should pass zeros for the six
- * pseudo arguments — folding zero is free (one add per axis).
+ * Callers with no position-pass output should pass zeros for the
+ * pseudo-velocity — folding zero is free (one add per axis).
  *
- * KinematicPosition bodies are treated like Dynamic for the position
- * update — if the gameplay code is driving them, their velocity is
- * whatever the user wrote (typically zero); the step is effectively a
- * no-op in that case. KinematicVelocity bodies advance under their
- * user-set velocity.
+ * Both kinematic kinds advance under the velocity they carry. For a
+ * KinematicVelocity body that is what the user wrote. For a KinematicPosition
+ * body driven by {@link PhysicsSystem#setTargetPose} it is the velocity the
+ * step derived to reach the target (the step then lands it on the target
+ * exactly); a KinematicPosition body only ever posed directly carries none, and
+ * this integrates nothing for it.
  *
  * Persistent linear / angular velocity is read from the data-oriented
  * {@link SolverBodyState} span (`ss` / `base`); the pose remains authoritative
@@ -32,12 +35,8 @@
  * @param {RigidBody} rb
  * @param {Transform64} transform
  * @param {number} dt
- * @param {number} ps_lin_x pseudo-linear-velocity x (0 when no contacts)
- * @param {number} ps_lin_y
- * @param {number} ps_lin_z
- * @param {number} ps_ang_x pseudo-angular-velocity x (0 when no contacts)
- * @param {number} ps_ang_y
- * @param {number} ps_ang_z
+ * @param {Float64Array} pseudo holds the pseudo-velocity (zeros when no contacts)
+ * @param {number} pseudo_offset where in `pseudo` its linear x is; linear y, z, angular x, y, z follow
  */
-export function integrate_position(ss: Float64Array, base: number, rb: RigidBody, transform: Transform64, dt: number, ps_lin_x: number, ps_lin_y: number, ps_lin_z: number, ps_ang_x: number, ps_ang_y: number, ps_ang_z: number): void;
+export function integrate_position(ss: Float64Array, base: number, rb: RigidBody, transform: Transform64, dt: number, pseudo: Float64Array, pseudo_offset: number): void;
 //# sourceMappingURL=integrate_position.d.ts.map

package/src/engine/physics/integration/integrate_position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrate_position.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_position.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,uCAZW,YAAY,QACZ,MAAM,6CAGN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,QA+ChB"}
+{"version":3,"file":"integrate_position.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_position.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uCARW,YAAY,QACZ,MAAM,6CAGN,MAAM,UACN,YAAY,iBACZ,MAAM,QAiDhB"}

package/src/engine/physics/integration/integrate_position.js

@@ -1,5 +1,6 @@
 import { BodyKind } from "../ecs/BodyKind.js";
-import { quat3_integrate } from "../../../core/geom/3d/quaternion/quat3_integrate.js";
+import { quat3_integrate_array } from "../../../core/geom/3d/quaternion/quat3_integrate.js";
+import { TRANSFORM64_ROTATION_OFFSET } from "../../ecs/transform/Transform64.js";
 import {
     SBS_QX, SBS_QY, SBS_QZ, SBS_QW,
     SBS_LV_X, SBS_LV_Y, SBS_LV_Z,
@@ -7,28 +8,32 @@ import {
 } from "../body/SolverBodyState.js";
 
 const scratch_q = new Float64Array(4);
+const scratch_omega = new Float64Array(3);
 
 /**
  * Integrate `transform.position` and `transform.rotation` from the body's
  * current linear and angular velocity over a step `dt`. Static bodies are
  * not touched.
  *
- * The trailing six arguments are the body's *pseudo-velocity*: the
- * position-pass output from the constraint solver (Catto split-impulse).
- * Pseudo-velocity exists only inside the step — it's folded into the
- * integration so the position update reflects depth correction, then
+ * `pseudo[pseudo_offset ..+5]` is the body's *pseudo-velocity*, linear then
+ * angular: the position-pass output from the constraint solver (Catto
+ * split-impulse). Pseudo-velocity exists only inside the step — it's folded
+ * into the integration so the position update reflects depth correction, then
  * implicitly discarded. The body's persistent `linearVelocity` /
  * `angularVelocity` (which carry restitution + warm-start across steps)
- * are never contaminated by it.
+ * are never contaminated by it. It is read from the array rather than passed
+ * as six numbers: this is not inlined into the step's loop, and a call that is
+ * not inlined boxes each number passed to it, per body per substep.
  *
- * Callers with no position-pass output should pass zeros for the six
- * pseudo arguments — folding zero is free (one add per axis).
+ * Callers with no position-pass output should pass zeros for the
+ * pseudo-velocity — folding zero is free (one add per axis).
  *
- * KinematicPosition bodies are treated like Dynamic for the position
- * update — if the gameplay code is driving them, their velocity is
- * whatever the user wrote (typically zero); the step is effectively a
- * no-op in that case. KinematicVelocity bodies advance under their
- * user-set velocity.
+ * Both kinematic kinds advance under the velocity they carry. For a
+ * KinematicVelocity body that is what the user wrote. For a KinematicPosition
+ * body driven by {@link PhysicsSystem#setTargetPose} it is the velocity the
+ * step derived to reach the target (the step then lands it on the target
+ * exactly); a KinematicPosition body only ever posed directly carries none, and
+ * this integrates nothing for it.
  *
  * Persistent linear / angular velocity is read from the data-oriented
  * {@link SolverBodyState} span (`ss` / `base`); the pose remains authoritative
@@ -42,27 +47,19 @@ const scratch_q = new Float64Array(4);
  * @param {RigidBody} rb
  * @param {Transform64} transform
  * @param {number} dt
- * @param {number} ps_lin_x pseudo-linear-velocity x (0 when no contacts)
- * @param {number} ps_lin_y
- * @param {number} ps_lin_z
- * @param {number} ps_ang_x pseudo-angular-velocity x (0 when no contacts)
- * @param {number} ps_ang_y
- * @param {number} ps_ang_z
+ * @param {Float64Array} pseudo holds the pseudo-velocity (zeros when no contacts)
+ * @param {number} pseudo_offset where in `pseudo` its linear x is; linear y, z, angular x, y, z follow
  */
-export function integrate_position(
-    ss, base, rb, transform, dt,
-    ps_lin_x, ps_lin_y, ps_lin_z,
-    ps_ang_x, ps_ang_y, ps_ang_z,
-) {
+export function integrate_position(ss, base, rb, transform, dt, pseudo, pseudo_offset) {
     if (rb.kind === BodyKind.Static) {
         return;
     }
 
     // Combined integration velocity: persistent + pseudo. The pseudo
     // contribution exists only for this step and never lands in the velocity.
-    const vx = ss[base + SBS_LV_X] + ps_lin_x;
-    const vy = ss[base + SBS_LV_Y] + ps_lin_y;
-    const vz = ss[base + SBS_LV_Z] + ps_lin_z;
+    const vx = ss[base + SBS_LV_X] + pseudo[pseudo_offset];
+    const vy = ss[base + SBS_LV_Y] + pseudo[pseudo_offset + 1];
+    const vz = ss[base + SBS_LV_Z] + pseudo[pseudo_offset + 2];
 
     // The translation IS the matrix translation column, so this write lands in the matrix as it is
     // made and owes no updateMatrix. Announcing the move is the caller’s job: it happens once per
@@ -74,17 +71,23 @@ export function integrate_position(
         transform.translation_z + vz * dt
     );
 
-    const wx = ss[base + SBS_AV_X] + ps_ang_x;
-    const wy = ss[base + SBS_AV_Y] + ps_ang_y;
-    const wz = ss[base + SBS_AV_Z] + ps_ang_z;
+    const wx = ss[base + SBS_AV_X] + pseudo[pseudo_offset + 3];
+    const wy = ss[base + SBS_AV_Y] + pseudo[pseudo_offset + 4];
+    const wz = ss[base + SBS_AV_Z] + pseudo[pseudo_offset + 5];
     if (wx !== 0 || wy !== 0 || wz !== 0) {
-        quat3_integrate(
-            scratch_q,
-            transform.rotation_x, transform.rotation_y, transform.rotation_z, transform.rotation_w,
-            wx, wy, wz,
-            dt
-        );
-        transform.setRotation(scratch_q[0], scratch_q[1], scratch_q[2], scratch_q[3]);
+        // The rotation and the angular velocity go in arrays: the integrator is not inlined here, and
+        // handed them as numbers it would box all seven.
+        const omega = scratch_omega;
+        omega[0] = wx;
+        omega[1] = wy;
+        omega[2] = wz;
+        quat3_integrate_array(scratch_q, 0, transform, TRANSFORM64_ROTATION_OFFSET, omega, 0, dt);
+        // Written into the transform's rotation lanes, as setRotation writes them (the transform is a
+        // Float64Array): setRotation is not inlined here, and handed the four numbers it would box them.
+        transform[TRANSFORM64_ROTATION_OFFSET] = scratch_q[0];
+        transform[TRANSFORM64_ROTATION_OFFSET + 1] = scratch_q[1];
+        transform[TRANSFORM64_ROTATION_OFFSET + 2] = scratch_q[2];
+        transform[TRANSFORM64_ROTATION_OFFSET + 3] = scratch_q[3];
 
         // the orientation moved, so the matrix is now behind the components
         transform.updateMatrix();

package/src/engine/physics/integration/integrate_velocity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrate_velocity.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_velocity.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,8EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB;AAED;;;;;;;;;;;;GAYG;AACH,qFAFW,MAAM,QAkDhB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CARW,YAAY,QACZ,MAAM,qBAEN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkChB"}
+{"version":3,"file":"integrate_velocity.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_velocity.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,8EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QA0DhB;AAED;;;;;;;;;;;;GAYG;AACH,qFAFW,MAAM,QAqDhB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CARW,YAAY,QACZ,MAAM,qBAEN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkChB"}

package/src/engine/physics/integration/integrate_velocity.js

@@ -1,7 +1,7 @@
 import { SBS_AV_X, SBS_AV_Y, SBS_AV_Z, SBS_LV_X, SBS_LV_Y, SBS_LV_Z, } from "../body/SolverBodyState.js";
 import { BodyKind } from "../ecs/BodyKind.js";
 import { RigidBodyFlags } from "../ecs/RigidBodyFlags.js";
-import { world_inverse_inertia_apply } from "../inertia/world_inverse_inertia.js";
+import { world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inertia.js";
 
 const scratch_angular = new Float64Array(3);
 
@@ -99,7 +99,13 @@ export function integrate_velocity(rb, transform, gx, gy, gz, dt) {
     let avy = av[1];
     let avz = av[2];
     if (at[0] !== 0 || at[1] !== 0 || at[2] !== 0) {
-        world_inverse_inertia_apply(scratch_angular, 0, locked_inverse_inertia(rb), transform.rotation, at[0], at[1], at[2]);
+        const ii = locked_inverse_inertia(rb);
+        world_inverse_inertia_apply_raw(
+            scratch_angular, 0,
+            ii[0], ii[1], ii[2],
+            transform.rotation_x, transform.rotation_y, transform.rotation_z, transform.rotation_w,
+            at[0], at[1], at[2]
+        );
         avx += scratch_angular[0] * dt;
         avy += scratch_angular[1] * dt;
         avz += scratch_angular[2] * dt;
@@ -156,9 +162,12 @@ export function integrate_velocity_forces(rb, transform, dt) {
 
     if (at[0] !== 0 || at[1] !== 0 || at[2] !== 0) {
 
-        world_inverse_inertia_apply(
+        const ii = locked_inverse_inertia(rb);
+
+        world_inverse_inertia_apply_raw(
             scratch_angular, 0,
-            locked_inverse_inertia(rb), transform.rotation,
+            ii[0], ii[1], ii[2],
+            transform.rotation_x, transform.rotation_y, transform.rotation_z, transform.rotation_w,
             at[0],
             at[1],
             at[2]

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

@@ -53,8 +53,9 @@ export class IslandBuilder {
      * 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.
+     * total. Insertion sort: used for short slices only (see
+     * {@link __sort_contact_slice}), where re-reading the keys per compare is
+     * cheaper than gathering them, and there is nothing to allocate.
      *
      * @private
      * @param {Uint32Array} data
@@ -79,7 +80,8 @@ export class IslandBuilder {
     /**
      * Union-find parent table, indexed by body index (NOT packed id).
      * Sized to `storage.high_water_mark` at `build` time; reallocated by
-     * doubling when the body pool grows past current capacity.
+     * doubling when the body pool grows past current capacity. Every body is
+     * its own root except those the last build united.
      * @type {Uint32Array}
      */
     parent: Uint32Array;
@@ -119,8 +121,8 @@ export class IslandBuilder {
      */
     contact_offsets: Uint32Array;
     /**
-     * Flattened manifold slot ids, grouped by island, sorted ascending
-     * within each island.
+     * Flattened manifold slot ids, grouped by island, sorted by canonical
+     * entity pair within each island (see the class doc).
      * @type {Uint32Array}
      */
     contact_data: Uint32Array;
@@ -131,11 +133,47 @@ export class IslandBuilder {
     contact_total: number;
     /**
      * Scratch: root body index → island id, or -1 if unassigned.
-     * Sized in lockstep with `parent`.
+     * Sized in lockstep with `parent`. -1 everywhere between builds: a build
+     * puts back the roots it wrote.
      * @private
      * @type {Int32Array}
      */
     private __root_to_island;
+    /**
+     * Scratch: the body indices whose `parent` entry the last build may have
+     * changed — every index it handed to the union-find — so the next build
+     * can put just those back to their own roots. Sized in lockstep with
+     * `parent`; `__uf_touched_count` valid entries.
+     *
+     * This and the generation stamps below keep a build's cost proportional to
+     * the bodies and contacts it sees, not to the body-slot high-water mark:
+     * re-initialising `parent`, `island_of_body` and `__root_to_island` over
+     * every slot made a build cost over a millisecond at a million slots with
+     * ten bodies awake; it costs 0.009 ms now.
+     * @private
+     * @type {Uint32Array}
+     */
+    private __uf_touched;
+    /**
+     * @private
+     * @type {number}
+     */
+    private __uf_touched_count;
+    /**
+     * Scratch: per body index, the build generation that last recorded it in
+     * {@link __uf_touched}, so each index is recorded once a build. Sized in
+     * lockstep with `parent`.
+     * @private
+     * @type {Int32Array}
+     */
+    private __uf_stamp;
+    /**
+     * Current build generation for {@link __uf_stamp}; never 0 once a build
+     * has begun, so a fresh (zeroed) stamp never reads as recorded.
+     * @private
+     * @type {number}
+     */
+    private __uf_generation;
     /**
      * Scratch: list of distinct root indices observed this frame, used
      * to sort them ascending before assigning island ids.
@@ -149,6 +187,41 @@ export class IslandBuilder {
      * @type {Uint32Array}
      */
     private __cursors;
+    /**
+     * Scratch for the keyed merge sort of long island contact slices: per
+     * element, the canonical entity pair (lo, hi) and the slot id, in two
+     * ping-pong banks. Empty until a slice longer than
+     * {@link CONTACT_SORT_INSERTION_MAX} is seen, then grown by doubling to the
+     * longest slice so far.
+     * @private
+     * @type {Int32Array}
+     */
+    private __sort_lo;
+    /**
+     * @private
+     * @type {Int32Array}
+     */
+    private __sort_hi;
+    /**
+     * @private
+     * @type {Uint32Array}
+     */
+    private __sort_slot;
+    /**
+     * @private
+     * @type {Int32Array}
+     */
+    private __sort_lo_swap;
+    /**
+     * @private
+     * @type {Int32Array}
+     */
+    private __sort_hi_swap;
+    /**
+     * @private
+     * @type {Uint32Array}
+     */
+    private __sort_slot_swap;
     /**
      * (Re)build islands from `manifolds`' currently-touched non-sensor slots
      * and the bodies in `storage`'s awake list.
@@ -176,6 +249,33 @@ export class IslandBuilder {
      * @private
      */
     private __build_contact_csr;
+    /**
+     * Sort `data[start..end)` (manifold slot ids) by canonical entity pair,
+     * producing exactly the order {@link __sort_slots_by_entity_pair} produces,
+     * for every input.
+     *
+     * Short slices go to that insertion sort. A connected pile is one island
+     * whose contacts arrive in manifold slot order, which is unrelated to entity
+     * order (inversions ≈ n²/4), so the insertion sort was quadratic there:
+     * 2,464 contacts in one island took 6.0 ms a step, 5,190 took 24 ms.
+     * Longer slices gather each slot's (lo, hi) key once and run a bottom-up
+     * merge sort over the retained scratch banks — O(n log n), no allocation
+     * once the banks have grown.
+     *
+     * Both sorts are stable (the insertion shifts only past strictly greater
+     * keys; the merge takes the left run on ties), and a stable sort's output is
+     * determined by the keys and the input order alone, so the two agree element
+     * for element — duplicate keys included, though a frame holds one slot per
+     * pair.
+     *
+     * @private
+     * @param {Uint32Array} data
+     * @param {number} start
+     * @param {number} end exclusive
+     * @param {BodyStorage} storage
+     * @param {ManifoldStore} manifolds
+     */
+    private __sort_contact_slice;
     /**
      * Resolve which island a manifold slot belongs to.
      *
@@ -192,6 +292,19 @@ export class IslandBuilder {
      * @param {number} n
      */
     private __ensure_body_capacity;
+    /**
+     * Roll the build generation for {@link __uf_stamp}; on (astronomically
+     * unlikely) Int32 wrap, clear the stamps so a recycled generation value
+     * can't read as already recorded. Same scheme as SolverBodyState#begin.
+     * @private
+     */
+    private __next_uf_generation;
+    /**
+     * Record that this build hands body index `idx` to the union-find, once.
+     * @private
+     * @param {number} idx
+     */
+    private __uf_touch;
     /**
      * @private
      * @param {number} n
@@ -207,5 +320,10 @@ export class IslandBuilder {
      * @param {number} n
      */
     private __ensure_contact_data_capacity;
+    /**
+     * @private
+     * @param {number} n
+     */
+    private __ensure_sort_capacity;
 }
 //# sourceMappingURL=IslandBuilder.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAuFI;;;;;OAKG;IACH,gCAMC;IA0ND;;;;;;;;;;;;;OAaG;IACH,2CAmBC;IAED;;;;;OAKG;IACH,6BAIC;IAED;;;OAGG;IACH,6BAIC;IAlXD;;;;;OAKG;IACH,QAFU,WAAW,CAEQ;IAE7B;;;;OAIG;IACH,gBAFU,UAAU,CAEgB;IAEpC;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,cAFU,WAAW,CAEa;IAElC;;;;OAIG;IACH,WAFU,WAAW,CAEW;IAEhC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,iBAFU,WAAW,CAEgB;IAErC;;;;OAIG;IACH,cAFU,WAAW,CAEc;IAEnC;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;OAKG;IACH,yBAAsC;IAEtC;;;;;OAKG;IACH,wBAAsC;IAEtC;;;;OAIG;IACH,kBAA+B;IAgB/B;;;;;;;;;;;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"}
+{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAyKI;;;;;OAKG;IACH,gCAMC;IAqWD;;;;;;;;;;;;;;OAcG;IACH,2CAmBC;IAED;;;;;OAKG;IACH,6BAIC;IAED;;;OAGG;IACH,6BAIC;IAhlBD;;;;;;OAMG;IACH,QAFU,WAAW,CAEQ;IAE7B;;;;OAIG;IACH,gBAFU,UAAU,CAEyB;IAE7C;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,cAFU,WAAW,CAEa;IAElC;;;;OAIG;IACH,WAFU,WAAW,CAEW;IAEhC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,iBAFU,WAAW,CAEgB;IAErC;;;;OAIG;IACH,cAFU,WAAW,CAEc;IAEnC;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;OAMG;IACH,yBAA+C;IAE/C;;;;;;;;;;;;;OAaG;IACH,qBAAmC;IAEnC;;;OAGG;IACH,2BAAuB;IAEvB;;;;;;OAMG;IACH,mBAAgC;IAEhC;;;;;OAKG;IACH,wBAAoB;IAEpB;;;;;OAKG;IACH,wBAAsC;IAEtC;;;;OAIG;IACH,kBAA+B;IAE/B;;;;;;;;OAQG;IACH,kBAA8B;IAE9B;;;OAGG;IACH,kBAA8B;IAE9B;;;OAGG;IACH,oBAAiC;IAEjC;;;OAGG;IACH,uBAAmC;IAEnC;;;OAGG;IACH,uBAAmC;IAEnC;;;OAGG;IACH,yBAAsC;IAgBtC;;;;;;;;;;;OAWG;IACH,8DANW,WAAW,uBACX,OAAO,UACP,OAAO,QAgIjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BA0CC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,6BAoFC;IA4DD;;;;;;;;;OASG;IACH,yBAsBC;IAID;;;OAGG;IACH,+BAeC;IAED;;;;;OAKG;IACH,6BAQC;IAED;;;;OAIG;IACH,mBAOC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;IAED;;;OAGG;IACH,+BAUC;CACJ"}