@driftengine/physics 4.8.3 → 4.8.5

package/dist/skinnedClothSetup.d.ts

@@ -0,0 +1,160 @@
+/**
+ * What a skinned cloth is made from: particles, their limits, the constraints between them and the
+ * numbers the solver runs at — plain arrays, so a port decoding a middleware's cooked data hands it
+ * over as it decoded it, and the GPU solver uploads the same arrays the CPU one reads.
+ *
+ * **Skinned** because its anchor is a skeleton rather than a world: a kinematic particle (inverse
+ * mass 0) is placed by its joint influences every step, and every limit is measured from where
+ * skinning would put a particle. `ClothBody` is the other kind — a sheet in a physics world — and
+ * stays that.
+ *
+ * Validated at construction and refused by name: a cloth whose arrays disagree in length would read
+ * past an end on the GPU, where nothing says so.
+ */
+/** Distance constraints: two particles, a rest length, a compliance (metres per newton). */
+export interface DistanceConstraints {
+    /** Two particle indices a constraint. */
+    readonly pairs: Uint32Array;
+    readonly rest: Float32Array;
+    readonly compliance: Float32Array;
+    /**
+     * Graph-colour batches, as offsets into the constraints: batch `b` is constraints
+     * `batches[b]` to `batches[b + 1]`, none of which moves a particle another in the batch moves.
+     * Absent, the solver colours them itself. Given, they are checked and refused if they overlap.
+     */
+    readonly batches?: Uint32Array;
+}
+/** Dihedral bending: four particles — the shared edge, then each triangle's far corner. */
+export interface BendingConstraints {
+    readonly quads: Uint32Array;
+    /** The angle between the two triangles' normals at rest, in radians: π is flat. */
+    readonly rest: Float32Array;
+    readonly compliance: Float32Array;
+    readonly batches?: Uint32Array;
+}
+/** Long-range attachments: a particle may be no further than a length from a kinematic anchor. */
+export interface TetherConstraints {
+    readonly particles: Uint32Array;
+    readonly anchors: Uint32Array;
+    readonly lengths: Float32Array;
+}
+/**
+ * Where a particle may not go, measured from where skinning puts it. Each optional, one entry a
+ * particle (two for a stop), and `Infinity` is none — which is how cooked data says it.
+ */
+export interface ClothLimits {
+    /** Metres from the skinned position a particle may not leave: a sphere around it. */
+    readonly maxDistance?: Float32Array;
+    /** A distance and a radius a particle: a sphere behind the skinned position, along its normal. */
+    readonly backstop?: Float32Array;
+    /** The same in front. */
+    readonly frontstop?: Float32Array;
+    /** Metres a particle keeps from a collider's surface. */
+    readonly thickness?: Float32Array;
+    /**
+     * Which particles collide with each other, one flag each. **Accepted and not yet simulated**: a
+     * garment held by its colliders and its backstops does not need it to look right, and the GPU
+     * solver has no neighbour search yet. Carried so a set-up need not be rewritten when it arrives.
+     */
+    readonly selfCollision?: Uint8Array;
+}
+/**
+ * A collider on a joint: a sphere, or a tapered capsule along its frame's +Z.
+ *
+ * Its frame is in the joint's own space, so it rides the joint whatever the animation does.
+ */
+export interface ClothCollider {
+    readonly joint: number;
+    readonly radius: number;
+    /** The radius at the far end; the same as `radius` where absent. */
+    readonly radius2?: number;
+    /** Metres along the frame's +Z; zero or absent is a sphere. */
+    readonly length?: number;
+    /** Sixteen floats, column-major, in the joint's space; identity where absent. */
+    readonly frame?: Float32Array;
+}
+/** What the solver runs at. Every field has a default; the defaults are a garment's, not a sheet's. */
+export interface SkinnedClothParameters {
+    /** The fixed step, in seconds. The solver runs whole steps whatever the frame. Default 1/60. */
+    readonly step?: number;
+    /** Substeps a step. Default 1. */
+    readonly substeps?: number;
+    /** Constraint passes a substep. Default 4. */
+    readonly iterations?: number;
+    /** Metres a second squared, world space. Default [0, −9.81, 0]. */
+    readonly gravity?: readonly [number, number, number];
+    /**
+     * The log of the velocity kept after a second: `ln 0.25` keeps a quarter. Zero is none; it is
+     * applied as `exp(damping · h)` a substep, so it means one thing at every step length.
+     */
+    readonly damping?: number;
+    /** The same, of the velocity relative to the wind: how fast the air takes the cloth with it. */
+    readonly drag?: number;
+    /**
+     * Metres a second, world space: the air the cloth starts in. Default still air. A garment in a
+     * scene follows the scene's wind a frame at a time, through `setWind`.
+     */
+    readonly wind?: readonly [number, number, number];
+    /**
+     * How much of the character's own movement and turning the cloth keeps as its own, 0 to 1: 1 is
+     * simulated wholly in the world, so a dash leaves the hem behind; 0 moves it with the character.
+     * Default 1.
+     */
+    readonly linearInertia?: number;
+    readonly angularInertia?: number;
+    /** Scales every max distance, for a garment worn looser or tighter than cooked. Default 1. */
+    readonly maxDistanceScale?: number;
+    /** Metres added to every collider's radius, beyond a particle's own thickness. Default 0. */
+    readonly margin?: number;
+    /** A move of the character's origin past this, between two poses, resets the cloth. Default none. */
+    readonly teleportDistance?: number;
+    /** A turn past this many radians between two poses resets it too. Default none. */
+    readonly teleportAngle?: number;
+    /** Steps run at once when the cloth is reset, so it starts hanging rather than falling. */
+    readonly settleSteps?: number;
+    /** Steps over which a reset cloth blends from its skinned pose into its simulation. */
+    readonly blendSteps?: number;
+}
+/** Everything a skinned cloth is made from. */
+export interface SkinnedClothSetup {
+    /** Rest positions, three floats a particle, in the space the skinning starts from. */
+    readonly positions: Float32Array;
+    /** One a particle: zero is kinematic, following its skinned position exactly. */
+    readonly inverseMass: Float32Array;
+    readonly distance: DistanceConstraints;
+    readonly bending?: BendingConstraints;
+    readonly tethers?: TetherConstraints;
+    readonly parameters: SkinnedClothParameters;
+    /** Rest normals, three floats a particle: what a backstop and a frontstop are measured along. */
+    readonly normals?: Float32Array;
+    /** Up to eight joint influences a particle, as `MeshData` carries them. Absent: not skinned. */
+    readonly joints?: Float32Array;
+    readonly weights?: Float32Array;
+    readonly joints2?: Float32Array;
+    readonly weights2?: Float32Array;
+    /** Sixteen floats a joint: each joint's inverse bind matrix, column-major. */
+    readonly inverseBind?: Float32Array;
+    readonly limits?: ClothLimits;
+    readonly colliders?: readonly ClothCollider[];
+}
+/** The parameters with every default filled in. */
+export interface ResolvedClothParameters {
+    readonly step: number;
+    readonly substeps: number;
+    readonly iterations: number;
+    readonly gravity: readonly [number, number, number];
+    readonly damping: number;
+    readonly drag: number;
+    readonly wind: readonly [number, number, number];
+    readonly linearInertia: number;
+    readonly angularInertia: number;
+    readonly maxDistanceScale: number;
+    readonly margin: number;
+    readonly teleportDistance: number;
+    readonly teleportAngle: number;
+    readonly settleSteps: number;
+    readonly blendSteps: number;
+}
+export declare function resolveClothParameters(parameters: SkinnedClothParameters): ResolvedClothParameters;
+/** Refuse a set-up whose arrays disagree, naming the array and both lengths. */
+export declare function validateClothSetup(setup: SkinnedClothSetup): void;

