@woosh/meep-engine 2.142.0 → 2.143.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.142.0",
+  "version": "2.143.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/geom/3d/shape/CapsuleShape3D.d.ts

@@ -33,7 +33,7 @@ export class CapsuleShape3D extends AbstractShape3D {
      */
     equals(other: CapsuleShape3D): boolean;
     /**
-     * Fast type-check marker, mirroring `UnitSphereShape3D.prototype.isUnitSphereShape3D`
+     * Fast type-check marker, mirroring `SphereShape3D.prototype.isSphereShape3D`
      * and `BoxShape3D.prototype.isBoxShape3D`. Lets the physics narrowphase
      * dispatch capsule-sphere / capsule-capsule / capsule-box pairs to
      * closed-form helpers (capsule = Minkowski sum of segment + sphere; all

package/src/core/geom/3d/shape/CapsuleShape3D.js

@@ -210,7 +210,7 @@ export class CapsuleShape3D extends AbstractShape3D {
 }
 
 /**
- * Fast type-check marker, mirroring `UnitSphereShape3D.prototype.isUnitSphereShape3D`
+ * Fast type-check marker, mirroring `SphereShape3D.prototype.isSphereShape3D`
  * and `BoxShape3D.prototype.isBoxShape3D`. Lets the physics narrowphase
  * dispatch capsule-sphere / capsule-capsule / capsule-box pairs to
  * closed-form helpers (capsule = Minkowski sum of segment + sphere; all

package/src/core/geom/3d/shape/SphereShape3D.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sphere of arbitrary `radius`, centred at the body's local origin.
+ *
+ * Mirrors the {@link BoxShape3D} (arbitrary half-extents) ↔
+ * {@link UnitCubeShape3D} (fixed 0.5) relationship: this is the general
+ * parametrised sphere, and {@link UnitSphereShape3D} is the `radius = 1`
+ * special case kept for the JSON `'sphere'` tag and the shared `INSTANCE`
+ * singleton.
+ *
+ * The physics narrowphase recognises spheres via the shared `isSphereShape3D`
+ * prototype marker and reads `radius`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SphereShape3D extends AbstractShape3D {
+    /**
+     * Convenience constructor.
+     * @param {number} radius
+     * @returns {SphereShape3D}
+     */
+    static from(radius: number): SphereShape3D;
+    /**
+     * Sphere radius, in the body's local frame.
+     * @type {number}
+     */
+    radius: number;
+    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    compute_bounding_box(result: any): void;
+    nearest_point_on_surface(result: any, reference: any): void;
+    signed_distance_gradient_at_point(result: any, point: any): number;
+    signed_distance_at_point(point: any): number;
+    contains_point(point: any): boolean;
+    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * Fast type-check marker. Lets the physics narrowphase short-circuit
+     * sphere-involved pairs to closed-form solvers (reading `radius`) rather than
+     * running GJK + EPA on a smooth surface (the EPA-degenerate case). `true` for
+     * both {@link SphereShape3D} and {@link UnitSphereShape3D} (via the prototype
+     * chain).
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isSphereShape3D: boolean;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+//# sourceMappingURL=SphereShape3D.d.ts.map

package/src/core/geom/3d/shape/SphereShape3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/SphereShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH;IAUI;;;;OAIG;IACH,oBAHW,MAAM,GACJ,aAAa,CAMzB;IAhBG;;;OAGG;IACH,QAFU,MAAM,CAED;IAwBnB,qGAQC;IAED,wCAQC;IAED,4DAaC;IAED,mEAEC;IAED,6CAEC;IAED,oCAOC;IAED,kFAMC;IAOL;;;;;;;;OAQG;IACH,0BAFU,OAAO,CAEsB;CAXtC;gCAhH+B,sBAAsB"}

package/src/core/geom/3d/shape/SphereShape3D.js

@@ -0,0 +1,127 @@
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { randomPointInSphere } from "../../random/randomPointInSphere.js";
+import { v3_length } from "../../vec3/v3_length.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
+
+/**
+ * Sphere of arbitrary `radius`, centred at the body's local origin.
+ *
+ * Mirrors the {@link BoxShape3D} (arbitrary half-extents) ↔
+ * {@link UnitCubeShape3D} (fixed 0.5) relationship: this is the general
+ * parametrised sphere, and {@link UnitSphereShape3D} is the `radius = 1`
+ * special case kept for the JSON `'sphere'` tag and the shared `INSTANCE`
+ * singleton.
+ *
+ * The physics narrowphase recognises spheres via the shared `isSphereShape3D`
+ * prototype marker and reads `radius`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SphereShape3D extends AbstractShape3D {
+    constructor() {
+        super();
+        /**
+         * Sphere radius, in the body's local frame.
+         * @type {number}
+         */
+        this.radius = 1;
+    }
+
+    /**
+     * Convenience constructor.
+     * @param {number} radius
+     * @returns {SphereShape3D}
+     */
+    static from(radius) {
+        const s = new SphereShape3D();
+        s.radius = radius;
+        return s;
+    }
+
+    get volume() {
+        const r = this.radius;
+        return (4 / 3) * Math.PI * r * r * r;
+    }
+
+    get surface_area() {
+        const r = this.radius;
+        return 4 * Math.PI * r * r;
+    }
+
+    support(result, result_offset, direction_x, direction_y, direction_z) {
+        // Farthest point along `direction` on a sphere of this radius. Matches
+        // the unit-sphere convention (no normalisation — callers pass a unit
+        // direction); for radius r it is simply the direction scaled by r.
+        const r = this.radius;
+        result[result_offset] = direction_x * r;
+        result[result_offset + 1] = direction_y * r;
+        result[result_offset + 2] = direction_z * r;
+    }
+
+    compute_bounding_box(result) {
+        const r = this.radius;
+        result[0] = -r;
+        result[1] = -r;
+        result[2] = -r;
+        result[3] = r;
+        result[4] = r;
+        result[5] = r;
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const r_x = reference[0];
+        const r_y = reference[1];
+        const r_z = reference[2];
+
+        const len = v3_length(r_x, r_y, r_z);
+        // At the centre the nearest surface point is undefined; return the
+        // centre rather than NaN/Inf.
+        const d = len > 0 ? this.radius / len : 0;
+
+        result[0] = r_x * d;
+        result[1] = r_y * d;
+        result[2] = r_z * d;
+    }
+
+    signed_distance_gradient_at_point(result, point) {
+        return compute_signed_distance_gradient_by_sampling(result, this, point);
+    }
+
+    signed_distance_at_point(point) {
+        return v3_length(point[0], point[1], point[2]) - this.radius;
+    }
+
+    contains_point(point) {
+        const x = point[0];
+        const y = point[1];
+        const z = point[2];
+        const r = this.radius;
+
+        return (x * x + y * y + z * z) < r * r;
+    }
+
+    sample_random_point_in_volume(result, result_offset, random) {
+        randomPointInSphere(random, result, result_offset);
+        const r = this.radius;
+        result[result_offset] *= r;
+        result[result_offset + 1] *= r;
+        result[result_offset + 2] *= r;
+    }
+
+    hash() {
+        return computeHashFloat(this.radius);
+    }
+}
+
+/**
+ * Fast type-check marker. Lets the physics narrowphase short-circuit
+ * sphere-involved pairs to closed-form solvers (reading `radius`) rather than
+ * running GJK + EPA on a smooth surface (the EPA-degenerate case). `true` for
+ * both {@link SphereShape3D} and {@link UnitSphereShape3D} (via the prototype
+ * chain).
+ * @readonly
+ * @type {boolean}
+ */
+SphereShape3D.prototype.isSphereShape3D = true;

