@driftengine/physics 4.8.3 → 4.8.4

package/dist/exact.js

@@ -0,0 +1,331 @@
+/**
+ * Transcendentals that give the same bits on every JavaScript engine.
+ *
+ * **Not more accurate than `Math`, and that is not what they are for.** These are within a couple
+ * of units in the last place of correctly rounded, which is about what a platform `sin` gives you.
+ * What they are is *reproducible*: ECMAScript declines to specify `sin`, `cos`, `exp`, `acos` and
+ * eighteen more, so two engines may differ by an ulp, and an ulp is enough to make two peers running
+ * the same simulation disagree — first invisibly, then completely.
+ *
+ * **In physics rather than core since 4.8.4**: a skinned cloth's damping needs `exp` and its bending
+ * `acos`, the simulation set may not call the platform's, and physics imports no other package. Core
+ * re-exports physics wholesale, so `exactExp` from `@driftengine/core` is the same function.
+ *
+ * `scripts/determinism.mjs` is the gate that refuses the unspecified ones inside the simulation set
+ * and names the twenty-two. Its header carries the other half of the argument: `+ - * /` are IEEE
+ * 754 operations by specification, JavaScript permits no fused-multiply-add contraction, and
+ * `Math.sqrt` is required correctly rounded and is *not* on that list. **So everything below uses
+ * only those five operations**, which is the whole design: reproducibility by construction rather
+ * than by hoping two engines chose the same algorithm.
+ *
+ * ---
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * `exactSin`, `exactCos`, `exactExp`, `exactAcos` and `exactLog`. Five, because five is what the
+ * engine and its first consumer actually reach for: the terrain binding's slope angle needs `acos`,
+ * a lockstep fixture rotating anything needs `sin` and `cos`, exponential decay needs `exp`, and a
+ * detector's box prior is a logit of the patch grid, which needs `log`.
+ *
+ * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
+ * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
+ * a quaternion component against a half-angle's sine. *Reversed by* a site that genuinely needs a
+ * signed angle from two components, at which point it arrives with its own golden vectors.
+ *
+ * ## Nothing in core imports these
+ *
+ * Deliberately. `core-only` is the one size figure in this repository that every consumer pays, and
+ * a module reachable from `createRenderer` is in it whether anybody calls it or not. These are
+ * reached by the script bindings and by consumers who ask for them, so tree-shaking keeps them out
+ * of a bundle that does not, which is measured rather than assumed.
+ *
+ * ## The coefficients
+ *
+ * The polynomial and rational coefficients are fdlibm's, which is the ancestor of most platform
+ * libms and is public domain. They are written as literals: **a literal is the same number on
+ * every engine, which is the only property being bought.** Their provenance matters less than their
+ * fixity — a coefficient somebody re-derived to one more digit is a different function, and
+ * `exact.test.ts`'s golden bit patterns are what would catch that.
+ */
+/*
+ * π/2 in four pieces, most significant first, so a large multiple of it can be removed without
+ * losing the small remainder in the subtraction.
+ *
+ * **Two pieces are not enough and the measurement says so**: at an angle of 740 radians a two-part
+ * reduction leaves `sin` and `cos` 18.5 ulps out, because `k * PIO2_1` needs more than 53 bits once
+ * `k` grows. Three brings it under two ulps for the cost of two multiplies.
+ *
+ * **`PIO2_TAIL` and `PIO2_TAIL_LO` are one number in two halves, not two successive corrections.**
+ * fdlibm carries a fourth constant, `pio2_1t`, which is the tail for its *single*-iteration path;
+ * `pio2_2` is the same tail rounded differently, with `pio2_2t` as its own tail, and the two paths
+ * are alternatives. Refining the first with the second is not more accurate, it is wrong: it
+ * subtracts the tail twice and took `sin` to 2.2e11 ulps out, which is how this comment came to be
+ * here.
+ */
+const PIO2_1 = 1.5707963267341256;
+const PIO2_TAIL = 6.077100506303966e-11;
+const PIO2_TAIL_LO = 2.0222662487959506e-21;
+const TWO_OVER_PI = 0.6366197723675814;
+const HALF_PI = 1.5707963267948966;
+const PI = 3.141592653589793;
+/* fdlibm's `__kernel_sin` coefficients. */
+const S1 = -1.6666666666666632e-1;
+const S2 = 8.33333333332249e-3;
+const S3 = -1.984126982985795e-4;
+const S4 = 2.7557313707070068e-6;
+const S5 = -2.5050760253406863e-8;
+const S6 = 1.5896909952115501e-10;
+/* fdlibm's `__kernel_cos` coefficients. */
+const C1 = 4.1666666666666602e-2;
+const C2 = -1.388888888887411e-3;
+const C3 = 2.480158728947673e-5;
+const C4 = -2.7557314351390663e-7;
+const C5 = 2.0875723212981748e-9;
+const C6 = -1.1359647557788195e-11;
+/* fdlibm's `asin` rational, numerator then denominator. */
+const P0 = 1.6666666666666666e-1;
+const P1 = -3.2556581862240092e-1;
+const P2 = 2.0121253213486293e-1;
+const P3 = -4.0055534500679411e-2;
+const P4 = 7.9153499428981453e-4;
+const P5 = 3.4793310759602117e-5;
+const Q1 = -2.4033949117344142;
+const Q2 = 2.0209457602335057;
+const Q3 = -6.8828397160545329e-1;
+const Q4 = 7.7038150555901935e-2;
+/** ln 2, split for the same reason π/2 is. */
+const LN2_HI = 0.6931471803691238;
+const LN2_LO = 1.9082149292705877e-10;
+const ONE_OVER_LN2 = 1.4426950408889634;
+/** 2^(2^i), for i = 0 to 9. Every one is exact, so a product of them is exact. */
+const POW2 = [
+    2, 4, 16, 256, 65536, 4294967296, 1.8446744073709552e19, 3.402823669209385e38,
+    1.157920892373162e77, 1.3407807929942597e154,
+];
+/**
+ * Two to an integer power, by binary decomposition of the exponent.
+ *
+ * Multiplication by a power of two is exact in IEEE 754, so this is exact wherever it does not
+ * overflow — which is what makes it a legitimate substitute for the `Math.pow` a range reduction
+ * would otherwise reach for.
+ *
+ * A large negative exponent lands on zero instead of a subnormal, because the reciprocal is taken
+ * after the product overflows. That is `exp` underflowing to zero, which is where it was going.
+ */
+function pow2(exponent) {
+    let remaining = exponent < 0 ? -exponent : exponent;
+    let result = 1;
+    let index = 0;
+    while (remaining > 0 && index < POW2.length) {
+        if ((remaining & 1) === 1)
+            result *= POW2[index];
+        remaining >>= 1;
+        index += 1;
+    }
+    return exponent < 0 ? 1 / result : result;
+}
+/** sin on [-π/4, π/4]. */
+function sinKernel(x) {
+    const z = x * x;
+    const poly = S1 + z * (S2 + z * (S3 + z * (S4 + z * (S5 + z * S6))));
+    return x + x * z * poly;
+}
+/** cos on [-π/4, π/4]. */
+function cosKernel(x) {
+    const z = x * x;
+    const poly = C1 + z * (C2 + z * (C3 + z * (C4 + z * (C5 + z * C6))));
+    return 1 - 0.5 * z + z * z * poly;
+}
+/**
+ * Fold an angle into [-π/4, π/4] and say which quadrant it came from.
+ *
+ * Cody-Waite: the multiple of π/2 is removed in pieces, so the subtraction that produces a small
+ * remainder from two large numbers does not lose the bits it is supposed to keep. One-piece
+ * reduction is accurate to about 1e-8 at an angle of a thousand radians, which for a simulation
+ * that accumulates rotation is the difference between an object facing forward and facing sideways
+ * after a few minutes.
+ */
+function reduce(x) {
+    const k = Math.round(x * TWO_OVER_PI);
+    /* The leading piece, whose product with `k` is exact for every `k` a simulation reaches. */
+    const head = x - k * PIO2_1;
+    /*
+     * The tail, in two halves. `head - tail` loses the bits below its own last place, and
+     * `PIO2_TAIL_LO - (head - r - tail)` is exactly those bits recovered — the same
+     * subtract-and-recover fdlibm uses on its two-iteration path.
+     */
+    const tail = k * PIO2_TAIL;
+    let r = head - tail;
+    const lost = k * PIO2_TAIL_LO - (head - r - tail);
+    r = r - lost;
+    return { r, quadrant: ((k % 4) + 4) % 4 };
+}
+/** `Math.sin`, reproducibly. NaN in, NaN out; an infinity answers NaN, as `Math.sin` does. */
+export function exactSin(x) {
+    if (!Number.isFinite(x))
+        return Number.NaN;
+    const { r, quadrant } = reduce(x);
+    switch (quadrant) {
+        case 0:
+            return sinKernel(r);
+        case 1:
+            return cosKernel(r);
+        case 2:
+            return -sinKernel(r);
+        default:
+            return -cosKernel(r);
+    }
+}
+/** `Math.cos`, reproducibly. */
+export function exactCos(x) {
+    if (!Number.isFinite(x))
+        return Number.NaN;
+    const { r, quadrant } = reduce(x);
+    switch (quadrant) {
+        case 0:
+            return cosKernel(r);
+        case 1:
+            return -sinKernel(r);
+        case 2:
+            return -cosKernel(r);
+        default:
+            return sinKernel(r);
+    }
+}
+/**
+ * `Math.exp`, reproducibly.
+ *
+ * Reduce by a multiple of ln 2 into [-ln2/2, ln2/2], sum the Taylor series there, and scale by a
+ * power of two. **A degree-14 series and not a shorter minimax**, because on that interval the
+ * fifteenth term is about 4e-20 — below the precision of a double — so the series is exact to the
+ * representation and there is nothing a fitted polynomial would buy.
+ */
+export function exactExp(x) {
+    if (Number.isNaN(x))
+        return Number.NaN;
+    if (x === Number.POSITIVE_INFINITY)
+        return Number.POSITIVE_INFINITY;
+    if (x === Number.NEGATIVE_INFINITY)
+        return 0;
+    if (x > 709.782712893384)
+        return Number.POSITIVE_INFINITY;
+    if (x < -745.1332191019411)
+        return 0;
+    const k = Math.round(x * ONE_OVER_LN2);
+    const r = x - k * LN2_HI - k * LN2_LO;
+    /* Horner over 1/n!, highest term first. */
+    let sum = 1 / 87178291200; // 1/14!
+    sum = 1 / 6227020800 + r * sum; // 1/13!
+    sum = 1 / 479001600 + r * sum; // 1/12!
+    sum = 1 / 39916800 + r * sum; // 1/11!
+    sum = 1 / 3628800 + r * sum; // 1/10!
+    sum = 1 / 362880 + r * sum; // 1/9!
+    sum = 1 / 40320 + r * sum; // 1/8!
+    sum = 1 / 5040 + r * sum; // 1/7!
+    sum = 1 / 720 + r * sum; // 1/6!
+    sum = 1 / 120 + r * sum; // 1/5!
+    sum = 1 / 24 + r * sum; // 1/4!
+    sum = 1 / 6 + r * sum; // 1/3!
+    sum = 0.5 + r * sum;
+    sum = 1 + r * sum;
+    sum = 1 + r * sum;
+    return sum * pow2(k);
+}
+/* fdlibm's `log` polynomial in s², for log(1 + f) around f = 0 by way of s = f / (2 + f). */
+const LG1 = 6.66666666666673513e-1;
+const LG2 = 3.999999999940941908e-1;
+const LG3 = 2.857142874366239149e-1;
+const LG4 = 2.222219843214978396e-1;
+const LG5 = 1.818357216161805012e-1;
+const LG6 = 1.531383769920937332e-1;
+const LG7 = 1.479819860511658591e-1;
+const TWO54 = 1.8014398509481984e16;
+const SMALLEST_NORMAL = 2.2250738585072014e-308;
+/* A double's two words, for reading and setting an exponent; one view, reused. */
+const words = new DataView(new ArrayBuffer(8));
+/**
+ * `Math.log`, reproducibly: fdlibm's algorithm, which is also V8's.
+ *
+ * Take the power of two out as `k` and leave a significand in [√2/2, √2), so that `f = m - 1` is
+ * small either side of zero; then log(1 + f) = f - f²/2 + s·(f²/2 + R(s²)) with s = f/(2 + f), and
+ * `k·ln 2` added back in two parts so the large part loses nothing. The exponent is read and the
+ * significand rescaled through the double's own words — integer operations, not transcendentals.
+ */
+export function exactLog(x) {
+    if (Number.isNaN(x) || x < 0)
+        return Number.NaN;
+    if (x === 0)
+        return Number.NEGATIVE_INFINITY;
+    if (x === Number.POSITIVE_INFINITY)
+        return x;
+    let k = 0;
+    let value = x;
+    if (value < SMALLEST_NORMAL) {
+        k = -54;
+        value *= TWO54;
+    }
+    words.setFloat64(0, value);
+    let hx = words.getUint32(0);
+    k += (hx >>> 20) - 1023;
+    hx &= 0x000fffff;
+    /* Keep the significand at or above √2/2: past √2, halve it and count one more power of two. */
+    const i = (hx + 0x95f64) & 0x100000;
+    words.setUint32(0, hx | (i ^ 0x3ff00000));
+    k += i >>> 20;
+    const f = words.getFloat64(0) - 1;
+    if ((0x000fffff & (2 + hx)) < 3) {
+        /* |f| < 2^-20: two terms of the series are the whole answer. */
+        if (f === 0)
+            return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
+        const r = f * f * (0.5 - 0.3333333333333333 * f);
+        return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
+    }
+    const s = f / (2 + f);
+    const z = s * s;
+    const w = z * z;
+    const t1 = w * (LG2 + w * (LG4 + w * LG6));
+    const t2 = z * (LG1 + w * (LG3 + w * (LG5 + w * LG7)));
+    const r = t2 + t1;
+    /* Far enough from one that f²/2 is worth carrying apart from f. */
+    if (((hx - 0x6147a) | (0x6b851 - hx)) > 0) {
+        const half = 0.5 * f * f;
+        return k === 0
+            ? f - (half - s * (half + r))
+            : k * LN2_HI - (half - (s * (half + r) + k * LN2_LO) - f);
+    }
+    return k === 0 ? f - s * (f - r) : k * LN2_HI - (s * (f - r) - k * LN2_LO - f);
+}
+/** fdlibm's `asin` rational on `z = x²`, valid where `z` is small. */
+function asinRational(z) {
+    const numerator = z * (P0 + z * (P1 + z * (P2 + z * (P3 + z * (P4 + z * P5)))));
+    const denominator = 1 + z * (Q1 + z * (Q2 + z * (Q3 + z * Q4)));
+    return numerator / denominator;
+}
+/**
+ * `Math.acos`, reproducibly. Outside [-1, 1] this answers NaN, as `Math.acos` does.
+ *
+ * Three branches rather than one, and the split at ±0.5 is the reason it is accurate near the ends:
+ * `acos` has infinite derivative at ±1, so a polynomial in `x` loses its footing there. Substituting
+ * `s = sqrt((1 ∓ x)/2)` moves the awkward point to zero, where a polynomial is comfortable — which
+ * is also why `sqrt` being exactly rounded matters here rather than being a convenience.
+ */
+export function exactAcos(x) {
+    if (Number.isNaN(x) || x > 1 || x < -1)
+        return Number.NaN;
+    if (x === 1)
+        return 0;
+    if (x === -1)
+        return PI;
+    if (x >= 0.5) {
+        const z = (1 - x) / 2;
+        const s = Math.sqrt(z);
+        return 2 * (s + s * asinRational(z));
+    }
+    if (x <= -0.5) {
+        const z = (1 + x) / 2;
+        const s = Math.sqrt(z);
+        return PI - 2 * (s + s * asinRational(z));
+    }
+    const z = x * x;
+    return HALF_PI - (x + x * asinRational(z));
+}

