@driftengine/physics 4.8.2 → 4.8.4

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.2",
+  "version": "4.8.4",
   "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);
+}

package/src/clothControl.ts

@@ -0,0 +1,131 @@
+/**
+ * When a skinned cloth steps: its poses, whole fixed steps, the reset a teleport forces, the steps
+ * a reset settles and the blend back into the simulation after it — apart from what a step does to
+ * the particles, which a `ClothDevice` owns.
+ *
+ * **Apart so that two solvers take one decision.** `SkinnedCloth` here moves particles in arrays on
+ * the CPU; `@driftengine/core` moves them in buffers on a GPU. Both are driven by this, so a frame
+ * runs the same steps at the same fractions on either, a teleport resets both at the same pose, and
+ * a blend reaches the simulation over the same steps — which is what lets the device parity check
+ * compare positions rather than schedules.
+ *
+ * **What it gives up**: a device sees a step as a fraction and a blend share, not as the arrays it
+ * came from, so a device that wanted a different schedule — substeps chosen per frame, say — would
+ * have to grow this rather than decide it alone.
+ */
+import { jumped } from './clothPose.ts';
+import { ClothTargets } from './clothTargets.ts';
+import { resolveClothParameters } from './skinnedClothSetup.ts';
+import type { ResolvedClothParameters, SkinnedClothSetup } from './skinnedClothSetup.ts';
+
+/** What moves a skinned cloth's particles: the CPU's arrays, or a GPU's buffers. */
+export interface ClothDevice {
+  /**
+   * The targets changed what they hold — took a pose, settled on it, or consumed the one a frame
+   * stepped toward. A device that keeps its own copy of the skinned positions follows here.
+   */
+  targetsChanged(change: 'posed' | 'settled' | 'consumed'): void;
+  /** Every particle at its latest skinned position, at rest, its step start with it. */
+  rest(): void;
+  /**
+   * One fixed step, `fraction` of the way from the last pose to the latest. `blend` is the share of
+   * the simulation kept against the skinned pose after it, or 0 for no blend at all — not 1, which
+   * is a real last step of a blend and is applied.
+   */
+  step(fraction: number, blend: number): void;
+}
+
+/** A skinned cloth's schedule, over one device. */
+export class ClothControl {
+  readonly parameters: ResolvedClothParameters;
+  readonly targets: ClothTargets;
+  private accumulator = 0;
+  /** Steps left in the blend from the skinned pose after a reset. */
+  private blendLeft = 0;
+
+  /**
+   * `particlesOnCpu` false leaves the skinned particle positions to the device: the targets keep
+   * the model matrices, the skin matrices and the colliders, which is all a GPU needs from them.
+   */
+  constructor(
+    setup: SkinnedClothSetup,
+    private readonly device: ClothDevice,
+    particlesOnCpu = true,
+  ) {
+    this.parameters = resolveClothParameters(setup.parameters);
+    this.targets = new ClothTargets(setup, particlesOnCpu);
+  }
+
+  /**
+   * The skeleton's pose for the steps to come: each joint's global matrix, model space, sixteen
+   * floats a joint, and the model matrix. The first pose, and one past the teleport thresholds,
+   * resets the cloth to it; any other is reached across the steps of the next `advance`.
+   */
+  setPose(globals: Float32Array, model: Float32Array): void {
+    const { teleportDistance, teleportAngle } = this.parameters;
+    const first = !this.targets.posed;
+    const jump = !first && jumped(this.targets.model, model, teleportDistance, teleportAngle);
+    this.targets.pose(globals, model);
+    this.device.targetsChanged('posed');
+    if (first || jump) this.reset();
+  }
+
+  /**
+   * Every particle at its skinned position, at rest; then the set-up's settle steps at once, and its
+   * blend steps from the skinned pose into the simulation over the steps that follow.
+   */
+  reset(): void {
+    this.targets.settle();
+    this.device.targetsChanged('settled');
+    this.device.rest();
+    this.accumulator = 0;
+    this.blendLeft = 0;
+    for (let s = 0; s < this.parameters.settleSteps; s++) this.stepAt(1);
+    this.blendLeft = this.parameters.blendSteps;
+  }
+
+  /**
+   * Advance by `dt` seconds of the caller's time, in whole fixed steps; how many ran. The remainder
+   * is kept for the next call, and `alpha` says how far into the next step it reaches.
+   */
+  advance(dt: number): number {
+    this.accumulator += dt;
+    const step = this.parameters.step;
+    /* A millionth of a step of slack, so 1/30 is two steps of 1/60 and not one and a remainder. */
+    const steps = Math.floor((this.accumulator + step * 1e-6) / step);
+    for (let k = 0; k < steps; k++) {
+      this.accumulator -= step;
+      this.stepAt((k + 1) / steps);
+    }
+    if (steps > 0) this.consume();
+    if (this.accumulator < 0) this.accumulator = 0;
+    return steps;
+  }
+
+  /** How far the time handed to `advance` reaches into the next step, 0 to 1. */
+  get alpha(): number {
+    return Math.min(1, this.accumulator / this.parameters.step);
+  }
+
+  /** One fixed step, all the way to the latest pose: for a caller in the engine's fixed-step loop. */
+  step(): void {
+    this.stepAt(1);
+    this.consume();
+  }
+
+  private consume(): void {
+    this.targets.consume();
+    this.device.targetsChanged('consumed');
+  }
+
+  /** The targets moved to `fraction`, the share a blend keeps, then the device's step. */
+  private stepAt(fraction: number): void {
+    this.targets.at(fraction);
+    let blend = 0;
+    if (this.blendLeft > 0) {
+      blend = (this.parameters.blendSteps - this.blendLeft + 1) / this.parameters.blendSteps;
+      this.blendLeft--;
+    }
+    this.device.step(fraction, blend);
+  }
+}

