@woosh/meep-engine 3.43.0 → 3.44.0

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js

@@ -517,16 +517,26 @@ export class GPUMeshSkinningContext {
      * registrations (which would otherwise try to look up the freed
      * skin's matrix offset on the next bindings upload and assert).
      *
+     * **A mesh bound before its clone exists is forgotten too.** It has no binding record yet, only
+     * its skin, and keeping that skin past this call would leave the entity naming a freed id: the
+     * next skin to take the id would deform it, and binding it to a skin of its own would be refused
+     * as a rebind.
+     *
      * @param {number} skin_id
      */
     unbind_all_by_skin(skin_id) {
         for (let i = this.#bindings.length - 1; i >= 0; i--) {
             const b = this.#bindings[i];
             if (b.skin_id === skin_id) {
-                this.#skin_by_entity.delete(b.entity);
                 this.#drop_binding_at(i);
             }
         }
+
+        for (const [entity, bound] of this.#skin_by_entity) {
+            if (bound === skin_id) {
+                this.#skin_by_entity.delete(entity);
+            }
+        }
     }
 
     /**

package/src/shade/renderer/geometry/BoxGeometry.d.ts

@@ -11,16 +11,6 @@ export class BoxGeometry extends MeshletGeometry {
      */
     constructor(width?: number, height?: number, depth?: number);
 }
-/**
- */
-export class PlaneGeometry extends MeshletGeometry {
-    /**
-     * @param {number} [width]
-     * @param {number} [height]
-     * @param {number} [widthSegments]
-     * @param {number} [heightSegments]
-     */
-    constructor(width?: number, height?: number, widthSegments?: number, heightSegments?: number);
-}
+export { PlaneGeometry } from "./PlaneGeometry.js";
 import { MeshletGeometry } from "./MeshletGeometry.js";
 //# sourceMappingURL=BoxGeometry.d.ts.map

package/src/shade/renderer/geometry/BoxGeometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BoxGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/BoxGeometry.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH;IACI;;;;OAIG;IACH,oBAJW,MAAM,WACN,MAAM,UACN,MAAM,EAKhB;CACJ;AAED;GACG;AACH;IACI;;;;;OAKG;IACH,oBALW,MAAM,WACN,MAAM,kBACN,MAAM,mBACN,MAAM,EAKhB;CACJ;gCAlC+B,sBAAsB"}
+{"version":3,"file":"BoxGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/BoxGeometry.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI;;;;OAIG;IACH,oBAJW,MAAM,WACN,MAAM,UACN,MAAM,EAKhB;CACJ;;gCAlB+B,sBAAsB"}

package/src/shade/renderer/geometry/BoxGeometry.js

@@ -1,7 +1,6 @@
 import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
 import { MeshletGeometry } from "./MeshletGeometry.js";
 import { make_box_geometry } from "./primitives/make_box_geometry.js";
-import { make_plane_geometry } from "./primitives/make_plane_geometry.js";
 
 /**
  * Axis-aligned box, ready to render. Constructs a regular triangulated
@@ -20,17 +19,11 @@ export class BoxGeometry extends MeshletGeometry {
     }
 }
 
-/**
- */
-export class PlaneGeometry extends MeshletGeometry {
+export {
+    // The tag goes on the specifier, inside the braces: on the statement, TypeScript never sees it.
     /**
-     * @param {number} [width]
-     * @param {number} [height]
-     * @param {number} [widthSegments]
-     * @param {number} [heightSegments]
+     * @deprecated `PlaneGeometry` moved to its own module, one class per file like every other
+     * primitive. Import {@link PlaneGeometry} from "./PlaneGeometry.js" instead.
      */
-    constructor(width = 1, height = 1, widthSegments = 1, heightSegments = 1) {
-        super();
-        meshlet_geometry_build_from_geometry(make_plane_geometry(width, height, widthSegments, heightSegments), this);
-    }
-}
+    PlaneGeometry
+} from "./PlaneGeometry.js";

package/src/shade/renderer/geometry/CapsuleGeometry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Capsule along the Y axis, ready to render: the same shape a `CapsuleShape3D` of the same radius
+ * and height describes. Constructs a regular triangulated `Geometry` and immediately converts it to
+ * the meshlet representation the renderer consumes.
+ *
+ * @see make_capsule_geometry
+ */
+export class CapsuleGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius]
+     * @param {number} [height] length of the straight section, not counting the caps
+     * @param {number} [capSegments] segments from each pole to the equator
+     * @param {number} [radialSegments] segments around the axis
+     * @param {number} [heightSegments] segments along the straight section
+     */
+    constructor(radius?: number, height?: number, capSegments?: number, radialSegments?: number, heightSegments?: number);
+}
+import { MeshletGeometry } from "./MeshletGeometry.js";
+//# sourceMappingURL=CapsuleGeometry.d.ts.map