package/dist/index.d.ts

@@ -58,6 +58,15 @@ export type { EscapeResult, EscapeVeto, StallEscapeOptions, StallInput } from '.
 export { ESCAPE_EASED, ESCAPE_IDLE, ESCAPE_PUSHED, ESCAPE_SEALED, StallEscape, } from './stallEscape.ts';
 export type { ClothOptions } from './cloth.ts';
 export { ClothBody, makeClothGrid } from './cloth.ts';
+export { SkinnedCloth } from './skinnedCloth.ts';
+export { ClothControl } from './clothControl.ts';
+export type { ClothDevice } from './clothControl.ts';
+export type { ClothTargets } from './clothTargets.ts';
+export { validateClothSetup } from './skinnedClothSetup.ts';
+export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './exact.ts';
+export { batchesOf, colourConstraints } from './clothBatches.ts';
+export type { ClothBatches } from './clothBatches.ts';
+export type { BendingConstraints, ClothCollider, ClothLimits, DistanceConstraints, ResolvedClothParameters, SkinnedClothParameters, SkinnedClothSetup, TetherConstraints, } from './skinnedClothSetup.ts';
 export type { Collider, ColliderBytes, ColliderGroup } from './colliderSet.ts';
 export { ColliderSet, boxCollider, colliderFromShape } from './colliderSet.ts';
 export { fingerprintBodies, fingerprintColliders } from './fingerprint.ts';

