@driftengine/physics 4.8.3 → 4.8.5

package/dist/clothBatches.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare function colourConstraints(indices: Uint32Array, arity: number, inverseMass: Float32Array): ClothBatches;
+/**
+ * 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 declare function givenBatches(name: string, indices: Uint32Array, arity: number, inverseMass: Float32Array, batches: Uint32Array): ClothBatches;
+/**
+ * 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 declare function batchesOf(name: string, indices: Uint32Array, arity: number, inverseMass: Float32Array, given: Uint32Array | undefined): ClothBatches;

package/dist/clothBatches.js

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+/** Colour `indices`, `arity` particles a constraint, around the particles `inverseMass` pins. */
+export function colourConstraints(indices, arity, inverseMass) {
+    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 = [];
+    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];
+                if (inverseMass[p] === 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];
+            if (inverseMass[p] === 0)
+                continue;
+            (used[p] ??= new Set()).add(chosen);
+        }
+    }
+    const batches = new Uint32Array(colours + 1);
+    for (let k = 0; k < constraints; k++)
+        batches[colour[k] + 1]++;
+    for (let c = 0; c < colours; c++)
+        batches[c + 1] = batches[c + 1] + batches[c];
+    const cursor = batches.slice(0, colours);
+    const order = new Uint32Array(constraints);
+    for (let k = 0; k < constraints; k++)
+        order[cursor[colour[k]]++] = 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, indices, arity, inverseMass, batches) {
+    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]; k < batches[b + 1]; k++) {
+            for (let j = 0; j < arity; j++) {
+                const p = indices[k * arity + j];
+                if (inverseMass[p] === 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, indices, arity, inverseMass, given) {
+    return given === undefined
+        ? colourConstraints(indices, arity, inverseMass)
+        : givenBatches(name, indices, arity, inverseMass, given);
+}

package/dist/clothControl.d.ts

@@ -0,0 +1,55 @@
+import { ClothTargets } from './clothTargets.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 declare class ClothControl {
+    private readonly device;
+    readonly parameters: ResolvedClothParameters;
+    readonly targets: ClothTargets;
+    private accumulator;
+    /** Steps left in the blend from the skinned pose after a reset. */
+    private blendLeft;
+    /**
+     * `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, device: ClothDevice, particlesOnCpu?: boolean);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** How far the time handed to `advance` reaches into the next step, 0 to 1. */
+    get alpha(): number;
+    /** One fixed step, all the way to the latest pose: for a caller in the engine's fixed-step loop. */
+    step(): void;
+    private consume;
+    /** The targets moved to `fraction`, the share a blend keeps, then the device's step. */
+    private stepAt;
+}

package/dist/clothControl.js

@@ -0,0 +1,106 @@
+/**
+ * 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.js';
+import { ClothTargets } from './clothTargets.js';
+import { resolveClothParameters } from './skinnedClothSetup.js';
+/** A skinned cloth's schedule, over one device. */
+export class ClothControl {
+    device;
+    parameters;
+    targets;
+    accumulator = 0;
+    /** Steps left in the blend from the skinned pose after a reset. */
+    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, device, particlesOnCpu = true) {
+        this.device = device;
+        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, model) {
+        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() {
+        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) {
+        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() {
+        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() {
+        this.stepAt(1);
+        this.consume();
+    }
+    consume() {
+        this.targets.consume();
+        this.device.targetsChanged('consumed');
+    }
+    /** The targets moved to `fraction`, the share a blend keeps, then the device's step. */
+    stepAt(fraction) {
+        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/dist/clothLimits.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare function applyMaxDistance(position: Float32Array, inverseMass: Float32Array, target: Float32Array, maxDistance: Float32Array, scale: number): void;
+/**
+ * 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 declare function applyStops(position: Float32Array, inverseMass: Float32Array, target: Float32Array, normal: Float32Array, stops: Float32Array, side: number): void;
+/**
+ * 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 declare function applyColliders(position: Float32Array, inverseMass: Float32Array, thickness: Float32Array | null, margin: number, ends: Float32Array, radii: Float32Array, colliders: number): void;

package/dist/clothLimits.js

@@ -0,0 +1,108 @@
+/**
+ * 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, inverseMass, target, maxDistance, scale) {
+    for (let i = 0; i < inverseMass.length; i++) {
+        if (inverseMass[i] === 0)
+            continue;
+        const limit = maxDistance[i] * scale;
+        if (!(limit < Infinity))
+            continue;
+        const at = i * 3;
+        const dx = position[at] - target[at];
+        const dy = position[at + 1] - target[at + 1];
+        const dz = position[at + 2] - target[at + 2];
+        const d2 = dx * dx + dy * dy + dz * dz;
+        if (d2 <= limit * limit)
+            continue;
+        const s = limit / Math.sqrt(d2);
+        position[at] = target[at] + dx * s;
+        position[at + 1] = target[at + 1] + dy * s;
+        position[at + 2] = target[at + 2] + 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, inverseMass, target, normal, stops, side) {
+    for (let i = 0; i < inverseMass.length; i++) {
+        if (inverseMass[i] === 0)
+            continue;
+        const distance = stops[i * 2];
+        const radius = stops[i * 2 + 1];
+        if (!(distance < Infinity) || !(radius > 0))
+            continue;
+        const at = i * 3;
+        const reach = (distance + radius) * side;
+        const cx = target[at] + normal[at] * reach;
+        const cy = target[at + 1] + normal[at + 1] * reach;
+        const cz = target[at + 2] + normal[at + 2] * 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, at, cx, cy, cz, radius) {
+    const dx = position[at] - cx;
+    const dy = position[at + 1] - cy;
+    const dz = position[at + 2] - 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, inverseMass, thickness, margin, ends, radii, colliders) {
+    for (let i = 0; i < inverseMass.length; i++) {
+        if (inverseMass[i] === 0)
+            continue;
+        const at = i * 3;
+        const pad = (thickness === null ? 0 : thickness[i]) + margin;
+        for (let k = 0; k < colliders; k++) {
+            const ax = ends[k * 6];
+            const ay = ends[k * 6 + 1];
+            const az = ends[k * 6 + 2];
+            const ex = ends[k * 6 + 3] - ax;
+            const ey = ends[k * 6 + 4] - ay;
+            const ez = ends[k * 6 + 5] - az;
+            const e2 = ex * ex + ey * ey + ez * ez;
+            let t = 0;
+            if (e2 > 1e-18) {
+                t =
+                    ((position[at] - ax) * ex +
+                        (position[at + 1] - ay) * ey +
+                        (position[at + 2] - az) * ez) /
+                        e2;
+                t = Math.min(1, Math.max(0, t));
+            }
+            const r0 = radii[k * 2];
+            const r1 = radii[k * 2 + 1];
+            pushOut(position, at, ax + ex * t, ay + ey * t, az + ez * t, r0 + (r1 - r0) * t + pad);
+        }
+    }
+}

package/dist/clothPose.d.ts

@@ -0,0 +1,36 @@
+/** `a × b` into `out` at `at`, column-major 4×4. `out` may not alias either. */
+export declare function multiply4(a: ArrayLike<number>, aAt: number, b: ArrayLike<number>, bAt: number, out: Float32Array, at: number): void;
+/** `model × global_j × inverseBind_j` for every joint, into `skin`. */
+export declare function skinMatrices(globals: Float32Array, inverseBind: Float32Array, model: Float32Array, scratch: Float32Array, skin: Float32Array): void;
+/**
+ * Each particle's skinned position and normal, by up to eight influences, into `position` and
+ * `normal`. Without a rig (`skin` null), the rest pose under the model matrix alone.
+ */
+export declare function skinParticles(rest: Float32Array, restNormal: Float32Array | null, joints: Float32Array | null, weights: Float32Array | null, joints2: Float32Array | null, weights2: Float32Array | null, skin: Float32Array | null, model: Float32Array, position: Float32Array, normal: Float32Array): void;
+/**
+ * Each collider's two ends in the world, six floats a collider: `model × global × frame` applied to
+ * the frame's origin and to `length` along its +Z. A sphere's two ends are one point.
+ */
+export declare function placeColliders(colliders: readonly {
+    readonly joint: number;
+    readonly length?: number;
+    readonly frame?: Float32Array;
+}[], globals: Float32Array, model: Float32Array, scratch: Float32Array, ends: Float32Array): void;
+/**
+ * Carry free particles by the share of the character's motion they do not keep as their own.
+ *
+ * The character moved by `next × previous⁻¹`: a rotation about its old origin and a move of that
+ * origin. A particle is moved by `1 − angularInertia` of the first and `1 − linearInertia` of the
+ * second, its velocity turned by the same share — so inertia 1 leaves the cloth in the world and 0
+ * moves it as if it were simulated in the character's space. **A blend of the rotated point, not a
+ * fraction of the angle**, which is exact at the two ends and, for the few degrees a character turns
+ * in a step, indistinguishable between them; it needs no trigonometry, so it is the same bits on
+ * every engine. Both matrices rigid.
+ */
+export declare function carryParticles(position: Float32Array, velocity: Float32Array, inverseMass: Float32Array, previous: Float32Array, next: Float32Array, linearInertia: number, angularInertia: number): void;
+/**
+ * How far the character jumped between two poses: its origin's distance and its rotation's angle.
+ * The angle through `trace`, `cos θ = (tr R − 1) / 2`, compared as a cosine, through `exactCos` so
+ * every engine draws the line in one place.
+ */
+export declare function jumped(previous: Float32Array, next: Float32Array, distance: number, angle: number): boolean;