package/src/clothLimits.ts

@@ -0,0 +1,133 @@
+/**
+ * Where a skinned cloth's particles may not go: the limits measured from each particle's skinned
+ * position, and the colliders its skeleton carries.
+ *
+ * **Projections, not constraints with compliance.** A limit is a statement about the body — a
+ * garment does not pass through the hip it is cut for — so a particle past one is put back on its
+ * surface, at once and wholly. Applied after the constraint iterations of every substep, so a stiff
+ * garment pulling a particle into the body loses.
+ *
+ * Allocation-free, and each function a kernel the GPU solver mirrors.
+ */
+
+/** A particle further than `maxDistance[i] · scale` from its skinned position is put back on that sphere. */
+export function applyMaxDistance(
+  position: Float32Array,
+  inverseMass: Float32Array,
+  target: Float32Array,
+  maxDistance: Float32Array,
+  scale: number,
+): void {
+  for (let i = 0; i < inverseMass.length; i++) {
+    if ((inverseMass[i] as number) === 0) continue;
+    const limit = (maxDistance[i] as number) * scale;
+    if (!(limit < Infinity)) continue;
+    const at = i * 3;
+    const dx = (position[at] as number) - (target[at] as number);
+    const dy = (position[at + 1] as number) - (target[at + 1] as number);
+    const dz = (position[at + 2] as number) - (target[at + 2] as number);
+    const d2 = dx * dx + dy * dy + dz * dz;
+    if (d2 <= limit * limit) continue;
+    const s = limit / Math.sqrt(d2);
+    position[at] = (target[at] as number) + dx * s;
+    position[at + 1] = (target[at + 1] as number) + dy * s;
+    position[at + 2] = (target[at + 2] as number) + dz * s;
+  }
+}
+
+/**
+ * A sphere the particle may not enter, on one side of its skinned position: behind it along the
+ * skinned normal for a backstop (`side` −1), in front for a frontstop (`side` +1). `stops` holds a
+ * distance and a radius a particle; the centre is `distance + radius` from the skinned position,
+ * so the sphere's near surface is `distance` from it. An infinite distance is no stop.
+ */
+export function applyStops(
+  position: Float32Array,
+  inverseMass: Float32Array,
+  target: Float32Array,
+  normal: Float32Array,
+  stops: Float32Array,
+  side: number,
+): void {
+  for (let i = 0; i < inverseMass.length; i++) {
+    if ((inverseMass[i] as number) === 0) continue;
+    const distance = stops[i * 2] as number;
+    const radius = stops[i * 2 + 1] as number;
+    if (!(distance < Infinity) || !(radius > 0)) continue;
+    const at = i * 3;
+    const reach = (distance + radius) * side;
+    const cx = (target[at] as number) + (normal[at] as number) * reach;
+    const cy = (target[at + 1] as number) + (normal[at + 1] as number) * reach;
+    const cz = (target[at + 2] as number) + (normal[at + 2] as number) * reach;
+    pushOut(position, at, cx, cy, cz, radius);
+  }
+}
+
+/** Put the point at `at` on the sphere's surface if it is inside. A point at the centre stays. */
+function pushOut(
+  position: Float32Array,
+  at: number,
+  cx: number,
+  cy: number,
+  cz: number,
+  radius: number,
+): void {
+  const dx = (position[at] as number) - cx;
+  const dy = (position[at + 1] as number) - cy;
+  const dz = (position[at + 2] as number) - cz;
+  const d2 = dx * dx + dy * dy + dz * dz;
+  if (d2 >= radius * radius || d2 < 1e-18) return;
+  const s = radius / Math.sqrt(d2);
+  position[at] = cx + dx * s;
+  position[at + 1] = cy + dy * s;
+  position[at + 2] = cz + dz * s;
+}
+
+/**
+ * Every particle out of every collider: a sphere, or a tapered capsule from `ends[k·6]` to
+ * `ends[k·6+3]` whose radius runs from `radii[k·2]` to `radii[k·2+1]` — plus the particle's
+ * thickness and the cloth's margin.
+ *
+ * **A tapered capsule is pushed out from the nearest point on its axis**, at the radius interpolated
+ * there. That is the usual approximation of a cone-swept sphere and what character cloth solvers
+ * ship: exact where the two radii are equal, and where they differ it puts a particle a little off
+ * the true surface on the narrowing side — by a fraction of the taper over the capsule's length,
+ * which for a limb is millimetres. What would make it wrong is a collider tapering steeply over a
+ * short length, a cone more than a limb; the exact distance to a swept sphere is the fix then.
+ */
+export function applyColliders(
+  position: Float32Array,
+  inverseMass: Float32Array,
+  thickness: Float32Array | null,
+  margin: number,
+  ends: Float32Array,
+  radii: Float32Array,
+  colliders: number,
+): void {
+  for (let i = 0; i < inverseMass.length; i++) {
+    if ((inverseMass[i] as number) === 0) continue;
+    const at = i * 3;
+    const pad = (thickness === null ? 0 : (thickness[i] as number)) + margin;
+    for (let k = 0; k < colliders; k++) {
+      const ax = ends[k * 6] as number;
+      const ay = ends[k * 6 + 1] as number;
+      const az = ends[k * 6 + 2] as number;
+      const ex = (ends[k * 6 + 3] as number) - ax;
+      const ey = (ends[k * 6 + 4] as number) - ay;
+      const ez = (ends[k * 6 + 5] as number) - az;
+      const e2 = ex * ex + ey * ey + ez * ez;
+      let t = 0;
+      if (e2 > 1e-18) {
+        t =
+          (((position[at] as number) - ax) * ex +
+            ((position[at + 1] as number) - ay) * ey +
+            ((position[at + 2] as number) - az) * ez) /
+          e2;
+        t = Math.min(1, Math.max(0, t));
+      }
+      const r0 = radii[k * 2] as number;
+      const r1 = radii[k * 2 + 1] as number;
+      pushOut(position, at, ax + ex * t, ay + ey * t, az + ez * t, r0 + (r1 - r0) * t + pad);
+    }
+  }
+}