@woosh/meep-engine 2.156.0 → 2.158.0

package/src/engine/physics/fluid/solver/v3_mac_subtract_pressure_gradient.js

@@ -0,0 +1,104 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Subtract the pressure gradient from a MAC velocity field in place — the
+ * face-exact counterpart of the collocated
+ * {@link v3_grid_subtract_pressure_gradient}:
+ *
+ *     u(face) −= p(right cell) − p(left cell)        (h = 1)
+ *
+ * Per face:
+ *   - both adjacent cells fluid: subtract the pressure difference.
+ *   - PINNED face (either adjacent cell solid): SKIPPED — its stored value is
+ *     the wall's normal-velocity boundary condition (0 for static solids,
+ *     the wall speed for movers; see {@link v3_mac_compute_face_solid}) and
+ *     must survive the projection. Stray deposits are prevented upstream:
+ *     the mask rebuild zeroes faces on every unpinned→pinned transition and
+ *     every transport/effector kernel skips pinned faces.
+ *   - domain-edge face (open boundary): the missing cell is the Dirichlet
+ *     ghost p = 0, so interior pressure vents flow out through the face.
+ *
+ * Together with {@link v3_mac_compute_divergence} and the unchanged 7-point
+ * solve this forms an exact discrete Helmholtz projection: solve error aside,
+ * post-projection divergence is zero — including immediately beside walls,
+ * which the collocated form could only approximate.
+ *
+ * Face grid layout: see {@link v3_mac_compute_face_solid}.
+ *
+ * @param {Float32Array} vel_u  Mutated in place, (res_x+1)·res_y·res_z.
+ * @param {Float32Array} vel_v  Mutated in place, res_x·(res_y+1)·res_z.
+ * @param {Float32Array} vel_w  Mutated in place, res_x·res_y·(res_z+1).
+ * @param {Float32Array|Float16Array} pressure  Cell-centered, from the solve.
+ * @param {Uint8Array} face_solid_x  From {@link v3_mac_compute_face_solid}.
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ */
+export function v3_mac_subtract_pressure_gradient(vel_u, vel_v, vel_w, pressure, face_solid_x, face_solid_y, face_solid_z, res_x, res_y, res_z) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(vel_u.length, (res_x + 1) * res_y * res_z, "vel_u covers grid");
+    assert.greaterThanOrEqual(vel_v.length, res_x * (res_y + 1) * res_z, "vel_v covers grid");
+    assert.greaterThanOrEqual(vel_w.length, res_x * res_y * (res_z + 1), "vel_w covers grid");
+    assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
+
+    const cell_slice = res_x * res_y;
+    const sx = res_x + 1;
+
+    // x-faces.
+    for (let z = 0; z < res_z; z++) {
+        const c_z = z * cell_slice;
+        const f_z = z * sx * res_y;
+        for (let y = 0; y < res_y; y++) {
+            const c_y = c_z + y * res_x;
+            const f_y = f_z + y * sx;
+            for (let x = 0; x <= res_x; x++) {
+                const f = f_y + x;
+                if (face_solid_x[f] !== 0) {
+                    // Boundary condition — preserved, not zeroed.
+                    continue;
+                }
+                const p_left = x === 0 ? 0 : pressure[c_y + x - 1];
+                const p_right = x === res_x ? 0 : pressure[c_y + x];
+                vel_u[f] -= p_right - p_left;
+            }
+        }
+    }
+
+    // y-faces.
+    for (let z = 0; z < res_z; z++) {
+        const c_z = z * cell_slice;
+        const f_z = z * res_x * (res_y + 1);
+        for (let y = 0; y <= res_y; y++) {
+            const f_y = f_z + y * res_x;
+            const c_below = c_z + (y - 1) * res_x;
+            const c_above = c_z + y * res_x;
+            for (let x = 0; x < res_x; x++) {
+                const f = f_y + x;
+                if (face_solid_y[f] !== 0) {
+                    continue;
+                }
+                const p_below = y === 0 ? 0 : pressure[c_below + x];
+                const p_above = y === res_y ? 0 : pressure[c_above + x];
+                vel_v[f] -= p_above - p_below;
+            }
+        }
+    }
+
+    // z-faces.
+    for (let z = 0; z <= res_z; z++) {
+        const f_z = z * cell_slice;
+        const c_near = (z - 1) * cell_slice;
+        const c_far = z * cell_slice;
+        for (let i = 0; i < cell_slice; i++) {
+            const f = f_z + i;
+            if (face_solid_z[f] !== 0) {
+                continue;
+            }
+            const p_near = z === 0 ? 0 : pressure[c_near + i];
+            const p_far = z === res_z ? 0 : pressure[c_far + i];
+            vel_w[f] -= p_far - p_near;
+        }
+    }
+}