package/src/core/geom/3d/shape/UnitSphereShape3D.d.ts

@@ -1,27 +1,39 @@
 /**
- * Sphere with diameter of 2 (radius = 1)
+ * Sphere with radius 1 (diameter 2), centred at the origin.
+ *
+ * @deprecated Use {@link SphereShape3D} instead — UnitSphereShape3D is now a
+ * thin subclass that just pins `radius` to `1`. All geometry (`support`,
+ * `signed_distance_at_point`, `volume`, `surface_area`,
+ * `nearest_point_on_surface`, ...) is inherited from {@link SphereShape3D}.
+ *
+ * Kept only for:
+ *   - the `UnitSphereShape3D.INSTANCE` shared singleton that scenes, colliders,
+ *     and tests embed by reference
+ *   - the JSON `'sphere'` type-tag round-trip in `shape_to_type` /
+ *     `type_adapters` (an `instanceof` check, which is why we still need a
+ *     distinct subclass rather than a constant `SphereShape3D` instance)
+ *
+ * For new code prefer:
+ *   - `new SphereShape3D()` — also defaults to `radius = 1`
+ *   - `SphereShape3D.from(radius)` — express by radius
  */
-export class UnitSphereShape3D extends AbstractShape3D {
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
-    compute_bounding_box(result: any): void;
-    nearest_point_on_surface(result: any, reference: any): void;
-    signed_distance_gradient_at_point(result: any, point: any): number;
-    signed_distance_at_point(point: any): number;
-    contains_point(point: any): boolean;
-    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+export class UnitSphereShape3D extends SphereShape3D {
     /**
-     * Fast type-check marker (mirrors {@link Transform.prototype.isTransform}). Lets
-     * downstream code dispatch on shape kind without instanceof / import coupling.
-     * Use case: physics narrowphase short-circuits sphere-sphere to a closed-form
-     * solution rather than running GJK+EPA on a smooth surface (which is the EPA
-     * degenerate case).
+     * Shared singleton. Many call sites — JSON deserialisation, the default
+     * {@link Collider} shape, tests — embed this by reference rather than
+     * allocating a fresh sphere.
+     * @type {UnitSphereShape3D}
+     */
+    static INSTANCE: UnitSphereShape3D;
+    /**
+     * @deprecated Prefer dispatching on `isSphereShape3D`, which is `true` for both
+     * UnitSphereShape3D (inherited via prototype chain) and {@link SphereShape3D}.
+     * Retained so any older external code that already narrowed via this marker
+     * keeps working.
      * @readonly
      * @type {boolean}
      */
     readonly isUnitSphereShape3D: boolean;
 }
-export namespace UnitSphereShape3D {
-    let INSTANCE: UnitSphereShape3D;
-}
-import { AbstractShape3D } from "./AbstractShape3D.js";
+import { SphereShape3D } from "./SphereShape3D.js";
 //# sourceMappingURL=UnitSphereShape3D.d.ts.map

package/src/core/geom/3d/shape/UnitSphereShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnitSphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitSphereShape3D.js"],"names":[],"mappings":"AAKA;;GAEG;AACH;IASI,qGAQC;IAED,wCAQC;IAED,4DAYC;IAED,mEAEC;IAED,6CAMC;IAED,oCAMC;IAED,kFAEC;IASL;;;;;;;;OAQG;IACH,8BAFU,OAAO,CAE8B;CAb9C;;;;gCA5E+B,sBAAsB"}
+{"version":3,"file":"UnitSphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitSphereShape3D.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAKI;;;;;OAKG;IACH,iBAFU,iBAAiB,CAEe;IAG9C;;;;;;;OAOG;IACH,8BAFU,OAAO,CAE8B;CAV9C;8BAjC6B,oBAAoB"}

package/src/core/geom/3d/shape/UnitSphereShape3D.js

@@ -1,92 +1,44 @@
-import { randomPointInSphere } from "../../random/randomPointInSphere.js";
-import { v3_length } from "../../vec3/v3_length.js";
-import { AbstractShape3D } from "./AbstractShape3D.js";
-import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
-
-/**
- * Sphere with diameter of 2 (radius = 1)
- */
-export class UnitSphereShape3D extends AbstractShape3D {
-    get volume() {
-        return (4 / 3) * Math.PI;
-    }
-
-    get surface_area() {
-        return Math.PI * 4;
-    }
-
-    support(result, result_offset, direction_x, direction_y, direction_z) {
-
-        // since the sphere has a radius of 1, we don't have to multiply by it
-
-        result[result_offset] = direction_x;
-        result[result_offset + 1] = direction_y;
-        result[result_offset + 2] = direction_z;
-
-    }
-
-    compute_bounding_box(result) {
-        result[0] = -1;
-        result[1] = -1;
-        result[2] = -1;
-
-        result[3] = 1;
-        result[4] = 1;
-        result[5] = 1;
-    }
-
-    nearest_point_on_surface(result, reference) {
-
-        const r_x = reference[0];
-        const r_y = reference[1];
-        const r_z = reference[2];
-
-        // normalize vector to 1 radius
-        const d = 1 / v3_length(r_x, r_y, r_z);
-
-        result[0] = r_x * d;
-        result[1] = r_y * d;
-        result[2] = r_z * d;
-    }
-
-    signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
-    }
-
-    signed_distance_at_point(point) {
-        return v3_length(
-            point[0],
-            point[1],
-            point[2]
-        ) - 1;
-    }
-
-    contains_point(point) {
-        const x = point[0];
-        const y = point[1];
-        const z = point[2];
-
-        return (x * x + y * y + z * z) < 1;
-    }
-
-    sample_random_point_in_volume(result, result_offset, random) {
-        randomPointInSphere(random, result, result_offset);
-    }
-
-    hash() {
-        return 13;
-    }
-}
-
-UnitSphereShape3D.INSTANCE = new UnitSphereShape3D();
-
-/**
- * Fast type-check marker (mirrors {@link Transform.prototype.isTransform}). Lets
- * downstream code dispatch on shape kind without instanceof / import coupling.
- * Use case: physics narrowphase short-circuits sphere-sphere to a closed-form
- * solution rather than running GJK+EPA on a smooth surface (which is the EPA
- * degenerate case).
- * @readonly
- * @type {boolean}
- */
-UnitSphereShape3D.prototype.isUnitSphereShape3D = true;
+import { SphereShape3D } from "./SphereShape3D.js";
+
+/**
+ * Sphere with radius 1 (diameter 2), centred at the origin.
+ *
+ * @deprecated Use {@link SphereShape3D} instead — UnitSphereShape3D is now a
+ * thin subclass that just pins `radius` to `1`. All geometry (`support`,
+ * `signed_distance_at_point`, `volume`, `surface_area`,
+ * `nearest_point_on_surface`, ...) is inherited from {@link SphereShape3D}.
+ *
+ * Kept only for:
+ *   - the `UnitSphereShape3D.INSTANCE` shared singleton that scenes, colliders,
+ *     and tests embed by reference
+ *   - the JSON `'sphere'` type-tag round-trip in `shape_to_type` /
+ *     `type_adapters` (an `instanceof` check, which is why we still need a
+ *     distinct subclass rather than a constant `SphereShape3D` instance)
+ *
+ * For new code prefer:
+ *   - `new SphereShape3D()` — also defaults to `radius = 1`
+ *   - `SphereShape3D.from(radius)` — express by radius
+ */
+export class UnitSphereShape3D extends SphereShape3D {
+    // No constructor / no method overrides on purpose. SphereShape3D's
+    // constructor already sets radius to 1, and every geometry method is
+    // correct for that case verbatim.
+
+    /**
+     * Shared singleton. Many call sites — JSON deserialisation, the default
+     * {@link Collider} shape, tests — embed this by reference rather than
+     * allocating a fresh sphere.
+     * @type {UnitSphereShape3D}
+     */
+    static INSTANCE = new UnitSphereShape3D();
+}
+
+/**
+ * @deprecated Prefer dispatching on `isSphereShape3D`, which is `true` for both
+ * UnitSphereShape3D (inherited via prototype chain) and {@link SphereShape3D}.
+ * Retained so any older external code that already narrowed via this marker
+ * keeps working.
+ * @readonly
+ * @type {boolean}
+ */
+UnitSphereShape3D.prototype.isUnitSphereShape3D = true;