package/dist/skinnedClothSetup.js

@@ -0,0 +1,120 @@
+/**
+ * What a skinned cloth is made from: particles, their limits, the constraints between them and the
+ * numbers the solver runs at — plain arrays, so a port decoding a middleware's cooked data hands it
+ * over as it decoded it, and the GPU solver uploads the same arrays the CPU one reads.
+ *
+ * **Skinned** because its anchor is a skeleton rather than a world: a kinematic particle (inverse
+ * mass 0) is placed by its joint influences every step, and every limit is measured from where
+ * skinning would put a particle. `ClothBody` is the other kind — a sheet in a physics world — and
+ * stays that.
+ *
+ * Validated at construction and refused by name: a cloth whose arrays disagree in length would read
+ * past an end on the GPU, where nothing says so.
+ */
+export function resolveClothParameters(parameters) {
+    return {
+        step: parameters.step ?? 1 / 60,
+        substeps: Math.max(1, Math.floor(parameters.substeps ?? 1)),
+        iterations: Math.max(1, Math.floor(parameters.iterations ?? 4)),
+        gravity: parameters.gravity ?? [0, -9.81, 0],
+        damping: parameters.damping ?? 0,
+        drag: parameters.drag ?? 0,
+        wind: parameters.wind ?? [0, 0, 0],
+        linearInertia: Math.min(1, Math.max(0, parameters.linearInertia ?? 1)),
+        angularInertia: Math.min(1, Math.max(0, parameters.angularInertia ?? 1)),
+        maxDistanceScale: parameters.maxDistanceScale ?? 1,
+        margin: parameters.margin ?? 0,
+        teleportDistance: parameters.teleportDistance ?? Infinity,
+        teleportAngle: parameters.teleportAngle ?? Infinity,
+        settleSteps: Math.max(0, Math.floor(parameters.settleSteps ?? 0)),
+        blendSteps: Math.max(0, Math.floor(parameters.blendSteps ?? 0)),
+    };
+}
+/** Refuse a set-up whose arrays disagree, naming the array and both lengths. */
+export function validateClothSetup(setup) {
+    const count = setup.positions.length / 3;
+    const fail = (what) => {
+        throw new Error(`skinned cloth: ${what}`);
+    };
+    if (!Number.isInteger(count) || count === 0) {
+        fail(`positions hold ${setup.positions.length} floats, which is not a whole number of particles`);
+    }
+    if (setup.inverseMass.length !== count) {
+        fail(`inverseMass has ${setup.inverseMass.length} entries for ${count} particles`);
+    }
+    const indices = (name, values, arity, constraints) => {
+        if (values.length !== constraints * arity) {
+            fail(`${name} has ${values.length} indices for ${constraints} constraints of ${arity}`);
+        }
+        for (let i = 0; i < values.length; i++) {
+            if (values[i] >= count)
+                fail(`${name}[${i}] names particle ${values[i]} of ${count}`);
+        }
+    };
+    const { distance, bending, tethers, parameters } = setup;
+    const links = distance.rest.length;
+    if (distance.compliance.length !== links)
+        fail(`distance compliance has ${distance.compliance.length} for ${links}`);
+    indices('distance.pairs', distance.pairs, 2, links);
+    if (bending !== undefined) {
+        const quads = bending.rest.length;
+        if (bending.compliance.length !== quads)
+            fail(`bending compliance has ${bending.compliance.length} for ${quads}`);
+        indices('bending.quads', bending.quads, 4, quads);
+    }
+    if (tethers !== undefined) {
+        const n = tethers.lengths.length;
+        indices('tethers.particles', tethers.particles, 1, n);
+        indices('tethers.anchors', tethers.anchors, 1, n);
+        for (let i = 0; i < n; i++) {
+            if (setup.inverseMass[tethers.anchors[i]] !== 0) {
+                fail(`tether ${i} is anchored to particle ${tethers.anchors[i]}, which is not kinematic`);
+            }
+        }
+    }
+    const step = parameters.step ?? 1 / 60;
+    if (!(step > 0))
+        fail(`a step of ${step} seconds`);
+    const per = (name, values, width) => {
+        if (values !== undefined && values.length !== count * width) {
+            fail(`${name} has ${values.length} entries for ${count} particles of ${width}`);
+        }
+    };
+    per('normals', setup.normals, 3);
+    per('joints', setup.joints, 4);
+    per('weights', setup.weights, 4);
+    per('joints2', setup.joints2, 4);
+    per('weights2', setup.weights2, 4);
+    per('limits.maxDistance', setup.limits?.maxDistance, 1);
+    per('limits.backstop', setup.limits?.backstop, 2);
+    per('limits.frontstop', setup.limits?.frontstop, 2);
+    per('limits.thickness', setup.limits?.thickness, 1);
+    per('limits.selfCollision', setup.limits?.selfCollision, 1);
+    if ((setup.joints === undefined) !== (setup.weights === undefined))
+        fail('joints without weights, or weights without joints');
+    if ((setup.joints2 === undefined) !== (setup.weights2 === undefined))
+        fail('joints2 without weights2, or the reverse');
+    if (setup.joints2 !== undefined && setup.joints === undefined)
+        fail('a second set of influences without the first');
+    const bones = (setup.inverseBind?.length ?? 0) / 16;
+    if (!Number.isInteger(bones))
+        fail(`inverseBind holds ${setup.inverseBind?.length} floats, not a whole number of matrices`);
+    if (setup.joints !== undefined && bones === 0)
+        fail('joints without inverseBind matrices to skin them by');
+    for (const set of [setup.joints, setup.joints2]) {
+        if (set === undefined)
+            continue;
+        for (let i = 0; i < set.length; i++) {
+            if (set[i] >= bones)
+                fail(`a particle names joint ${set[i]} of ${bones}`);
+        }
+    }
+    (setup.colliders ?? []).forEach((collider, k) => {
+        if (collider.joint >= bones)
+            fail(`collider ${k} is on joint ${collider.joint} of ${bones}`);
+        if (!(collider.radius > 0))
+            fail(`collider ${k} has radius ${collider.radius}`);
+        if (collider.frame !== undefined && collider.frame.length !== 16)
+            fail(`collider ${k}'s frame is not sixteen floats`);
+    });
+}

