@woosh/meep-engine 3.39.0 → 3.41.0

package/src/engine/physics/constraint/solve_constraints.d.ts

@@ -1,38 +1,3 @@
-/**
- * Swing-twist decomposition of the relative rotation `qD = conj(qA)⊗qB`, giving
- * the per-frame-axis angular positions used by wide-cone angular DOFs.
- *
- * Decomposes `qD = swing ⊗ twist`, with **twist** the rotation about frame
- * axis X (the bone / twist axis) and **swing** the residual tilt (a rotation
- * about an axis in the YZ plane that carries X to its new direction). Writes,
- * into `out`:
- *   - `out[0]` = signed twist angle about X, in `(−π, π]` — *exact*, so a twist
- *     limit engages at the true angle, not the `2·sin(θ/2)` small-angle proxy;
- *   - `out[1]`, `out[2]` = the swing angle distributed over Y and Z
- *     (`φ·axis`, φ the true swing angle), so independent Y/Z swing limits form
- *     an accurate (box-shaped) cone that holds at large tilt.
- * Reduces continuously to the small-angle vector near identity. Pure scratch /
- * locals — no allocation, suitable for the per-substep hot loop. (The Quaternion
- * class has an object-based `computeSwingAndTwist`; this is the inlined,
- * allocation-free form — see the bench that justifies it.)
- *
- * @param {number} dx  qD x
- * @param {number} dy  qD y
- * @param {number} dz  qD z
- * @param {number} dw  qD w
- * @param {Float64Array} out  length-3 destination (frame-axis positions)
- */
-export function swing_twist_error(dx: number, dy: number, dz: number, dw: number, out: Float64Array): void;
-/**
- * {@link swing_twist_error} with `qD` read from `q[q_offset ..+3]`, `[x, y, z, w]`: the one place the
- * arithmetic lives. For a caller whose inlining budget is spent, where a call taking the four numbers
- * would box each into a new heap object.
- *
- * @param {Float64Array} q
- * @param {number} q_offset
- * @param {Float64Array} out  length-3 destination (frame-axis positions)
- */
-export function swing_twist_error_array(q: Float64Array, q_offset: number, out: Float64Array): void;
 /**
  * Solve every joint for one substep: prepare each joint's rows at the current
  * poses, then run `iters` Gauss-Seidel passes over all of them. The first pass

package/src/engine/physics/constraint/solve_constraints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AAwZA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,sCANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,YAAY,QAWtB;AAKD;;;;;;;;GAQG;AACH,2CAJW,YAAY,YACZ,MAAM,OACN,YAAY,QAoCtB;AA+gBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qCAXW,OAAO,iCAEP,MAAM,SAEN,MAAM,YAGN,OAAO,QAgCjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAJW,OAAO,mCAEP,OAAO,QAgBjB"}
+{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AAs6BA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qCAXW,OAAO,iCAEP,MAAM,SAEN,MAAM,YAGN,OAAO,QAgCjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAJW,OAAO,mCAEP,OAAO,QAgBjB"}

package/src/engine/physics/constraint/solve_constraints.js

@@ -2,6 +2,7 @@ import { assert } from "../../../core/assert.js";
 import { apply_impulse_to_body } from "../solver/apply_impulse_to_body.js";
 import { quat3_multiply_array } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
 import { quat3_to_matrix3_array } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
+import { swing_twist_error_array } from "../../../core/geom/3d/quaternion/swing_twist_error.js";
 import { v3_quaternion_apply_array } from "../../../core/geom/vec3/v3_quaternion_apply.js";
 import { TRANSFORM64_ROTATION_OFFSET } from "../../ecs/transform/Transform64.js";
 import { body_id_index } from "../body/BodyStorage.js";
@@ -406,89 +407,6 @@ function invert_sym3(K, out) {
     return true;
 }
 
-/**
- * Swing-twist decomposition of the relative rotation `qD = conj(qA)⊗qB`, giving
- * the per-frame-axis angular positions used by wide-cone angular DOFs.
- *
- * Decomposes `qD = swing ⊗ twist`, with **twist** the rotation about frame
- * axis X (the bone / twist axis) and **swing** the residual tilt (a rotation
- * about an axis in the YZ plane that carries X to its new direction). Writes,
- * into `out`:
- *   - `out[0]` = signed twist angle about X, in `(−π, π]` — *exact*, so a twist
- *     limit engages at the true angle, not the `2·sin(θ/2)` small-angle proxy;
- *   - `out[1]`, `out[2]` = the swing angle distributed over Y and Z
- *     (`φ·axis`, φ the true swing angle), so independent Y/Z swing limits form
- *     an accurate (box-shaped) cone that holds at large tilt.
- * Reduces continuously to the small-angle vector near identity. Pure scratch /
- * locals — no allocation, suitable for the per-substep hot loop. (The Quaternion
- * class has an object-based `computeSwingAndTwist`; this is the inlined,
- * allocation-free form — see the bench that justifies it.)
- *
- * @param {number} dx  qD x
- * @param {number} dy  qD y
- * @param {number} dz  qD z
- * @param {number} dw  qD w
- * @param {Float64Array} out  length-3 destination (frame-axis positions)
- */
-export function swing_twist_error(dx, dy, dz, dw, out) {
-    const q = swing_twist_inputs;
-
-    q[0] = dx;
-    q[1] = dy;
-    q[2] = dz;
-    q[3] = dw;
-
-    swing_twist_error_array(q, 0, out);
-}
-
-/** Where {@link swing_twist_error} packs its quaternion. */
-const swing_twist_inputs = new Float64Array(4);
-
-/**
- * {@link swing_twist_error} with `qD` read from `q[q_offset ..+3]`, `[x, y, z, w]`: the one place the
- * arithmetic lives. For a caller whose inlining budget is spent, where a call taking the four numbers
- * would box each into a new heap object.
- *
- * @param {Float64Array} q
- * @param {number} q_offset
- * @param {Float64Array} out  length-3 destination (frame-axis positions)
- */
-export function swing_twist_error_array(q, q_offset, out) {
-    let dx = q[q_offset], dy = q[q_offset + 1], dz = q[q_offset + 2], dw = q[q_offset + 3];
-
-    // Shortest arc: work with the hemisphere where dw ≥ 0.
-    if (dw < 0) { dx = -dx; dy = -dy; dz = -dz; dw = -dw; }
-
-    const nxt = Math.sqrt(dx * dx + dw * dw); // |twist| (before normalising)
-    let sy, sz, sw;
-    if (nxt < 1e-12) {
-        // dw ≈ 0 and dx ≈ 0: a ~180° pure swing — twist is undefined, take 0.
-        out[0] = 0;
-        // Swing is qD itself; distribute its angle over Y/Z below.
-        sy = dy; sz = dz; sw = dw;
-    } else {
-        out[0] = 2 * Math.atan2(dx, dw); // exact signed twist about X
-        const tx = dx / nxt, tw = dw / nxt; // normalised twist (tx,0,0,tw)
-        // swing = qD ⊗ conj(twist); its X component is identically 0.
-        sy = dy * tw - dz * tx;
-        sz = dy * tx + dz * tw;
-        sw = dw * tw + dx * tx;
-    }
-
-    if (sw < 0) { sy = -sy; sz = -sz; sw = -sw; }
-    const syz = Math.sqrt(sy * sy + sz * sz);
-    if (syz < 1e-9) {
-        // Near-zero swing: small-angle vector (continuous with φ·axis as φ→0).
-        out[1] = 2 * sy;
-        out[2] = 2 * sz;
-    } else {
-        const phi = 2 * Math.atan2(syz, sw); // exact swing angle in [0, π]
-        const s = phi / syz;
-        out[1] = sy * s;
-        out[2] = sz * s;
-    }
-}
-
 /**
  * Fill the row parameters for one DOF given its mode, signed position and
  * signed velocity.

package/src/engine/physics/ecs/ContactProbe.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Finds where a cast from a reference meets the world, and puts the entity it is on there.
+ *
+ * Every tick {@link ContactProbeSystem} casts a sphere of {@link radius} — a ray, at 0 — from the
+ * reference's world position plus {@link offset}, along {@link direction}, for {@link distance}, through
+ * the physics system's colliders. On a hit the entity is placed at the contact on the surface, turned
+ * as the reference is and tilted so the reference's up is the surface's normal. On a miss it is placed
+ * where the reference is. It knows nothing about who reads it: a foot reaching for the ground, a decal,
+ * an AI checking its footing.
+ *
+ * - The entity is placed through its own {@link TransformAttachment}, whose parent is up to the rig.
+ * - The character's own colliders are passed through: those whose lifetime ({@link ParentEntity})
+ *   leads to the same root as the probe's own.
+ * - The reference may be a bone a clip drives: its pose is evaluated exactly, as the GPU shows it. It
+ *   must not be a bone a CPU writer holds (IK, cloth), or the probe would read that writer's answer
+ *   and the writer would chase its own output.
+ *
+ * Entity ids are transient, so this is never saved.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactProbe {
+    /**
+     * @param {{reference:number, offset:number[], direction:number[], distance:number, radius:number}} options
+     * every field required
+     * @returns {ContactProbe}
+     */
+    static from({ reference, offset, direction, distance, radius }: {
+        reference: number;
+        offset: number[];
+        direction: number[];
+        distance: number;
+        radius: number;
+    }): ContactProbe;
+    /**
+     * The entity the cast starts from.
+     * @type {number}
+     */
+    reference: number;
+    /**
+     * Where the cast starts, relative to the reference's world position, in world axes.
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly offset: Float64Array;
+    /**
+     * Which way the cast goes, in world, of unit length.
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly direction: Float64Array;
+    /**
+     * How far the cast reaches.
+     * @type {number}
+     */
+    distance: number;
+    /**
+     * The radius of the sphere cast; 0 casts a ray.
+     * @type {number}
+     */
+    radius: number;
+    /**
+     * Whether the last cast met anything. Written by {@link ContactProbeSystem}.
+     * @type {boolean}
+     */
+    hit: boolean;
+}
+export namespace ContactProbe {
+    let typeName: string;
+    let serializable: boolean;
+}
+//# sourceMappingURL=ContactProbe.d.ts.map

