@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -0,0 +1,83 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Legacy (pre-mask) red-black SOR pressure solve, kept ONLY for the
+ * bench.spec.js A/B comparison against the mask-driven variant. Do not import
+ * from production code — {@link v3_grid_solve_pressure} is the live solver.
+ *
+ * Behaviourally identical to the live solver, but reads from the raw `solid`
+ * mask and performs boundary checks inline. Used to measure the per-step cost
+ * difference attributable to mask preprocessing.
+ *
+ * @param {Float32Array|Float16Array} pressure
+ * @param {Float32Array|Float16Array} divergence
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} iterations
+ * @param {number} omega
+ * @param {Uint8Array} solid
+ */
+export function v3_grid_solve_pressure_unmasked_legacy(pressure, divergence, res_x, res_y, res_z, iterations, omega, solid) {
+    const cell_count = res_x * res_y * res_z;
+
+    assert.notEqual(pressure, divergence, "pressure must not alias divergence");
+    assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
+    assert.greaterThanOrEqual(divergence.length, cell_count, "divergence covers grid");
+    assert.isNonNegativeInteger(iterations, "iterations");
+    assert.greaterThan(omega, 0, "omega");
+    assert.lessThan(omega, 2, "omega");
+
+    if (iterations === 0) {
+        return;
+    }
+
+    const slice_size = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+    const one_minus_omega = 1 - omega;
+
+    for (let iter = 0; iter < iterations; iter++) {
+        for (let pass = 0; pass < 2; pass++) {
+            for (let z = 0; z < res_z; z++) {
+                const z_off = z * slice_size;
+                const has_zm = z > 0;
+                const has_zp = z < last_z;
+
+                for (let y = 0; y < res_y; y++) {
+                    const y_off = y * res_x;
+                    const has_ym = y > 0;
+                    const has_yp = y < last_y;
+
+                    let x_start = ((z + y) & 1) ^ pass;
+
+                    for (let x = x_start; x < res_x; x += 2) {
+                        const c = z_off + y_off + x;
+
+                        if (solid[c] !== 0) {
+                            continue;
+                        }
+
+                        let sum = 0;
+                        let count = 0;
+
+                        if (x > 0      && solid[c - 1] === 0)          { sum += pressure[c - 1];          count++; }
+                        if (x < last_x && solid[c + 1] === 0)          { sum += pressure[c + 1];          count++; }
+                        if (has_ym     && solid[c - res_x] === 0)      { sum += pressure[c - res_x];      count++; }
+                        if (has_yp     && solid[c + res_x] === 0)      { sum += pressure[c + res_x];      count++; }
+                        if (has_zm     && solid[c - slice_size] === 0) { sum += pressure[c - slice_size]; count++; }
+                        if (has_zp     && solid[c + slice_size] === 0) { sum += pressure[c + slice_size]; count++; }
+
+                        if (count === 0) {
+                            continue;
+                        }
+
+                        const p_target = (sum - divergence[c]) / count;
+                        pressure[c] = one_minus_omega * pressure[c] + omega * p_target;
+                    }
+                }
+            }
+        }
+    }
+}

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Subtract the pressure gradient from a velocity field in-place, making the velocity
+ * (approximately) divergence-free:
+ *
+ *     v(c) -= 0.5 * ( p(x+1) - p(x-1), p(y+1) - p(y-1), p(z+1) - p(z-1) )
+ *
+ * Pairs with {@link v3_grid_solve_pressure}. After this, divergence will be
+ * close to zero in the bulk; residual divergence at boundaries / under-converged solves
+ * is normal.
+ *
+ * Boundary cells use one-sided differences. Solid cells have their velocity zeroed
+ * (no-slip), and neighbour gradients across a solid face reflect the cell's own
+ * pressure (consistent with the Neumann condition used in the solve), which keeps the
+ * flow tangent to the boundary.
+ *
+ * @param {Float32Array} vel_x       Mutated in place.
+ * @param {Float32Array} vel_y       Mutated in place.
+ * @param {Float32Array} vel_z       Mutated in place.
+ * @param {Float32Array} pressure    From {@link v3_grid_solve_pressure}.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid         Required (zero-filled for a wall-free domain).
+ */
+export function v3_grid_subtract_pressure_gradient(vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, pressure: Float32Array, res_x: number, res_y: number, res_z: number, solid: Uint8Array): void;
+//# sourceMappingURL=v3_grid_subtract_pressure_gradient.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,0DATW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,SACN,UAAU,QA6CpB"}

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