package/src/engine/physics/inertia/world_inverse_inertia.d.ts

@@ -63,5 +63,34 @@ export function world_inverse_inertia_apply(result: number[] | Float64Array, res
  * @param {number} vy
  * @param {number} vz
  */
-export function world_inverse_inertia_apply_raw(result: number[] | Float64Array, result_offset: number, ix: number, iy: number, iz: number, qx: number, qy: number, qz: number, qw: number, vx: number, vy: number, vz: number): void;
+/**
+ * Quadratic-form contribution of one body to a unit-axis velocity
+ * constraint's effective mass: `(r × axis)ᵀ · I_w⁻¹ · (r × axis)`, where `r`
+ * is the body-relative application point. The full constraint denominator is
+ * `invM_A + invM_B + contribution_A + contribution_B`.
+ *
+ * The shared kernel behind the contact/joint solver's SoA path and the
+ * 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).
+ *
+ * @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} rx
+ * @param {number} ry
+ * @param {number} rz Body-relative application point.
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az Unit constraint axis.
+ * @param {number[]|Float64Array} scratch length >= 3, clobbered
+ * @returns {number}
+ */
+export function angular_effective_mass_raw(ix: number, iy: number, iz: number, qx: number, qy: number, qz: number, qw: number, rx: number, ry: number, rz: number, ax: number, ay: number, az: number, scratch: number[] | Float64Array): number;
+export function world_inverse_inertia_apply_raw(result: any, result_offset: any, ix: any, iy: any, iz: any, qx: any, qy: any, qz: any, qw: any, vx: any, vy: any, vz: any): void;
 //# sourceMappingURL=world_inverse_inertia.d.ts.map

package/src/engine/physics/inertia/world_inverse_inertia.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oDAVW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,qBACN;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,YAEjC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,MAE5C,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wDAbW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QA4ChB"}
+{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oDAVW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,qBACN;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,YAEjC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,MAE5C,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+CAhBW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAgBlB;AAED,iLA0CC"}

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

@@ -1,116 +1,160 @@
-/**
- * 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;
-}
+/**
+ * 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
+ */
+/**
+ * Quadratic-form contribution of one body to a unit-axis velocity
+ * constraint's effective mass: `(r × axis)ᵀ · I_w⁻¹ · (r × axis)`, where `r`
+ * is the body-relative application point. The full constraint denominator is
+ * `invM_A + invM_B + contribution_A + contribution_B`.
+ *
+ * The shared kernel behind the contact/joint solver's SoA path and the
+ * 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).
+ *
+ * @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} rx
+ * @param {number} ry
+ * @param {number} rz Body-relative application point.
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az Unit constraint axis.
+ * @param {number[]|Float64Array} scratch length >= 3, clobbered
+ * @returns {number}
+ */
+export function angular_effective_mass_raw(
+    ix, iy, iz,
+    qx, qy, qz, qw,
+    rx, ry, rz,
+    ax, ay, az,
+    scratch
+) {
+    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);
+
+    return cx * scratch[0] + cy * scratch[1] + cz * scratch[2];
+}
+
+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
+    // PosedShape3D.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.js

@@ -1,97 +1,97 @@
-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];
-    }
-}
+import { BodyKind } from "../ecs/BodyKind.js";
+import { quat3_integrate } from "../../../core/geom/3d/quaternion/quat3_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;
+        quat3_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];
+    }
+}