@woosh/meep-engine 2.141.0 → 2.143.0

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

@@ -82,6 +82,18 @@ export class Joint {
      * @type {Uint8Array}
      */
     readonly dofMode: Uint8Array;
+    /**
+     * How the three angular DOF positions are measured. `false` (default) uses
+     * the per-axis small-angle rotation vector — exact at the rest pose and
+     * cheap, correct for welds, hinges, and modest angular limits. `true`
+     * switches to the **swing-twist** decomposition: angular X is the *twist*
+     * (rotation about the bone / X axis) and angular Y/Z are the *swing* (tilt
+     * off it), each measured as an exact angle. Use it for wide cone-twist
+     * range-of-motion (ragdoll shoulders) where the small-angle measure
+     * under-reports large angles. See {@link asConeTwist}.
+     * @type {boolean}
+     */
+    swingTwist: boolean;
     /**
      * Lower / upper bounds per DOF, used by {@link DofMode.LIMITED}. Linear in
      * metres, angular in radians. (Reserved — consumed once the LIMITED mode
@@ -165,6 +177,109 @@ export class Joint {
      * @returns {Joint} this
      */
     asPrismatic(freeLinearAxis?: number): Joint;
+    /**
+     * Configure as a cone-twist (ragdoll) joint: a ball-socket point (3 linear
+     * locked) whose angular motion is a limited **twist** about the bone (frame
+     * X) and a limited **swing** cone off it (frame Y / Z). Enables
+     * {@link swingTwist} so the limits are measured as exact angles, holding
+     * accurately at the wide ranges ragdoll shoulders need.
+     *
+     * Orient {@link localBasisA} / {@link localBasisB} so frame X runs along the
+     * bone. The swing cone is box-shaped: independent Y and Z half-angles
+     * (`swingLimitZ` defaults to `swingLimitY` for a circular cone).
+     *
+     * @param {number} twistLower @param {number} twistUpper  twist bounds, rad.
+     * @param {number} swingLimitY  swing half-angle about frame Y, rad.
+     * @param {number} [swingLimitZ]  swing half-angle about frame Z, rad
+     *   (defaults to `swingLimitY`).
+     * @returns {Joint} this
+     */
+    asConeTwist(twistLower: number, twistUpper: number, swingLimitY: number, swingLimitZ?: number): Joint;
+    /**
+     * Limit a linear DOF to a travel range along its frame axis (slider
+     * end-stops): the DOF slides freely within `[lower, upper]` metres and is
+     * resisted at the stops. Sets {@link DofMode.LIMITED} on that axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} lower @param {number} upper  travel bounds in metres
+     *   (signed anchor-A offset from anchor-B along the frame axis).
+     * @returns {Joint} this
+     */
+    setLinearLimit(axis: number, lower: number, upper: number): Joint;
+    /**
+     * Limit an angular DOF to a rotation range about its frame axis (joint
+     * range-of-motion): free within `[lower, upper]` radians, resisted at the
+     * stops. Sets {@link DofMode.LIMITED} on that angular axis.
+     *
+     * The angular position is a first-order (small-angle) measure, so the
+     * effective stop is accurate for modest ranges (hinge / slider end-stops)
+     * but under-reports large angles — wide cones (ragdoll shoulders) want the
+     * swing-twist decomposition (already available as
+     * `Quaternion.computeSwingAndTwist` / `computeTwistAngle`). See the solver
+     * module docs.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} lower @param {number} upper  rotation bounds in radians.
+     * @returns {Joint} this
+     */
+    setAngularLimit(axis: number, lower: number, upper: number): Joint;
+    /**
+     * Drive a linear DOF at a target speed along its frame axis (piston,
+     * conveyor, powered slider). A force-limited velocity servo: it pulls the
+     * relative velocity toward `targetVelocity` as hard as `maxForce` allows.
+     * Sets {@link DofMode.MOTOR} on that axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} targetVelocity  desired relative anchor speed of A w.r.t.
+     *   B along the frame axis, m/s (sign convention A − B).
+     * @param {number} maxForce  force budget in newtons (`Infinity` for an
+     *   ideal velocity drive; `0` makes the motor inert).
+     * @returns {Joint} this
+     */
+    setLinearMotor(axis: number, targetVelocity: number, maxForce: number): Joint;
+    /**
+     * Drive an angular DOF at a target rate about its frame axis (wheel drive,
+     * powered hinge / door, turntable). A force-(torque-)limited velocity servo
+     * pulling the relative angular velocity toward `targetVelocity`. Sets
+     * {@link DofMode.MOTOR} on that angular axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} targetVelocity  desired relative angular rate of B w.r.t.
+     *   A about the frame axis, rad/s (sign convention B − A — so for a
+     *   world-anchored motor a positive target spins body A negatively about
+     *   the axis).
+     * @param {number} maxForce  torque budget in newton-metres (`Infinity` for
+     *   an ideal drive; `0` makes the motor inert).
+     * @returns {Joint} this
+     */
+    setAngularMotor(axis: number, targetVelocity: number, maxForce: number): Joint;
+    /**
+     * Make a linear DOF a compliant spring along its frame axis (suspension,
+     * bungee, soft-return slider). The spring drives the DOF toward its zero
+     * (the rest pose — place the anchors / basis so the relaxed position is
+     * `C·axis = 0`) with stiffness and damping, yielding under load rather than
+     * holding rigid. Sets {@link DofMode.SPRING} on that axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} stiffness  spring constant `k`, N/m (0 ⇒ pure damper).
+     * @param {number} damping    damping coefficient `c`, N·s/m (0 ⇒ undamped).
+     * @returns {Joint} this
+     */
+    setLinearSpring(axis: number, stiffness: number, damping: number): Joint;
+    /**
+     * Make an angular DOF a compliant torsional spring about its frame axis
+     * (soft-return hinge, sway bar, soft ragdoll joint). Drives the relative
+     * rotation about the axis toward zero with stiffness and damping. Sets
+     * {@link DofMode.SPRING} on that angular axis. Uses the small-angle measure
+     * (see the solver module docs), so it is for modest ranges.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} stiffness  torsional spring constant `k`, N·m/rad
+     *   (0 ⇒ pure damper).
+     * @param {number} damping    torsional damping, N·m·s/rad (0 ⇒ undamped).
+     * @returns {Joint} this
+     */
+    setAngularSpring(axis: number, stiffness: number, damping: number): Joint;
     /**
      * @readonly
      * @type {boolean}

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

@@ -1 +1 @@
-{"version":3,"file":"Joint.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Joint.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,0BAFU,MAAM,CAEc;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;OAGG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,SAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,uBAFU,OAAO,CAEmB;IAEpC;;;;;OAKG;IACH,uBAFU,OAAO,CAEmB;IAEpC;;;;;;;;;OASG;IACH,sBAFU,UAAU,CAEW;IAE/B;;;;;;;OAOG;IACH,sBAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,kBAFU,UAAU,CAKjB;IAEH;;;;;;OAMG;IACH,wBAFU,YAAY,CAEc;IACpC,qCAAqC;IACrC,wBADqB,YAAY,CACG;IAEpC;;;;;OAKG;IACH,uBAFU,YAAY,CAEa;IACnC,qCAAqC;IACrC,qBADqB,YAAY,CACA;IAEjC;;;;;OAKG;IACH,iCAFU,YAAY,CAEuB;IAC7C,qCAAqC;IACrC,2BADqB,YAAY,CACM;IAEvC;;;;;OAKG;IACH,qBAFU,YAAY,CAEW;IAEjC;;;OAGG;IACH,UAFU,MAAM,CAEF;IACd;;;OAGG;IACH,UAFU,MAAM,CAEO;IACvB;;;OAGG;IACH,UAFU,MAAM,CAEa;IAE7B;;;;;OAKG;IACH,gBAFa,KAAK,CAUjB;IAED;;;;OAIG;IACH,UAFa,KAAK,CAKjB;IAED;;;;;;;;OAQG;IACH,0BAJW,MAAM,GAEJ,KAAK,CAWjB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,GAEJ,KAAK,CAWjB;IASL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CAZtB;;kBAIS,MAAM;;oBAjOI,+BAA+B;uBAC5B,kCAAkC"}
+{"version":3,"file":"Joint.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Joint.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,0BAFU,MAAM,CAEc;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;OAGG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,SAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,uBAFU,OAAO,CAEmB;IAEpC;;;;;OAKG;IACH,uBAFU,OAAO,CAEmB;IAEpC;;;;;;;;;OASG;IACH,sBAFU,UAAU,CAEW;IAE/B;;;;;;;OAOG;IACH,sBAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,kBAFU,UAAU,CAKjB;IAEH;;;;;;;;;;OAUG;IACH,YAFU,OAAO,CAEE;IAEnB;;;;;;OAMG;IACH,wBAFU,YAAY,CAEc;IACpC,qCAAqC;IACrC,wBADqB,YAAY,CACG;IAEpC;;;;;OAKG;IACH,uBAFU,YAAY,CAEa;IACnC,qCAAqC;IACrC,qBADqB,YAAY,CACA;IAEjC;;;;;OAKG;IACH,iCAFU,YAAY,CAEuB;IAC7C,qCAAqC;IACrC,2BADqB,YAAY,CACM;IAEvC;;;;;OAKG;IACH,qBAFU,YAAY,CAEW;IAEjC;;;OAGG;IACH,UAFU,MAAM,CAEF;IACd;;;OAGG;IACH,UAFU,MAAM,CAEO;IACvB;;;OAGG;IACH,UAFU,MAAM,CAEa;IAE7B;;;;;OAKG;IACH,gBAFa,KAAK,CAUjB;IAED;;;;OAIG;IACH,UAFa,KAAK,CAKjB;IAED;;;;;;;;OAQG;IACH,0BAJW,MAAM,GAEJ,KAAK,CAWjB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,GAEJ,KAAK,CAWjB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,wBANW,MAAM,cAAqB,MAAM,eACjC,MAAM,gBACN,MAAM,GAEJ,KAAK,CAiBjB;IAED;;;;;;;;;OASG;IACH,qBALW,MAAM,SACN,MAAM,SAAgB,MAAM,GAE1B,KAAK,CAOjB;IAED;;;;;;;;;;;;;;;OAeG;IACH,sBAJW,MAAM,SACN,MAAM,SAAgB,MAAM,GAC1B,KAAK,CAOjB;IAED;;;;;;;;;;;;OAYG;IACH,qBAPW,MAAM,kBACN,MAAM,YAEN,MAAM,GAEJ,KAAK,CAOjB;IAED;;;;;;;;;;;;;;OAcG;IACH,sBATW,MAAM,kBACN,MAAM,YAIN,MAAM,GAEJ,KAAK,CAOjB;IAED;;;;;;;;;;;OAWG;IACH,sBALW,MAAM,aACN,MAAM,WACN,MAAM,GACJ,KAAK,CAOjB;IAED;;;;;;;;;;;;OAYG;IACH,uBANW,MAAM,aACN,MAAM,WAEN,MAAM,GACJ,KAAK,CAOjB;IASL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CAZtB;;kBAIS,MAAM;;oBAzYI,+BAA+B;uBAC5B,kCAAkC"}

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

@@ -99,6 +99,19 @@ export class Joint {
         DofMode.FREE, DofMode.FREE, DofMode.FREE,
     ]);
 
+    /**
+     * How the three angular DOF positions are measured. `false` (default) uses
+     * the per-axis small-angle rotation vector — exact at the rest pose and
+     * cheap, correct for welds, hinges, and modest angular limits. `true`
+     * switches to the **swing-twist** decomposition: angular X is the *twist*
+     * (rotation about the bone / X axis) and angular Y/Z are the *swing* (tilt
+     * off it), each measured as an exact angle. Use it for wide cone-twist
+     * range-of-motion (ragdoll shoulders) where the small-angle measure
+     * under-reports large angles. See {@link asConeTwist}.
+     * @type {boolean}
+     */
+    swingTwist = false;
+
     /**
      * Lower / upper bounds per DOF, used by {@link DofMode.LIMITED}. Linear in
      * metres, angular in radians. (Reserved — consumed once the LIMITED mode
@@ -219,6 +232,161 @@ export class Joint {
         this.dofMode[5] = DofMode.LOCKED;
         return this;
     }
+
+    /**
+     * Configure as a cone-twist (ragdoll) joint: a ball-socket point (3 linear
+     * locked) whose angular motion is a limited **twist** about the bone (frame
+     * X) and a limited **swing** cone off it (frame Y / Z). Enables
+     * {@link swingTwist} so the limits are measured as exact angles, holding
+     * accurately at the wide ranges ragdoll shoulders need.
+     *
+     * Orient {@link localBasisA} / {@link localBasisB} so frame X runs along the
+     * bone. The swing cone is box-shaped: independent Y and Z half-angles
+     * (`swingLimitZ` defaults to `swingLimitY` for a circular cone).
+     *
+     * @param {number} twistLower @param {number} twistUpper  twist bounds, rad.
+     * @param {number} swingLimitY  swing half-angle about frame Y, rad.
+     * @param {number} [swingLimitZ]  swing half-angle about frame Z, rad
+     *   (defaults to `swingLimitY`).
+     * @returns {Joint} this
+     */
+    asConeTwist(twistLower, twistUpper, swingLimitY, swingLimitZ = swingLimitY) {
+        this.dofMode[0] = DofMode.LOCKED;
+        this.dofMode[1] = DofMode.LOCKED;
+        this.dofMode[2] = DofMode.LOCKED;
+        this.swingTwist = true;
+        this.dofMode[3] = DofMode.LIMITED;
+        this.dofLowerLimit[3] = twistLower;
+        this.dofUpperLimit[3] = twistUpper;
+        this.dofMode[4] = DofMode.LIMITED;
+        this.dofLowerLimit[4] = -swingLimitY;
+        this.dofUpperLimit[4] = swingLimitY;
+        this.dofMode[5] = DofMode.LIMITED;
+        this.dofLowerLimit[5] = -swingLimitZ;
+        this.dofUpperLimit[5] = swingLimitZ;
+        return this;
+    }
+
+    /**
+     * Limit a linear DOF to a travel range along its frame axis (slider
+     * end-stops): the DOF slides freely within `[lower, upper]` metres and is
+     * resisted at the stops. Sets {@link DofMode.LIMITED} on that axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} lower @param {number} upper  travel bounds in metres
+     *   (signed anchor-A offset from anchor-B along the frame axis).
+     * @returns {Joint} this
+     */
+    setLinearLimit(axis, lower, upper) {
+        this.dofMode[axis] = DofMode.LIMITED;
+        this.dofLowerLimit[axis] = lower;
+        this.dofUpperLimit[axis] = upper;
+        return this;
+    }
+
+    /**
+     * Limit an angular DOF to a rotation range about its frame axis (joint
+     * range-of-motion): free within `[lower, upper]` radians, resisted at the
+     * stops. Sets {@link DofMode.LIMITED} on that angular axis.
+     *
+     * The angular position is a first-order (small-angle) measure, so the
+     * effective stop is accurate for modest ranges (hinge / slider end-stops)
+     * but under-reports large angles — wide cones (ragdoll shoulders) want the
+     * swing-twist decomposition (already available as
+     * `Quaternion.computeSwingAndTwist` / `computeTwistAngle`). See the solver
+     * module docs.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} lower @param {number} upper  rotation bounds in radians.
+     * @returns {Joint} this
+     */
+    setAngularLimit(axis, lower, upper) {
+        this.dofMode[3 + axis] = DofMode.LIMITED;
+        this.dofLowerLimit[3 + axis] = lower;
+        this.dofUpperLimit[3 + axis] = upper;
+        return this;
+    }
+
+    /**
+     * Drive a linear DOF at a target speed along its frame axis (piston,
+     * conveyor, powered slider). A force-limited velocity servo: it pulls the
+     * relative velocity toward `targetVelocity` as hard as `maxForce` allows.
+     * Sets {@link DofMode.MOTOR} on that axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} targetVelocity  desired relative anchor speed of A w.r.t.
+     *   B along the frame axis, m/s (sign convention A − B).
+     * @param {number} maxForce  force budget in newtons (`Infinity` for an
+     *   ideal velocity drive; `0` makes the motor inert).
+     * @returns {Joint} this
+     */
+    setLinearMotor(axis, targetVelocity, maxForce) {
+        this.dofMode[axis] = DofMode.MOTOR;
+        this.dofMotorTargetVelocity[axis] = targetVelocity;
+        this.dofMotorMaxForce[axis] = maxForce;
+        return this;
+    }
+
+    /**
+     * Drive an angular DOF at a target rate about its frame axis (wheel drive,
+     * powered hinge / door, turntable). A force-(torque-)limited velocity servo
+     * pulling the relative angular velocity toward `targetVelocity`. Sets
+     * {@link DofMode.MOTOR} on that angular axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} targetVelocity  desired relative angular rate of B w.r.t.
+     *   A about the frame axis, rad/s (sign convention B − A — so for a
+     *   world-anchored motor a positive target spins body A negatively about
+     *   the axis).
+     * @param {number} maxForce  torque budget in newton-metres (`Infinity` for
+     *   an ideal drive; `0` makes the motor inert).
+     * @returns {Joint} this
+     */
+    setAngularMotor(axis, targetVelocity, maxForce) {
+        this.dofMode[3 + axis] = DofMode.MOTOR;
+        this.dofMotorTargetVelocity[3 + axis] = targetVelocity;
+        this.dofMotorMaxForce[3 + axis] = maxForce;
+        return this;
+    }
+
+    /**
+     * Make a linear DOF a compliant spring along its frame axis (suspension,
+     * bungee, soft-return slider). The spring drives the DOF toward its zero
+     * (the rest pose — place the anchors / basis so the relaxed position is
+     * `C·axis = 0`) with stiffness and damping, yielding under load rather than
+     * holding rigid. Sets {@link DofMode.SPRING} on that axis.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} stiffness  spring constant `k`, N/m (0 ⇒ pure damper).
+     * @param {number} damping    damping coefficient `c`, N·s/m (0 ⇒ undamped).
+     * @returns {Joint} this
+     */
+    setLinearSpring(axis, stiffness, damping) {
+        this.dofMode[axis] = DofMode.SPRING;
+        this.dofStiffness[axis] = stiffness;
+        this.dofDamping[axis] = damping;
+        return this;
+    }
+
+    /**
+     * Make an angular DOF a compliant torsional spring about its frame axis
+     * (soft-return hinge, sway bar, soft ragdoll joint). Drives the relative
+     * rotation about the axis toward zero with stiffness and damping. Sets
+     * {@link DofMode.SPRING} on that angular axis. Uses the small-angle measure
+     * (see the solver module docs), so it is for modest ranges.
+     *
+     * @param {number} axis  frame axis: 0 = x, 1 = y, 2 = z.
+     * @param {number} stiffness  torsional spring constant `k`, N·m/rad
+     *   (0 ⇒ pure damper).
+     * @param {number} damping    torsional damping, N·m·s/rad (0 ⇒ undamped).
+     * @returns {Joint} this
+     */
+    setAngularSpring(axis, stiffness, damping) {
+        this.dofMode[3 + axis] = DofMode.SPRING;
+        this.dofStiffness[3 + axis] = stiffness;
+        this.dofDamping[3 + axis] = damping;
+        return this;
+    }
 }
 
 /**

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

@@ -0,0 +1,29 @@
+/**
+ * Binary serialization for {@link Joint}.
+ *
+ * Writes the configurable / persistent fields: the two anchor entities, the
+ * local anchor points and basis frames, and the per-DOF mode + limit / spring /
+ * motor config. Transient runtime state owned by the {@link PhysicsSystem} —
+ * the warm-start accumulator (`dofImpulse`) and the resolved `_bodyIdA` /
+ * `_bodyIdB` / `_jointId` — is deliberately excluded; it is recomputed on
+ * `link_joint`, and serialising it would tie the stream to a particular world
+ * instance.
+ */
+export class JointSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof Joint;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {Joint} value
+     */
+    serialize(buffer: BinaryBuffer, value: Joint): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {Joint} value
+     */
+    deserialize(buffer: BinaryBuffer, value: Joint): void;
+}
+import { BinaryClassSerializationAdapter } from "../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { Joint } from "./Joint.js";
+//# sourceMappingURL=JointSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JointSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/JointSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH;;IAEI,oBAAc;IACd,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,KAAK,QAwBf;IAED;;;OAGG;IACH,yCAFW,KAAK,QAqBf;CACJ;gDAvE+C,6DAA6D;sBACvF,YAAY"}

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