package/dist/index.js

@@ -23,6 +23,25 @@ export { accelerateAlong } from './groundMotor.js';
 export { applyBuoyancy, createBuoyancy } from './buoyancy.js';
 export { ESCAPE_EASED, ESCAPE_IDLE, ESCAPE_PUSHED, ESCAPE_SEALED, StallEscape, } from './stallEscape.js';
 export { ClothBody, makeClothGrid } from './cloth.js';
+/*
+ * Cloth anchored to a skeleton rather than a world: a garment. The CPU solver is the reference and
+ * runs under WebGL2 and in Node; `@driftengine/core` runs the same kernels on WebGPU.
+ */
+export { SkinnedCloth } from './skinnedCloth.js';
+/*
+ * The schedule both solvers share — poses, whole steps, resets and the blend — and the device
+ * interface the GPU solver implements, with what it reads: the targets' matrices and colliders,
+ * and the set-up checked and batched exactly as the CPU solver checks and batches it.
+ */
+export { ClothControl } from './clothControl.js';
+export { validateClothSetup } from './skinnedClothSetup.js';
+/*
+ * Transcendentals that give the same bits on every engine. Here rather than in core since 4.8.4,
+ * because the simulation needs them and this package imports nothing; core re-exports them with
+ * the rest of physics.
+ */
+export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './exact.js';
+export { batchesOf, colourConstraints } from './clothBatches.js';
 export { ColliderSet, boxCollider, colliderFromShape } from './colliderSet.js';
 export { fingerprintBodies, fingerprintColliders } from './fingerprint.js';
 export { combineMassProperties, createMassProperties, shapeMassProperties } from './mass.js';