package/src/shade/renderer/geometry/CapsuleGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapsuleGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/CapsuleGeometry.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH;IACI;;;;;;OAMG;IACH,qBANW,MAAM,WACN,MAAM,gBACN,MAAM,mBACN,MAAM,mBACN,MAAM,EAKhB;CACJ;gCAtB+B,sBAAsB"}

package/src/shade/renderer/geometry/CapsuleGeometry.js

@@ -0,0 +1,24 @@
+import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "./MeshletGeometry.js";
+import { make_capsule_geometry } from "./primitives/make_capsule_geometry.js";
+
+/**
+ * Capsule along the Y axis, ready to render: the same shape a `CapsuleShape3D` of the same radius
+ * and height describes. Constructs a regular triangulated `Geometry` and immediately converts it to
+ * the meshlet representation the renderer consumes.
+ *
+ * @see make_capsule_geometry
+ */
+export class CapsuleGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius]
+     * @param {number} [height] length of the straight section, not counting the caps
+     * @param {number} [capSegments] segments from each pole to the equator
+     * @param {number} [radialSegments] segments around the axis
+     * @param {number} [heightSegments] segments along the straight section
+     */
+    constructor(radius = 1, height = 1, capSegments = 4, radialSegments = 8, heightSegments = 1) {
+        super();
+        meshlet_geometry_build_from_geometry(make_capsule_geometry(radius, height, capSegments, radialSegments, heightSegments), this);
+    }
+}

package/src/shade/renderer/geometry/ConeGeometry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cone along the Y axis with its apex at the top, ready to render. Constructs a regular triangulated
+ * `Geometry` and immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_cone_geometry
+ */
+export class ConeGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius] radius of the base
+     * @param {number} [height]
+     * @param {number} [radialSegments] segments around the axis
+     * @param {number} [heightSegments] segments along the axis
+     * @param {boolean} [openEnded] leave the base off
+     * @param {number} [thetaStart]
+     * @param {number} [thetaLength] how much of the turn to build, in radians
+     */
+    constructor(radius?: number, height?: number, radialSegments?: number, heightSegments?: number, openEnded?: boolean, thetaStart?: number, thetaLength?: number);
+}
+import { MeshletGeometry } from "./MeshletGeometry.js";
+//# sourceMappingURL=ConeGeometry.d.ts.map

package/src/shade/renderer/geometry/ConeGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConeGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/ConeGeometry.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;;;;;;OAQG;IACH,qBARW,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,EAahB;CACJ;gCA/B+B,sBAAsB"}

package/src/shade/renderer/geometry/ConeGeometry.js

@@ -0,0 +1,33 @@
+import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "./MeshletGeometry.js";
+import { make_cone_geometry } from "./primitives/make_cone_geometry.js";
+
+/**
+ * Cone along the Y axis with its apex at the top, ready to render. Constructs a regular triangulated
+ * `Geometry` and immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_cone_geometry
+ */
+export class ConeGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius] radius of the base
+     * @param {number} [height]
+     * @param {number} [radialSegments] segments around the axis
+     * @param {number} [heightSegments] segments along the axis
+     * @param {boolean} [openEnded] leave the base off
+     * @param {number} [thetaStart]
+     * @param {number} [thetaLength] how much of the turn to build, in radians
+     */
+    constructor(
+        radius = 1,
+        height = 1,
+        radialSegments = 8,
+        heightSegments = 1,
+        openEnded = false,
+        thetaStart = 0,
+        thetaLength = Math.PI * 2
+    ) {
+        super();
+        meshlet_geometry_build_from_geometry(make_cone_geometry(radius, height, radialSegments, heightSegments, openEnded, thetaStart, thetaLength), this);
+    }
+}