package/dist/skinnedClothSolve.d.ts

@@ -0,0 +1,22 @@
+/** A particle's predicted position: damping and drag, then gravity, then a substep of travel. */
+export declare function predictParticles(position: Float32Array, previous: Float32Array, velocity: Float32Array, inverseMass: Float32Array, h: number, keep: number, dragKeep: number, gravity: readonly [number, number, number], wind: readonly [number, number, number]): void;
+/** Distance constraints `order[from]` to `order[to]`, one batch. */
+export declare function solveDistanceBatch(position: Float32Array, inverseMass: Float32Array, pairs: Uint32Array, rest: Float32Array, compliance: Float32Array, lambda: Float32Array, order: Uint32Array, from: number, to: number, invH2: number): void;
+/**
+ * Dihedral bending constraints of one batch: Müller et al.'s position-based bending constraint, the
+ * angle between the two triangles' normals held at its rest value (π is flat).
+ *
+ * The constraint is `acos(n1 · n2) − rest`, whose gradient is the paper's `q` vectors over
+ * `sin θ`: **the paper's `q` are the negative of the derivative of `n1 · n2`**, measured against a
+ * finite difference at every component, which is why its update carries a minus sign where a reader
+ * taking `q` for the derivative would put a plus — and why a first version here folded a hinge
+ * further instead of unfolding it. **Divided rather than multiplied through**, because near flat the `q` vectors vanish
+ * with `sin θ` and their ratio stays finite: the paper's own form, `sin θ · q`, slows to nothing just
+ * where a garment spends its time. A configuration within a millionth of flat or of folded shut is
+ * left for the next iteration rather than divided by.
+ */
+export declare function solveBendingBatch(position: Float32Array, inverseMass: Float32Array, quads: Uint32Array, rest: Float32Array, compliance: Float32Array, lambda: Float32Array, order: Uint32Array, from: number, to: number, invH2: number): void;
+/** Tethers: a particle further than its length from its kinematic anchor is brought back to it. */
+export declare function solveTethers(position: Float32Array, particles: Uint32Array, anchors: Uint32Array, lengths: Float32Array): void;
+/** Velocities from where the substep moved each free particle. */
+export declare function finishParticles(position: Float32Array, previous: Float32Array, velocity: Float32Array, inverseMass: Float32Array, invH: number): void;