package/src/engine/physics/ecs/ContactProbe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContactProbe.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ContactProbe.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAuCI;;;;OAIG;IACH,gEAJW;QAAC,SAAS,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,EAAE,CAAC;QAAC,SAAS,EAAC,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAA;KAAC,GAErF,YAAY,CAuBxB;IAhED;;;OAGG;IACH,WAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,iBAFU,YAAY,CAEO;IAE7B;;;;OAIG;IACH,oBAFU,YAAY,CAEgB;IAEtC;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,KAFU,OAAO,CAEL;CA6Bf;;kBAIS,MAAM;sBAMN,OAAO"}

package/src/engine/physics/ecs/ContactProbe.js

@@ -0,0 +1,103 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Finds where a cast from a reference meets the world, and puts the entity it is on there.
+ *
+ * Every tick {@link ContactProbeSystem} casts a sphere of {@link radius} — a ray, at 0 — from the
+ * reference's world position plus {@link offset}, along {@link direction}, for {@link distance}, through
+ * the physics system's colliders. On a hit the entity is placed at the contact on the surface, turned
+ * as the reference is and tilted so the reference's up is the surface's normal. On a miss it is placed
+ * where the reference is. It knows nothing about who reads it: a foot reaching for the ground, a decal,
+ * an AI checking its footing.
+ *
+ * - The entity is placed through its own {@link TransformAttachment}, whose parent is up to the rig.
+ * - The character's own colliders are passed through: those whose lifetime ({@link ParentEntity})
+ *   leads to the same root as the probe's own.
+ * - The reference may be a bone a clip drives: its pose is evaluated exactly, as the GPU shows it. It
+ *   must not be a bone a CPU writer holds (IK, cloth), or the probe would read that writer's answer
+ *   and the writer would chase its own output.
+ *
+ * Entity ids are transient, so this is never saved.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactProbe {
+    /**
+     * The entity the cast starts from.
+     * @type {number}
+     */
+    reference = -1;
+
+    /**
+     * Where the cast starts, relative to the reference's world position, in world axes.
+     * @readonly
+     * @type {Float64Array}
+     */
+    offset = new Float64Array(3);
+
+    /**
+     * Which way the cast goes, in world, of unit length.
+     * @readonly
+     * @type {Float64Array}
+     */
+    direction = Float64Array.of(0, -1, 0);
+
+    /**
+     * How far the cast reaches.
+     * @type {number}
+     */
+    distance = 0;
+
+    /**
+     * The radius of the sphere cast; 0 casts a ray.
+     * @type {number}
+     */
+    radius = 0;
+
+    /**
+     * Whether the last cast met anything. Written by {@link ContactProbeSystem}.
+     * @type {boolean}
+     */
+    hit = false;
+
+    /**
+     * @param {{reference:number, offset:number[], direction:number[], distance:number, radius:number}} options
+     * every field required
+     * @returns {ContactProbe}
+     */
+    static from({ reference, offset, direction, distance, radius }) {
+        assert.isNonNegativeInteger(reference, 'reference');
+        assert.equal(offset.length, 3, 'offset is [x, y, z]');
+        assert.equal(direction.length, 3, 'direction is [x, y, z]');
+        assert.ok(Math.abs(Math.hypot(direction[0], direction[1], direction[2]) - 1) < 1e-9, 'direction is of unit length');
+        assert.ok(distance > 0, 'distance is positive');
+        assert.ok(radius >= 0, 'radius is not negative');
+
+        const probe = new ContactProbe();
+
+        probe.reference = reference;
+        probe.offset[0] = offset[0];
+        probe.offset[1] = offset[1];
+        probe.offset[2] = offset[2];
+        probe.direction[0] = direction[0];
+        probe.direction[1] = direction[1];
+        probe.direction[2] = direction[2];
+        probe.distance = distance;
+        probe.radius = radius;
+
+        return probe;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+ContactProbe.typeName = "ContactProbe";
+
+/**
+ * Entity ids are transient: serialization is not applicable.
+ * @type {boolean}
+ */
+ContactProbe.serializable = false;

package/src/engine/physics/ecs/ContactProbeSystem.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Casts each {@link ContactProbe} and places its entity at what the cast meets.
+ *
+ * Runs in `update`, where the clips' times for the tick are set: a reference a clip drives is
+ * evaluated exactly (`T64WorldCache`), as the GPU draws it.
+ *
+ * **Register it before a system that reads where it puts its entities** and that writes
+ * `TransformAttachment` too, IK's among them. Both read and write `TransformAttachment`, so the
+ * order declared access derives leaves the two a cycle, and between them the scheduler keeps the
+ * order they were registered in.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactProbeSystem extends System<any> {
+    constructor();
+    dependencies: (typeof TransformAttachment | typeof ContactProbe)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof AnimationGraphController> | ResourceAccessSpecification<typeof Animation> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof GPUStateAuthority> | ResourceAccessSpecification<typeof ParentEntity> | ResourceAccessSpecification<typeof ContactProbe>)[];
+    /**
+     * @param {ContactProbe} probe
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    link(probe: ContactProbe, attachment: TransformAttachment, entity: number): void;
+    /**
+     * @param {ContactProbe} probe
+     * @param {TransformAttachment} attachment
+     * @param {number} entity
+     */
+    unlink(probe: ContactProbe, attachment: TransformAttachment, entity: number): void;
+    update(time_delta_seconds: any): void;
+    #private;
+}
+import { System } from "../../ecs/System.js";
+import { TransformAttachment } from "../../ecs/transform-attachment/TransformAttachment.js";
+import { ContactProbe } from "./ContactProbe.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { Collider } from "./Collider.js";
+import { AnimationGraphController } from "../../graphics3/animation/AnimationGraphController.js";
+import { Animation } from "../../ecs/animation/Animation.js";
+import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
+import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+//# sourceMappingURL=ContactProbeSystem.d.ts.map

package/src/engine/physics/ecs/ContactProbeSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContactProbeSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ContactProbeSystem.js"],"names":[],"mappings":"AAqEA;;;;;;;;;;;;;GAaG;AACH;;IAEI,mEAAmD;IAEnD,2bASE;IAyCF;;;;OAIG;IACH,YAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAUhB;IAED;;;;OAIG;IACH,cAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAWhB;IAED,sCA2BC;;CAiKJ;uBA1VsB,qBAAqB;oCAER,uDAAuD;6BAY9D,mBAAmB;4BALzC,oCAAoC;4CAbC,oDAAoD;yBAiBvE,eAAe;yCAHC,uDAAuD;0BAbtE,kCAAkC;kCAC1B,oCAAoC;6BACzC,kCAAkC"}