@@ -0,0 +1,70 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Subtract the pressure gradient from a velocity field in-place, making the velocity
+ * (approximately) divergence-free:
+ *
+ *     v(c) -= 0.5 * ( p(x+1) - p(x-1), p(y+1) - p(y-1), p(z+1) - p(z-1) )
+ *
+ * Pairs with {@link v3_grid_solve_pressure}. After this, divergence will be
+ * close to zero in the bulk; residual divergence at boundaries / under-converged solves
+ * is normal.
+ *
+ * Boundary cells use one-sided differences. Solid cells have their velocity zeroed
+ * (no-slip), and neighbour gradients across a solid face reflect the cell's own
+ * pressure (consistent with the Neumann condition used in the solve), which keeps the
+ * flow tangent to the boundary.
+ *
+ * @param {Float32Array} vel_x       Mutated in place.
+ * @param {Float32Array} vel_y       Mutated in place.
+ * @param {Float32Array} vel_z       Mutated in place.
+ * @param {Float32Array} pressure    From {@link v3_grid_solve_pressure}.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} solid         Required (zero-filled for a wall-free domain).
+ */
+export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure, res_x, res_y, res_z, solid) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
+    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
+    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
+    assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
+
+    const slice_size = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+
+                if (solid[c] !== 0) {
+                    vel_x[c] = 0;
+                    vel_y[c] = 0;
+                    vel_z[c] = 0;
+                    continue;
+                }
+
+                // Reflect pressure across a solid neighbour: that face contributes 0
+                // to the gradient, consistent with ∂p/∂n = 0 at the wall.
+                const p_xm = (x > 0      && solid[c - 1] === 0)          ? pressure[c - 1]          : pressure[c];
+                const p_xp = (x < last_x && solid[c + 1] === 0)          ? pressure[c + 1]          : pressure[c];
+                const p_ym = (y > 0      && solid[c - res_x] === 0)      ? pressure[c - res_x]      : pressure[c];
+                const p_yp = (y < last_y && solid[c + res_x] === 0)      ? pressure[c + res_x]      : pressure[c];
+                const p_zm = (z > 0      && solid[c - slice_size] === 0) ? pressure[c - slice_size] : pressure[c];
+                const p_zp = (z < last_z && solid[c + slice_size] === 0) ? pressure[c + slice_size] : pressure[c];
+
+                vel_x[c] -= 0.5 * (p_xp - p_xm);
+                vel_y[c] -= 0.5 * (p_yp - p_ym);
+                vel_z[c] -= 0.5 * (p_zp - p_zm);
+            }
+        }
+    }
+}

package/src/engine/physics/gjk/expanding_polytope_algorithm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expanding_polytope_algorithm.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/expanding_polytope_algorithm.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;GAUG;AACH,qDATW,MAAM,EAAE,iBACR,MAAM,KACN,MAAM,EAAE,KACR,MAAM,EAAE,KACR,MAAM,EAAE,KACR,MAAM,EAAE,wDAgQlB"}
+{"version":3,"file":"expanding_polytope_algorithm.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/expanding_polytope_algorithm.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;GAUG;AACH,qDATW,MAAM,EAAE,iBACR,MAAM,KACN,MAAM,EAAE,KACR,MAAM,EAAE,KACR,MAAM,EAAE,KACR,MAAM,EAAE,wDA8PlB"}

package/src/engine/physics/gjk/expanding_polytope_algorithm.js