package/dist/skinnedCloth.d.ts

@@ -0,0 +1,63 @@
+import type { ResolvedClothParameters, SkinnedClothSetup } from './skinnedClothSetup.ts';
+/**
+ * A garment's particles, constraints and solver state, stepped at the set-up's fixed step. Read
+ * `positions` after a step, or `interpolate` between the last two for a frame's `alpha`. The
+ * schedule — poses, steps, resets, the blend — is `ClothControl`'s; this is its CPU device.
+ */
+export declare class SkinnedCloth {
+    /** How many particles. */
+    readonly count: number;
+    /** Where each particle is now, three floats a particle. */
+    readonly positions: Float32Array;
+    /** Metres a second, three floats a particle. */
+    readonly velocities: Float32Array;
+    readonly inverseMass: Float32Array;
+    /** The parameters with their defaults filled in. */
+    readonly parameters: ResolvedClothParameters;
+    /** Where each particle was when the last step began, for drawing on `alpha`. */
+    private readonly stepStart;
+    /** Where each particle was when the current substep began, for its velocity. */
+    private readonly substepStart;
+    private readonly distance;
+    private readonly bending;
+    private readonly tethers;
+    private readonly control;
+    private readonly targets;
+    private readonly limits;
+    private readonly colliders;
+    /** The air the cloth drags toward, metres a second: the set-up's until `setWind` says otherwise. */
+    private readonly wind;
+    constructor(setup: SkinnedClothSetup);
+    /**
+     * The air the steps to come drag the cloth toward, world space, metres a second: the frame's
+     * sample of the scene's one wind, so a garment moves with the smoke and the grass rather than
+     * with a second wind of its own. See `AGENTS.md`, "One wind, sampled once".
+     */
+    setWind(x: number, y: number, z: number): void;
+    /** See `ClothControl.setPose`. */
+    setPose(globals: Float32Array, model: Float32Array): void;
+    /** See `ClothControl.reset`. */
+    reset(): void;
+    /** See `ClothControl.advance`. */
+    advance(dt: number): number;
+    /** How far the time handed to `advance` reaches into the next step, 0 to 1. */
+    get alpha(): number;
+    /** Each particle between the start and the end of the last step, at `alpha`, into `out`. */
+    interpolate(alpha: number, out: Float32Array): void;
+    /** One fixed step, all the way to the latest pose: for a caller in the engine's fixed-step loop. */
+    step(): void;
+    /** Every particle at its latest skinned position, at rest. */
+    private rest;
+    /**
+     * One fixed step, `fraction` of the way from the last pose to the latest: carried by the share of
+     * the character's motion it does not keep, its kinematic particles placed, then its substeps —
+     * each predicted, constrained, limited and turned into velocities.
+     */
+    private stepAt;
+    /** The limits and the colliders, after the constraints, so a garment pulling into the body loses. */
+    private limit;
+    /** After a reset, the share of the simulation drawn grows from nothing to all over the blend. */
+    private blend;
+    /** Every batch of one kind, in colour order. */
+    private solve;
+}

