@driftengine/physics 3.61.0

package/dist/cloth.js

@@ -0,0 +1,587 @@
+import { BODY_STATIC } from './bodies.js';
+import { LOCAL_POSE, closestOnCylinder, isCylinder, readCylinder } from './cylinder.js';
+import { faceCount } from './faces.js';
+export class ClothBody {
+    /** xyz-packed particle positions. */
+    position;
+    /** xyz-packed velocities. */
+    velocity;
+    /** Inverse mass per particle. Zero pins it. */
+    invMass;
+    count;
+    /** Two particle indices per constraint. */
+    link;
+    rest;
+    /** Compliance per constraint, so stretch and bend can differ. */
+    compliance;
+    previous;
+    lambda;
+    linkCount;
+    iterations;
+    damping;
+    thickness;
+    /** See `ClothOptions.coupling`. 0 is one-way, which is the default. */
+    coupling;
+    /** See `ClothOptions.particleMass`. Kilograms, read only by the coupling. */
+    particleMass;
+    /** See `ClothOptions.selfDistance`. 0 is off, which is the default. */
+    selfDistance;
+    /**
+     * Who is linked to whom, as CSR: `neighbourStart[i]` to `neighbourStart[i + 1]` indexes
+     * `neighbour`.
+     *
+     * **Built once, because the link set never changes** and the self-collision pass asks "are these
+     * two linked" once per candidate pair per tick. A `Set` of packed pairs would answer the same
+     * question with a hash probe and an allocation at construction the size of the link list; a
+     * sorted adjacency answers it with a scan over the eight or so neighbours a grid particle has,
+     * which is shorter than the probe.
+     *
+     * Empty when `selfDistance` is 0, so a sheet that does not collide with itself pays neither the
+     * memory nor the build.
+     */
+    neighbourStart;
+    neighbour;
+    /**
+     * The spatial hash the self-collision pass rebuilds each tick: a cell list over the particles.
+     *
+     * **A hash rather than a grid, because a sheet has no bounds worth allocating for.** A curtain
+     * hanging in a room occupies a sliver of it, and a dense grid over the room's extent would be
+     * mostly empty cells rebuilt every tick. The table is sized once from the particle count and
+     * reused; `cellHead` and `cellNext` are the standard two arrays, so a rebuild is one pass that
+     * writes and allocates nothing.
+     */
+    cellHead;
+    cellNext;
+    gravityX;
+    gravityY;
+    gravityZ;
+    constructor(positions, links, bendLinks, options = {}) {
+        this.count = positions.length / 3;
+        this.position = new Float32Array(positions);
+        this.velocity = new Float32Array(positions.length);
+        this.invMass = new Float32Array(this.count).fill(1);
+        this.previous = new Float32Array(positions.length);
+        this.iterations = Math.max(1, options.iterations ?? 8);
+        this.damping = options.damping ?? 0.02;
+        this.thickness = options.thickness ?? 0.02;
+        this.coupling = Math.min(1, Math.max(0, options.coupling ?? 0));
+        this.particleMass = Math.max(0, options.particleMass ?? 0.05);
+        this.selfDistance = Math.max(0, options.selfDistance ?? 0);
+        this.gravityX = options.gravityX ?? 0;
+        this.gravityY = options.gravityY ?? -9.81;
+        this.gravityZ = options.gravityZ ?? 0;
+        const stretch = options.stretchCompliance ?? 0;
+        const bend = options.bendCompliance ?? 1e-4;
+        const total = links.length / 2 + bendLinks.length / 2;
+        this.linkCount = total;
+        this.link = new Int32Array(total * 2);
+        this.rest = new Float32Array(total);
+        this.compliance = new Float32Array(total);
+        this.lambda = new Float32Array(total);
+        let at = 0;
+        for (const [set, value] of [
+            [links, stretch],
+            [bendLinks, bend],
+        ]) {
+            for (let i = 0; i + 1 < set.length; i += 2) {
+                const a = set[i] ?? 0;
+                const b = set[i + 1] ?? 0;
+                this.link[at * 2] = a;
+                this.link[at * 2 + 1] = b;
+                this.rest[at] = distance(this.position, a, b);
+                this.compliance[at] = value;
+                at++;
+            }
+        }
+        /*
+         * The adjacency and the hash, built only where self-collision is on.
+         *
+         * Two counting passes rather than an array of arrays: the first counts each particle's links
+         * and the second fills them, which is the standard CSR build and allocates two typed arrays
+         * instead of one per particle.
+         *
+         * The table has one bucket a particle. A hash with as many buckets as things in it averages
+         * one occupant a bucket, and the cost of a collision is a longer scan rather than a wrong
+         * answer — the cell key is part of the comparison below, so two particles that hash together
+         * from different cells are separated by the distance test they were going to take anyway.
+         */
+        if (this.selfDistance > 0) {
+            this.neighbourStart = new Int32Array(this.count + 1);
+            for (let k = 0; k < total; k++) {
+                this.neighbourStart[(this.link[k * 2] ?? 0) + 1]++;
+                this.neighbourStart[(this.link[k * 2 + 1] ?? 0) + 1]++;
+            }
+            for (let i = 0; i < this.count; i++) {
+                this.neighbourStart[i + 1] =
+                    (this.neighbourStart[i + 1] ?? 0) + (this.neighbourStart[i] ?? 0);
+            }
+            this.neighbour = new Int32Array(total * 2);
+            const cursor = new Int32Array(this.neighbourStart.subarray(0, this.count));
+            for (let k = 0; k < total; k++) {
+                const a = this.link[k * 2] ?? 0;
+                const b = this.link[k * 2 + 1] ?? 0;
+                this.neighbour[cursor[a]++] = b;
+                this.neighbour[cursor[b]++] = a;
+            }
+            this.cellHead = new Int32Array(Math.max(1, this.count)).fill(-1);
+            this.cellNext = new Int32Array(this.count);
+        }
+        else {
+            this.neighbourStart = EMPTY_INDEX;
+            this.neighbour = EMPTY_INDEX;
+            this.cellHead = EMPTY_INDEX;
+            this.cellNext = EMPTY_INDEX;
+        }
+    }
+    /** Pin a particle where it is, or release it. */
+    pin(index, pinned = true) {
+        this.invMass[index] = pinned ? 0 : 1;
+    }
+    /**
+     * Advance one fixed tick.
+     *
+     * Integrate, project every constraint `iterations` times, then derive velocity from how far each
+     * particle actually moved — which is what makes it position-based: a constraint that moves a
+     * particle also, by construction, changes its velocity, so nothing has to reconcile the two.
+     */
+    step(world, dt) {
+        const n = this.count;
+        const retain = 1 / (1 + this.damping * dt);
+        for (let i = 0; i < n; i++) {
+            const im = this.invMass[i] ?? 0;
+            this.previous[i * 3] = this.position[i * 3] ?? 0;
+            this.previous[i * 3 + 1] = this.position[i * 3 + 1] ?? 0;
+            this.previous[i * 3 + 2] = this.position[i * 3 + 2] ?? 0;
+            if (im === 0)
+                continue;
+            const vx = ((this.velocity[i * 3] ?? 0) + this.gravityX * dt) * retain;
+            const vy = ((this.velocity[i * 3 + 1] ?? 0) + this.gravityY * dt) * retain;
+            const vz = ((this.velocity[i * 3 + 2] ?? 0) + this.gravityZ * dt) * retain;
+            this.position[i * 3] = (this.position[i * 3] ?? 0) + vx * dt;
+            this.position[i * 3 + 1] = (this.position[i * 3 + 1] ?? 0) + vy * dt;
+            this.position[i * 3 + 2] = (this.position[i * 3 + 2] ?? 0) + vz * dt;
+        }
+        this.lambda.fill(0);
+        const invH2 = 1 / (dt * dt);
+        for (let pass = 0; pass < this.iterations; pass++) {
+            for (let k = 0; k < this.linkCount; k++)
+                this.project(k, invH2);
+        }
+        /*
+         * Self-collision after the constraints and before the bodies, which is the order that makes
+         * both of them mean what they say. A sheet resolved against itself *first* would then be
+         * stretched back into its own fold by the distance constraints; one resolved against the world
+         * first would be pushed back into a body by its own self-collision. The world is what the
+         * sheet may not enter under any circumstances, so it goes last.
+         */
+        if (this.selfDistance > 0)
+            this.collideSelf();
+        if (world)
+            this.collideParticles(world, dt);
+        const invDt = 1 / dt;
+        for (let i = 0; i < n; i++) {
+            if ((this.invMass[i] ?? 0) === 0) {
+                this.velocity[i * 3] = 0;
+                this.velocity[i * 3 + 1] = 0;
+                this.velocity[i * 3 + 2] = 0;
+                continue;
+            }
+            this.velocity[i * 3] = ((this.position[i * 3] ?? 0) - (this.previous[i * 3] ?? 0)) * invDt;
+            this.velocity[i * 3 + 1] =
+                ((this.position[i * 3 + 1] ?? 0) - (this.previous[i * 3 + 1] ?? 0)) * invDt;
+            this.velocity[i * 3 + 2] =
+                ((this.position[i * 3 + 2] ?? 0) - (this.previous[i * 3 + 2] ?? 0)) * invDt;
+        }
+    }
+    /**
+     * One distance constraint, with its compliance.
+     *
+     * `α = compliance / h²` is what makes the stiffness independent of the step and of the iteration
+     * count. At zero compliance this reduces exactly to an ordinary position-based projection, which
+     * is why an inextensible sheet costs nothing extra.
+     */
+    project(k, invH2) {
+        const a = this.link[k * 2] ?? 0;
+        const b = this.link[k * 2 + 1] ?? 0;
+        const wa = this.invMass[a] ?? 0;
+        const wb = this.invMass[b] ?? 0;
+        const w = wa + wb;
+        if (w === 0)
+            return;
+        const dx = (this.position[b * 3] ?? 0) - (this.position[a * 3] ?? 0);
+        const dy = (this.position[b * 3 + 1] ?? 0) - (this.position[a * 3 + 1] ?? 0);
+        const dz = (this.position[b * 3 + 2] ?? 0) - (this.position[a * 3 + 2] ?? 0);
+        const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (length < 1e-9)
+            return;
+        const c = length - (this.rest[k] ?? 0);
+        const alpha = (this.compliance[k] ?? 0) * invH2;
+        const old = this.lambda[k] ?? 0;
+        const delta = (-c - alpha * old) / (w + alpha);
+        this.lambda[k] = old + delta;
+        const nx = (dx / length) * delta;
+        const ny = (dy / length) * delta;
+        const nz = (dz / length) * delta;
+        this.position[a * 3] = (this.position[a * 3] ?? 0) - nx * wa;
+        this.position[a * 3 + 1] = (this.position[a * 3 + 1] ?? 0) - ny * wa;
+        this.position[a * 3 + 2] = (this.position[a * 3 + 2] ?? 0) - nz * wa;
+        this.position[b * 3] = (this.position[b * 3] ?? 0) + nx * wb;
+        this.position[b * 3 + 1] = (this.position[b * 3 + 1] ?? 0) + ny * wb;
+        this.position[b * 3 + 2] = (this.position[b * 3 + 2] ?? 0) + nz * wb;
+    }
+    /**
+     * Keep the sheet out of itself: a spatial hash over the particles, and a symmetric push apart.
+     *
+     * **The hash is rebuilt every tick and that is the cheap half.** One pass over the particles
+     * writing two integers each, against a structure that tried to be incremental and would have to
+     * know which particles moved — which in a cloth solver is all of them.
+     *
+     * The cell size is the self-collision distance, so a particle's neighbours are in its own cell
+     * and the twenty-six around it. **The 3x3x3 scan is what makes the answer complete**: a pair at
+     * the distance exactly cannot be in cells more than one apart, and a scan of the own cell alone
+     * would miss every pair straddling a boundary — which is most of them, since a folded sheet lies
+     * along one.
+     *
+     * **Each pair is resolved once, by index order.** Visiting both halves would apply the
+     * correction twice and turn a resting fold into a buzzing one; the `other > i` test is what
+     * makes the pass a sweep over pairs rather than over particles.
+     *
+     * A projection rather than a constraint with compliance, unlike the distance links: a contact is
+     * an inequality — it does nothing until it is violated — and XPBD's accumulated multiplier is
+     * for a constraint that holds all tick. *What that gives up* is that the stiffness of a fold is
+     * the iteration count's again, for this one term. *What would make it wrong* is a consumer
+     * wanting a fold to have a measurable resistance, at which point it needs its own multiplier
+     * array and a sign clamp on it.
+     */
+    collideSelf() {
+        const n = this.count;
+        const radius = this.selfDistance;
+        const inverseCell = 1 / radius;
+        this.cellHead.fill(-1);
+        const buckets = this.cellHead.length;
+        for (let i = 0; i < n; i++) {
+            const key = cellKey(Math.floor((this.position[i * 3] ?? 0) * inverseCell), Math.floor((this.position[i * 3 + 1] ?? 0) * inverseCell), Math.floor((this.position[i * 3 + 2] ?? 0) * inverseCell), buckets);
+            this.cellNext[i] = this.cellHead[key] ?? -1;
+            this.cellHead[key] = i;
+        }
+        for (let i = 0; i < n; i++) {
+            const wi = this.invMass[i] ?? 0;
+            const px = this.position[i * 3] ?? 0;
+            const py = this.position[i * 3 + 1] ?? 0;
+            const pz = this.position[i * 3 + 2] ?? 0;
+            const cx = Math.floor(px * inverseCell);
+            const cy = Math.floor(py * inverseCell);
+            const cz = Math.floor(pz * inverseCell);
+            for (let dx = -1; dx <= 1; dx++) {
+                for (let dy = -1; dy <= 1; dy++) {
+                    for (let dz = -1; dz <= 1; dz++) {
+                        let other = this.cellHead[cellKey(cx + dx, cy + dy, cz + dz, buckets)] ?? -1;
+                        while (other >= 0) {
+                            /* Index order, so a pair is met once however many cells they share a bucket with. */
+                            if (other > i && !this.linked(i, other)) {
+                                this.separate(i, other, wi, px, py, pz, radius);
+                            }
+                            other = this.cellNext[other] ?? -1;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /** Whether a link joins these two. A scan over the eight or so a grid particle has. */
+    linked(a, b) {
+        const from = this.neighbourStart[a] ?? 0;
+        const to = this.neighbourStart[a + 1] ?? from;
+        for (let at = from; at < to; at++) {
+            if (this.neighbour[at] === b)
+                return true;
+        }
+        return false;
+    }
+    /** Push two particles apart to exactly `radius`, split by their inverse masses. */
+    separate(a, b, wa, ax, ay, az, radius) {
+        const wb = this.invMass[b] ?? 0;
+        const w = wa + wb;
+        if (w === 0)
+            return;
+        const dx = (this.position[b * 3] ?? 0) - ax;
+        const dy = (this.position[b * 3 + 1] ?? 0) - ay;
+        const dz = (this.position[b * 3 + 2] ?? 0) - az;
+        const squared = dx * dx + dy * dy + dz * dz;
+        if (squared >= radius * radius)
+            return;
+        const length = Math.sqrt(squared);
+        /*
+         * Two particles at exactly the same point have no direction to separate along, and picking one
+         * arbitrarily would pick the same one for every such pair — so a whole collapsed fold would
+         * open along one axis. Left alone instead: the next tick's integration moves them apart, and a
+         * pair genuinely coincident is a sheet that has already failed.
+         */
+        if (length < 1e-9)
+            return;
+        const push = (radius - length) / length / w;
+        const mx = dx * push;
+        const my = dy * push;
+        const mz = dz * push;
+        this.position[a * 3] = ax - mx * wa;
+        this.position[a * 3 + 1] = ay - my * wa;
+        this.position[a * 3 + 2] = az - mz * wa;
+        this.position[b * 3] = (this.position[b * 3] ?? 0) + mx * wb;
+        this.position[b * 3 + 1] = (this.position[b * 3 + 1] ?? 0) + my * wb;
+        this.position[b * 3 + 2] = (this.position[b * 3 + 2] ?? 0) + mz * wb;
+    }
+    /**
+     * Push every particle out of anything it has entered, and hand the body back what it took.
+     *
+     * **The impulse is derived from the correction rather than measured**, which is what makes the
+     * exchange cost one multiply: the constraint solve has already decided where the particle would
+     * be, the push says where it must be instead, and the difference over the tick is the velocity
+     * the collision removed from it. `m·Δ/h` is that momentum, and the body gets its negative at the
+     * point of contact — a push straight down on a plank's end tips the plank, because
+     * `applyImpulse` takes the point.
+     *
+     * A static body is skipped for the impulse rather than for the push: scenery does not move, and
+     * `applyImpulse` would return without doing anything anyway.
+     */
+    collideParticles(world, dt) {
+        const bodies = world.bodies;
+        const exchange = this.coupling > 0 ? (this.particleMass * this.coupling) / dt : 0;
+        for (let i = 0; i < this.count; i++) {
+            if ((this.invMass[i] ?? 0) === 0)
+                continue;
+            const px = this.position[i * 3] ?? 0;
+            const py = this.position[i * 3 + 1] ?? 0;
+            const pz = this.position[i * 3 + 2] ?? 0;
+            for (let b = 0; b < bodies.count; b++) {
+                const shape = bodies.shape[b];
+                if (!shape)
+                    continue;
+                // A cheap reject before anything expensive: the shape's own bounding sphere.
+                const bx = bodies.posX[b] ?? 0;
+                const by = bodies.posY[b] ?? 0;
+                const bz = bodies.posZ[b] ?? 0;
+                const dx = px - bx;
+                const dy = py - by;
+                const dz = pz - bz;
+                const reach = shape.boundRadius + this.thickness;
+                if (dx * dx + dy * dy + dz * dz > reach * reach)
+                    continue;
+                POSE.x = bx;
+                POSE.y = by;
+                POSE.z = bz;
+                POSE.qx = bodies.rotX[b] ?? 0;
+                POSE.qy = bodies.rotY[b] ?? 0;
+                POSE.qz = bodies.rotZ[b] ?? 0;
+                POSE.qw = bodies.rotW[b] ?? 1;
+                if (!pushOut(shape, POSE, px, py, pz, this.thickness, OUT))
+                    continue;
+                this.position[i * 3] = OUT[0];
+                this.position[i * 3 + 1] = OUT[1];
+                this.position[i * 3 + 2] = OUT[2];
+                /*
+                 * The other half of the exchange. Negated, because the push moved the particle *away*
+                 * from the body and the body is what pushed it — Newton's third law with the tick length
+                 * folded in. At the contact point rather than at the centre, so a sheet landing on one end
+                 * of a plank tips it.
+                 */
+                if (exchange > 0 && bodies.type[b] !== BODY_STATIC) {
+                    world.applyImpulse(b, -(OUT[0] - px) * exchange, -(OUT[1] - py) * exchange, -(OUT[2] - pz) * exchange, px, py, pz);
+                }
+                // A static body is scenery, so one push settles it; a moving one is resolved next tick.
+                if (bodies.type[b] === BODY_STATIC)
+                    break;
+            }
+        }
+    }
+}
+/** What a sheet with no self-collision carries instead of four arrays it will never read. */
+const EMPTY_INDEX = new Int32Array(0);
+const POSE = { x: 0, y: 0, z: 0, qx: 0, qy: 0, qz: 0, qw: 1 };
+const OUT = new Float64Array(3);
+const LOCAL = new Float64Array(3);
+const CYLINDER = new Float64Array(11);
+const SURFACE = new Float64Array(7);
+/**
+ * Move a point to the outside of a shape, if it is inside. Returns whether it moved.
+ *
+ * Works in the shape's own frame so a rotated body costs one rotation rather than a transformed
+ * copy of its geometry. A faceless shape is a sphere or a capsule and is handled by its radius; a
+ * polytope is pushed out along its least-penetrating face.
+ */
+function pushOut(shape, pose, px, py, pz, thickness, out) {
+    unrotate(pose, px - pose.x, py - pose.y, pz - pose.z, LOCAL);
+    const lx = LOCAL[0];
+    const ly = LOCAL[1];
+    const lz = LOCAL[2];
+    const faces = faceCount(shape);
+    if (isCylinder(shape)) {
+        /*
+         * A cylinder in its own coordinates, which is where this function already is. `closestOnCylinder`
+         * answers all four regions — beside the side, past a cap, past a rim, inside — so a particle
+         * that has entered near the rim comes out at the rim rather than being pushed through the solid
+         * along whichever of the two surfaces the code happened to test first.
+         */
+        readCylinder(shape, LOCAL_POSE, CYLINDER);
+        closestOnCylinder(CYLINDER, lx, ly, lz, SURFACE);
+        const want = shape.radius + thickness;
+        if (SURFACE[6] >= want)
+            return false;
+        rotate(pose, SURFACE[0] + SURFACE[3] * want, SURFACE[1] + SURFACE[4] * want, SURFACE[2] + SURFACE[5] * want, out);
+        out[0] += pose.x;
+        out[1] += pose.y;
+        out[2] += pose.z;
+        return true;
+    }
+    if (faces === 0) {
+        // The segment the shape is built on, then its radius.
+        const count = shape.vertices.length / 3;
+        const ax = shape.vertices[0] ?? 0;
+        const ay = shape.vertices[1] ?? 0;
+        const az = shape.vertices[2] ?? 0;
+        const bx = count > 1 ? (shape.vertices[3] ?? 0) : ax;
+        const by = count > 1 ? (shape.vertices[4] ?? 0) : ay;
+        const bz = count > 1 ? (shape.vertices[5] ?? 0) : az;
+        const ex = bx - ax;
+        const ey = by - ay;
+        const ez = bz - az;
+        const ee = ex * ex + ey * ey + ez * ez;
+        let t = 0;
+        if (ee > 1e-12) {
+            t = ((lx - ax) * ex + (ly - ay) * ey + (lz - az) * ez) / ee;
+            t = t < 0 ? 0 : t > 1 ? 1 : t;
+        }
+        const cx = ax + ex * t;
+        const cy = ay + ey * t;
+        const cz = az + ez * t;
+        let nx = lx - cx;
+        let ny = ly - cy;
+        let nz = lz - cz;
+        const d = Math.sqrt(nx * nx + ny * ny + nz * nz);
+        const want = shape.radius + thickness;
+        if (d >= want)
+            return false;
+        if (d < 1e-9) {
+            nx = 0;
+            ny = 1;
+            nz = 0;
+        }
+        else {
+            nx /= d;
+            ny /= d;
+            nz /= d;
+        }
+        rotate(pose, cx + nx * want, cy + ny * want, cz + nz * want, out);
+        out[0] += pose.x;
+        out[1] += pose.y;
+        out[2] += pose.z;
+        return true;
+    }
+    let bestFace = 0;
+    let best = -Infinity;
+    for (let f = 0; f < faces; f++) {
+        const d = lx * (shape.facePlanes[f * 4] ?? 0) +
+            ly * (shape.facePlanes[f * 4 + 1] ?? 0) +
+            lz * (shape.facePlanes[f * 4 + 2] ?? 0) -
+            (shape.facePlanes[f * 4 + 3] ?? 0) -
+            shape.radius;
+        if (d > best) {
+            best = d;
+            bestFace = f;
+        }
+    }
+    if (best >= thickness)
+        return false;
+    const move = thickness - best;
+    rotate(pose, lx + (shape.facePlanes[bestFace * 4] ?? 0) * move, ly + (shape.facePlanes[bestFace * 4 + 1] ?? 0) * move, lz + (shape.facePlanes[bestFace * 4 + 2] ?? 0) * move, out);
+    out[0] += pose.x;
+    out[1] += pose.y;
+    out[2] += pose.z;
+    return true;
+}
+function rotate(pose, x, y, z, out) {
+    const tx = 2 * (pose.qy * z - pose.qz * y);
+    const ty = 2 * (pose.qz * x - pose.qx * z);
+    const tz = 2 * (pose.qx * y - pose.qy * x);
+    out[0] = x + pose.qw * tx + (pose.qy * tz - pose.qz * ty);
+    out[1] = y + pose.qw * ty + (pose.qz * tx - pose.qx * tz);
+    out[2] = z + pose.qw * tz + (pose.qx * ty - pose.qy * tx);
+}
+function unrotate(pose, x, y, z, out) {
+    const qx = -pose.qx;
+    const qy = -pose.qy;
+    const qz = -pose.qz;
+    const qw = pose.qw;
+    const tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+    out[0] = x + qw * tx + (qy * tz - qz * ty);
+    out[1] = y + qw * ty + (qz * tx - qx * tz);
+    out[2] = z + qw * tz + (qx * ty - qy * tx);
+}
+/**
+ * Three cell coordinates into one bucket, by the standard three-prime mix.
+ *
+ * The primes are the ones every published spatial hash for particles uses, and the reason to take
+ * them rather than invent three is that a poor choice shows up as a *distribution* rather than as
+ * an error: buckets that fill unevenly, a scan that lengthens, and a sheet that costs more the
+ * further it is from the origin. `>>> 0` before the modulo, because a negative cell coordinate is
+ * ordinary — a sheet hanging below the origin has them — and a negative bucket index would read
+ * `undefined` out of the table and start every chain empty.
+ */
+function cellKey(x, y, z, buckets) {
+    return (((x * 73856093) ^ (y * 19349663) ^ (z * 83492791)) >>> 0) % buckets;
+}
+function distance(p, a, b) {
+    const dx = (p[b * 3] ?? 0) - (p[a * 3] ?? 0);
+    const dy = (p[b * 3 + 1] ?? 0) - (p[a * 3 + 1] ?? 0);
+    const dz = (p[b * 3 + 2] ?? 0) - (p[a * 3 + 2] ?? 0);
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/**
+ * A rectangular sheet: positions, its stretch links, and the bend links across them.
+ *
+ * Bend links skip a particle rather than joining diagonals, because a diagonal resists *shear* and a
+ * skip resists *bowing*, and a sheet that cannot shear drapes like cardboard.
+ *
+ * **A skip-one distance constraint resists curvature and not orientation**, which is worth knowing
+ * before tuning it: three collinear particles satisfy it at any angle, so a flat sheet and a sheet
+ * hanging straight down are equally happy. Measured — a cantilever pinned along one edge settles at
+ * exactly vertical whether the bend compliance is 1e-8 or 1e6. What it *does* buy is 12.5
+ * millimetres less bow on a strip pinned at both ends with slack.
+ *
+ * **What would make it wrong** is a consumer wanting a cloak to stand out from a shoulder, and the
+ * answer then is a dihedral-angle constraint over the two triangles either side of an edge, which
+ * knows a rest angle and therefore knows the difference between flat and folded.
+ */
+export function makeClothGrid(columns, rows, spacing) {
+    const positions = new Float32Array(columns * rows * 3);
+    const links = [];
+    const bend = [];
+    const at = (c, r) => r * columns + c;
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < columns; c++) {
+            const i = at(c, r);
+            positions[i * 3] = c * spacing;
+            positions[i * 3 + 1] = 0;
+            positions[i * 3 + 2] = r * spacing;
+            if (c + 1 < columns)
+                links.push(i, at(c + 1, r));
+            if (r + 1 < rows)
+                links.push(i, at(c, r + 1));
+            // Shear, which a grid needs or it folds flat along a diagonal.
+            if (c + 1 < columns && r + 1 < rows)
+                links.push(i, at(c + 1, r + 1));
+            if (c + 1 < columns && r + 1 < rows)
+                links.push(at(c + 1, r), at(c, r + 1));
+            if (c + 2 < columns)
+                bend.push(i, at(c + 2, r));
+            if (r + 2 < rows)
+                bend.push(i, at(c, r + 2));
+        }
+    }
+    return {
+        positions,
+        links: new Int32Array(links),
+        bendLinks: new Int32Array(bend),
+    };
+}

package/dist/collide/aabb.d.ts

@@ -0,0 +1,10 @@
+/** An axis-aligned box, and the one operation that builds one. */
+export interface Aabb {
+    minX: number;
+    minY: number;
+    minZ: number;
+    maxX: number;
+    maxY: number;
+    maxZ: number;
+}
+export declare function aabbFromCenter(cx: number, cy: number, cz: number, hx: number, hy: number, hz: number): Aabb;

package/dist/collide/aabb.js

@@ -0,0 +1,11 @@
+/** An axis-aligned box, and the one operation that builds one. */
+export function aabbFromCenter(cx, cy, cz, hx, hy, hz) {
+    return {
+        minX: cx - hx,
+        minY: cy - hy,
+        minZ: cz - hz,
+        maxX: cx + hx,
+        maxY: cy + hy,
+        maxZ: cz + hz,
+    };
+}