package/src/core/geom/3d/shape/json/shape_to_type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shape_to_type.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/shape_to_type.js"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,uDAFa,MAAM,CAgBlB"}
+{"version":3,"file":"shape_to_type.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/shape_to_type.js"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,uDAFa,MAAM,CAkBlB"}

package/src/core/geom/3d/shape/json/shape_to_type.js

@@ -1,8 +1,8 @@
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
+import { SphereShape3D } from "../SphereShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
 import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
-import { UnitSphereShape3D } from "../UnitSphereShape3D.js";
 
 /**
  *
@@ -14,7 +14,9 @@ export function shape_to_type(shape) {
         return 'union';
     } else if (shape instanceof UnitCubeShape3D) {
         return 'cube';
-    } else if (shape instanceof UnitSphereShape3D) {
+    } else if (shape instanceof SphereShape3D) {
+        // Covers UnitSphereShape3D (radius 1) and SphereShape3D (arbitrary);
+        // the 'sphere' adapter carries the radius.
         return 'sphere';
     } else if (shape instanceof TransformedShape3D) {
         return 'transform';

package/src/core/geom/3d/shape/json/type_adapters.d.ts

@@ -4,8 +4,17 @@ export namespace type_adapters {
         function write(): {};
     }
     namespace sphere {
-        function read(): UnitSphereShape3D;
-        function write(): {};
+        function read({ radius }?: {
+            radius: any;
+        }): SphereShape3D;
+        /**
+         * @param {SphereShape3D} object
+         */
+        function write(object: SphereShape3D): {
+            radius?: undefined;
+        } | {
+            radius: number;
+        };
     }
     namespace capsule {
         function read({ radius, height }: {
@@ -49,7 +58,7 @@ export namespace type_adapters {
     }
 }
 import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
-import { UnitSphereShape3D } from "../UnitSphereShape3D.js";
+import { SphereShape3D } from "../SphereShape3D.js";
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";

package/src/core/geom/3d/shape/json/type_adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type_adapters.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/type_adapters.js"],"names":[],"mappings":";;QAUQ,iCAEC;QACD,qBAEC;;;QAGD,mCAEC;QACD,qBAEC;;;QAGD;;;2BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;+BAIC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;yBAIC;QACD;;;WAGG;QACH;;UAIC;;;gCApEuB,uBAAuB;kCACrB,yBAAyB;+BAJ5B,sBAAsB;mCAClB,0BAA0B;6BAChC,oBAAoB"}
+{"version":3,"file":"type_adapters.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/json/type_adapters.js"],"names":[],"mappings":";;QAWQ,iCAEC;QACD,qBAEC;;;QAGD;;0BAQC;QACD;;WAEG;QACH;;;;UAIC;;;QAGD;;;2BAEC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;;+BAIC;QACD;;;WAGG;QACH;;;UAKC;;;QAGD;;yBAIC;QACD;;;WAGG;QACH;;UAIC;;;gCA/EuB,uBAAuB;8BAHzB,qBAAqB;+BADpB,sBAAsB;mCAElB,0BAA0B;6BAChC,oBAAoB"}

package/src/core/geom/3d/shape/json/type_adapters.js

@@ -1,4 +1,5 @@
 import { CapsuleShape3D } from "../CapsuleShape3D.js";
+import { SphereShape3D } from "../SphereShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
 import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
@@ -16,11 +17,22 @@ export const type_adapters = {
         }
     },
     'sphere': {
-        read() {
-            return UnitSphereShape3D.INSTANCE;
+        read({ radius } = {}) {
+            // Backward-compatible: legacy 'sphere' entries have no radius and
+            // map to the unit-sphere singleton. A radius of 1 is also treated
+            // as the unit sphere so re-saved unit spheres keep sharing INSTANCE.
+            if (radius === undefined || radius === 1) {
+                return UnitSphereShape3D.INSTANCE;
+            }
+            return SphereShape3D.from(radius);
         },
-        write() {
-            return {};
+        /**
+         * @param {SphereShape3D} object
+         */
+        write(object) {
+            // Omit radius for the unit case to keep the serialized form
+            // byte-identical to the pre-SphereShape3D 'sphere' tag.
+            return object.radius === 1 ? {} : { radius: object.radius };
         }
     },
     'capsule': {

package/src/core/geom/3d/shape/util/shape_to_visual_entity.js

@@ -8,10 +8,10 @@ import { AttachmentSockets } from "../../../../../engine/ecs/sockets/AttachmentS
 import { Transform } from "../../../../../engine/ecs/transform/Transform.js";
 import { DrawMode } from "../../../../../engine/graphics/ecs/mesh-v2/DrawMode.js";
 import { ShadedGeometry } from "../../../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { SphereShape3D } from "../SphereShape3D.js";
 import { TransformedShape3D } from "../TransformedShape3D.js";
 import { UnionShape3D } from "../UnionShape3D.js";
 import { UnitCubeShape3D } from "../UnitCubeShape3D.js";
-import { UnitSphereShape3D } from "../UnitSphereShape3D.js";
 
 const g_unit_sphere = makeHelperSphereGeometry(0.5, 32);
 const g_unit_cube = makeHelperBoxGeometry(1, 1, 1);
@@ -149,7 +149,7 @@ export function shape_to_visual_entity(shape, ecd) {
         return composite_shape_to_entity(shape, ecd);
     } else if (shape instanceof UnitCubeShape3D) {
         return cube_shape_to_entity(shape, ecd);
-    } else if (shape instanceof UnitSphereShape3D) {
+    } else if (shape instanceof SphereShape3D) {
         return sphere_shape_to_entity(shape, ecd);
     } else if (shape instanceof TransformedShape3D) {
         return transformed_shape_to_entity(shape, ecd);

package/src/engine/control/first-person/DESIGN_COLLISION.md

@@ -0,0 +1,255 @@
+# Collision handling — construction plan
+
+Companion to DESIGN.md (base controller) and TODO.md. This is the
+roadmap for taking the controller's collision response from the current
+2.5D split to a unified, slope-aware, anti-tunnelling mover modelled on
+the Quake → Source `TryPlayerMove` / `CategorizePosition` lineage —
+using the now-accurate `shapeCast` / `raycast` the physics engine
+gained over the P1–P6 narrowphase work.
+
+Every phase is **guard-test-first**: write the failing spec that pins
+the behaviour, then implement until green, then run the full
+first-person suite. Phases are ordered so the controller stays shippable
+and tested after each one — no flag day.
+
+---
+
+## 1. Goal & non-goals
+
+**Goal.** A single swept move-and-slide that handles walls, floors,
+ceilings, ramps, and getting unstuck — with true surface normals — so
+abilities (Slide, WallRun, Mantle) inherit correct collision for free
+by routing their motion through it.
+
+**Non-goals.**
+- Bunny-hop / strafe-jump emergent acceleration. We deliberately
+  *preserve* momentum (Mirror's Edge / modern-CoD model), not *amplify*
+  it (Quake / Titanfall model). See the momentum note in DESIGN.md.
+- A full dynamics solver for the player. The player stays a
+  `KinematicPosition` body; the controller owns the Transform.
+- Replacing the abilities' bespoke motion models — only giving them a
+  correct shared mover to call.
+
+---
+
+## 2. Current state (one paragraph)
+
+`_integrateVerticalAndResolveGround` does a **2.5D split**: gravity →
+horizontal-only swept slide (`_moveAndSlide`, 4-iteration collide-and-
+slide, `SKIN = 0.005`, `CAST_STEP_HEIGHT = 0.05`) → a *direct* vertical
+position add → a downward-ray ground resolver that snaps a scalar Y.
+The slide projects against true narrowphase normals (good), but: the
+ground resolver discards the surface normal (no slopes), vertical motion
+isn't swept (tunnels through thin floors, no ceiling detection), corners
+re-project planes independently (no crease/dead-stop), and there's no
+depenetration. Full analysis in the review that preceded this doc.
+
+---
+
+## 3. Physics capabilities we can now lean on
+
+The P1–P6 narrowphase + query work made the two primitives we depend on
+narrowphase-exact. This plan is only feasible because of it.
+
+| Capability | Status | Source |
+|---|---|---|
+| `raycast` exact surface **normal** (sphere/box/capsule/mesh/heightmap) | ✅ landed | refine_ray_hit P1–P3 (`6f931b4`, `5cc2e3e`, `1a2a602`, `4c2292c`) |
+| `shapeCast` true contact **normal at TOI** via MPR (not broadphase −dir) | ✅ landed | MPR normal-recovery in `shape_cast.js` |
+| `shapeCast` **start-in-contact** → returns `t=0` + valid normal | ✅ landed | `shape_cast.js:195`, normal probe `:350` |
+| `shapeCast` analytic slab-narrowing (long-sweep accuracy/perf) | ✅ landed | `shape_cast.js:203` |
+| EPA adaptive tolerance (no silent sub-mm failure) | ✅ landed | P2.2 (`8ff15a6`) |
+| MPR fallback when EPA doesn't converge | ✅ landed | P3.1 (`419b94a`) |
+| box-box edge-edge closest-pair (not centre-midpoint) | ✅ landed | P3.2 (`419b94a`) |
+| capsule-vs-triangle closed-form multi-point manifold | ✅ landed | P1.1c (`eaa75fa`) |
+| GJK separating-axis cache (cheap warm casts) | ✅ landed | P2.1 (`60ca759`) |
+| `overlap(shape,pos,rot,out,off,filter)` → body-id list | ✅ landed | `overlap_shape.js` |
+| `compute_penetration(...)` → depth + B→A direction | ⚠️ **internal-only** | `compute_penetration.js` — not on PhysicsSystem |
+
+Query contract notes the plan relies on:
+- `shapeCast` `result.t` is a **world distance** when the ray direction
+  is unit-length and `tMax = sweepLength` (how `_moveAndSlide` already
+  uses it). New casts must keep that convention.
+- `result.position` is the **swept shape centre**, not the surface
+  contact point. We never need the contact point in this plan; flagged
+  in case edge/foot placement ever does.
+- `result.normal` is the **target's outward** surface normal.
+
+---
+
+## 4. Target architecture
+
+Replace the 2.5D split with a **unified swept solve + ground
+categorize**, the Source pattern:
+
+```
+move(dt):
+  applyGravityToVelocity()                       # vy -= g·dt
+  delta = velocity · dt                          # full 3D, gravity folded in
+  collideAndSlide(delta)                          # swept, all axes, crease-aware
+  categorizeGround()                              # short down-probe → grounded + normal
+  if grounded and walkable: stayOnGround()        # snap to surface, zero vy
+```
+
+Three pieces:
+
+1. **`collideAndSlide(delta)`** — the existing 4-iteration loop,
+   generalised to 3D and made crease-aware (two-plane seam projection,
+   three-plane dead-stop). Gravity is part of `delta`, so floors and
+   ceilings are just contact planes — anti-tunnelling falls out.
+
+2. **`categorizeGround()`** — a short **downward `shapeCast`** (the
+   capsule swept down by `SKIN + groundProbeBand`, e.g. ~6 cm). Returns
+   `{grounded, surfaceY, normal}`. Replaces the scalar-Y resolver as the
+   authoritative ground source when physics is present; the host
+   resolver / flat-ground stays as the no-physics fallback, behind one
+   `_probeGround()` function so callers never branch (uniform flow).
+
+3. **`stayOnGround()`** — when categorize says grounded on a walkable
+   plane, snap `position.y` to `surfaceY` and zero `vy`. This is what
+   kills the SKIN-vs-snap **bounce** (the bug we hit earlier): grounded
+   is a *band test + active snap*, not a strict `y <= testY`
+   inequality, so landing at `floor + SKIN` doesn't re-flag airborne.
+
+Walkability gate: `groundNormal.y >= MIN_WALK_NORMAL` (≈0.7, ~45°). On a
+steeper face the player isn't grounded — they slide, because the slope
+is just another clip plane in `collideAndSlide` and gravity carries them
+down it.
+
+---
+
+## 5. Phased plan
+
+### Phase 1 — Ground normal + slope policy
+*Review gap #1. Highest feel/realism leverage; lowest risk.*
+
+- Add `_probeGround(runtime, bodyTransform) → {grounded, surfaceY, normal}`.
+  Physics path: downward `shapeCast` of the capsule, read `hit.normal`.
+  No-physics path: existing resolver / flat-ground, normal = `(0,1,0)`.
+- Write `state.groundNormal`. Add `MIN_WALK_NORMAL` to config.
+- Reproject grounded horizontal velocity onto the ground plane
+  (`v -= (v·n)·n`) so ramps don't launch (downhill) or clip (uphill).
+- Steep face → not grounded → slides under gravity.
+
+**Guard tests** (new `GroundSlope.spec.js`): walk up a 30° ramp keeps
+speed and stays grounded; stand on shallow slope = grounded with correct
+normal; 60° face = not grounded, player slides downhill, not glued.
+
+**Risk:** low. Self-contained; resolver fallback unchanged for existing
+tests.
+
+### Phase 2 — Crease / corner handling
+*Review gap #3. Cheap correctness win in the existing loop.*
+
+- Track planes hit within one `_moveAndSlide` call. On a second plane
+  that re-violates the first, project the residual onto the seam
+  `normalize(n₁ × n₂)`. On a third plane in one frame, zero the residual
+  (and the into-wall velocity) — Quake's dead-stop.
+
+**Guard tests** (extend `MoveAndSlide.spec.js`): oblique (non-axis)
+inside corner stops cleanly with no residual leak and no tick-to-tick
+chatter; narrow wedge dead-stops instead of squirting through.
+
+**Risk:** low–medium. Pure addition to the slide loop; existing
+single-plane tests must stay green.
+
+### Phase 3 — Unify vertical into the swept solve
+*Review gap #2 (anti-tunnel). The structural change; do it after 1 & 2
+so slope + crease are already trustworthy.*
+
+- Fold gravity-driven vertical into the swept `delta`; remove the direct
+  `position.y += vy·dt` add.
+- Replace the strict-inequality resolver snap with
+  `categorizeGround()` + `stayOnGround()` (§4).
+- Route Slide / WallRun vertical through the same mover (TODO's "ability
+  motion routing" — they stop hand-integrating gravity).
+
+**Guard tests** (new `VerticalSweep.spec.js`): drop from height onto a
+thin physics slab — no tunnelling, lands on top; jump straight into a
+ceiling — stops, doesn't pass through; **the stationary-on-floor case
+stays at y≈0 across 120 ticks** (generalise the earlier no-bounce repro,
+now without an escape pass to mask it).
+
+**Risk:** medium–high. Changes the contract `_integrate…` exposes to
+abilities; they're updated in the same phase. This is the phase most
+likely to surface a physics gap (see §6).
+
+### Phase 4 — Depenetration safety net
+*Review gap #4. Minimal, not the rolled-back ring-buffer escape.*
+
+- One bounded nudge: if the capsule starts a tick overlapping (detect
+  via `shapeCast` `t=0`, or `overlap()`), push out along the contact
+  normal by `depth + SKIN`, capped at ~4 iterations. No ring buffer, no
+  teleport, no rescue signal — just don't stay solid.
+- **Blocked on §6 requirement #1** for a clean depth. Without it, the
+  fallback is a fixed-step nudge along the normal (no exact depth),
+  which is cruder but unblocks the phase.
+
+**Guard tests** (new `Depenetration.spec.js`): spawn the player
+straddling a box surface → within a few ticks they're outside; a body
+that spawns on top of a standing player → player ends up clear; deep
+burial terminates (no infinite loop), doesn't teleport.
+
+**Risk:** low if requirement #1 lands; medium otherwise (cruder nudge
+needs more tuning).
+
+### Phase 5 — Real step-up *(optional / deferrable)*
+*Review gap #5.*
+
+- Source-style `raise → move → trace-down` for stairs above the 5 cm
+  implicit step, OR keep stairs as the Mantle ability's job and document
+  the curb ceiling. Likely **defer** — Mantle already covers ledges; a
+  decision, not necessarily code.
+
+---
+
+## 6. Unsatisfied physics requirements
+
+Things I'd want from the physics engine to build §5 cleanly. None block
+Phases 1–3; #1 shapes Phase 4.
+
+1. **Public penetration/contact query — `PhysicsSystem.computePenetration`
+   (or `contact`).** `compute_penetration(out_dir, shapeA, posA, rotA,
+   shapeB, posB, rotB) → depth` already exists and is exactly right, but
+   it's an **internal narrowphase utility, not exposed** on
+   `PhysicsSystem`. Phase 4 depenetration wants `{normal, depth}` for the
+   player capsule vs each overlapping body. Today I can get the *fact* of
+   overlap (`overlap()` → ids) and a *normal* (`shapeCast` `t=0`), but
+   **not the depth** — `shapeCast` discards it at `t=0`. Wiring this
+   through is small (the function is written and tested) and is the
+   single highest-value API add for the controller. **Priority: HIGH.**
+
+2. **`overlap()` that can optionally emit per-body `{normal, depth}`,
+   not just ids.** Subsumed by #1 if I call `computePenetration` per
+   returned id — acceptable. Only worth doing natively if profiling
+   shows the per-body re-query matters. **Priority: LOW** (covered by #1).
+
+3. **Contact *point* (not just swept-centre) from `shapeCast`.** Not
+   needed for this plan, but any future foot-placement / ledge-edge or
+   multi-point ground balancing wants the world contact point.
+   `result.position` is the swept centre today. **Priority: LOW.**
+
+4. **Multi-contact ground manifold from one query.** `shapeCast` returns
+   the single closest-`t` contact. A capsule straddling the seam between
+   two boxes gets one normal, not both — fine for v1 grounded snap, a
+   limitation for precise edge-balancing. **Priority: LOW.**
+
+If only one thing gets built: **#1**. It turns Phase 4 from "tune a
+blind nudge" into "push out by the exact reported depth," and it's
+mostly plumbing over code that already exists and is tested.
+
+---
+
+## 7. Constants (ours ← reference lineage)
+
+| Constant | Plan value | Reference | Note |
+|---|---|---|---|
+| slide iterations | 4 | Quake `numbumps` 4 | unchanged |
+| `SKIN` | 0.005 m | Fauerby `veryCloseDistance` ~0.005 | unchanged |
+| `MIN_WALK_NORMAL` | ~0.7 (≈45°) | Quake3 `MIN_WALK_NORMAL` 0.7 / Source `normal.z ≥ 0.7` | **new, Phase 1** |
+| ground-probe band | ~0.06 m | Source `StayOnGround` ~2 u down-snap | **new, Phase 3** |
+| crease dead-stop | zero on 3rd plane | Quake `SV_FlyMove` | **new, Phase 2** |
+| step height | 0.05 m (implicit) | Source `sv_stepsize` 18 u (~0.34 m) | Phase 5 decision |
+
+Overbounce: we keep the clip at effective `1.0` gated on into-wall
+(`v·n < 0`), relying on `SKIN` for clearance, rather than Quake3's
+`OVERCLIP 1.001` nudge. No change planned — equivalent in practice.

package/src/engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AmbientOcclusionPostProcessEffect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js"],"names":[],"mappings":"AAoBA;IAIQ,WAA0C;IAI1C,2BAQE;IAyBF;;;;OAIG;IACH,sBAA0B;IAE1B;;;;OAIG;IACH,2BAA6B;IAG7B;;;;OAIG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,wBAA2B;IAE3B,8CAUE;IAEF;;;;OAIG;IACH,uBAAwB;IAExB;;;;;OAKG;IACH,2BASE;IAKF;;;;OAIG;IACH,0BAAwD;IAK5D;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,oBAeC;IAED,iBAEC;IAED,2BAkCC;IAED,uBASC;IAED;;;OAGG;IACH,iBAwBC;IAED;;;OAGG;IACH,4BAFW,OAAO,QAiCjB;IAED;;;;OAIG;IACH,gCASC;IAED;;;;OAIG;IACH,mCAUC;IAGD,oCAcC;IAED,wBA2CC;IAED,yBAiBC;CAEJ;6BA/Y4B,uCAAuC;+BAD7D,OAAO;6CAAP,OAAO"}
+{"version":3,"file":"AmbientOcclusionPostProcessEffect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js"],"names":[],"mappings":"AAoBA;IAIQ,WAA0C;IAI1C,2BAQE;IAyBF;;;;OAIG;IACH,sBAA0B;IAE1B;;;;OAIG;IACH,2BAA6B;IAG7B;;;;OAIG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,wBAA2B;IAE3B,8CAUE;IAEF;;;;OAIG;IACH,uBAAwB;IAExB;;;;;OAKG;IACH,2BASE;IAKF;;;;OAIG;IACH,0BAAwD;IAK5D;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,oBAeC;IAED,iBAEC;IAED,2BAoCC;IAED,uBASC;IAED;;;OAGG;IACH,iBAwBC;IAED;;;OAGG;IACH,4BAFW,OAAO,QAiCjB;IAED;;;;OAIG;IACH,gCASC;IAED;;;;OAIG;IACH,mCAUC;IAGD,oCAcC;IAED,wBA2CC;IAED,yBAiBC;CAEJ;6BAjZ4B,uCAAuC;+BAD7D,OAAO;6CAAP,OAAO"}

package/src/engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js

@@ -187,7 +187,9 @@ export class AmbientOcclusionPostProcessEffect extends EnginePlugin {
 
         const camera = this.__render_camera;
 
-        uniforms.size.value.set(this.__render_target.width, this.__render_target.height);
+        // AO renders at half-res but samples the full-res depth buffer, so `size` is the full (depth)
+        // resolution -- all texel math then lands on depth texel centres rather than texel boundaries
+        uniforms.size.value.set(this.__composit_layer.renderTarget.width, this.__composit_layer.renderTarget.height);
 
         // setup camera
         const near = camera.near;

package/src/engine/graphics/render/buffer/simple-fx/ao/SAOShader.js

@@ -217,8 +217,8 @@ const SAOShader = {
 		// radius over which an occluder's contribution fades to zero at the edge. Must be in [0, 1]. (GTAO)
 		const float GTAO_EFFECT_FALLOFF_RANGE = 0.615;
 
-		float getOccludedFraction( const in vec3 centerViewPosition ) {
-			vec3 centerViewNormal = getViewNormal( centerViewPosition, vUv );
+		float getOccludedFraction( const in vec3 centerViewPosition, const in vec2 centerUv ) {
+			vec3 centerViewNormal = getViewNormal( centerViewPosition, centerUv );
 
 			// sample origin lifted slightly off the surface along the normal (see SURFACE_BIAS)
 			vec3 sampleOrigin = centerViewPosition + centerViewNormal * ( kernelRadius * SURFACE_BIAS );
@@ -267,7 +267,7 @@ const SAOShader = {
 				vec2 sampleUv = ( clip.xy / clip.w ) * 0.5 + 0.5;
 
 				// screen-space offset from the centre, in pixels
-				vec2 offsetPixels = ( sampleUv - vUv ) * size;
+				vec2 offsetPixels = ( sampleUv - centerUv ) * size;
 
 				// push forward along the screen direction by the self-occlusion margin (extends the
 				// screen-space radius), then snap to the nearest pixel centre so the depth fetch is
@@ -276,7 +276,7 @@ const SAOShader = {
 				offsetPixels += offsetPixels / max( offsetLength, EPSILON ) * SELF_OCCLUSION_MARGIN_PIXELS;
 				offsetPixels = round( offsetPixels );
 
-				sampleUv = vUv + offsetPixels / size;
+				sampleUv = centerUv + offsetPixels / size;
 
 				// samples outside the screen have no depth to test against
 				if ( sampleUv.x < 0.0 || sampleUv.x > 1.0 || sampleUv.y < 0.0 || sampleUv.y > 1.0 ) {
@@ -316,15 +316,20 @@ const SAOShader = {
 		}
 
 		void main() {
-			float centerDepth = getDepth( vUv );
+			// snap to the centre of the full-res depth texel we sample. The half-res pass otherwise
+			// lands on texel boundaries, where NEAREST biases consistently to one side and the
+			// reconstructed position disagrees with the sampled depth -> asymmetric edge self-occlusion.
+			vec2 centerUv = ( floor( vUv * size ) + 0.5 ) / size;
+
+			float centerDepth = getDepth( centerUv );
 			if( centerDepth >= ( 1.0 - EPSILON ) ) {
 				discard;
 			}
 
 			float centerViewZ = getViewZ( centerDepth );
-			vec3 viewPosition = getViewPosition( vUv, centerDepth, centerViewZ );
+			vec3 viewPosition = getViewPosition( centerUv, centerDepth, centerViewZ );
 
-			float occlusion = getOccludedFraction( viewPosition );
+			float occlusion = getOccludedFraction( viewPosition, centerUv );
 
 			// intensity is an artistic power: 1.0 leaves the physical estimate untouched, higher
 			// darkens occluded areas while leaving fully-lit areas at 1.0

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/refine_ray_hit.js

@@ -41,10 +41,10 @@ const ln = new Float64Array(3); // surface normal in shape-local frame
  *   {@link RAY_REFINE_UNSUPPORTED} when the shape has no exact ray test here
  */
 export function refine_ray_hit(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
-    if (shape.isUnitSphereShape3D === true) {
+    if (shape.isSphereShape3D === true) {
         // Rotation-invariant: translate into the sphere's frame; the local
         // normal is already the world normal.
-        return ray_sphere_local(outNormal, ox - position.x, oy - position.y, oz - position.z, dx, dy, dz, tMax, 1);
+        return ray_sphere_local(outNormal, ox - position.x, oy - position.y, oz - position.z, dx, dy, dz, tMax, shape.radius);
     }
 
     if (shape.isBoxShape3D === true || shape.isCapsuleShape3D === true) {

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

@@ -1,12 +1,13 @@
 /**
- * Closed-form contact generation for two unit spheres positioned in world
- * space. Returns whether the spheres overlap. On overlap, `out` is populated
- * with `[nx, ny, nz, depth]` where the normal points from B toward A and
- * `depth` is the positive penetration distance.
+ * Closed-form contact generation for two spheres positioned in world space.
+ * Returns whether the spheres overlap. On overlap, `out` is populated with
+ * `[nx, ny, nz, depth]` where the normal (unit length) points from B toward A
+ * and `depth` is the positive penetration distance.
  *
- * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
- * scaling on the body's transform is irrelevant under our "no scale on
- * physics transforms" assumption.
+ * Each sphere's radius is passed explicitly (`radius_a` / `radius_b`) — the
+ * caller reads it from the shape (`SphereShape3D.radius`; 1 for the
+ * {@link UnitSphereShape3D} special case). Any scaling on the body's transform
+ * is irrelevant under our "no scale on physics transforms" assumption.
  *
  * Centres-coincident is a singular case for the general normal but is
  * resolved here by picking +X as a deterministic tie-break direction.

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

@@ -1 +1 @@
-{"version":3,"file":"sphere_sphere_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_sphere_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,2CAXW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA4BnB"}
+{"version":3,"file":"sphere_sphere_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_sphere_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,2CAXW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA4BnB"}

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

@@ -1,12 +1,13 @@
 /**
- * Closed-form contact generation for two unit spheres positioned in world
- * space. Returns whether the spheres overlap. On overlap, `out` is populated
- * with `[nx, ny, nz, depth]` where the normal points from B toward A and
- * `depth` is the positive penetration distance.
+ * Closed-form contact generation for two spheres positioned in world space.
+ * Returns whether the spheres overlap. On overlap, `out` is populated with
+ * `[nx, ny, nz, depth]` where the normal (unit length) points from B toward A
+ * and `depth` is the positive penetration distance.
  *
- * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
- * scaling on the body's transform is irrelevant under our "no scale on
- * physics transforms" assumption.
+ * Each sphere's radius is passed explicitly (`radius_a` / `radius_b`) — the
+ * caller reads it from the shape (`SphereShape3D.radius`; 1 for the
+ * {@link UnitSphereShape3D} special case). Any scaling on the body's transform
+ * is irrelevant under our "no scale on physics transforms" assumption.
  *
  * Centres-coincident is a singular case for the general normal but is
  * resolved here by picking +X as a deterministic tie-break direction.