package/src/shade/renderer/geometry/CylinderGeometry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cylinder along the Y axis, ready to render. Constructs a regular triangulated `Geometry` and
+ * immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_cylinder_geometry
+ */
+export class CylinderGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radiusTop]
+     * @param {number} [radiusBottom]
+     * @param {number} [height]
+     * @param {number} [radialSegments] segments around the axis
+     * @param {number} [heightSegments] segments along the axis
+     * @param {boolean} [openEnded] leave the caps off
+     * @param {number} [thetaStart]
+     * @param {number} [thetaLength] how much of the turn to build, in radians
+     */
+    constructor(radiusTop?: number, radiusBottom?: number, height?: number, radialSegments?: number, heightSegments?: number, openEnded?: boolean, thetaStart?: number, thetaLength?: number);
+}
+import { MeshletGeometry } from "./MeshletGeometry.js";
+//# sourceMappingURL=CylinderGeometry.d.ts.map

package/src/shade/renderer/geometry/CylinderGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CylinderGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/CylinderGeometry.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;;;;;;;OASG;IACH,wBATW,MAAM,iBACN,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,EAchB;CACJ;gCAjC+B,sBAAsB"}

package/src/shade/renderer/geometry/CylinderGeometry.js

@@ -0,0 +1,35 @@
+import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "./MeshletGeometry.js";
+import { make_cylinder_geometry } from "./primitives/make_cylinder_geometry.js";
+
+/**
+ * Cylinder along the Y axis, ready to render. Constructs a regular triangulated `Geometry` and
+ * immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_cylinder_geometry
+ */
+export class CylinderGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radiusTop]
+     * @param {number} [radiusBottom]
+     * @param {number} [height]
+     * @param {number} [radialSegments] segments around the axis
+     * @param {number} [heightSegments] segments along the axis
+     * @param {boolean} [openEnded] leave the caps off
+     * @param {number} [thetaStart]
+     * @param {number} [thetaLength] how much of the turn to build, in radians
+     */
+    constructor(
+        radiusTop = 1,
+        radiusBottom = 1,
+        height = 1,
+        radialSegments = 8,
+        heightSegments = 1,
+        openEnded = false,
+        thetaStart = 0,
+        thetaLength = Math.PI * 2
+    ) {
+        super();
+        meshlet_geometry_build_from_geometry(make_cylinder_geometry(radiusTop, radiusBottom, height, radialSegments, heightSegments, openEnded, thetaStart, thetaLength), this);
+    }
+}

package/src/shade/renderer/geometry/PlaneGeometry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plane in the XY plane facing +Z, ready to render. Constructs a regular triangulated `Geometry`
+ * and immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_plane_geometry
+ */
+export class PlaneGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [width]
+     * @param {number} [height]
+     * @param {number} [widthSegments]
+     * @param {number} [heightSegments]
+     */
+    constructor(width?: number, height?: number, widthSegments?: number, heightSegments?: number);
+}
+import { MeshletGeometry } from "./MeshletGeometry.js";
+//# sourceMappingURL=PlaneGeometry.d.ts.map

package/src/shade/renderer/geometry/PlaneGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaneGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/PlaneGeometry.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;;;OAKG;IACH,oBALW,MAAM,WACN,MAAM,kBACN,MAAM,mBACN,MAAM,EAKhB;CACJ;gCApB+B,sBAAsB"}

package/src/shade/renderer/geometry/PlaneGeometry.js

@@ -0,0 +1,22 @@
+import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "./MeshletGeometry.js";
+import { make_plane_geometry } from "./primitives/make_plane_geometry.js";
+
+/**
+ * Plane in the XY plane facing +Z, ready to render. Constructs a regular triangulated `Geometry`
+ * and immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_plane_geometry
+ */
+export class PlaneGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [width]
+     * @param {number} [height]
+     * @param {number} [widthSegments]
+     * @param {number} [heightSegments]
+     */
+    constructor(width = 1, height = 1, widthSegments = 1, heightSegments = 1) {
+        super();
+        meshlet_geometry_build_from_geometry(make_plane_geometry(width, height, widthSegments, heightSegments), this);
+    }
+}

