@woosh/meep-engine 2.147.0 → 2.148.0

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

@@ -1,77 +1,116 @@
-/**
- * Apply the world-frame inverse inertia tensor of a rigid body to a world-space
- * vector and write the result.
- *
- * Body-frame inverse inertia is supplied as a diagonal in principal axes
- * (a Vector3-like with `.x .y .z`). World inverse inertia is
- * `I_w⁻¹ = R · diag · R^T` where `R` is the body's orientation. We compute
- * `result = R · diag · R^T · v` without materialising the full 3x3 matrix:
- *
- *   1. `v_body = R^T · v`   (rotate v into body frame)
- *   2. scale component-wise by the diagonal
- *   3. `result = R · v_body_scaled`
- *
- * Quaternion-rotate-vector uses the standard `q · v · q*` identity. Inverse
- * rotation uses the conjugate quaternion.
- *
- * Sphere short-circuit: if the inverse inertia is isotropic (ix === iy === iz),
- * the rotation cancels and `result = ix * v`. Skip the trig and save the work.
- *
- * Decoupled from RigidBody / Transform on purpose — callers pass only what
- * is actually read. Lets `compute_penetration` and other standalone
- * geometry helpers reuse this without manufacturing a body.
- *
- * @param {number[]|Float64Array} result length >= 3
- * @param {number} result_offset
- * @param {{x: number, y: number, z: number}} inv_inertia_local
- *        Body-frame inverse inertia diagonal (typically `rb.inverseInertiaLocal`).
- * @param {{x: number, y: number, z: number, w: number}} rotation
- *        Body orientation as a unit quaternion (typically `transform.rotation`).
- * @param {number} vx
- * @param {number} vy
- * @param {number} vz
- */
-export function world_inverse_inertia_apply(
-    result, result_offset,
-    inv_inertia_local, rotation,
-    vx, vy, vz
-) {
-    const ix = inv_inertia_local.x, iy = inv_inertia_local.y, iz = inv_inertia_local.z;
-
-    if (ix === iy && iy === iz) {
-        // Isotropic — rotation cancels.
-        result[result_offset]     = vx * ix;
-        result[result_offset + 1] = vy * ix;
-        result[result_offset + 2] = vz * ix;
-        return;
-    }
-
-    const qx = rotation.x, qy = rotation.y, qz = rotation.z, qw = rotation.w;
-
-    // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
-    // quaternion (-qx, -qy, -qz, qw). Inlined for V8 inliner — see
-    // PosedShape.support and core/geom/vec3/v3_quat3_apply_inverse.js
-    // for the canonical form.
-    const cx = -qx, cy = -qy, cz = -qz;
-    const tx = qw * vx + cy * vz - cz * vy;
-    const ty = qw * vy + cz * vx - cx * vz;
-    const tz = qw * vz + cx * vy - cy * vx;
-    const tw = -cx * vx - cy * vy - cz * vz;
-    const vbx = tx * qw + tw * qx + ty * qz - tz * qy;
-    const vby = ty * qw + tw * qy + tz * qx - tx * qz;
-    const vbz = tz * qw + tw * qz + tx * qy - ty * qx;
-
-    // Step 2: scale by the principal-frame diagonal.
-    const sx = vbx * ix;
-    const sy = vby * iy;
-    const sz = vbz * iz;
-
-    // Step 3: result = R · scaled = q · scaled · q*. Inlined likewise.
-    const ux =  qw * sx + qy * sz - qz * sy;
-    const uy =  qw * sy + qz * sx - qx * sz;
-    const uz =  qw * sz + qx * sy - qy * sx;
-    const uw = -qx * sx - qy * sy - qz * sz;
-    result[result_offset]     = ux * qw + uw * (-qx) + uy * (-qz) - uz * (-qy);
-    result[result_offset + 1] = uy * qw + uw * (-qy) + uz * (-qx) - ux * (-qz);
-    result[result_offset + 2] = uz * qw + uw * (-qz) + ux * (-qy) - uy * (-qx);
-}
+/**
+ * Apply the world-frame inverse inertia tensor of a rigid body to a world-space
+ * vector and write the result.
+ *
+ * Body-frame inverse inertia is supplied as a diagonal in principal axes
+ * (a Vector3-like with `.x .y .z`). World inverse inertia is
+ * `I_w⁻¹ = R · diag · R^T` where `R` is the body's orientation. We compute
+ * `result = R · diag · R^T · v` without materialising the full 3x3 matrix:
+ *
+ *   1. `v_body = R^T · v`   (rotate v into body frame)
+ *   2. scale component-wise by the diagonal
+ *   3. `result = R · v_body_scaled`
+ *
+ * Quaternion-rotate-vector uses the standard `q · v · q*` identity. Inverse
+ * rotation uses the conjugate quaternion.
+ *
+ * Sphere short-circuit: if the inverse inertia is isotropic (ix === iy === iz),
+ * the rotation cancels and `result = ix * v`. Skip the trig and save the work.
+ *
+ * Decoupled from RigidBody / Transform on purpose — callers pass only what
+ * is actually read. Lets `compute_penetration` and other standalone
+ * geometry helpers reuse this without manufacturing a body.
+ *
+ * @param {number[]|Float64Array} result length >= 3
+ * @param {number} result_offset
+ * @param {{x: number, y: number, z: number}} inv_inertia_local
+ *        Body-frame inverse inertia diagonal (typically `rb.inverseInertiaLocal`).
+ * @param {{x: number, y: number, z: number, w: number}} rotation
+ *        Body orientation as a unit quaternion (typically `transform.rotation`).
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ */
+export function world_inverse_inertia_apply(
+    result, result_offset,
+    inv_inertia_local, rotation,
+    vx, vy, vz
+) {
+    // Thin object-reading wrapper over the raw-float kernel. Reads the
+    // quaternion fields eagerly (harmless in the isotropic short-circuit,
+    // where they're ignored) so the kernel is the single source of the math —
+    // keeping object callers and the data-oriented (SoA) solver path
+    // bit-identical.
+    world_inverse_inertia_apply_raw(
+        result, result_offset,
+        inv_inertia_local.x, inv_inertia_local.y, inv_inertia_local.z,
+        rotation.x, rotation.y, rotation.z, rotation.w,
+        vx, vy, vz
+    );
+}
+
+/**
+ * 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
+ * `{x,y,z}` / `{x,y,z,w}` objects. 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
+ */
+export function world_inverse_inertia_apply_raw(
+    result, result_offset,
+    ix, iy, iz,
+    qx, qy, qz, qw,
+    vx, vy, vz
+) {
+
+    if (ix === iy && iy === iz) {
+        // Isotropic — rotation cancels.
+        result[result_offset] = vx * ix;
+        result[result_offset + 1] = vy * ix;
+        result[result_offset + 2] = vz * ix;
+        return;
+    }
+
+    // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
+    // quaternion (-qx, -qy, -qz, qw). Inlined for V8 inliner — see
+    // PosedShape.support and core/geom/vec3/v3_quat3_apply_inverse.js
+    // for the canonical form.
+    const tx = qw * vx - qy * vz + qz * vy;
+    const ty = qw * vy - qz * vx + qx * vz;
+    const tz = qw * vz - qx * vy + qy * vx;
+    const tw = qx * vx + qy * vy + qz * vz;
+
+    const vbx = tx * qw + tw * qx + ty * qz - tz * qy;
+    const vby = ty * qw + tw * qy + tz * qx - tx * qz;
+    const vbz = tz * qw + tw * qz + tx * qy - ty * qx;
+
+    // Step 2: scale by the principal-frame diagonal.
+    const sx = vbx * ix;
+    const sy = vby * iy;
+    const sz = vbz * iz;
+
+    // Step 3: result = R · scaled = q · scaled · q*. Inlined likewise.
+    const ux = qw * sx + qy * sz - qz * sy;
+    const uy = qw * sy + qz * sx - qx * sz;
+    const uz = qw * sz + qx * sy - qy * sx;
+    const uw = -qx * sx - qy * sy - qz * sz;
+
+    result[result_offset] = ux * qw - uw * qx - uy * qz + uz * qy;
+    result[result_offset + 1] = uy * qw - uw * qy - uz * qx + ux * qz;
+    result[result_offset + 2] = uz * qw - uw * qz - ux * qy + uy * qx;
+}

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

