@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -0,0 +1,117 @@
+import { assert } from "../../../core/assert.js";
+import { MASS_PROPERTIES_SIZE } from "./MASS_PROPERTIES_SIZE.js";
+
+/**
+ * The hull's bounding box, for the scale of the inward-winding check.
+ * @type {Float64Array}
+ */
+const scratch_bounds = new Float64Array(6);
+
+/**
+ * Mass properties of a solid convex hull, in its own frame (see {@link MASS_PROPERTIES_SIZE}).
+ *
+ * The solid is cut into one tetrahedron per surface triangle, each fanned from a common reference
+ * point: the hull's first vertex. Over a closed, outward-wound surface the signed tetrahedra sum
+ * to the solid whatever point they share, so the point is chosen for round-off — on the hull, the
+ * coordinates entering the products stay on the scale of the hull rather than of its distance
+ * from the frame's origin. For a tetrahedron with a vertex at the reference and the others at
+ * v1, v2, v3 (relative), with D = v1 · (v2 × v3) six times its signed volume and v4 = v1 + v2 + v3:
+ *
+ *   volume  D / 6,   centroid  v4 / 4,   ∫ x_i x_j dV = D / 120 · (Σ_k v_k,i · v_k,j over v1..v4)
+ *
+ * The second moments about the reference are then moved to the centre of mass by the parallel
+ * axis theorem. The construction is Box3D's hull mass (hull.c, `b3ComputeHullMass` and the hull
+ * builder's inertia pass; MIT, Erin Catto), applied to the hull's triangles.
+ *
+ * The vertices are read as stored (`Float32Array`) and every product is formed in float64.
+ *
+ * A hull with no volume (flat, or no triangles) is the empty solid: all zeros. A hull wound inward
+ * sums to minus its volume and is refused (dev assert); with asserts stripped it too reads as all
+ * zeros.
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/ConvexHullShape3D.js").ConvexHullShape3D} shape a
+ *   closed, outward-CCW hull, as {@link ConvexHullShape3D.from} builds
+ * @param {number} density kg/m³
+ */
+export function convex_hull_mass_properties(out, shape, density) {
+    assert.isNumber(density, 'density');
+
+    const v = shape.vertices;
+    const idx = shape.indices;
+    const triangle_count = idx.length / 3;
+
+    if (v.length < 3 || triangle_count === 0) {
+        out.fill(0, 0, MASS_PROPERTIES_SIZE);
+        return;
+    }
+
+    const ox = v[0], oy = v[1], oz = v[2];
+
+    let volume6 = 0;
+    let sx = 0, sy = 0, sz = 0;
+    let xx = 0, yy = 0, zz = 0, xy = 0, xz = 0, yz = 0;
+
+    for (let t = 0; t < triangle_count; t++) {
+        const ia = idx[t * 3] * 3, ib = idx[t * 3 + 1] * 3, ic = idx[t * 3 + 2] * 3;
+
+        const x1 = v[ia] - ox, y1 = v[ia + 1] - oy, z1 = v[ia + 2] - oz;
+        const x2 = v[ib] - ox, y2 = v[ib + 1] - oy, z2 = v[ib + 2] - oz;
+        const x3 = v[ic] - ox, y3 = v[ic + 1] - oy, z3 = v[ic + 2] - oz;
+
+        // D = v1 · (v2 × v3)
+        const D = x1 * (y2 * z3 - z2 * y3) + y1 * (z2 * x3 - x2 * z3) + z1 * (x2 * y3 - y2 * x3);
+
+        const x4 = x1 + x2 + x3, y4 = y1 + y2 + y3, z4 = z1 + z2 + z3;
+
+        volume6 += D;
+        sx += D * x4;
+        sy += D * y4;
+        sz += D * z4;
+
+        xx += D * (x1 * x1 + x2 * x2 + x3 * x3 + x4 * x4);
+        yy += D * (y1 * y1 + y2 * y2 + y3 * y3 + y4 * y4);
+        zz += D * (z1 * z1 + z2 * z2 + z3 * z3 + z4 * z4);
+        xy += D * (x1 * y1 + x2 * y2 + x3 * y3 + x4 * y4);
+        xz += D * (x1 * z1 + x2 * z2 + x3 * z3 + x4 * z4);
+        yz += D * (y1 * z1 + y2 * z2 + y3 * z3 + y4 * z4);
+    }
+
+    // An inward-wound hull sums to minus its volume. ConvexHullShape3D's own volume is the
+    // magnitude, so nothing upstream catches it; here it would weigh as nothing. A flat hull sums
+    // to zero, give or take rounding on the scale of its extent.
+    shape.compute_bounding_box(scratch_bounds);
+    const extent = Math.max(scratch_bounds[3] - scratch_bounds[0], scratch_bounds[4] - scratch_bounds[1], scratch_bounds[5] - scratch_bounds[2]);
+    assert.ok(volume6 >= -1e-9 * extent * extent * extent,
+        `convex_hull_mass_properties: the hull's signed volume is ${volume6 / 6}, its triangles are wound inward; ConvexHullShape3D.from takes them outward CCW`);
+
+    if (!(volume6 > 0)) {
+        out.fill(0, 0, MASS_PROPERTIES_SIZE);
+        return;
+    }
+
+    const volume = volume6 / 6;
+
+    // centre of mass relative to the reference: Σ D·v4/4 over Σ D
+    const inv = 0.25 / volume6;
+    const cx = sx * inv, cy = sy * inv, cz = sz * inv;
+
+    // ∫ x_i x_j dV about the reference
+    const k = 1 / 120;
+    const ixx = xx * k, iyy = yy * k, izz = zz * k, ixy = xy * k, ixz = xz * k, iyz = yz * k;
+
+    const mass = density * volume;
+
+    out[0] = mass;
+    out[1] = ox + cx;
+    out[2] = oy + cy;
+    out[3] = oz + cz;
+
+    // Tensor about the centre: about the reference, less the centre's own share (parallel axis).
+    out[4] = density * ((iyy + izz) - volume * (cy * cy + cz * cz));
+    out[5] = density * ((ixx + izz) - volume * (cx * cx + cz * cz));
+    out[6] = density * ((ixx + iyy) - volume * (cx * cx + cy * cy));
+    out[7] = -density * (ixy - volume * cx * cy);
+    out[8] = -density * (ixz - volume * cx * cz);
+    out[9] = -density * (iyz - volume * cy * cz);
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Add one part of a compound solid to an accumulated record, in place (see
+ * {@link MASS_PROPERTIES_SIZE}). `part` is expressed in the part's own frame — as a shape function
+ * writes it — and is placed in the accumulator's frame (the body's) at `position` and `rotation`:
+ * the part's pose relative to the body origin, e.g. a child collider's local pose under its body.
+ *
+ * The result is again mass, centre of mass and the tensor about that centre: the part's tensor is
+ * turned into the body frame (R·I·Rᵀ), its centre placed (R·c + position), and both the
+ * accumulated solid's and the part's tensors moved onto the combined centre by the parallel axis
+ * theorem, I + m(|d|²E - d·dᵀ). A record of all zeros is the empty solid, so an accumulation starts
+ * from a fresh `Float64Array(MASS_PROPERTIES_SIZE)`; a part of no mass changes nothing.
+ *
+ * This is Box3D's `b3UpdateBodyMassData` (body.c, MIT, Erin Catto) done one part at a time, so it
+ * needs no second pass over the parts once the centre is known.
+ *
+ * @param {Float64Array|number[]} accumulator in/out, {@link MASS_PROPERTIES_SIZE} doubles in the
+ *   body frame
+ * @param {Float64Array|number[]} part {@link MASS_PROPERTIES_SIZE} doubles in the part's frame
+ * @param {ArrayLike<number>} position the part frame's origin in the body frame, as [x, y, z]
+ * @param {ArrayLike<number>} rotation the part frame's orientation in the body frame, a unit
+ *   quaternion as [x, y, z, w]
+ */
+export function mass_properties_accumulate(accumulator: Float64Array | number[], part: Float64Array | number[], position: ArrayLike<number>, rotation: ArrayLike<number>): void;
+//# sourceMappingURL=mass_properties_accumulate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mass_properties_accumulate.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/mass_properties_accumulate.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wDAPW,YAAY,GAAC,MAAM,EAAE,QAErB,YAAY,GAAC,MAAM,EAAE,YACrB,UAAU,MAAM,CAAC,YACjB,UAAU,MAAM,CAAC,QA+D3B"}

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