@@ -238,12 +238,12 @@ export function expanding_polytope_algorithm(
                 }
 
                 if (!found_edge) { //add current edge to list
-                    // assert(num_loose_edges<EPA_MAX_NUM_LOOSE_EDGES);
-
-                    assert.lessThan(num_loose_edges, EPA_MAX_NUM_LOOSE_EDGES);
-
                     if (num_loose_edges >= EPA_MAX_NUM_LOOSE_EDGES) {
-                        // this should not happen, but if it does it is best to be "kind of right" than to fail completely
+                        // Polytope degenerated (typically smooth-surface
+                        // pairs the dispatch should be special-casing — this
+                        // is the safety net). Bail out and return the
+                        // closest-face result accumulated so far instead of
+                        // crashing the simulation step.
                         break;
                     }
 
@@ -271,12 +271,10 @@ export function expanding_polytope_algorithm(
 
         //Reconstruct polytope with p added
         for (let i = 0; i < num_loose_edges; i++) {
-            // assert(num_faces<EPA_MAX_NUM_FACES);
-
-            assert.lessThan(num_faces, EPA_MAX_NUM_FACES);
-
             if (num_faces >= EPA_MAX_NUM_FACES) {
-                // should never happen
+                // Polytope hit the face cap before converging. Same
+                // degenerate-surface story as the loose-edge overflow above.
+                // Bail out and let the caller use the best face found so far.
                 break;
             }
 

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

@@ -0,0 +1,29 @@
+/**
+ * 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 stored as a diagonal in principal axes
+ * (`rb.inverseInertiaLocal`). 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.
+ *
+ * @param {number[]|Float64Array} result length >= 3
+ * @param {number} result_offset
+ * @param {RigidBody} rb
+ * @param {Transform} transform
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ */
+export function world_inverse_inertia_apply(result: number[] | Float64Array, result_offset: number, rb: RigidBody, transform: Transform, vx: number, vy: number, vz: number): void;
+//# sourceMappingURL=world_inverse_inertia.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,oDARW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,2CAGN,MAAM,MACN,MAAM,MACN,MAAM,QAqDhB"}

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

@@ -0,0 +1,79 @@
+/**
+ * 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 stored as a diagonal in principal axes
+ * (`rb.inverseInertiaLocal`). 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.
+ *
+ * @param {number[]|Float64Array} result length >= 3
+ * @param {number} result_offset
+ * @param {RigidBody} rb
+ * @param {Transform} transform
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ */
+export function world_inverse_inertia_apply(
+    result, result_offset,
+    rb, transform,
+    vx, vy, vz
+) {
+    const ii = rb.inverseInertiaLocal;
+    const ix = ii.x, iy = ii.y, iz = ii.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 q = transform.rotation;
+    const qx = q.x, qy = q.y, qz = q.z, qw = q.w;
+
+    // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
+    // quaternion (-qx, -qy, -qz, qw).
+    // Identity: v' = q · v · q*. For inverse rotation use q* on either side.
+    // Equivalent expanded form:
+    //   t = (q* · v_quat)   where v_quat = (vx, vy, vz, 0)
+    //   v_body = (t · q).xyz
+    {
+        const cx = -qx, cy = -qy, cz = -qz;
+        // t = c · v (Hamilton product, treating v as pure quaternion w=0)
+        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;
+        // v_body = t · (c*)  where c* = (qx, qy, qz, qw)
+        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 diagonal.
+        const sx = vbx * ix;
+        const sy = vby * iy;
+        const sz = vbz * iz;
+
+        // Step 3: result = R · scaled = q · scaled · q*
+        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

@@ -0,0 +1,16 @@
+/**
+ * Integrate `transform.position` and `transform.rotation` from the body's
+ * current linear and angular velocity over a step `dt`. Static bodies are not
+ * touched.
+ *
+ * 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
+ */
+export function integrate_position(rb: RigidBody, transform: Transform, dt: number): void;
+//# sourceMappingURL=integrate_position.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"integrate_position.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/integrate_position.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,4EAFW,MAAM,QA8BhB"}

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

@@ -0,0 +1,48 @@
+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.
+ *
+ * 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
+ */
+export function integrate_position(rb, transform, dt) {
+    if (rb.kind === BodyKind.Static) {
+        return;
+    }
+
+    const lv = rb.linearVelocity;
+    const p = transform.position;
+
+    // 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] + lv[0] * dt,
+        p[1] + lv[1] * dt,
+        p[2] + lv[2] * dt
+    );
+
+    const av = rb.angularVelocity;
+    if (av[0] !== 0 || av[1] !== 0 || av[2] !== 0) {
+        const q = transform.rotation;
+        quat_integrate(
+            scratch_q,
+            q[0], q[1], q[2], q[3],
+            av[0], av[1], av[2],
+            dt
+        );
+        q.set(scratch_q[0], scratch_q[1], scratch_q[2], scratch_q[3]);
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Semi-implicit Euler velocity integration for a single rigid body.
+ *
+ * For Dynamic bodies:
+ *  - gravity (scaled by `gravityScale`) and the accumulated force are converted
+ *    to a velocity delta via `1/mass`,
+ *  - accumulated torque is converted to angular acceleration via the
+ *    world-frame inverse inertia (R · diag(I_local) · R^T applied to τ),
+ *  - linear and angular damping are applied as a stable implicit decay
+ *    `v *= 1 / (1 + d·dt)` (Box2D / Bullet recipe — never goes negative, no
+ *    `exp()` call on the hot path),
+ *  - the force / torque accumulators are zeroed afterwards.
+ *
+ * Kinematic and Static bodies are skipped — their velocity is the
+ * user / animation system's responsibility.
+ *
+ * @param {RigidBody} rb
+ * @param {Transform} transform  used to rotate body-frame inertia into world
+ * @param {number} gx world gravity x
+ * @param {number} gy world gravity y
+ * @param {number} gz world gravity z
+ * @param {number} dt step size in seconds
+ */
+export function integrate_velocity(rb: RigidBody, transform: Transform, 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

@@ -0,0 +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"}

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

@@ -0,0 +1,79 @@
+import { BodyKind } from "../ecs/BodyKind.js";
+import { world_inverse_inertia_apply } from "../inertia/world_inverse_inertia.js";
+
+const scratch_angular = new Float64Array(3);
+
+/**
+ * Semi-implicit Euler velocity integration for a single rigid body.
+ *
+ * For Dynamic bodies:
+ *  - gravity (scaled by `gravityScale`) and the accumulated force are converted
+ *    to a velocity delta via `1/mass`,
+ *  - accumulated torque is converted to angular acceleration via the
+ *    world-frame inverse inertia (R · diag(I_local) · R^T applied to τ),
+ *  - linear and angular damping are applied as a stable implicit decay
+ *    `v *= 1 / (1 + d·dt)` (Box2D / Bullet recipe — never goes negative, no
+ *    `exp()` call on the hot path),
+ *  - the force / torque accumulators are zeroed afterwards.
+ *
+ * Kinematic and Static bodies are skipped — their velocity is the
+ * user / animation system's responsibility.
+ *
+ * @param {RigidBody} rb
+ * @param {Transform} transform  used to rotate body-frame inertia into world
+ * @param {number} gx world gravity x
+ * @param {number} gy world gravity y
+ * @param {number} gz world gravity z
+ * @param {number} dt step size in seconds
+ */
+export function integrate_velocity(rb, transform, gx, gy, gz, dt) {
+    const af = rb.accumulatedForce;
+    const at = rb.accumulatedTorque;
+
+    if (rb.kind !== BodyKind.Dynamic) {
+        // Direct indexing — no observer listens to body-internal accumulators.
+        af[0] = 0; af[1] = 0; af[2] = 0;
+        at[0] = 0; at[1] = 0; at[2] = 0;
+        return;
+    }
+
+    const inv_m = rb.mass > 0 ? 1 / rb.mass : 0;
+    const gs = rb.gravityScale;
+
+    // Linear velocity update: v += (F * invM + g * gravityScale) * dt
+    const lv = rb.linearVelocity;
+    let lvx = lv[0] + (af[0] * inv_m + gx * gs) * dt;
+    let lvy = lv[1] + (af[1] * inv_m + gy * gs) * dt;
+    let lvz = lv[2] + (af[2] * inv_m + gz * gs) * dt;
+
+    if (rb.linearDamping > 0) {
+        const k = 1 / (1 + rb.linearDamping * dt);
+        lvx *= k;
+        lvy *= k;
+        lvz *= k;
+    }
+    lv[0] = lvx; lv[1] = lvy; lv[2] = lvz;
+
+    // Angular velocity update: ω += I_world⁻¹ · τ · dt
+    const av = rb.angularVelocity;
+    let avx = av[0];
+    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, rb, transform, at[0], at[1], at[2]);
+        avx += scratch_angular[0] * dt;
+        avy += scratch_angular[1] * dt;
+        avz += scratch_angular[2] * dt;
+    }
+
+    if (rb.angularDamping > 0) {
+        const k = 1 / (1 + rb.angularDamping * dt);
+        avx *= k;
+        avy *= k;
+        avz *= k;
+    }
+    av[0] = avx; av[1] = avy; av[2] = avz;
+
+    af[0] = 0; af[1] = 0; af[2] = 0;
+    at[0] = 0; at[1] = 0; at[2] = 0;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Advance a unit quaternion `q` by an angular velocity `omega` over a step `dt`,
+ * using the first-order formula
+ *
+ *     dq/dt = 0.5 * Omega(omega) * q
+ *
+ * where `Omega(omega)` is the pure-quaternion `(omega_x, omega_y, omega_z, 0)`.
+ * Result is renormalised so the output stays unit.
+ *
+ * This is the standard semi-implicit angular integrator (Catto GDC 2009 et al.).
+ * For typical game-physics step sizes (1/60 s) and angular speeds, the
+ * first-order error is dominated by the renormalisation projection back to the
+ * unit sphere — closed-form exp via axis-angle would only matter for very large
+ * `|omega|·dt`.
+ *
+ * @param {number[]|Float64Array|Quaternion} result_q  destination (may alias `qx..qw`)
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @param {number} omega_x
+ * @param {number} omega_y
+ * @param {number} omega_z
+ * @param {number} dt
+ */
+export function quat_integrate(result_q: number[] | Float64Array | Quaternion, qx: number, qy: number, qz: number, qw: number, omega_x: number, omega_y: number, omega_z: number, dt: number): void;
+//# sourceMappingURL=quat_integrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quat_integrate.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/integration/quat_integrate.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,yCAVW,MAAM,EAAE,GAAC,YAAY,aAAW,MAChC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,MACN,MAAM,QAsChB"}

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

@@ -0,0 +1,62 @@
+/**
+ * Advance a unit quaternion `q` by an angular velocity `omega` over a step `dt`,
+ * using the first-order formula
+ *
+ *     dq/dt = 0.5 * Omega(omega) * q
+ *
+ * where `Omega(omega)` is the pure-quaternion `(omega_x, omega_y, omega_z, 0)`.
+ * Result is renormalised so the output stays unit.
+ *
+ * This is the standard semi-implicit angular integrator (Catto GDC 2009 et al.).
+ * For typical game-physics step sizes (1/60 s) and angular speeds, the
+ * first-order error is dominated by the renormalisation projection back to the
+ * unit sphere — closed-form exp via axis-angle would only matter for very large
+ * `|omega|·dt`.
+ *
+ * @param {number[]|Float64Array|Quaternion} result_q  destination (may alias `qx..qw`)
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @param {number} omega_x
+ * @param {number} omega_y
+ * @param {number} omega_z
+ * @param {number} dt
+ */
+export function quat_integrate(
+    result_q,
+    qx, qy, qz, qw,
+    omega_x, omega_y, omega_z,
+    dt
+) {
+    const h = 0.5 * dt;
+
+    const dqx = h * (omega_x * qw + omega_y * qz - omega_z * qy);
+    const dqy = h * (omega_y * qw + omega_z * qx - omega_x * qz);
+    const dqz = h * (omega_z * qw + omega_x * qy - omega_y * qx);
+    const dqw = -h * (omega_x * qx + omega_y * qy + omega_z * qz);
+
+    let nx = qx + dqx;
+    let ny = qy + dqy;
+    let nz = qz + dqz;
+    let nw = qw + dqw;
+
+    // Renormalise. Using sqrt (which is bit-exact across IEEE-754 platforms)
+    // rather than the (3 - |q|²)/2 cheap-Newton trick — the latter biases
+    // length for non-unit inputs.
+    const norm_sqr = nx * nx + ny * ny + nz * nz + nw * nw;
+    if (norm_sqr > 0) {
+        const inv_len = 1 / Math.sqrt(norm_sqr);
+        nx *= inv_len;
+        ny *= inv_len;
+        nz *= inv_len;
+        nw *= inv_len;
+    } else {
+        nx = 0; ny = 0; nz = 0; nw = 1;
+    }
+
+    result_q[0] = nx;
+    result_q[1] = ny;
+    result_q[2] = nz;
+    result_q[3] = nw;
+}