@@ -20,6 +20,16 @@
  * no-op in that case. KinematicVelocity bodies advance under their
  * user-set velocity.
  *
+ * Persistent linear / angular velocity is read from the data-oriented
+ * {@link SolverBodyState} span (`ss` / `base`); the pose remains authoritative
+ * on the `Transform` and is written through `.set()` so its onChanged
+ * subscribers and the per-substep concave re-detection keep seeing the moved
+ * pose. The integrated orientation is mirrored back into the solver state so
+ * the next substep's impulse loop evaluates world inertia against the current
+ * frame.
+ *
+ * @param {Float64Array} ss solver-body-state data array
+ * @param {number} base `body_index * SBS_STRIDE`
  * @param {RigidBody} rb
  * @param {Transform} transform
  * @param {number} dt
@@ -30,5 +40,5 @@
  * @param {number} ps_ang_y
  * @param {number} ps_ang_z
  */
-export function integrate_position(rb: RigidBody, transform: Transform, 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: Transform, 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;
 //# 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":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,4EARW,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,QA2ChB"}
+{"version":3,"file":"integrate_position.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_position.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,uCAZW,YAAY,QACZ,MAAM,2CAGN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,QA8ChB"}

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

@@ -1,79 +1,97 @@
-import { BodyKind } from "../ecs/BodyKind.js";
-import { quat_integrate } from "./quat_integrate.js";
-
-const scratch_q = new Float64Array(4);
-
-/**
- * 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
- * implicitly discarded. The body's persistent `linearVelocity` /
- * `angularVelocity` (which carry restitution + warm-start across steps)
- * are never contaminated by it.
- *
- * Callers with no position-pass output should pass zeros for the six
- * pseudo arguments — 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.
- *
- * @param {RigidBody} rb
- * @param {Transform} 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
- */
-export function integrate_position(
-    rb, transform, dt,
-    ps_lin_x, ps_lin_y, ps_lin_z,
-    ps_ang_x, ps_ang_y, ps_ang_z,
-) {
-    if (rb.kind === BodyKind.Static) {
-        return;
-    }
-
-    const lv = rb.linearVelocity;
-    const p = transform.position;
-
-    // Combined integration velocity: persistent + pseudo. The pseudo
-    // contribution exists only for this step and never lands in `lv`.
-    const vx = lv[0] + ps_lin_x;
-    const vy = lv[1] + ps_lin_y;
-    const vz = lv[2] + ps_lin_z;
-
-    // Direct reads via typed-array index; the write goes through .set() so
-    // Transform's onChanged subscribers (matrix recompose, parent/child sync,
-    // viewport position, fog-of-war reveal) fire once per body per step.
-    p.set(
-        p[0] + vx * dt,
-        p[1] + vy * dt,
-        p[2] + vz * dt
-    );
-
-    const av = rb.angularVelocity;
-    const wx = av[0] + ps_ang_x;
-    const wy = av[1] + ps_ang_y;
-    const wz = av[2] + ps_ang_z;
-    if (wx !== 0 || wy !== 0 || wz !== 0) {
-        const q = transform.rotation;
-        quat_integrate(
-            scratch_q,
-            q[0], q[1], q[2], q[3],
-            wx, wy, wz,
-            dt
-        );
-        q.set(scratch_q[0], scratch_q[1], scratch_q[2], scratch_q[3]);
-    }
-}
+import { BodyKind } from "../ecs/BodyKind.js";
+import { quat_integrate } from "./quat_integrate.js";
+import {
+    SBS_QX, SBS_QY, SBS_QZ, SBS_QW,
+    SBS_LV_X, SBS_LV_Y, SBS_LV_Z,
+    SBS_AV_X, SBS_AV_Y, SBS_AV_Z,
+} from "../body/SolverBodyState.js";
+
+const scratch_q = new Float64Array(4);
+
+/**
+ * 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
+ * implicitly discarded. The body's persistent `linearVelocity` /
+ * `angularVelocity` (which carry restitution + warm-start across steps)
+ * are never contaminated by it.
+ *
+ * Callers with no position-pass output should pass zeros for the six
+ * pseudo arguments — 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.
+ *
+ * Persistent linear / angular velocity is read from the data-oriented
+ * {@link SolverBodyState} span (`ss` / `base`); the pose remains authoritative
+ * on the `Transform` and is written through `.set()` so its onChanged
+ * subscribers and the per-substep concave re-detection keep seeing the moved
+ * pose. The integrated orientation is mirrored back into the solver state so
+ * the next substep's impulse loop evaluates world inertia against the current
+ * frame.
+ *
+ * @param {Float64Array} ss solver-body-state data array
+ * @param {number} base `body_index * SBS_STRIDE`
+ * @param {RigidBody} rb
+ * @param {Transform} 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
+ */
+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,
+) {
+    if (rb.kind === BodyKind.Static) {
+        return;
+    }
+
+    const p = transform.position;
+
+    // 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;
+
+    // The write goes through .set() so Transform's onChanged subscribers
+    // (matrix recompose, parent/child sync, viewport position, fog-of-war
+    // reveal) fire — pose stays authoritative on the Transform.
+    p.set(
+        p[0] + vx * dt,
+        p[1] + vy * dt,
+        p[2] + 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;
+    if (wx !== 0 || wy !== 0 || wz !== 0) {
+        const q = transform.rotation;
+        quat_integrate(
+            scratch_q,
+            q[0], q[1], q[2], q[3],
+            wx, wy, wz,
+            dt
+        );
+        q.set(scratch_q[0], scratch_q[1], scratch_q[2], scratch_q[3]);
+        // Mirror the moved orientation into the solver state.
+        ss[base + SBS_QX] = scratch_q[0];
+        ss[base + SBS_QY] = scratch_q[1];
+        ss[base + SBS_QZ] = scratch_q[2];
+        ss[base + SBS_QW] = scratch_q[3];
+    }
+}

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

@@ -46,10 +46,19 @@ export function integrate_velocity_forces(rb: RigidBody, transform: Transform, d
  * cancels exactly — keeping a resting stack at zero velocity. Damping is the
  * stable implicit decay `v *= 1/(1 + d·dt)` applied at the substep `dt`.
  *
+ * Velocity (and the damping it applies) lives in the data-oriented
+ * {@link SolverBodyState} for the duration of the substep loop; this reads and
+ * writes that span by `base`. The body's configuration (kind / gravityScale /
+ * damping coefficients) is still read from the `RigidBody` — cheap, once per
+ * body per substep, and unchanged across the step.
+ *
+ * @param {Float64Array} ss solver-body-state data array
+ * @param {number} base `body_index * SBS_STRIDE`
  * @param {RigidBody} rb
- * @param {Transform} transform  (unused; signature symmetry with the family)
- * @param {number} gx @param {number} gy @param {number} gz world gravity
+ * @param {number} gx
+ * @param {number} gy
+ * @param {number} gz world gravity
  * @param {number} dt sub-step size in seconds
  */
-export function integrate_velocity_gravity(rb: RigidBody, transform: Transform, gx: number, gy: number, gz: number, dt: number): void;
+export function integrate_velocity_gravity(ss: Float64Array, base: number, rb: RigidBody, gx: number, gy: number, gz: number, dt: number): void;
 //# sourceMappingURL=integrate_velocity.d.ts.map

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":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB;AAED;;;;;;;;;;;;GAYG;AACH,mFAFW,MAAM,QA6BhB;AAED;;;;;;;;;;;;;;GAcG;AACH,oFAHW,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,QAwBhB"}
+{"version":3,"file":"integrate_velocity.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_velocity.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4EALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAoDhB;AAED;;;;;;;;;;;;GAYG;AACH,mFAFW,MAAM,QAkDhB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CARW,YAAY,QACZ,MAAM,qBAEN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAkChB"}