@@ -0,0 +1,93 @@
+import { assert } from "../../../core/assert.js";
+import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
+
+/**
+ * Rotation of the part being added, from {@link quat3_to_matrix3}: element `3a + j` is row j of
+ * column a of the rotation matrix R.
+ * @type {Float64Array}
+ */
+const scratch_rotation = new Float64Array(9);
+
+/**
+ * Add one part of a compound solid to an accumulated record, in place (see
+ * {@link MASS_PROPERTIES_SIZE}). `part` is expressed in the part's own frame — as a shape function
+ * writes it — and is placed in the accumulator's frame (the body's) at `position` and `rotation`:
+ * the part's pose relative to the body origin, e.g. a child collider's local pose under its body.
+ *
+ * The result is again mass, centre of mass and the tensor about that centre: the part's tensor is
+ * turned into the body frame (R·I·Rᵀ), its centre placed (R·c + position), and both the
+ * accumulated solid's and the part's tensors moved onto the combined centre by the parallel axis
+ * theorem, I + m(|d|²E - d·dᵀ). A record of all zeros is the empty solid, so an accumulation starts
+ * from a fresh `Float64Array(MASS_PROPERTIES_SIZE)`; a part of no mass changes nothing.
+ *
+ * This is Box3D's `b3UpdateBodyMassData` (body.c, MIT, Erin Catto) done one part at a time, so it
+ * needs no second pass over the parts once the centre is known.
+ *
+ * @param {Float64Array|number[]} accumulator in/out, {@link MASS_PROPERTIES_SIZE} doubles in the
+ *   body frame
+ * @param {Float64Array|number[]} part {@link MASS_PROPERTIES_SIZE} doubles in the part's frame
+ * @param {ArrayLike<number>} position the part frame's origin in the body frame, as [x, y, z]
+ * @param {ArrayLike<number>} rotation the part frame's orientation in the body frame, a unit
+ *   quaternion as [x, y, z, w]
+ */
+export function mass_properties_accumulate(accumulator, part, position, rotation) {
+    const m = part[0];
+    assert.greaterThanOrEqual(m, 0, 'part mass');
+
+    if (m === 0) {
+        return;
+    }
+
+    quat3_to_matrix3(scratch_rotation, 0, rotation[0], rotation[1], rotation[2], rotation[3]);
+    const R = scratch_rotation;
+    const r00 = R[0], r10 = R[1], r20 = R[2];
+    const r01 = R[3], r11 = R[4], r21 = R[5];
+    const r02 = R[6], r12 = R[7], r22 = R[8];
+
+    // The part's centre in the body frame.
+    const lx = part[1], ly = part[2], lz = part[3];
+    const px = r00 * lx + r01 * ly + r02 * lz + position[0];
+    const py = r10 * lx + r11 * ly + r12 * lz + position[1];
+    const pz = r20 * lx + r21 * ly + r22 * lz + position[2];
+
+    // The part's tensor in the body frame, R·T·Rᵀ, T symmetric.
+    const a = part[4], b = part[5], c = part[6], d = part[7], e = part[8], f = part[9];
+
+    // rows of R·T
+    const t00 = r00 * a + r01 * d + r02 * e, t01 = r00 * d + r01 * b + r02 * f, t02 = r00 * e + r01 * f + r02 * c;
+    const t10 = r10 * a + r11 * d + r12 * e, t11 = r10 * d + r11 * b + r12 * f, t12 = r10 * e + r11 * f + r12 * c;
+    const t20 = r20 * a + r21 * d + r22 * e, t21 = r20 * d + r21 * b + r22 * f, t22 = r20 * e + r21 * f + r22 * c;
+
+    // (R·T)·Rᵀ: element (j, k) is row j of R·T against row k of R
+    const ixx = t00 * r00 + t01 * r01 + t02 * r02;
+    const iyy = t10 * r10 + t11 * r11 + t12 * r12;
+    const izz = t20 * r20 + t21 * r21 + t22 * r22;
+    const ixy = t00 * r10 + t01 * r11 + t02 * r12;
+    const ixz = t00 * r20 + t01 * r21 + t02 * r22;
+    const iyz = t10 * r20 + t11 * r21 + t12 * r22;
+
+    // The combined centre.
+    const M = accumulator[0];
+    const cx = accumulator[1], cy = accumulator[2], cz = accumulator[3];
+
+    const total = M + m;
+    const nx = (M * cx + m * px) / total;
+    const ny = (M * cy + m * py) / total;
+    const nz = (M * cz + m * pz) / total;
+
+    // Each solid's offset from the combined centre.
+    const ax = cx - nx, ay = cy - ny, az = cz - nz;
+    const bx = px - nx, by = py - ny, bz = pz - nz;
+
+    accumulator[0] = total;
+    accumulator[1] = nx;
+    accumulator[2] = ny;
+    accumulator[3] = nz;
+
+    accumulator[4] += ixx + M * (ay * ay + az * az) + m * (by * by + bz * bz);
+    accumulator[5] += iyy + M * (ax * ax + az * az) + m * (bx * bx + bz * bz);
+    accumulator[6] += izz + M * (ax * ax + ay * ay) + m * (bx * bx + by * by);
+    accumulator[7] += ixy - M * ax * ay - m * bx * by;
+    accumulator[8] += ixz - M * ax * az - m * bx * bz;
+    accumulator[9] += iyz - M * ay * az - m * by * bz;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Mass properties of a solid sphere, in its own frame (see {@link MASS_PROPERTIES_SIZE}):
+ * mass ρ·4/3·πr³, centred on its origin, ⅖mr² about every axis.
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/SphereShape3D.js").SphereShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function sphere_mass_properties(out: Float64Array | number[], shape: import("../../../core/geom/3d/shape/SphereShape3D.js").SphereShape3D, density: number): void;
+/**
+ * Mass properties of a solid box, in its own frame (see {@link MASS_PROPERTIES_SIZE}): with half
+ * extents (a, b, c), mass ρ·8abc, centred on its origin, m(b² + c²)/3 about X and likewise about
+ * Y and Z.
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/BoxShape3D.js").BoxShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function box_mass_properties(out: Float64Array | number[], shape: import("../../../core/geom/3d/shape/BoxShape3D.js").BoxShape3D, density: number): void;
+/**
+ * Mass properties of a solid cylinder along Y, in its own frame (see {@link MASS_PROPERTIES_SIZE}):
+ * radius r and full height h, mass ρ·πr²h, centred on its origin, ½mr² about Y and
+ * m(3r² + h²)/12 about X and Z.
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/CylinderShape3D.js").CylinderShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function cylinder_mass_properties(out: Float64Array | number[], shape: import("../../../core/geom/3d/shape/CylinderShape3D.js").CylinderShape3D, density: number): void;
+/**
+ * Mass properties of a solid capsule along Y, in its own frame (see {@link MASS_PROPERTIES_SIZE}):
+ * a cylinder of radius r and length h (`shape.height`, the straight section) capped by two
+ * hemispheres, centred on its origin.
+ *
+ * The cylinder contributes its own inertia; the two caps together are a sphere of mass m_s, ⅖m_s·r²
+ * about every axis taken about their flat faces' centres, moved out to the capsule's centre: each
+ * cap's centre of mass is 3r/8 past its face, so the shift about X and Z adds
+ * m_s·((h/2 + 3r/8)² - (3r/8)²) = m_s·h·(2h + 3r)/8. The same composition as Box3D's
+ * `b3ComputeCapsuleMass` (capsule.c, MIT, Erin Catto).
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/CapsuleShape3D.js").CapsuleShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function capsule_mass_properties(out: Float64Array | number[], shape: import("../../../core/geom/3d/shape/CapsuleShape3D.js").CapsuleShape3D, density: number): void;
+//# sourceMappingURL=primitive_mass_properties.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"primitive_mass_properties.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/primitive_mass_properties.js"],"names":[],"mappings":"AAyBA;;;;;;;GAOG;AACH,4CAJW,YAAY,GAAC,MAAM,EAAE,SACrB,OAAO,8CAA8C,EAAE,aAAa,WACpE,MAAM,QAUhB;AAED;;;;;;;;GAQG;AACH,yCAJW,YAAY,GAAC,MAAM,EAAE,SACrB,OAAO,2CAA2C,EAAE,UAAU,WAC9D,MAAM,QAchB;AAED;;;;;;;;GAQG;AACH,8CAJW,YAAY,GAAC,MAAM,EAAE,SACrB,OAAO,gDAAgD,EAAE,eAAe,WACxE,MAAM,QAWhB;AAED;;;;;;;;;;;;;;GAcG;AACH,6CAJW,YAAY,GAAC,MAAM,EAAE,SACrB,OAAO,+CAA+C,EAAE,cAAc,WACtE,MAAM,QAkBhB"}

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

@@ -0,0 +1,118 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Write a record centred on the shape's origin with a diagonal tensor — every primitive here is
+ * symmetric about its own origin and axes.
+ *
+ * @param {Float64Array|number[]} out
+ * @param {number} mass
+ * @param {number} ixx
+ * @param {number} iyy
+ * @param {number} izz
+ */
+function write_centred_diagonal(out, mass, ixx, iyy, izz) {
+    out[0] = mass;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = 0;
+    out[4] = ixx;
+    out[5] = iyy;
+    out[6] = izz;
+    out[7] = 0;
+    out[8] = 0;
+    out[9] = 0;
+}
+
+/**
+ * Mass properties of a solid sphere, in its own frame (see {@link MASS_PROPERTIES_SIZE}):
+ * mass ρ·4/3·πr³, centred on its origin, ⅖mr² about every axis.
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/SphereShape3D.js").SphereShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function sphere_mass_properties(out, shape, density) {
+    assert.isNumber(density, 'density');
+
+    const r = shape.radius;
+    const mass = density * (4 / 3) * Math.PI * r * r * r;
+    const i = 0.4 * mass * r * r;
+
+    write_centred_diagonal(out, mass, i, i, i);
+}
+
+/**
+ * Mass properties of a solid box, in its own frame (see {@link MASS_PROPERTIES_SIZE}): with half
+ * extents (a, b, c), mass ρ·8abc, centred on its origin, m(b² + c²)/3 about X and likewise about
+ * Y and Z.
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/BoxShape3D.js").BoxShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function box_mass_properties(out, shape, density) {
+    assert.isNumber(density, 'density');
+
+    const h = shape.half_extents;
+    const a2 = h.x * h.x, b2 = h.y * h.y, c2 = h.z * h.z;
+    const mass = density * 8 * h.x * h.y * h.z;
+
+    write_centred_diagonal(out, mass,
+        mass * (b2 + c2) / 3,
+        mass * (a2 + c2) / 3,
+        mass * (a2 + b2) / 3
+    );
+}
+
+/**
+ * Mass properties of a solid cylinder along Y, in its own frame (see {@link MASS_PROPERTIES_SIZE}):
+ * radius r and full height h, mass ρ·πr²h, centred on its origin, ½mr² about Y and
+ * m(3r² + h²)/12 about X and Z.
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/CylinderShape3D.js").CylinderShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function cylinder_mass_properties(out, shape, density) {
+    assert.isNumber(density, 'density');
+
+    const r = shape.radius;
+    const h = shape.height;
+    const mass = density * Math.PI * r * r * h;
+    const across = mass * (3 * r * r + h * h) / 12;
+
+    write_centred_diagonal(out, mass, across, 0.5 * mass * r * r, across);
+}
+
+/**
+ * Mass properties of a solid capsule along Y, in its own frame (see {@link MASS_PROPERTIES_SIZE}):
+ * a cylinder of radius r and length h (`shape.height`, the straight section) capped by two
+ * hemispheres, centred on its origin.
+ *
+ * The cylinder contributes its own inertia; the two caps together are a sphere of mass m_s, ⅖m_s·r²
+ * about every axis taken about their flat faces' centres, moved out to the capsule's centre: each
+ * cap's centre of mass is 3r/8 past its face, so the shift about X and Z adds
+ * m_s·((h/2 + 3r/8)² - (3r/8)²) = m_s·h·(2h + 3r)/8. The same composition as Box3D's
+ * `b3ComputeCapsuleMass` (capsule.c, MIT, Erin Catto).
+ *
+ * @param {Float64Array|number[]} out receives {@link MASS_PROPERTIES_SIZE} doubles
+ * @param {import("../../../core/geom/3d/shape/CapsuleShape3D.js").CapsuleShape3D} shape
+ * @param {number} density kg/m³
+ */
+export function capsule_mass_properties(out, shape, density) {
+    assert.isNumber(density, 'density');
+
+    const r = shape.radius;
+    const h = shape.height;
+
+    const cylinder_mass = density * Math.PI * r * r * h;
+    const sphere_mass = density * (4 / 3) * Math.PI * r * r * r;
+
+    const sphere_i = 0.4 * sphere_mass * r * r;
+    const cap_shift = 0.125 * sphere_mass * (3 * r + 2 * h) * h;
+
+    const across = cylinder_mass * (3 * r * r + h * h) / 12 + sphere_i + cap_shift;
+    const along = 0.5 * cylinder_mass * r * r + sphere_i;
+
+    write_centred_diagonal(out, cylinder_mass + sphere_mass, across, along, across);
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Write a body's {@link RigidBody#mass} and {@link RigidBody#inverseInertiaLocal} from a
+ * mass-properties record (see {@link MASS_PROPERTIES_SIZE}) in the body's frame — one shape's, or
+ * a compound's from {@link mass_properties_accumulate}.
+ *
+ * **The record must already fit how meep solves a body**, and this does not change that: the
+ * solver turns a body about its Transform64 origin, with a diagonal inverse inertia in the body's
+ * frame. It has no centre-of-mass offset and no full tensor. So the record's centre of mass must
+ * be the body origin and its principal axes the body's axes. Arrange the colliders for it — place
+ * a compound's child colliders so their combined centre falls on the body origin, and orient the
+ * body frame along the solid's principal axes. Asserts (dev) refuse a record whose centre is off
+ * the origin by more than a millionth of its radius of gyration, or whose off-diagonal entries
+ * exceed a millionth of its largest moment; a production build, with asserts stripped, writes the
+ * diagonal regardless, which misrepresents such a body.
+ *
+ * A principal moment of zero is written as an inverse of zero, which
+ * {@link RigidBody#inverseInertiaLocal} reads as that rotation being locked. No shape function
+ * writes one: a solid with no extent along an axis has no volume, so no mass, and is refused above.
+ * It takes mass concentrated on an axis — a record written by hand for a point mass or an ideal thin
+ * rod.
+ *
+ * @param {import("../ecs/RigidBody.js").RigidBody} rigidBody
+ * @param {Float64Array|number[]} mass_properties {@link MASS_PROPERTIES_SIZE} doubles in the body
+ *   frame
+ */
+export function rigid_body_set_mass_properties(rigidBody: import("../ecs/RigidBody.js").RigidBody, mass_properties: Float64Array | number[]): void;
+//# sourceMappingURL=rigid_body_set_mass_properties.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rigid_body_set_mass_properties.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/rigid_body_set_mass_properties.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0DAJW,OAAO,qBAAqB,EAAE,SAAS,mBACvC,YAAY,GAAC,MAAM,EAAE,QA4B/B"}

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

@@ -0,0 +1,62 @@
+import { assert } from "../../../core/assert.js";
+import { v3_set } from "../../../core/geom/vec3/v3_set.js";
+
+/**
+ * How far from the body's frame a record may be and still be written: the centre of mass within
+ * this fraction of the solid's radius of gyration of the origin, each off-diagonal entry within
+ * this fraction of the largest moment.
+ * @type {number}
+ */
+const TOLERANCE = 1e-6;
+
+/**
+ * Write a body's {@link RigidBody#mass} and {@link RigidBody#inverseInertiaLocal} from a
+ * mass-properties record (see {@link MASS_PROPERTIES_SIZE}) in the body's frame — one shape's, or
+ * a compound's from {@link mass_properties_accumulate}.
+ *
+ * **The record must already fit how meep solves a body**, and this does not change that: the
+ * solver turns a body about its Transform64 origin, with a diagonal inverse inertia in the body's
+ * frame. It has no centre-of-mass offset and no full tensor. So the record's centre of mass must
+ * be the body origin and its principal axes the body's axes. Arrange the colliders for it — place
+ * a compound's child colliders so their combined centre falls on the body origin, and orient the
+ * body frame along the solid's principal axes. Asserts (dev) refuse a record whose centre is off
+ * the origin by more than a millionth of its radius of gyration, or whose off-diagonal entries
+ * exceed a millionth of its largest moment; a production build, with asserts stripped, writes the
+ * diagonal regardless, which misrepresents such a body.
+ *
+ * A principal moment of zero is written as an inverse of zero, which
+ * {@link RigidBody#inverseInertiaLocal} reads as that rotation being locked. No shape function
+ * writes one: a solid with no extent along an axis has no volume, so no mass, and is refused above.
+ * It takes mass concentrated on an axis — a record written by hand for a point mass or an ideal thin
+ * rod.
+ *
+ * @param {import("../ecs/RigidBody.js").RigidBody} rigidBody
+ * @param {Float64Array|number[]} mass_properties {@link MASS_PROPERTIES_SIZE} doubles in the body
+ *   frame
+ */
+export function rigid_body_set_mass_properties(rigidBody, mass_properties) {
+    const mass = mass_properties[0];
+    assert.greaterThan(mass, 0, 'rigid_body_set_mass_properties: the solid has no mass');
+
+    const cx = mass_properties[1], cy = mass_properties[2], cz = mass_properties[3];
+    const ixx = mass_properties[4], iyy = mass_properties[5], izz = mass_properties[6];
+    const ixy = mass_properties[7], ixz = mass_properties[8], iyz = mass_properties[9];
+
+    // The trace of the tensor about the centre is 2∫|r|² dm, so its mean square distance from the
+    // centre is trace / 2m.
+    const gyration_squared = (ixx + iyy + izz) / (2 * mass);
+    assert.ok(cx * cx + cy * cy + cz * cz <= TOLERANCE * TOLERANCE * gyration_squared,
+        `rigid_body_set_mass_properties: the centre of mass (${cx}, ${cy}, ${cz}) is not at the body origin; the solver turns a body about its origin`);
+
+    const largest = Math.max(ixx, iyy, izz);
+    const off_limit = TOLERANCE * largest;
+    assert.ok(Math.abs(ixy) <= off_limit && Math.abs(ixz) <= off_limit && Math.abs(iyz) <= off_limit,
+        `rigid_body_set_mass_properties: the body's axes are not the solid's principal axes (Ixy ${ixy}, Ixz ${ixz}, Iyz ${iyz}); the solver keeps a diagonal inertia`);
+
+    rigidBody.mass = mass;
+    v3_set(rigidBody.inverseInertiaLocal, 0,
+        ixx > 0 ? 1 / ixx : 0,
+        iyy > 0 ? 1 / iyy : 0,
+        izz > 0 ? 1 / izz : 0
+    );
+}

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

@@ -26,34 +26,13 @@
  * @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
  */
 export function world_inverse_inertia_apply(result: number[] | Float64Array, result_offset: number, inv_inertia_local: number[] | Float64Array, rotation: number[] | Float64Array, vx: number, vy: number, vz: number): void;
-/**
- * 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`
@@ -64,7 +43,8 @@ export function world_inverse_inertia_apply(result: number[] | Float64Array, res
  * 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
@@ -83,5 +63,67 @@ export function world_inverse_inertia_apply(result: number[] | Float64Array, res
  * @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;
+/**
+ * {@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: number[] | Float64Array, result_offset: number, inv_inertia: number[] | Float64Array, inv_inertia_offset: number, rotation: number[] | Float64Array, rotation_offset: number, lever: number[] | Float64Array, lever_offset: number, axis: number[] | Float64Array, axis_offset: number, scratch: number[] | Float64Array): void;
+/**
+ * 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: 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;
+/**
+ * {@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: number[] | Float64Array, result_offset: number, inv_inertia: number[] | Float64Array, inv_inertia_offset: number, rotation: number[] | Float64Array, rotation_offset: number, v: number[] | Float64Array, v_offset: number): 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,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,MAErB,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"}
+{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oDAXW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,qBACN,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,MAGrB,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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,CA4BlB;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,qDAZW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,QACN,MAAM,EAAE,GAAC,YAAY,eACrB,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,QA6B/B;AAKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,QAsBhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DATW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,EAAE,GAAC,YAAY,sBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,YACrB,MAAM,QAwDhB"}