@woosh/meep-engine 2.142.0 → 2.144.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.144.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/PointShape3D.d.ts

@@ -9,6 +9,7 @@ export class PointShape3D extends AbstractShape3D {
     nearest_point_on_surface(result: any, reference: any): void;
     sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
     support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    equals(other: any): boolean;
 }
 import { AbstractShape3D } from "./AbstractShape3D.js";
 //# sourceMappingURL=PointShape3D.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PointShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PointShape3D.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IA4CI,8BAAqC;IAnCrC,wCAOC;IAED,6CAEC;IAED,oCAEC;IAED,4DAIC;IAED,kFAIC;IAED,qGAIC;CAGJ;gCAlD+B,sBAAsB"}
+{"version":3,"file":"PointShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PointShape3D.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IAuDI,8BAAqC;IA9CrC,wCAOC;IAED,6CAEC;IAED,oCAEC;IAED,4DAIC;IAED,kFAIC;IAED,qGAIC;IAED,4BAGC;CASJ;gCA7D+B,sBAAsB"}

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

@@ -48,5 +48,16 @@ export class PointShape3D extends AbstractShape3D {
         result[result_offset + 2] = 0;
     }
 
+    equals(other) {
+        // Parameterless: identity is the type alone (a point has no fields).
+        return super.equals(other);
+    }
+
+    hash() {
+        // Constant — every PointShape3D is identical. Distinct from the
+        // base-class 0 so it doesn't collide with a hypothetical default shape.
+        return 0x504f494e; // "POIN"
+    }
+
     static INSTANCE = new PointShape3D();
 }

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

@@ -0,0 +1,48 @@
+/**
+ * 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;
+    equals(other: any): boolean;
+    /**
+     * 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;IAED,4BAEC;IAOL;;;;;;;;OAQG;IACH,0BAFU,OAAO,CAEsB;CAXtC;gCApH+B,sBAAsB"}

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

@@ -0,0 +1,131 @@
+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;
+    }
+
+    equals(other) {
+        return super.equals(other) && this.radius === other.radius;
+    }
+
+    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);