package/dist/skinnedClothSolve.js

@@ -0,0 +1,230 @@
+/**
+ * The skinned cloth's kernels: one substep's prediction, each kind of constraint over one batch, and
+ * the velocities a substep leaves.
+ *
+ * **Plain functions over flat arrays, one per GPU dispatch.** The WebGPU solver runs the same steps
+ * as compute passes over the same arrays, and its WGSL is written to be read beside this file: a
+ * kernel here is a thread's body there, the batch loop is the dispatch. Keeping them that shape is
+ * what lets the device parity check compare like with like.
+ *
+ * **XPBD throughout**: a constraint's compliance becomes `α = compliance / h²`, and its multiplier
+ * accumulates over the substep's iterations, so stiffness is a property of the cloth rather than of
+ * how many times it was iterated — §7 of the physics design, as `cloth.ts` states it.
+ *
+ * Allocation-free: every kernel writes into arrays it is handed.
+ */
+import { exactAcos } from './exact.js';
+/** A particle's predicted position: damping and drag, then gravity, then a substep of travel. */
+export function predictParticles(position, previous, velocity, inverseMass, h, keep, dragKeep, gravity, wind) {
+    const count = inverseMass.length;
+    for (let i = 0; i < count; i++) {
+        const at = i * 3;
+        previous[at] = position[at];
+        previous[at + 1] = position[at + 1];
+        previous[at + 2] = position[at + 2];
+        if (inverseMass[i] === 0)
+            continue;
+        for (let c = 0; c < 3; c++) {
+            const air = wind[c];
+            const v = air + (velocity[at + c] * keep - air) * dragKeep + gravity[c] * h;
+            velocity[at + c] = v;
+            position[at + c] = position[at + c] + v * h;
+        }
+    }
+}
+/** Distance constraints `order[from]` to `order[to]`, one batch. */
+export function solveDistanceBatch(position, inverseMass, pairs, rest, compliance, lambda, order, from, to, invH2) {
+    for (let n = from; n < to; n++) {
+        const k = order[n];
+        const a = pairs[k * 2];
+        const b = pairs[k * 2 + 1];
+        const wa = inverseMass[a];
+        const wb = inverseMass[b];
+        const w = wa + wb;
+        if (w === 0)
+            continue;
+        const dx = position[b * 3] - position[a * 3];
+        const dy = position[b * 3 + 1] - position[a * 3 + 1];
+        const dz = position[b * 3 + 2] - position[a * 3 + 2];
+        const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (length < 1e-9)
+            continue;
+        const alpha = compliance[k] * invH2;
+        const old = lambda[k];
+        const delta = (-(length - rest[k]) - alpha * old) / (w + alpha);
+        lambda[k] = old + delta;
+        const s = delta / length;
+        position[a * 3] = position[a * 3] - dx * s * wa;
+        position[a * 3 + 1] = position[a * 3 + 1] - dy * s * wa;
+        position[a * 3 + 2] = position[a * 3 + 2] - dz * s * wa;
+        position[b * 3] = position[b * 3] + dx * s * wb;
+        position[b * 3 + 1] = position[b * 3 + 1] + dy * s * wb;
+        position[b * 3 + 2] = position[b * 3 + 2] + dz * s * wb;
+    }
+}
+/* Scratch for one bending constraint: relative positions, normals and the four gradients. */
+const E = new Float64Array(3);
+const P3 = new Float64Array(3);
+const P4 = new Float64Array(3);
+const N1 = new Float64Array(3);
+const N2 = new Float64Array(3);
+const Q = new Float64Array(12);
+const W = new Float64Array(4);
+const IDS = new Uint32Array(4);
+/** A vector's length, through `Math.sqrt`, which every engine rounds the same. */
+function length3(v) {
+    const x = v[0];
+    const y = v[1];
+    const z = v[2];
+    return Math.sqrt(x * x + y * y + z * z);
+}
+function cross(a, b, out, at = 0) {
+    out[at] = a[1] * b[2] - a[2] * b[1];
+    out[at + 1] = a[2] * b[0] - a[0] * b[2];
+    out[at + 2] = a[0] * b[1] - a[1] * b[0];
+}
+/**
+ * Dihedral bending constraints of one batch: Müller et al.'s position-based bending constraint, the
+ * angle between the two triangles' normals held at its rest value (π is flat).
+ *
+ * The constraint is `acos(n1 · n2) − rest`, whose gradient is the paper's `q` vectors over
+ * `sin θ`: **the paper's `q` are the negative of the derivative of `n1 · n2`**, measured against a
+ * finite difference at every component, which is why its update carries a minus sign where a reader
+ * taking `q` for the derivative would put a plus — and why a first version here folded a hinge
+ * further instead of unfolding it. **Divided rather than multiplied through**, because near flat the `q` vectors vanish
+ * with `sin θ` and their ratio stays finite: the paper's own form, `sin θ · q`, slows to nothing just
+ * where a garment spends its time. A configuration within a millionth of flat or of folded shut is
+ * left for the next iteration rather than divided by.
+ */
+export function solveBendingBatch(position, inverseMass, quads, rest, compliance, lambda, order, from, to, invH2) {
+    for (let n = from; n < to; n++) {
+        const k = order[n];
+        const i1 = quads[k * 4];
+        const i2 = quads[k * 4 + 1];
+        const i3 = quads[k * 4 + 2];
+        const i4 = quads[k * 4 + 3];
+        const w1 = inverseMass[i1];
+        const w2 = inverseMass[i2];
+        const w3 = inverseMass[i3];
+        const w4 = inverseMass[i4];
+        if (w1 + w2 + w3 + w4 === 0)
+            continue;
+        for (let c = 0; c < 3; c++) {
+            const origin = position[i1 * 3 + c];
+            E[c] = position[i2 * 3 + c] - origin;
+            P3[c] = position[i3 * 3 + c] - origin;
+            P4[c] = position[i4 * 3 + c] - origin;
+        }
+        cross(E, P3, N1);
+        cross(E, P4, N2);
+        const l1 = length3(N1);
+        const l2 = length3(N2);
+        if (l1 < 1e-12 || l2 < 1e-12)
+            continue;
+        for (let c = 0; c < 3; c++) {
+            N1[c] = N1[c] / l1;
+            N2[c] = N2[c] / l2;
+        }
+        let d = N1[0] * N2[0] + N1[1] * N2[1];
+        d += N1[2] * N2[2];
+        d = Math.min(1, Math.max(-1, d));
+        const sine = Math.sqrt(1 - d * d);
+        if (sine < 1e-6)
+            continue;
+        /* q3 = (e × n2 + (n1 × e) d) / |e × p3|, q4 = (e × n1 + (n2 × e) d) / |e × p4|. */
+        crossInto(E, N2, N1, E, d, l1, Q, 6);
+        crossInto(E, N1, N2, E, d, l2, Q, 9);
+        /* q2 = −(p3 × n2 + (n1 × p3) d) / |e × p3| − (p4 × n1 + (n2 × p4) d) / |e × p4|. */
+        crossInto(P3, N2, N1, P3, d, l1, Q, 3);
+        const a0 = Q[3];
+        const a1 = Q[4];
+        const a2 = Q[5];
+        crossInto(P4, N1, N2, P4, d, l2, Q, 3);
+        Q[3] = -(a0 + Q[3]);
+        Q[4] = -(a1 + Q[4]);
+        Q[5] = -(a2 + Q[5]);
+        for (let c = 0; c < 3; c++) {
+            Q[c] = -(Q[3 + c] + Q[6 + c] + Q[9 + c]);
+        }
+        /* The gradient of acos(d) is q / sin θ (q being −∂d/∂p); its weighted squared length. */
+        const weights = W;
+        weights[0] = w1;
+        weights[1] = w2;
+        weights[2] = w3;
+        weights[3] = w4;
+        let sum = 0;
+        for (let j = 0; j < 4; j++) {
+            const qx = Q[j * 3];
+            const qy = Q[j * 3 + 1];
+            const qz = Q[j * 3 + 2];
+            sum += weights[j] * (qx * qx + qy * qy + qz * qz);
+        }
+        sum /= sine * sine;
+        if (sum < 1e-12)
+            continue;
+        const alpha = compliance[k] * invH2;
+        const old = lambda[k];
+        const delta = (-(exactAcos(d) - rest[k]) - alpha * old) / (sum + alpha);
+        lambda[k] = old + delta;
+        const scale = delta / sine;
+        const ids = IDS;
+        ids[0] = i1;
+        ids[1] = i2;
+        ids[2] = i3;
+        ids[3] = i4;
+        for (let j = 0; j < 4; j++) {
+            const w = weights[j];
+            if (w === 0)
+                continue;
+            const p = ids[j] * 3;
+            position[p] = position[p] + w * scale * Q[j * 3];
+            position[p + 1] = position[p + 1] + w * scale * Q[j * 3 + 1];
+            position[p + 2] = position[p + 2] + w * scale * Q[j * 3 + 2];
+        }
+    }
+}
+/** `(a × b + (c × e) · d) / length` into `out` at `at`. */
+function crossInto(a, b, c, e, d, length, out, at) {
+    const x1 = a[1] * b[2] - a[2] * b[1];
+    const y1 = a[2] * b[0] - a[0] * b[2];
+    const z1 = a[0] * b[1] - a[1] * b[0];
+    const x2 = c[1] * e[2] - c[2] * e[1];
+    const y2 = c[2] * e[0] - c[0] * e[2];
+    const z2 = c[0] * e[1] - c[1] * e[0];
+    out[at] = (x1 + x2 * d) / length;
+    out[at + 1] = (y1 + y2 * d) / length;
+    out[at + 2] = (z1 + z2 * d) / length;
+}
+/** Tethers: a particle further than its length from its kinematic anchor is brought back to it. */
+export function solveTethers(position, particles, anchors, lengths) {
+    for (let k = 0; k < lengths.length; k++) {
+        const p = particles[k] * 3;
+        const a = anchors[k] * 3;
+        const dx = position[p] - position[a];
+        const dy = position[p + 1] - position[a + 1];
+        const dz = position[p + 2] - position[a + 2];
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        const length = lengths[k];
+        if (distance <= length || distance < 1e-9)
+            continue;
+        const s = length / distance;
+        position[p] = position[a] + dx * s;
+        position[p + 1] = position[a + 1] + dy * s;
+        position[p + 2] = position[a + 2] + dz * s;
+    }
+}
+/** Velocities from where the substep moved each free particle. */
+export function finishParticles(position, previous, velocity, inverseMass, invH) {
+    for (let i = 0; i < inverseMass.length; i++) {
+        const at = i * 3;
+        if (inverseMass[i] === 0) {
+            velocity[at] = 0;
+            velocity[at + 1] = 0;
+            velocity[at + 2] = 0;
+            continue;
+        }
+        velocity[at] = (position[at] - previous[at]) * invH;
+        velocity[at + 1] = (position[at + 1] - previous[at + 1]) * invH;
+        velocity[at + 2] = (position[at + 2] - previous[at + 2]) * invH;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/physics",
-  "version": "4.8.3",
+  "version": "4.8.5",
   "description": "Collision shapes, spatial queries and swept kinematic collision",
   "license": "Apache-2.0",
   "type": "module",

package/src/clothBatches.ts

@@ -0,0 +1,115 @@
+/**
+ * Graph-colour batches: constraints grouped so that no batch moves a particle twice.
+ *
+ * **What makes a batch parallel.** Every constraint in a batch reads and writes particles no other
+ * constraint in it writes, so the batch can be solved in any order — one GPU thread a constraint —
+ * and give the answer it gives in sequence. The batches themselves still run one after another,
+ * which keeps the solve a Gauss–Seidel one: each batch sees what the last one moved.
+ *
+ * **A kinematic particle may be shared freely.** Nothing writes it, so two constraints holding the
+ * same pinned particle cannot race; colouring around it would only add batches.
+ *
+ * Greedy, in the order the constraints are given: each takes the first colour none of its moving
+ * particles has yet. Not the fewest colours there are, which is a hard problem; a chain gets two and
+ * a triangle mesh's edges about six to nine, which is what a solver colouring cooked data gets too.
+ */
+
+/** Constraints reordered by colour, and where each colour's run starts. */
+export interface ClothBatches {
+  /** Constraint indices, batch by batch. */
+  readonly order: Uint32Array;
+  /** Offsets into `order`: batch `b` is `order[batches[b]]` up to `order[batches[b + 1]]`. */
+  readonly batches: Uint32Array;
+}
+
+/** Colour `indices`, `arity` particles a constraint, around the particles `inverseMass` pins. */
+export function colourConstraints(
+  indices: Uint32Array,
+  arity: number,
+  inverseMass: Float32Array,
+): ClothBatches {
+  const constraints = indices.length / arity;
+  const colour = new Int32Array(constraints);
+  /* For each particle, a bit set of the colours already holding it, grown as colours are added. */
+  const used: Set<number>[] = [];
+  let colours = 0;
+  for (let k = 0; k < constraints; k++) {
+    let chosen = 0;
+    for (; ; chosen++) {
+      let free = true;
+      for (let j = 0; j < arity && free; j++) {
+        const p = indices[k * arity + j] as number;
+        if ((inverseMass[p] as number) === 0) continue;
+        if (used[p]?.has(chosen) === true) free = false;
+      }
+      if (free) break;
+    }
+    colour[k] = chosen;
+    colours = Math.max(colours, chosen + 1);
+    for (let j = 0; j < arity; j++) {
+      const p = indices[k * arity + j] as number;
+      if ((inverseMass[p] as number) === 0) continue;
+      (used[p] ??= new Set()).add(chosen);
+    }
+  }
+  const batches = new Uint32Array(colours + 1);
+  for (let k = 0; k < constraints; k++) batches[(colour[k] as number) + 1]++;
+  for (let c = 0; c < colours; c++)
+    batches[c + 1] = (batches[c + 1] as number) + (batches[c] as number);
+  const cursor = batches.slice(0, colours);
+  const order = new Uint32Array(constraints);
+  for (let k = 0; k < constraints; k++) order[cursor[colour[k] as number]++] = k;
+  return { order, batches };
+}
+
+/**
+ * Given batches, checked: they cover every constraint once, in order, and none moves a particle
+ * twice. Refused by name, because an overlap is a race on the GPU and a wrong answer nowhere else.
+ */
+export function givenBatches(
+  name: string,
+  indices: Uint32Array,
+  arity: number,
+  inverseMass: Float32Array,
+  batches: Uint32Array,
+): ClothBatches {
+  const constraints = indices.length / arity;
+  if (batches[0] !== 0 || batches[batches.length - 1] !== constraints) {
+    throw new Error(
+      `skinned cloth: ${name} batches run from ${batches[0]} to ${batches[batches.length - 1]}, ` +
+        `and must cover constraints 0 to ${constraints}`,
+    );
+  }
+  const seen = new Int32Array(inverseMass.length).fill(-1);
+  for (let b = 0; b + 1 < batches.length; b++) {
+    for (let k = batches[b] as number; k < (batches[b + 1] as number); k++) {
+      for (let j = 0; j < arity; j++) {
+        const p = indices[k * arity + j] as number;
+        if ((inverseMass[p] as number) === 0) continue;
+        if (seen[p] === b) {
+          throw new Error(
+            `skinned cloth: ${name} batch ${b} moves particle ${p} twice, so it cannot run in parallel`,
+          );
+        }
+        seen[p] = b;
+      }
+    }
+  }
+  return { order: Uint32Array.from({ length: constraints }, (_, k) => k), batches };
+}
+
+/**
+ * A kind of constraint's batches: the set-up's own, checked, where it gives them, and coloured here
+ * where it does not. One decision for both solvers, which must batch a garment the same way.
+ */
+export function batchesOf(
+  name: string,
+  indices: Uint32Array,
+  arity: number,
+  inverseMass: Float32Array,
+  given: Uint32Array | undefined,
+): ClothBatches {
+  return given === undefined
+    ? colourConstraints(indices, arity, inverseMass)
+    : givenBatches(name, indices, arity, inverseMass, given);
+}