@woosh/meep-engine 3.21.0 → 3.23.0

package/src/engine/physics/cloth/collider/cloth_collider_pack.js

@@ -0,0 +1,173 @@
+import { BoxShape3D } from "../../../../core/geom/3d/shape/BoxShape3D.js";
+import { CapsuleShape3D } from "../../../../core/geom/3d/shape/CapsuleShape3D.js";
+import { CylinderShape3D } from "../../../../core/geom/3d/shape/CylinderShape3D.js";
+import { PlaneShape3D } from "../../../../core/geom/3d/shape/PlaneShape3D.js";
+import { SphereShape3D } from "../../../../core/geom/3d/shape/SphereShape3D.js";
+import { ClothColliderKind } from "./ClothColliderKind.js";
+import {
+    CCR_FEATURE,
+    CCR_KIND,
+    CCR_PARAM_0,
+    CCR_PARAM_1,
+    CCR_PARAM_2,
+    CCR_PARAM_3
+} from "./ClothColliderRecord.js";
+
+/**
+ * # `AbstractShape3D` → a packed record's geometry
+ *
+ * The one place a cloth collider is a shape object rather than a row of floats.
+ * It runs when a `ClothCollider` is linked or its shape changes, never per step
+ * and never per particle.
+ *
+ * `instanceof` rather than the prototype markers the physics narrowphase uses,
+ * because this needs to distinguish *five* kinds rather than short-circuit one,
+ * and because a marker per kind would be five new fields on `core` shapes for
+ * one consumer's benefit. The ordering matters in one place and is commented
+ * where it does.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Write a shape's kind, parameters and feature size into a record.
+ *
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record record index, not a slot offset
+ * @param {AbstractShape3D} shape in its canonical local frame
+ * @param {number} stride
+ * @returns {boolean} `false` if the shape is not one cloth can collide against,
+ *   in which case nothing was written
+ */
+export function cloth_collider_pack(table, record, shape, stride) {
+    const r = record * stride;
+
+    if (shape instanceof SphereShape3D) {
+        // Covers UnitSphereShape3D, which is a SphereShape3D of radius 1.
+        const radius = shape.radius;
+
+        table[r + CCR_KIND] = ClothColliderKind.Sphere;
+        table[r + CCR_PARAM_0] = radius;
+        table[r + CCR_PARAM_1] = 0;
+        table[r + CCR_PARAM_2] = 0;
+        table[r + CCR_PARAM_3] = 0;
+        table[r + CCR_FEATURE] = radius;
+
+        return true;
+    }
+
+    if (shape instanceof CapsuleShape3D) {
+        const radius = shape.radius;
+
+        table[r + CCR_KIND] = ClothColliderKind.Capsule;
+        table[r + CCR_PARAM_0] = radius;
+        table[r + CCR_PARAM_1] = shape.height;
+        table[r + CCR_PARAM_2] = 0;
+        table[r + CCR_PARAM_3] = 0;
+
+        // A capsule's tightest curvature is its cap, which is its own radius.
+        table[r + CCR_FEATURE] = radius;
+
+        return true;
+    }
+
+    if (shape instanceof BoxShape3D) {
+        // Covers UnitCubeShape3D, which is a BoxShape3D pinned to 0.5.
+        const h = shape.half_extents;
+
+        table[r + CCR_KIND] = ClothColliderKind.Box;
+        table[r + CCR_PARAM_0] = h.x;
+        table[r + CCR_PARAM_1] = h.y;
+        table[r + CCR_PARAM_2] = h.z;
+        table[r + CCR_PARAM_3] = 0;
+
+        // A box has no curvature; its edges are creases, and the distance over
+        // which "the nearest face's normal" describes the surface is how far
+        // the nearest face extends — its smallest half-extent, conservatively.
+        table[r + CCR_FEATURE] = Math.min(h.x, Math.min(h.y, h.z));
+
+        return true;
+    }
+
+    if (shape instanceof CylinderShape3D) {
+        const radius = shape.radius;
+
+        table[r + CCR_KIND] = ClothColliderKind.Cylinder;
+        table[r + CCR_PARAM_0] = radius;
+        table[r + CCR_PARAM_1] = shape.height;
+        table[r + CCR_PARAM_2] = 0;
+        table[r + CCR_PARAM_3] = 0;
+        table[r + CCR_FEATURE] = Math.min(radius, shape.height * 0.5);
+
+        return true;
+    }
+
+    if (shape instanceof PlaneShape3D) {
+        table[r + CCR_KIND] = ClothColliderKind.Plane;
+        table[r + CCR_PARAM_0] = shape.normal_x;
+        table[r + CCR_PARAM_1] = shape.normal_y;
+        table[r + CCR_PARAM_2] = shape.normal_z;
+        table[r + CCR_PARAM_3] = shape.offset;
+
+        // A plane is flat everywhere, so its normal describes it at any
+        // distance and it never narrows a trust region.
+        table[r + CCR_FEATURE] = Infinity;
+
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * The AABB of a packed shape in its own local frame, ignoring pose.
+ *
+ * Written here rather than taken from `AbstractShape3D#compute_bounding_box`
+ * because a plane's box is `±Infinity` on its unbounded axes and the caller
+ * transforms this one — `0 · Infinity` is `NaN`, so an unbounded local box
+ * cannot go through a pose. {@link cloth_collider_local_bounds} therefore
+ * refuses a plane and the index bounds one directly from its world normal.
+ *
+ * @param {Float64Array|number[]} out `[x0, y0, z0, x1, y1, z1]`
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record
+ * @param {number} stride
+ * @returns {boolean} `false` for an unbounded kind, in which case `out` is untouched
+ */
+export function cloth_collider_local_bounds(out, table, record, stride) {
+    const r = record * stride;
+
+    const kind = table[r + CCR_KIND];
+
+    let hx;
+    let hy;
+    let hz;
+
+    if (kind === ClothColliderKind.Sphere) {
+        hx = hy = hz = table[r + CCR_PARAM_0];
+    } else if (kind === ClothColliderKind.Capsule) {
+        const radius = table[r + CCR_PARAM_0];
+
+        hx = hz = radius;
+        hy = radius + table[r + CCR_PARAM_1] * 0.5;
+    } else if (kind === ClothColliderKind.Box) {
+        hx = table[r + CCR_PARAM_0];
+        hy = table[r + CCR_PARAM_1];
+        hz = table[r + CCR_PARAM_2];
+    } else if (kind === ClothColliderKind.Cylinder) {
+        hx = hz = table[r + CCR_PARAM_0];
+        hy = table[r + CCR_PARAM_1] * 0.5;
+    } else {
+        return false;
+    }
+
+    out[0] = -hx;
+    out[1] = -hy;
+    out[2] = -hz;
+    out[3] = hx;
+    out[4] = hy;
+    out[5] = hz;
+
+    return true;
+}

package/src/engine/physics/cloth/collider/cloth_collider_sdf.d.ts

@@ -0,0 +1,94 @@
+/**
+ * # Evaluating a packed collider
+ *
+ * Two functions, and between them they are the whole of §8.2. One writes a
+ * collider's pose interpolated to a substep; the other evaluates its signed
+ * distance and gradient at a point, in the frame the table is expressed in.
+ *
+ * The evaluation is: bring the point into the collider's local frame with the
+ * inverse of the interpolated pose, evaluate the closed-form field there, and
+ * rotate the gradient back. That is three steps and no matrix — a rigid pose
+ * inverts by conjugating its quaternion and subtracting its translation, which
+ * costs less than storing an inverse and is exact rather than cached.
+ *
+ * The fields themselves live in `core/geom/3d/shape/sdf/` as free functions
+ * over scalars, so this dispatch and {@link SphereShape3D} and the rest are
+ * calling one implementation (§14.1). Before M2 those shapes fell back to
+ * `compute_signed_distance_gradient_by_sampling` — four field evaluations and a
+ * normalise, for shapes whose gradients are two lines of algebra.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Write every collider's pose interpolated to fraction `t` of the step into its
+ * own record. `t = 0` is the previous step's pose and `t = 1` is this one's.
+ *
+ * **This is the whole of "swept collision", and it is swept in translation and
+ * rotation but not in the *contact set*.** Which particles are in contact is
+ * decided once per step; where those colliders are is decided once per substep.
+ * The limit §7 P3 states — a collider spinning fast enough that a point on its
+ * surface travels more than its own radius within one substep can still be
+ * missed — is a limit on the second of those, and more substeps is the answer
+ * to it.
+ *
+ * The rotation is an `nlerp` rather than a `slerp`: it is not constant angular
+ * velocity, and over the fraction of a fixed step it is indistinguishable from
+ * one — the two differ by under a thousandth of a degree at the half-radian per
+ * step `CLOTH_ANCHOR_ROTATION_LIMIT` already treats as a spin.
+ *
+ * @param {Float32Array|Float64Array} table
+ * @param {number} count records in `table`
+ * @param {number} t `[0, 1]`
+ * @returns {void}
+ */
+export function cloth_collider_pose_at(table: Float32Array | Float64Array, count: number, t: number): void;
+/**
+ * Signed distance from a point to one packed collider's surface, with the unit
+ * outward gradient written into `gradient` at `gradient_offset`.
+ *
+ * The point and the gradient are both in the frame `table` is expressed in.
+ *
+ * @param {Float32Array|Float64Array|number[]} gradient
+ * @param {number} gradient_offset
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record record index, not a slot offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number} the signed distance
+ */
+export function cloth_collider_signed_distance(gradient: Float32Array | Float64Array | number[], gradient_offset: number, table: Float32Array | Float64Array, record: number, x: number, y: number, z: number): number;
+/**
+ * Bring a point expressed in a collider's own local frame out into the frame
+ * the table is expressed in, using the interpolated pose. This is the inverse
+ * of the localisation above, and it is what carries a friction anchor with a
+ * moving collider (§8.3): the anchor is stored where the collider will always
+ * agree it is, and read back wherever the collider has moved to.
+ *
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record
+ * @param {number} x local
+ * @param {number} y local
+ * @param {number} z local
+ * @returns {void}
+ */
+export function cloth_collider_from_local(out: Float32Array | Float64Array | number[], out_offset: number, table: Float32Array | Float64Array, record: number, x: number, y: number, z: number): void;
+/**
+ * Bring a point out of the table's frame into a collider's own local frame,
+ * using the interpolated pose. The anchoring half of
+ * {@link cloth_collider_from_local}.
+ *
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {void}
+ */
+export function cloth_collider_to_local(out: Float32Array | Float64Array | number[], out_offset: number, table: Float32Array | Float64Array, record: number, x: number, y: number, z: number): void;
+//# sourceMappingURL=cloth_collider_sdf.d.ts.map

package/src/engine/physics/cloth/collider/cloth_collider_sdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_collider_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_sdf.js"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8CALW,YAAY,GAAC,YAAY,SACzB,MAAM,KACN,MAAM,GACJ,IAAI,CAiDhB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,mBAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA4DlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAchB;AAED;;;;;;;;;;;;;GAaG;AACH,6CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAahB"}

package/src/engine/physics/cloth/collider/cloth_collider_sdf.js

@@ -0,0 +1,275 @@
+import { sdf3_box_gradient } from "../../../../core/geom/3d/shape/sdf/sdf3_box.js";
+import { sdf3_capsule_gradient } from "../../../../core/geom/3d/shape/sdf/sdf3_capsule.js";
+import { sdf3_cylinder_gradient } from "../../../../core/geom/3d/shape/sdf/sdf3_cylinder.js";
+import { sdf3_plane_gradient } from "../../../../core/geom/3d/shape/sdf/sdf3_plane.js";
+import { sdf3_sphere_gradient } from "../../../../core/geom/3d/shape/sdf/sdf3_sphere.js";
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import {
+    CCR_INTERP_QW,
+    CCR_INTERP_QX,
+    CCR_INTERP_QY,
+    CCR_INTERP_QZ,
+    CCR_INTERP_TX,
+    CCR_INTERP_TY,
+    CCR_INTERP_TZ,
+    CCR_KIND,
+    CCR_PARAM_0,
+    CCR_PARAM_1,
+    CCR_PARAM_2,
+    CCR_PARAM_3,
+    CCR_PREV_QW,
+    CCR_PREV_QX,
+    CCR_PREV_QY,
+    CCR_PREV_QZ,
+    CCR_PREV_TX,
+    CCR_PREV_TY,
+    CCR_PREV_TZ,
+    CCR_QW,
+    CCR_QX,
+    CCR_QY,
+    CCR_QZ,
+    CCR_STRIDE,
+    CCR_TX,
+    CCR_TY,
+    CCR_TZ
+} from "./ClothColliderRecord.js";
+import { ClothColliderKind } from "./ClothColliderKind.js";
+
+/**
+ * # Evaluating a packed collider
+ *
+ * Two functions, and between them they are the whole of §8.2. One writes a
+ * collider's pose interpolated to a substep; the other evaluates its signed
+ * distance and gradient at a point, in the frame the table is expressed in.
+ *
+ * The evaluation is: bring the point into the collider's local frame with the
+ * inverse of the interpolated pose, evaluate the closed-form field there, and
+ * rotate the gradient back. That is three steps and no matrix — a rigid pose
+ * inverts by conjugating its quaternion and subtracting its translation, which
+ * costs less than storing an inverse and is exact rather than cached.
+ *
+ * The fields themselves live in `core/geom/3d/shape/sdf/` as free functions
+ * over scalars, so this dispatch and {@link SphereShape3D} and the rest are
+ * calling one implementation (§14.1). Before M2 those shapes fell back to
+ * `compute_signed_distance_gradient_by_sampling` — four field evaluations and a
+ * normalise, for shapes whose gradients are two lines of algebra.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Write every collider's pose interpolated to fraction `t` of the step into its
+ * own record. `t = 0` is the previous step's pose and `t = 1` is this one's.
+ *
+ * **This is the whole of "swept collision", and it is swept in translation and
+ * rotation but not in the *contact set*.** Which particles are in contact is
+ * decided once per step; where those colliders are is decided once per substep.
+ * The limit §7 P3 states — a collider spinning fast enough that a point on its
+ * surface travels more than its own radius within one substep can still be
+ * missed — is a limit on the second of those, and more substeps is the answer
+ * to it.
+ *
+ * The rotation is an `nlerp` rather than a `slerp`: it is not constant angular
+ * velocity, and over the fraction of a fixed step it is indistinguishable from
+ * one — the two differ by under a thousandth of a degree at the half-radian per
+ * step `CLOTH_ANCHOR_ROTATION_LIMIT` already treats as a spin.
+ *
+ * @param {Float32Array|Float64Array} table
+ * @param {number} count records in `table`
+ * @param {number} t `[0, 1]`
+ * @returns {void}
+ */
+export function cloth_collider_pose_at(table, count, t) {
+    const s = 1 - t;
+
+    for (let i = 0; i < count; i++) {
+        const r = i * CCR_STRIDE;
+
+        table[r + CCR_INTERP_TX] = s * table[r + CCR_PREV_TX] + t * table[r + CCR_TX];
+        table[r + CCR_INTERP_TY] = s * table[r + CCR_PREV_TY] + t * table[r + CCR_TY];
+        table[r + CCR_INTERP_TZ] = s * table[r + CCR_PREV_TZ] + t * table[r + CCR_TZ];
+
+        const ax = table[r + CCR_PREV_QX];
+        const ay = table[r + CCR_PREV_QY];
+        const az = table[r + CCR_PREV_QZ];
+        const aw = table[r + CCR_PREV_QW];
+
+        let bx = table[r + CCR_QX];
+        let by = table[r + CCR_QY];
+        let bz = table[r + CCR_QZ];
+        let bw = table[r + CCR_QW];
+
+        // `q` and `−q` are one rotation, so the pair has to be brought onto the
+        // same hemisphere or the interpolation takes the long way round — which
+        // for a collider is a bone that spins through the character.
+        if (ax * bx + ay * by + az * bz + aw * bw < 0) {
+            bx = -bx;
+            by = -by;
+            bz = -bz;
+            bw = -bw;
+        }
+
+        const qx = s * ax + t * bx;
+        const qy = s * ay + t * by;
+        const qz = s * az + t * bz;
+        const qw = s * aw + t * bw;
+
+        const length = Math.sqrt(qx * qx + qy * qy + qz * qz + qw * qw);
+
+        // Two opposed quaternions cancel exactly, which the hemisphere fix
+        // above makes impossible; the guard is for a record whose poses were
+        // never written rather than for a rotation.
+        const inverse = length > 0 ? 1 / length : 0;
+
+        table[r + CCR_INTERP_QX] = qx * inverse;
+        table[r + CCR_INTERP_QY] = qy * inverse;
+        table[r + CCR_INTERP_QZ] = qz * inverse;
+        table[r + CCR_INTERP_QW] = length > 0 ? qw * inverse : 1;
+    }
+}
+
+/**
+ * Signed distance from a point to one packed collider's surface, with the unit
+ * outward gradient written into `gradient` at `gradient_offset`.
+ *
+ * The point and the gradient are both in the frame `table` is expressed in.
+ *
+ * @param {Float32Array|Float64Array|number[]} gradient
+ * @param {number} gradient_offset
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record record index, not a slot offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number} the signed distance
+ */
+export function cloth_collider_signed_distance(gradient, gradient_offset, table, record, x, y, z) {
+    const r = record * CCR_STRIDE;
+
+    const qx = table[r + CCR_INTERP_QX];
+    const qy = table[r + CCR_INTERP_QY];
+    const qz = table[r + CCR_INTERP_QZ];
+    const qw = table[r + CCR_INTERP_QW];
+
+    v3_quaternion_apply_inverse(
+        LOCAL_POINT, 0,
+        x - table[r + CCR_INTERP_TX],
+        y - table[r + CCR_INTERP_TY],
+        z - table[r + CCR_INTERP_TZ],
+        qx, qy, qz, qw
+    );
+
+    const lx = LOCAL_POINT[0];
+    const ly = LOCAL_POINT[1];
+    const lz = LOCAL_POINT[2];
+
+    const kind = table[r + CCR_KIND];
+
+    let distance;
+
+    if (kind === ClothColliderKind.Sphere) {
+        distance = sdf3_sphere_gradient(LOCAL_GRADIENT, 0, lx, ly, lz, table[r + CCR_PARAM_0]);
+    } else if (kind === ClothColliderKind.Capsule) {
+        distance = sdf3_capsule_gradient(
+            LOCAL_GRADIENT, 0, lx, ly, lz,
+            table[r + CCR_PARAM_0], table[r + CCR_PARAM_1]
+        );
+    } else if (kind === ClothColliderKind.Box) {
+        distance = sdf3_box_gradient(
+            LOCAL_GRADIENT, 0, lx, ly, lz,
+            table[r + CCR_PARAM_0], table[r + CCR_PARAM_1], table[r + CCR_PARAM_2]
+        );
+    } else if (kind === ClothColliderKind.Cylinder) {
+        distance = sdf3_cylinder_gradient(
+            LOCAL_GRADIENT, 0, lx, ly, lz,
+            table[r + CCR_PARAM_0], table[r + CCR_PARAM_1]
+        );
+    } else {
+        distance = sdf3_plane_gradient(
+            LOCAL_GRADIENT, 0, lx, ly, lz,
+            table[r + CCR_PARAM_0], table[r + CCR_PARAM_1], table[r + CCR_PARAM_2],
+            table[r + CCR_PARAM_3]
+        );
+    }
+
+    // The gradient is a direction, so it takes the rotation and not the
+    // translation.
+    v3_quaternion_apply(
+        gradient, gradient_offset,
+        LOCAL_GRADIENT[0], LOCAL_GRADIENT[1], LOCAL_GRADIENT[2],
+        qx, qy, qz, qw
+    );
+
+    return distance;
+}
+
+/**
+ * Bring a point expressed in a collider's own local frame out into the frame
+ * the table is expressed in, using the interpolated pose. This is the inverse
+ * of the localisation above, and it is what carries a friction anchor with a
+ * moving collider (§8.3): the anchor is stored where the collider will always
+ * agree it is, and read back wherever the collider has moved to.
+ *
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record
+ * @param {number} x local
+ * @param {number} y local
+ * @param {number} z local
+ * @returns {void}
+ */
+export function cloth_collider_from_local(out, out_offset, table, record, x, y, z) {
+    const r = record * CCR_STRIDE;
+
+    v3_quaternion_apply(
+        out, out_offset, x, y, z,
+        table[r + CCR_INTERP_QX], table[r + CCR_INTERP_QY],
+        table[r + CCR_INTERP_QZ], table[r + CCR_INTERP_QW]
+    );
+
+    out[out_offset] += table[r + CCR_INTERP_TX];
+    out[out_offset + 1] += table[r + CCR_INTERP_TY];
+    out[out_offset + 2] += table[r + CCR_INTERP_TZ];
+}
+
+/**
+ * Bring a point out of the table's frame into a collider's own local frame,
+ * using the interpolated pose. The anchoring half of
+ * {@link cloth_collider_from_local}.
+ *
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float32Array|Float64Array} table
+ * @param {number} record
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {void}
+ */
+export function cloth_collider_to_local(out, out_offset, table, record, x, y, z) {
+    const r = record * CCR_STRIDE;
+
+    v3_quaternion_apply_inverse(
+        out, out_offset,
+        x - table[r + CCR_INTERP_TX],
+        y - table[r + CCR_INTERP_TY],
+        z - table[r + CCR_INTERP_TZ],
+        table[r + CCR_INTERP_QX], table[r + CCR_INTERP_QY],
+        table[r + CCR_INTERP_QZ], table[r + CCR_INTERP_QW]
+    );
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const LOCAL_GRADIENT = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const LOCAL_POINT = new Float64Array(3);

package/src/engine/physics/cloth/ecs/Cloth.d.ts

@@ -0,0 +1,145 @@
+/**
+ * # The thing that simulates
+ *
+ * Put it on an entity and that entity's transform subtree becomes a simulated
+ * chain: a rope, a chain, a hanging sign, a mooring line, a multi-strand rig.
+ *
+ * ```js
+ * rope_top.add(Cloth.from(ClothDynamics.ROPE));
+ * ```
+ *
+ * **The anchor is the entity the component is on**, and nothing names anything.
+ * The particle set is that entity's own transform subtree, walked through
+ * `TransformAttachmentSystem#findChildrenOf` — the parent-to-children index the
+ * engine already maintains. Put `Cloth` on the top link of a rope and you get
+ * the rope; put it on a node with several chains under it and you get all of
+ * them in **one coupled solve**, which is what makes self-collision between
+ * them work when it arrives.
+ *
+ * Two rules keep the walk unambiguous:
+ *
+ * - **A nested `Cloth` claims its own subtree.** The walk stops when it meets
+ *   another `Cloth`, so independent hanging parts of one prop partition
+ *   naturally. The two solves are ordered by hierarchy depth, so the outer one
+ *   has written the inner one's anchor before the inner one reads it.
+ * - **{@link ClothExclude}** prunes a subtree from the walk, for the rig with a
+ *   non-simulated attachment point in the middle of a chain.
+ *
+ * From M3 a `ClothRig` alongside this component redirects the particle set to a
+ * skinned model instance's joints instead (§11.2). The solver is identical
+ * either way; only seeding and write-back differ, which is why there is no mode
+ * enum here — component presence does the job an enum would otherwise do badly.
+ *
+ * ## What has to be true of the subtree
+ *
+ * Every simulated entity needs a `TransformAttachment` naming its parent and a
+ * `Transform64`; that is what "is in the transform subtree" means, and it is
+ * the ordinary way anything is parented. The subtree is walked **once**, when
+ * the cloth first steps. Adding or removing links afterwards needs an explicit
+ * re-seed, which is the same contract `TransformAttachment#parent` already
+ * carries: remove the component and add it back.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Cloth {
+    /**
+     * @param {ClothDynamics} [dynamics] assigned by reference — pass a library
+     *   entry to share it, `.clone()` first to own it
+     * @param {object} [spec]
+     * @param {number} [spec.blend]
+     * @param {number} [spec.layer]
+     * @param {number} [spec.mask]
+     * @param {number} [spec.flags]
+     * @returns {Cloth}
+     */
+    static from(dynamics?: ClothDynamics, spec?: {
+        blend?: number;
+        layer?: number;
+        mask?: number;
+        flags?: number;
+    }): Cloth;
+    /**
+     * How it behaves. Assign a frozen library entry directly and it is shared,
+     * immutable and free; `.clone()` it and you own a copy to edit. Writing a
+     * field on an owned copy takes effect on the next step — the system
+     * compares what it last saw and re-parameterises the rows when it differs,
+     * so `cloth.dynamics.slack = 0.2` works live.
+     * @type {ClothDynamics}
+     */
+    dynamics: ClothDynamics;
+    /**
+     * `0` is the fully animated pose, `1` the fully simulated one.
+     *
+     * A lerp applied at write-back rather than a solver parameter, so it is
+     * free and always safe. It is the escape hatch for cinematics, for LOD, and
+     * for "turn it off for this one shot"; from M5 the culling pass drives it
+     * to blend a cloth back in without a pop.
+     * @type {number}
+     */
+    blend: number;
+    /**
+     * Collision layer this cloth belongs to, `RigidBody` semantics. Read from
+     * M2, when there is something to filter.
+     * @type {number}
+     */
+    layer: number;
+    /**
+     * Which `ClothCollider` layers this cloth collides against. Read from M2.
+     * @type {number}
+     */
+    mask: number;
+    /**
+     * @see ClothFlags
+     * @type {number}
+     */
+    flags: number;
+    /**
+     * @param {number|ClothFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag: number | ClothFlags): boolean;
+    /**
+     * @param {Cloth} other
+     * @returns {boolean}
+     */
+    equals(other: Cloth): boolean;
+    /**
+     * @returns {number}
+     */
+    hash(): number;
+    toJSON(): {
+        dynamics: {
+            stretch: number;
+            bend: number;
+            damping: number;
+            slack: number;
+            thickness: number;
+            inertia: number;
+            drag: number;
+            substeps: number;
+            iterations: number;
+            flags: number;
+        };
+        blend: number;
+        layer: number;
+        mask: number;
+        flags: number;
+    };
+    /**
+     * @param {object} json
+     */
+    fromJSON({ dynamics, blend, layer, mask, flags }: object): void;
+    toString(): string;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isCloth: boolean;
+}
+export namespace Cloth {
+    let typeName: string;
+}
+import { ClothDynamics } from "./ClothDynamics.js";
+import { ClothFlags } from "./ClothFlags.js";
+//# sourceMappingURL=Cloth.d.ts.map

package/src/engine/physics/cloth/ecs/Cloth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cloth.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/Cloth.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAkDI;;;;;;;;;OASG;IACH,uBATW,aAAa;QAGC,KAAK,GAAnB,MAAM;QACQ,KAAK,GAAnB,MAAM;QACQ,IAAI,GAAlB,MAAM;QACQ,KAAK,GAAnB,MAAM;QACJ,KAAK,CA6BjB;IArFD;;;;;;;OAOG;IACH,UAFU,aAAa,CAEQ;IAE/B;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,cAHW,MAAM,GAAC,UAAU,GACf,OAAO,CAInB;IAyCD;;;OAGG;IACH,cAHW,KAAK,GACH,OAAO,CAgBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAUlB;IAED;;;;;;;;;;;;;;;;;MAQC;IAED;;OAEG;IACH,kDAFW,MAAM,QAehB;IAED,mBAEC;IAGL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CANtB;;;;8BAxM6B,oBAAoB;2BACvB,iBAAiB"}