package/dist/skinnedCloth.js

@@ -0,0 +1,214 @@
+/**
+ * A skinned cloth on the CPU: the reference solver, and the one WebGL2 and Node run.
+ *
+ * **Whole fixed steps, whatever the frame.** The set-up names its step (a garment's is 1/60); a
+ * caller in the engine's own fixed-step loop calls `step` once a tick, and any other calls `advance`
+ * with the frame's time and the remainder waits for the next frame. The cloth therefore behaves the
+ * same at 60, 120 and 144 frames a second, and a frame draws it on `alpha` between its last two
+ * steps — the engine's rule, and what keeps a high refresh rate from drawing the same cloth twice.
+ *
+ * **What it gives up**: an `advance` of a long time runs that many steps, with no ceiling; a caller
+ * that stalls for a second gets a second of cloth. The engine's loop clamps its own catch-up, and a
+ * caller outside it is expected to clamp the time it hands over.
+ *
+ * Every step allocates nothing. The WebGPU solver in `@driftengine/core` runs the same kernels over
+ * the same data (`skinnedClothSolve.ts`, `clothLimits.ts`) under the same `ClothControl`, and is held
+ * to this one by a parity check on the device.
+ */
+import { batchesOf } from './clothBatches.js';
+import { ClothControl } from './clothControl.js';
+import { applyColliders, applyMaxDistance, applyStops } from './clothLimits.js';
+import { carryParticles } from './clothPose.js';
+import { exactExp } from './exact.js';
+import { finishParticles, predictParticles, solveBendingBatch, solveDistanceBatch, solveTethers, } from './skinnedClothSolve.js';
+import { validateClothSetup } from './skinnedClothSetup.js';
+function solvable(name, indices, arity, rest, compliance, inverseMass, given) {
+    const batches = batchesOf(name, indices, arity, inverseMass, given);
+    return { indices, rest, compliance, lambda: new Float32Array(rest.length), batches };
+}
+/**
+ * A garment's particles, constraints and solver state, stepped at the set-up's fixed step. Read
+ * `positions` after a step, or `interpolate` between the last two for a frame's `alpha`. The
+ * schedule — poses, steps, resets, the blend — is `ClothControl`'s; this is its CPU device.
+ */
+export class SkinnedCloth {
+    /** How many particles. */
+    count;
+    /** Where each particle is now, three floats a particle. */
+    positions;
+    /** Metres a second, three floats a particle. */
+    velocities;
+    inverseMass;
+    /** The parameters with their defaults filled in. */
+    parameters;
+    /** Where each particle was when the last step began, for drawing on `alpha`. */
+    stepStart;
+    /** Where each particle was when the current substep began, for its velocity. */
+    substepStart;
+    distance;
+    bending;
+    tethers;
+    control;
+    targets;
+    limits;
+    colliders;
+    /** The air the cloth drags toward, metres a second: the set-up's until `setWind` says otherwise. */
+    wind;
+    constructor(setup) {
+        validateClothSetup(setup);
+        this.count = setup.positions.length / 3;
+        this.positions = new Float32Array(setup.positions);
+        this.velocities = new Float32Array(setup.positions.length);
+        this.stepStart = new Float32Array(setup.positions);
+        this.substepStart = new Float32Array(setup.positions.length);
+        this.inverseMass = new Float32Array(setup.inverseMass);
+        const { distance, bending } = setup;
+        this.distance = solvable('distance', distance.pairs, 2, distance.rest, distance.compliance, this.inverseMass, distance.batches);
+        this.bending =
+            bending === undefined
+                ? null
+                : solvable('bending', bending.quads, 4, bending.rest, bending.compliance, this.inverseMass, bending.batches);
+        this.tethers = setup.tethers ?? null;
+        this.limits = setup.limits ?? {};
+        this.colliders = setup.colliders?.length ?? 0;
+        /* Made once, so a step builds nothing: the control calls back into the private step. */
+        const device = {
+            targetsChanged: () => { },
+            rest: () => {
+                this.rest();
+            },
+            step: (fraction, blend) => {
+                this.stepAt(fraction, blend);
+            },
+        };
+        this.control = new ClothControl(setup, device);
+        this.parameters = this.control.parameters;
+        this.targets = this.control.targets;
+        this.wind = [...this.parameters.wind];
+    }
+    /**
+     * The air the steps to come drag the cloth toward, world space, metres a second: the frame's
+     * sample of the scene's one wind, so a garment moves with the smoke and the grass rather than
+     * with a second wind of its own. See `AGENTS.md`, "One wind, sampled once".
+     */
+    setWind(x, y, z) {
+        this.wind[0] = x;
+        this.wind[1] = y;
+        this.wind[2] = z;
+    }
+    /** See `ClothControl.setPose`. */
+    setPose(globals, model) {
+        this.control.setPose(globals, model);
+    }
+    /** See `ClothControl.reset`. */
+    reset() {
+        this.control.reset();
+    }
+    /** See `ClothControl.advance`. */
+    advance(dt) {
+        return this.control.advance(dt);
+    }
+    /** How far the time handed to `advance` reaches into the next step, 0 to 1. */
+    get alpha() {
+        return this.control.alpha;
+    }
+    /** Each particle between the start and the end of the last step, at `alpha`, into `out`. */
+    interpolate(alpha, out) {
+        const from = this.stepStart;
+        const to = this.positions;
+        for (let i = 0; i < to.length; i++) {
+            const a = from[i];
+            out[i] = a + (to[i] - a) * alpha;
+        }
+    }
+    /** One fixed step, all the way to the latest pose: for a caller in the engine's fixed-step loop. */
+    step() {
+        this.control.step();
+    }
+    /** Every particle at its latest skinned position, at rest. */
+    rest() {
+        this.positions.set(this.targets.latest);
+        this.stepStart.set(this.positions);
+        this.velocities.fill(0);
+    }
+    /**
+     * One fixed step, `fraction` of the way from the last pose to the latest: carried by the share of
+     * the character's motion it does not keep, its kinematic particles placed, then its substeps —
+     * each predicted, constrained, limited and turned into velocities.
+     */
+    stepAt(fraction, blend) {
+        /* Where the last step ended, kinematic particles included, before this one moves anything. */
+        this.stepStart.set(this.positions);
+        const { step, substeps, iterations, damping, drag, gravity } = this.parameters;
+        const wind = this.wind;
+        const targets = this.targets;
+        carryParticles(this.positions, this.velocities, this.inverseMass, targets.modelBefore, targets.modelNow, this.parameters.linearInertia, this.parameters.angularInertia);
+        placeKinematic(this.positions, this.inverseMass, targets.position);
+        const h = step / substeps;
+        const invH = 1 / h;
+        const invH2 = invH * invH;
+        const keep = exactExp(damping * h);
+        const dragKeep = exactExp(drag * h);
+        for (let s = 0; s < substeps; s++) {
+            predictParticles(this.positions, this.substepStart, this.velocities, this.inverseMass, h, keep, dragKeep, gravity, wind);
+            this.distance.lambda.fill(0);
+            this.bending?.lambda.fill(0);
+            for (let pass = 0; pass < iterations; pass++) {
+                this.solve(this.distance, solveDistanceBatch, invH2);
+                if (this.bending !== null)
+                    this.solve(this.bending, solveBendingBatch, invH2);
+                const tethers = this.tethers;
+                if (tethers !== null) {
+                    solveTethers(this.positions, tethers.particles, tethers.anchors, tethers.lengths);
+                }
+            }
+            this.limit();
+            finishParticles(this.positions, this.substepStart, this.velocities, this.inverseMass, invH);
+        }
+        if (blend > 0)
+            this.blend(blend);
+    }
+    /** The limits and the colliders, after the constraints, so a garment pulling into the body loses. */
+    limit() {
+        const { positions, inverseMass, targets, limits } = this;
+        const { maxDistanceScale, margin } = this.parameters;
+        if (limits.maxDistance !== undefined) {
+            applyMaxDistance(positions, inverseMass, targets.position, limits.maxDistance, maxDistanceScale);
+        }
+        if (limits.backstop !== undefined) {
+            applyStops(positions, inverseMass, targets.position, targets.normal, limits.backstop, -1);
+        }
+        if (limits.frontstop !== undefined) {
+            applyStops(positions, inverseMass, targets.position, targets.normal, limits.frontstop, 1);
+        }
+        if (this.colliders > 0) {
+            applyColliders(positions, inverseMass, limits.thickness ?? null, margin, targets.colliderEnds, targets.colliderRadii, this.colliders);
+        }
+    }
+    /** After a reset, the share of the simulation drawn grows from nothing to all over the blend. */
+    blend(share) {
+        const target = this.targets.position;
+        for (let i = 0; i < this.positions.length; i++) {
+            const t = target[i];
+            this.positions[i] = t + (this.positions[i] - t) * share;
+            this.velocities[i] = this.velocities[i] * share;
+        }
+    }
+    /** Every batch of one kind, in colour order. */
+    solve(kind, kernel, invH2) {
+        const { batches, order } = kind.batches;
+        for (let b = 0; b + 1 < batches.length; b++) {
+            kernel(this.positions, this.inverseMass, kind.indices, kind.rest, kind.compliance, kind.lambda, order, batches[b], batches[b + 1], invH2);
+        }
+    }
+}
+/** Every kinematic particle exactly where skinning puts it at this step. */
+function placeKinematic(position, inverseMass, target) {
+    for (let i = 0; i < inverseMass.length; i++) {
+        if (inverseMass[i] !== 0)
+            continue;
+        position[i * 3] = target[i * 3];
+        position[i * 3 + 1] = target[i * 3 + 1];
+        position[i * 3 + 2] = target[i * 3 + 2];
+    }
+}