@@ -0,0 +1,72 @@
+import { BinaryClassSerializationAdapter } from "../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { Joint } from "./Joint.js";
+
+/**
+ * Binary serialization for {@link Joint}.
+ *
+ * Writes the configurable / persistent fields: the two anchor entities, the
+ * local anchor points and basis frames, and the per-DOF mode + limit / spring /
+ * motor config. Transient runtime state owned by the {@link PhysicsSystem} —
+ * the warm-start accumulator (`dofImpulse`) and the resolved `_bodyIdA` /
+ * `_bodyIdB` / `_jointId` — is deliberately excluded; it is recomputed on
+ * `link_joint`, and serialising it would tie the stream to a particular world
+ * instance.
+ */
+export class JointSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = Joint;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {Joint} value
+     */
+    serialize(buffer, value) {
+        // Anchor entities — entityB may be JOINT_WORLD (−1), so signed.
+        buffer.writeInt32(value.entityA);
+        buffer.writeInt32(value.entityB);
+
+        const la = value.localAnchorA, lb = value.localAnchorB;
+        buffer.writeFloat64(la.x); buffer.writeFloat64(la.y); buffer.writeFloat64(la.z);
+        buffer.writeFloat64(lb.x); buffer.writeFloat64(lb.y); buffer.writeFloat64(lb.z);
+
+        const ba = value.localBasisA, bb = value.localBasisB;
+        buffer.writeFloat64(ba[0]); buffer.writeFloat64(ba[1]); buffer.writeFloat64(ba[2]); buffer.writeFloat64(ba[3]);
+        buffer.writeFloat64(bb[0]); buffer.writeFloat64(bb[1]); buffer.writeFloat64(bb[2]); buffer.writeFloat64(bb[3]);
+
+        for (let i = 0; i < 6; i++) buffer.writeUint8(value.dofMode[i]);
+        for (let i = 0; i < 6; i++) buffer.writeFloat64(value.dofLowerLimit[i]);
+        for (let i = 0; i < 6; i++) buffer.writeFloat64(value.dofUpperLimit[i]);
+        for (let i = 0; i < 6; i++) buffer.writeFloat64(value.dofStiffness[i]);
+        for (let i = 0; i < 6; i++) buffer.writeFloat64(value.dofDamping[i]);
+        for (let i = 0; i < 6; i++) buffer.writeFloat64(value.dofMotorTargetVelocity[i]);
+        for (let i = 0; i < 6; i++) buffer.writeFloat64(value.dofMotorMaxForce[i]);
+
+        buffer.writeUint8(value.swingTwist ? 1 : 0);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {Joint} value
+     */
+    deserialize(buffer, value) {
+        value.entityA = buffer.readInt32();
+        value.entityB = buffer.readInt32();
+
+        value.localAnchorA.set(buffer.readFloat64(), buffer.readFloat64(), buffer.readFloat64());
+        value.localAnchorB.set(buffer.readFloat64(), buffer.readFloat64(), buffer.readFloat64());
+
+        value.localBasisA.set(buffer.readFloat64(), buffer.readFloat64(), buffer.readFloat64(), buffer.readFloat64());
+        value.localBasisB.set(buffer.readFloat64(), buffer.readFloat64(), buffer.readFloat64(), buffer.readFloat64());
+
+        for (let i = 0; i < 6; i++) value.dofMode[i] = buffer.readUint8();
+        for (let i = 0; i < 6; i++) value.dofLowerLimit[i] = buffer.readFloat64();
+        for (let i = 0; i < 6; i++) value.dofUpperLimit[i] = buffer.readFloat64();
+        for (let i = 0; i < 6; i++) value.dofStiffness[i] = buffer.readFloat64();
+        for (let i = 0; i < 6; i++) value.dofDamping[i] = buffer.readFloat64();
+        for (let i = 0; i < 6; i++) value.dofMotorTargetVelocity[i] = buffer.readFloat64();
+        for (let i = 0; i < 6; i++) value.dofMotorMaxForce[i] = buffer.readFloat64();
+
+        value.swingTwist = buffer.readUint8() !== 0;
+    }
+}