package/src/shade/renderer/geometry/TorusGeometry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Torus in the XY plane with its hole along Z, ready to render. Constructs a regular triangulated
+ * `Geometry` and immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_torus_geometry
+ */
+export class TorusGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius] distance from the centre of the hole to the centre of the tube
+     * @param {number} [tube] radius of the tube itself
+     * @param {number} [radialSegments] segments around the tube
+     * @param {number} [tubularSegments] segments around the ring
+     * @param {number} [arc] how much of the ring to build, in radians
+     */
+    constructor(radius?: number, tube?: number, radialSegments?: number, tubularSegments?: number, arc?: number);
+}
+import { MeshletGeometry } from "./MeshletGeometry.js";
+//# sourceMappingURL=TorusGeometry.d.ts.map

package/src/shade/renderer/geometry/TorusGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TorusGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/TorusGeometry.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;;;;OAMG;IACH,qBANW,MAAM,SACN,MAAM,mBACN,MAAM,oBACN,MAAM,QACN,MAAM,EAKhB;CACJ;gCArB+B,sBAAsB"}

package/src/shade/renderer/geometry/TorusGeometry.js

@@ -0,0 +1,23 @@
+import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "./MeshletGeometry.js";
+import { make_torus_geometry } from "./primitives/make_torus_geometry.js";
+
+/**
+ * Torus in the XY plane with its hole along Z, ready to render. Constructs a regular triangulated
+ * `Geometry` and immediately converts it to the meshlet representation the renderer consumes.
+ *
+ * @see make_torus_geometry
+ */
+export class TorusGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius] distance from the centre of the hole to the centre of the tube
+     * @param {number} [tube] radius of the tube itself
+     * @param {number} [radialSegments] segments around the tube
+     * @param {number} [tubularSegments] segments around the ring
+     * @param {number} [arc] how much of the ring to build, in radians
+     */
+    constructor(radius = 1, tube = 0.4, radialSegments = 8, tubularSegments = 6, arc = Math.PI * 2) {
+        super();
+        meshlet_geometry_build_from_geometry(make_torus_geometry(radius, tube, radialSegments, tubularSegments, arc), this);
+    }
+}

package/src/shade/renderer/geometry/UVSphereGeometry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sphere of rings and meridians with its poles on the Y axis, ready to render. Constructs a regular
+ * triangulated `Geometry` and immediately converts it to the meshlet representation the renderer
+ * consumes.
+ *
+ * @see make_uv_sphere_geometry
+ */
+export class UVSphereGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius]
+     * @param {number} [widthSegments] segments around the axis, at least 3
+     * @param {number} [heightSegments] segments from pole to pole, at least 2
+     * @param {number} [phiStart]
+     * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+     * @param {number} [thetaStart] where to start, in radians down from the north pole
+     * @param {number} [thetaLength] how far toward the south pole to build, in radians
+     */
+    constructor(radius?: number, widthSegments?: number, heightSegments?: number, phiStart?: number, phiLength?: number, thetaStart?: number, thetaLength?: number);
+}
+import { MeshletGeometry } from "./MeshletGeometry.js";
+//# sourceMappingURL=UVSphereGeometry.d.ts.map

package/src/shade/renderer/geometry/UVSphereGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UVSphereGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/UVSphereGeometry.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH;IACI;;;;;;;;OAQG;IACH,qBARW,MAAM,kBACN,MAAM,mBACN,MAAM,aACN,MAAM,cACN,MAAM,eACN,MAAM,gBACN,MAAM,EAahB;CACJ;gCAhC+B,sBAAsB"}

package/src/shade/renderer/geometry/UVSphereGeometry.js

@@ -0,0 +1,34 @@
+import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "./MeshletGeometry.js";
+import { make_uv_sphere_geometry } from "./primitives/make_uv_sphere_geometry.js";
+
+/**
+ * Sphere of rings and meridians with its poles on the Y axis, ready to render. Constructs a regular
+ * triangulated `Geometry` and immediately converts it to the meshlet representation the renderer
+ * consumes.
+ *
+ * @see make_uv_sphere_geometry
+ */
+export class UVSphereGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius]
+     * @param {number} [widthSegments] segments around the axis, at least 3
+     * @param {number} [heightSegments] segments from pole to pole, at least 2
+     * @param {number} [phiStart]
+     * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+     * @param {number} [thetaStart] where to start, in radians down from the north pole
+     * @param {number} [thetaLength] how far toward the south pole to build, in radians
+     */
+    constructor(
+        radius = 1,
+        widthSegments = 32,
+        heightSegments = 16,
+        phiStart = 0,
+        phiLength = Math.PI * 2,
+        thetaStart = 0,
+        thetaLength = Math.PI
+    ) {
+        super();
+        meshlet_geometry_build_from_geometry(make_uv_sphere_geometry(radius, widthSegments, heightSegments, phiStart, phiLength, thetaStart, thetaLength), this);
+    }
+}