package/src/engine/physics/narrowphase/narrowphase_step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AA6uCA;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QAyJlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,UACjD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,QAiD3D"}
+{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AAovCA;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QAyJlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,UACjD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,QAiD3D"}

package/src/engine/physics/narrowphase/narrowphase_step.js

@@ -358,8 +358,10 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
     const shapeA = colA.shape;
     const shapeB = colB.shape;
 
-    const isSphereA = shapeA.isUnitSphereShape3D === true;
-    const isSphereB = shapeB.isUnitSphereShape3D === true;
+    // isSphereShape3D covers both UnitSphereShape3D (fixed radius 1) and
+    // SphereShape3D (arbitrary radius). Both expose `radius`.
+    const isSphereA = shapeA.isSphereShape3D === true;
+    const isSphereB = shapeB.isSphereShape3D === true;
     // isBoxShape3D covers both UnitCubeShape3D (fixed 0.5) and BoxShape3D
     // (arbitrary half-extents). Both expose `half_extents` as a Vector3.
     const isBoxA    = shapeA.isBoxShape3D        === true;
@@ -369,12 +371,13 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
 
     // sphere-sphere
     if (isSphereA && isSphereB) {
+        const ra = shapeA.radius, rb = shapeB.radius;
 
         const ok = sphere_sphere_contact(
             sphere_result,
             trA.position.x, trA.position.y, trA.position.z,
             trB.position.x, trB.position.y, trB.position.z,
-            1, 1
+            ra, rb
         );
 
         if (!ok) return count;
@@ -383,23 +386,25 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
 
         // Sphere-sphere produces exactly one contact per pair; fid = 1
         // identifies it as a real feature (distinguishes from "no info" = 0)
-        // and is trivially stable across frames.
+        // and is trivially stable across frames. Witnesses are the surface
+        // points along the (unit) normal, scaled by each sphere's radius.
         return append_contact(count,
-            trA.position.x - nx, trA.position.y - ny, trA.position.z - nz,
-            trB.position.x + nx, trB.position.y + ny, trB.position.z + nz,
+            trA.position.x - nx * ra, trA.position.y - ny * ra, trA.position.z - nz * ra,
+            trB.position.x + nx * rb, trB.position.y + ny * rb, trB.position.z + nz * rb,
             nx, ny, nz, sphere_result[3], 1);
     }
 
     // sphere ↔ box
     if ((isSphereA && isBoxB) || (isBoxA && isSphereB)) {
-        const sphereTr = isSphereA ? trA : trB;
+        const sphereTr    = isSphereA ? trA : trB;
+        const sphereShape = isSphereA ? shapeA : shapeB;
         const boxTr    = isSphereA ? trB : trA;
         const boxShape = isSphereA ? shapeB : shapeA;
         const bh = boxShape.half_extents;
 
         const ok = sphere_box_contact(
             closed_form_result,
-            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1,
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, sphereShape.radius,
             boxTr.position.x, boxTr.position.y, boxTr.position.z,
             boxTr.rotation.x, boxTr.rotation.y, boxTr.rotation.z, boxTr.rotation.w,
             bh.x, bh.y, bh.z
@@ -491,12 +496,13 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
         const capsuleTr = isCapsuleA ? trA : trB;
         const capsuleShape = isCapsuleA ? colA.shape : colB.shape;
         const sphereTr    = isCapsuleA ? trB : trA;
+        const sphereShape = isCapsuleA ? colB.shape : colA.shape;
         const ok = capsule_sphere_contact(
             closed_form_result,
             capsuleTr.position.x, capsuleTr.position.y, capsuleTr.position.z,
             capsuleTr.rotation.x, capsuleTr.rotation.y, capsuleTr.rotation.z, capsuleTr.rotation.w,
             capsuleShape.radius, capsuleShape.height * 0.5,
-            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, sphereShape.radius
         );
         if (!ok) return count;
         let nx = closed_form_result[0], ny = closed_form_result[1], nz = closed_form_result[2];
@@ -639,14 +645,15 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
         const c_pos_y = concave_tr.position.y;
         const c_pos_z = concave_tr.position.z;
 
-        // Sphere fast-path: when the convex side is a UnitSphereShape3D we
-        // bypass GJK+EPA entirely per triangle and use the closed-form
+        // Sphere fast-path: when the convex side is a sphere we bypass GJK+EPA
+        // entirely per triangle and use the closed-form
         // {@link sphere_triangle_contact}. This avoids the EPA precision
         // wall on Triangle3D (whose support function is degenerate along
         // the face normal — all 3 vertices project to the same value),
         // which was producing noisy depths at small penetrations and
         // letting dropped spheres tunnel through heightmaps / meshes.
-        const isSphereConvex = convex_col.shape.isUnitSphereShape3D === true;
+        const isSphereConvex = convex_col.shape.isSphereShape3D === true;
+        const sphere_radius = isSphereConvex ? convex_col.shape.radius : 0;
 
         // Box fast-path: closed-form {@link box_triangle_contact} via SAT
         // over 13 axes + polygon clipping for face-vs-face contacts.
@@ -743,7 +750,7 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
 
                 const ok = sphere_triangle_contact(
                     sphere_triangle_result,
-                    convex_wx, convex_wy, convex_wz, 1,
+                    convex_wx, convex_wy, convex_wz, sphere_radius,
                     ax_w, ay_w, az_w,
                     bx_w, by_w, bz_w,
                     cx_w, cy_w, cz_w

package/src/engine/physics/narrowphase/ray_shapes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * # Local-frame ray ↔ primitive intersections (raycast narrowphase)
+ *
+ * Each function intersects a ray, **expressed in the shape's local frame**,
+ * against a canonical primitive at the origin (sphere at the origin; box
+ * axis-aligned spanning `[-h, +h]`; capsule along the local Y axis). They
+ * return the hit distance `t` along the ray (`Infinity` on a miss) and write
+ * the **local** outward surface normal (unit) into `outNormal[0..2]`.
+ *
+ * The ray-narrowphase dispatch transforms the world ray into the body's local
+ * frame once (rotate by the inverse body rotation — a unit direction stays
+ * unit, so `t` is preserved), calls the matching primitive, then rotates the
+ * returned local normal back to world. Keeping the primitives canonical lets
+ * the box and capsule tests be axis-aligned (cheap slab / cylinder math) and
+ * shares a single transform across them.
+ *
+ * Conventions:
+ *  - the ray direction is unit length (the caller guarantees it);
+ *  - the first surface crossing at or after the origin within `tMax` is
+ *    returned; a ray starting inside the shape returns its exit crossing;
+ *  - the normal is the geometric outward surface normal at the hit.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Ray vs a sphere of radius `r` centred at the local origin.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} r  sphere radius
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_sphere_local(outNormal: Float64Array, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, r: number): number;
+/**
+ * Ray vs an axis-aligned box spanning `[-hx,hx] × [-hy,hy] × [-hz,hz]` at the
+ * local origin (the canonical pose of {@link BoxShape3D}). Slab method, with
+ * the entry (or, origin-inside, exit) face's outward normal.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} hx @param {number} hy @param {number} hz  half-extents
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_box_local(outNormal: Float64Array, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, hx: number, hy: number, hz: number): number;
+/**
+ * Ray vs a capsule along the local Y axis: a cylinder of radius `r` over
+ * `y ∈ [−hh, hh]` capped by hemispheres of radius `r` at `(0, ±hh, 0)` — the
+ * canonical pose of {@link CapsuleShape3D} (`hh = height/2`). Tests the
+ * infinite cylinder (clamped to the segment) and the two cap spheres, taking
+ * the nearest valid crossing.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} r   capsule radius
+ * @param {number} hh  half-height of the cylindrical section (`height/2`)
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_capsule_local(outNormal: Float64Array, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, r: number, hh: number): number;
+//# sourceMappingURL=ray_shapes.d.ts.map

package/src/engine/physics/narrowphase/ray_shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ray_shapes.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/ray_shapes.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;GASG;AACH,4CAPW,YAAY,MACZ,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,KACN,MAAM,GACJ,MAAM,CAiBlB;AAED;;;;;;;;;;;GAWG;AACH,yCAPW,YAAY,MACZ,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,GAC1C,MAAM,CA+ClB;AAED;;;;;;;;;;;;;;GAcG;AACH,6CARW,YAAY,MACZ,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,KACN,MAAM,MACN,MAAM,GACJ,MAAM,CA6DlB"}