package/src/shade/renderer/geometry/primitives/make_capsule_geometry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A capsule along the Y axis, centred on the origin: a cylinder of length `height` closed by two
+ * hemispheres of `radius`, so the whole body spans `height + 2 * radius`. That is the same shape
+ * `CapsuleShape3D` describes for the same two numbers, so a collider and its mesh agree.
+ *
+ * The texture coordinates wrap `u` once around the axis and run `v` from the south pole (0) to the
+ * north pole (1) by arc length along the profile, so a texture is not stretched over the caps
+ * relative to the straight section.
+ *
+ * @param {number} [radius]
+ * @param {number} [height] length of the straight section, not counting the caps
+ * @param {number} [capSegments] segments from each pole to the equator, at least 1
+ * @param {number} [radialSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments along the straight section, at least 1 unless `height` is zero
+ * @returns {Geometry}
+ */
+export function make_capsule_geometry(radius?: number, height?: number, capSegments?: number, radialSegments?: number, heightSegments?: number): Geometry;
+import { Geometry } from "../Geometry.js";
+//# sourceMappingURL=make_capsule_geometry.d.ts.map

package/src/shade/renderer/geometry/primitives/make_capsule_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_capsule_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_capsule_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,+CAPW,MAAM,WACN,MAAM,gBACN,MAAM,mBACN,MAAM,mBACN,MAAM,GACJ,QAAQ,CA0LpB;yBA3MwB,gBAAgB"}

package/src/shade/renderer/geometry/primitives/make_capsule_geometry.js

@@ -0,0 +1,205 @@
+import { Attribute } from "../Attribute.js";
+import { Geometry } from "../Geometry.js";
+import { StandardAttributes } from "../StandardAttributes.js";
+
+/**
+ * A capsule along the Y axis, centred on the origin: a cylinder of length `height` closed by two
+ * hemispheres of `radius`, so the whole body spans `height + 2 * radius`. That is the same shape
+ * `CapsuleShape3D` describes for the same two numbers, so a collider and its mesh agree.
+ *
+ * The texture coordinates wrap `u` once around the axis and run `v` from the south pole (0) to the
+ * north pole (1) by arc length along the profile, so a texture is not stretched over the caps
+ * relative to the straight section.
+ *
+ * @param {number} [radius]
+ * @param {number} [height] length of the straight section, not counting the caps
+ * @param {number} [capSegments] segments from each pole to the equator, at least 1
+ * @param {number} [radialSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments along the straight section, at least 1 unless `height` is zero
+ * @returns {Geometry}
+ */
+export function make_capsule_geometry(radius = 1, height = 1, capSegments = 4, radialSegments = 8, heightSegments = 1) {
+
+    /*
+     A port of three's `CapsuleGeometry` onto `Geometry`: the same parameterisation, the same
+     arc-length texture coordinates and the same winding, writing meep attributes instead of three
+     ones. It departs at the poles, see below.
+
+     Derived from three.js (https://github.com/mrdoob/three.js), Copyright (c) 2010-2024 three.js authors, MIT licence.
+    */
+
+    const geo = new Geometry();
+
+    geo.name = "Capsule";
+
+    // segments
+
+    height = Math.max(0, height);
+    capSegments = Math.max(1, Math.floor(capSegments));
+    radialSegments = Math.max(3, Math.floor(radialSegments));
+
+    // a straight section of no length would be bands of no area, so then there is none and the two
+    // caps meet at a single equator, which is a sphere
+    heightSegments = height > 0 ? Math.max(1, Math.floor(heightSegments)) : 0;
+
+    // buffers
+
+    const indices = [];
+    const vertices = [];
+    const normals = [];
+    const uvs = [];
+
+    // helper variables
+
+    const halfHeight = height / 2;
+    const capArcLength = (Math.PI / 2) * radius;
+    const totalArcLength = 2 * capArcLength + height;
+
+    // rows run from the south pole up to the north pole; the two equators belong to the straight
+    // section, so both of its ends sit exactly at +-halfHeight with a level normal
+    const lastRow = capSegments * 2 + heightSegments;
+
+    let index = 0;
+    const grid = [];
+
+    // generate vertices, normals and uvs
+
+    for (let iy = 0; iy <= lastRow; iy++) {
+
+        // the profile: the outward normal in the (radial, Y) half plane, the row's height and its
+        // arc length from the south pole
+
+        let normalRadial;
+        let normalY;
+        let profileY;
+        let arcLength;
+
+        if (iy < capSegments) {
+
+            // southern cap, the angle measured up from the south pole
+
+            const angle = (iy / capSegments) * (Math.PI / 2);
+
+            normalRadial = Math.sin(angle);
+            normalY = -Math.cos(angle);
+            profileY = -halfHeight + radius * normalY;
+            arcLength = angle * radius;
+
+        } else if (iy <= capSegments + heightSegments) {
+
+            // straight section
+
+            const t = heightSegments > 0 ? (iy - capSegments) / heightSegments : 0;
+
+            normalRadial = 1;
+            normalY = 0;
+            profileY = -halfHeight + t * height;
+            arcLength = capArcLength + t * height;
+
+        } else {
+
+            // northern cap, the angle measured down from the north pole, so that the pole itself is
+            // an angle of exactly zero rather than a `Math.cos(Math.PI / 2)` that is not
+
+            const angle = ((lastRow - iy) / capSegments) * (Math.PI / 2);
+
+            normalRadial = Math.sin(angle);
+            normalY = Math.cos(angle);
+            profileY = halfHeight + radius * normalY;
+            arcLength = totalArcLength - angle * radius;
+
+        }
+
+        const profileRadius = radius * normalRadial;
+
+        const v = arcLength / totalArcLength;
+
+        // A ring at a pole is a single point. Three's grid still gives it a vertex per meridian,
+        // which puts two corners of every polar triangle on the same point. Here a pole holds one
+        // vertex per segment, turned to the middle of that segment, and each segment draws just the
+        // one triangle that has area; see `make_uv_sphere_geometry`, which does the same.
+        const pole = iy === 0 || iy === lastRow;
+
+        const rowVertexCount = pole ? radialSegments : radialSegments + 1;
+        const uOffset = pole ? 0.5 : 0;
+
+        const verticesRow = [];
+
+        for (let ix = 0; ix < rowVertexCount; ix++) {
+
+            const u = (ix + uOffset) / radialSegments;
+
+            const theta = u * Math.PI * 2;
+
+            const sinTheta = Math.sin(theta);
+            const cosTheta = Math.cos(theta);
+
+            // vertex
+
+            vertices.push(-profileRadius * cosTheta, profileY, profileRadius * sinTheta);
+
+            // normal, from the profile's angles rather than by normalising, so it is unit length by
+            // construction and stays defined at radius zero
+
+            normals.push(-normalRadial * cosTheta, normalY, normalRadial * sinTheta);
+
+            // uv
+
+            uvs.push(u, v);
+
+            verticesRow.push(index++);
+
+        }
+
+        grid.push(verticesRow);
+
+    }
+
+    // indices
+
+    for (let iy = 1; iy <= lastRow; iy++) {
+
+        const lower = grid[iy - 1];
+        const upper = grid[iy];
+
+        for (let ix = 0; ix < radialSegments; ix++) {
+
+            if (iy === 1) {
+
+                // the segment's south pole vertex stands in for both lower corners
+
+                indices.push(lower[ix], upper[ix + 1], upper[ix]);
+
+            } else if (iy === lastRow) {
+
+                // the segment's north pole vertex stands in for both upper corners
+
+                indices.push(lower[ix], lower[ix + 1], upper[ix]);
+
+            } else {
+
+                const i1 = lower[ix];
+                const i2 = lower[ix + 1];
+                const i3 = upper[ix];
+                const i4 = upper[ix + 1];
+
+                // faces
+
+                indices.push(i1, i2, i3);
+                indices.push(i2, i4, i3);
+
+            }
+
+        }
+
+    }
+
+    // build geometry
+
+    geo.index = Attribute.from(new Uint32Array(indices), 1, 'index');
+    geo.addAttribute(Attribute.from(new Float32Array(vertices), 3, StandardAttributes.Position));
+    geo.addAttribute(Attribute.from(new Float32Array(normals), 3, StandardAttributes.Normal));
+    geo.addAttribute(Attribute.from(new Float32Array(uvs), 2, StandardAttributes.TextureCoordinates0));
+
+    return geo;
+}