@driftengine/physics 4.8.3 → 4.8.4

package/dist/clothPose.js

@@ -0,0 +1,225 @@
+/**
+ * Where a skeleton puts a skinned cloth: each particle's skinned position and normal, each
+ * collider's ends, and the share of the character's own motion a free particle is carried by.
+ *
+ * **From joint globals and inverse binds, not from a skin palette.** A palette is `global × inverse
+ * bind` and is all skinning needs, but a collider sits on a joint's own frame, which only the
+ * global gives; taking both pieces lets one pose serve both. Model space throughout, then the model
+ * matrix, so the cloth simulates in the world and a turn swings it.
+ *
+ * **Normals are carried by each joint's upper 3×3**, not its inverse transpose: right for the
+ * rotations and uniform scales a rig is made of, and wrong for a sheared or non-uniformly scaled
+ * joint, which a garment's rig does not have. Renormalised after blending.
+ *
+ * Allocation-free: everything writes into arrays handed in.
+ */
+import { exactCos } from './exact.js';
+/** `a × b` into `out` at `at`, column-major 4×4. `out` may not alias either. */
+export function multiply4(a, aAt, b, bAt, out, at) {
+    for (let c = 0; c < 4; c++) {
+        for (let r = 0; r < 4; r++) {
+            let sum = 0;
+            for (let k = 0; k < 4; k++) {
+                sum += a[aAt + k * 4 + r] * b[bAt + c * 4 + k];
+            }
+            out[at + c * 4 + r] = sum;
+        }
+    }
+}
+/** `model × global_j × inverseBind_j` for every joint, into `skin`. */
+export function skinMatrices(globals, inverseBind, model, scratch, skin) {
+    const joints = inverseBind.length / 16;
+    for (let j = 0; j < joints; j++) {
+        multiply4(globals, j * 16, inverseBind, j * 16, scratch, 0);
+        multiply4(model, 0, scratch, 0, skin, j * 16);
+    }
+}
+/**
+ * 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 function skinParticles(rest, restNormal, joints, weights, joints2, weights2, skin, model, position, normal) {
+    const count = rest.length / 3;
+    for (let i = 0; i < count; i++) {
+        const x = rest[i * 3];
+        const y = rest[i * 3 + 1];
+        const z = rest[i * 3 + 2];
+        const nx = restNormal === null ? 0 : restNormal[i * 3];
+        const ny = restNormal === null ? 0 : restNormal[i * 3 + 1];
+        const nz = restNormal === null ? 1 : restNormal[i * 3 + 2];
+        let px = 0;
+        let py = 0;
+        let pz = 0;
+        let qx = 0;
+        let qy = 0;
+        let qz = 0;
+        if (skin === null || joints === null || weights === null) {
+            const m = model;
+            px = m[0] * x + m[4] * y + m[8] * z + m[12];
+            py = m[1] * x + m[5] * y + m[9] * z + m[13];
+            pz = m[2] * x + m[6] * y + m[10] * z + m[14];
+            qx = m[0] * nx + m[4] * ny + m[8] * nz;
+            qy = m[1] * nx + m[5] * ny + m[9] * nz;
+            qz = m[2] * nx + m[6] * ny + m[10] * nz;
+        }
+        else {
+            for (let set = 0; set < 2; set++) {
+                const js = set === 0 ? joints : joints2;
+                const ws = set === 0 ? weights : weights2;
+                if (js === null || ws === null)
+                    continue;
+                for (let k = 0; k < 4; k++) {
+                    const w = ws[i * 4 + k];
+                    if (w === 0)
+                        continue;
+                    const m = js[i * 4 + k] * 16;
+                    px +=
+                        w *
+                            (skin[m] * x +
+                                skin[m + 4] * y +
+                                skin[m + 8] * z +
+                                skin[m + 12]);
+                    py +=
+                        w *
+                            (skin[m + 1] * x +
+                                skin[m + 5] * y +
+                                skin[m + 9] * z +
+                                skin[m + 13]);
+                    pz +=
+                        w *
+                            (skin[m + 2] * x +
+                                skin[m + 6] * y +
+                                skin[m + 10] * z +
+                                skin[m + 14]);
+                    qx +=
+                        w *
+                            (skin[m] * nx +
+                                skin[m + 4] * ny +
+                                skin[m + 8] * nz);
+                    qy +=
+                        w *
+                            (skin[m + 1] * nx +
+                                skin[m + 5] * ny +
+                                skin[m + 9] * nz);
+                    qz +=
+                        w *
+                            (skin[m + 2] * nx +
+                                skin[m + 6] * ny +
+                                skin[m + 10] * nz);
+                }
+            }
+        }
+        position[i * 3] = px;
+        position[i * 3 + 1] = py;
+        position[i * 3 + 2] = pz;
+        const length = Math.sqrt(qx * qx + qy * qy + qz * qz);
+        const inverse = length > 1e-12 ? 1 / length : 0;
+        normal[i * 3] = qx * inverse;
+        normal[i * 3 + 1] = qy * inverse;
+        normal[i * 3 + 2] = qz * inverse;
+    }
+}
+/**
+ * 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 function placeColliders(colliders, globals, model, scratch, ends) {
+    for (let k = 0; k < colliders.length; k++) {
+        const collider = colliders[k];
+        multiply4(model, 0, globals, collider.joint * 16, scratch, 0);
+        const frame = collider.frame;
+        if (frame !== undefined) {
+            multiply4(scratch, 0, frame, 0, scratch, 16);
+            scratch.copyWithin(0, 16, 32);
+        }
+        const length = collider.length ?? 0;
+        for (let c = 0; c < 3; c++) {
+            const origin = scratch[12 + c];
+            ends[k * 6 + c] = origin;
+            ends[k * 6 + 3 + c] = origin + scratch[8 + c] * length;
+        }
+    }
+}
+/**
+ * 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 function carryParticles(position, velocity, inverseMass, previous, next, linearInertia, angularInertia) {
+    const turn = 1 - angularInertia;
+    const move = 1 - linearInertia;
+    if (turn === 0 && move === 0)
+        return;
+    /* R = R_next × R_previousᵀ, row r column c at r + c·3. */
+    const r = ROTATION;
+    for (let row = 0; row < 3; row++) {
+        for (let col = 0; col < 3; col++) {
+            let sum = 0;
+            for (let k = 0; k < 3; k++)
+                sum += next[k * 4 + row] * previous[k * 4 + col];
+            r[row + col * 3] = sum;
+        }
+    }
+    const ox = previous[12];
+    const oy = previous[13];
+    const oz = previous[14];
+    const dx = (next[12] - ox) * move;
+    const dy = (next[13] - oy) * move;
+    const dz = (next[14] - oz) * move;
+    for (let i = 0; i < inverseMass.length; i++) {
+        if (inverseMass[i] === 0)
+            continue;
+        const at = i * 3;
+        const x = position[at] - ox;
+        const y = position[at + 1] - oy;
+        const z = position[at + 2] - oz;
+        position[at] =
+            position[at] +
+                (r[0] * x + r[3] * y + r[6] * z - x) * turn +
+                dx;
+        position[at + 1] =
+            position[at + 1] +
+                (r[1] * x + r[4] * y + r[7] * z - y) * turn +
+                dy;
+        position[at + 2] =
+            position[at + 2] +
+                (r[2] * x + r[5] * y + r[8] * z - z) * turn +
+                dz;
+        const vx = velocity[at];
+        const vy = velocity[at + 1];
+        const vz = velocity[at + 2];
+        velocity[at] =
+            vx + (r[0] * vx + r[3] * vy + r[6] * vz - vx) * turn;
+        velocity[at + 1] =
+            vy + (r[1] * vx + r[4] * vy + r[7] * vz - vy) * turn;
+        velocity[at + 2] =
+            vz + (r[2] * vx + r[5] * vy + r[8] * vz - vz) * turn;
+    }
+}
+const ROTATION = new Float64Array(9);
+/**
+ * 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 function jumped(previous, next, distance, angle) {
+    const dx = next[12] - previous[12];
+    const dy = next[13] - previous[13];
+    const dz = next[14] - previous[14];
+    if (dx * dx + dy * dy + dz * dz > distance * distance)
+        return true;
+    if (!(angle < Math.PI))
+        return false;
+    let trace = 0;
+    for (let d = 0; d < 3; d++) {
+        for (let k = 0; k < 3; k++)
+            trace += next[k * 4 + d] * previous[k * 4 + d];
+    }
+    return (trace - 1) / 2 < exactCos(angle);
+}

package/dist/clothTargets.d.ts

@@ -0,0 +1,44 @@
+import type { SkinnedClothSetup } from './skinnedClothSetup.ts';
+/** Skinned positions and normals from the last two poses, and the model matrices between. */
+export declare class ClothTargets {
+    private readonly setup;
+    private readonly particlesOnCpu;
+    /** Where skinning puts each particle at the step being taken. */
+    readonly position: Float32Array;
+    /** Its skinned normal at the latest pose. */
+    readonly normal: Float32Array;
+    /** The model matrix at the step being taken, and at the one before it. */
+    readonly modelNow: Float32Array<ArrayBuffer>;
+    readonly modelBefore: Float32Array<ArrayBuffer>;
+    /** Each collider's two ends, six floats a collider, at the latest pose. */
+    readonly colliderEnds: Float32Array;
+    /** Each collider's two radii. */
+    readonly colliderRadii: Float32Array;
+    /** Whether a pose has been given at all. */
+    posed: boolean;
+    /** `model × global × inverse bind` a joint at the latest pose, or null for a cloth with no rig. */
+    readonly skin: Float32Array | null;
+    private readonly from;
+    private readonly to;
+    private readonly modelFrom;
+    private readonly modelTo;
+    private readonly scratch;
+    private readonly colliders;
+    constructor(setup: SkinnedClothSetup, particlesOnCpu?: boolean);
+    /** The model matrix the latest pose was given at. */
+    get model(): Float32Array;
+    /** Take a new pose: the old one becomes where this frame's steps start from. */
+    pose(globals: Float32Array, model: Float32Array): void;
+    /** Forget the pose before the latest: steps start where the latest one is. */
+    settle(): void;
+    /**
+     * The steps of a frame have run: the next frame's start from this pose, not the one before it, or
+     * a frame given no new pose would interpolate back from the old one and jump the cloth.
+     */
+    consume(): void;
+    /** The skinned positions and the model matrix `fraction` of the way from the last pose to this one. */
+    at(fraction: number): void;
+    /** The latest skinned positions, which `reset` puts every particle at. */
+    get latest(): Float32Array;
+    private skinAt;
+}

package/dist/clothTargets.js

@@ -0,0 +1,124 @@
+/**
+ * A skinned cloth's pose: where skinning puts every particle at the last two poses, where it puts
+ * them at a step between, and where the colliders are.
+ *
+ * **Interpolated across the steps of one frame.** A frame that runs two steps moves its kinematic
+ * particles half way at the first and the rest at the second, rather than all at once — a fixed
+ * step must not turn a 120 Hz animation into a 60 Hz one with a jump in it. The model matrix is
+ * blended the same way for the inertia carry; a blend of two rigid matrices is not quite rigid, by
+ * the few thousandths of a degree a character turns between two steps.
+ *
+ * Before any pose the rest positions stand in, under an identity model, so a cloth that is never
+ * posed is the plain solver it was in H1's tests.
+ *
+ * **The particles' skinned positions can be left to a device.** A GPU solver skins them itself, from
+ * `skin`, so `particlesOnCpu` false keeps only what is per joint or per collider — the model
+ * matrices, the skin matrices and the colliders' ends — and `position`, `normal` and `latest` then
+ * hold the rest pose and are not to be read.
+ */
+import { placeColliders, skinMatrices, skinParticles } from './clothPose.js';
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+/** Skinned positions and normals from the last two poses, and the model matrices between. */
+export class ClothTargets {
+    setup;
+    particlesOnCpu;
+    /** Where skinning puts each particle at the step being taken. */
+    position;
+    /** Its skinned normal at the latest pose. */
+    normal;
+    /** The model matrix at the step being taken, and at the one before it. */
+    modelNow = new Float32Array(IDENTITY);
+    modelBefore = new Float32Array(IDENTITY);
+    /** Each collider's two ends, six floats a collider, at the latest pose. */
+    colliderEnds;
+    /** Each collider's two radii. */
+    colliderRadii;
+    /** Whether a pose has been given at all. */
+    posed = false;
+    /** `model × global × inverse bind` a joint at the latest pose, or null for a cloth with no rig. */
+    skin;
+    from;
+    to;
+    modelFrom = new Float32Array(IDENTITY);
+    modelTo = new Float32Array(IDENTITY);
+    scratch = new Float32Array(32);
+    colliders;
+    constructor(setup, particlesOnCpu = true) {
+        this.setup = setup;
+        this.particlesOnCpu = particlesOnCpu;
+        const count = setup.positions.length;
+        this.from = new Float32Array(setup.positions);
+        this.to = new Float32Array(setup.positions);
+        this.position = new Float32Array(setup.positions);
+        this.normal = new Float32Array(count);
+        const bones = (setup.inverseBind?.length ?? 0) / 16;
+        this.skin = setup.joints === undefined || bones === 0 ? null : new Float32Array(bones * 16);
+        this.colliders = setup.colliders ?? [];
+        this.colliderEnds = new Float32Array(this.colliders.length * 6);
+        this.colliderRadii = new Float32Array(this.colliders.length * 2);
+        this.colliders.forEach((collider, k) => {
+            this.colliderRadii[k * 2] = collider.radius;
+            this.colliderRadii[k * 2 + 1] = collider.radius2 ?? collider.radius;
+        });
+        this.skinAt(new Float32Array(Math.max(16, bones * 16)), this.modelTo);
+    }
+    /** The model matrix the latest pose was given at. */
+    get model() {
+        return this.modelTo;
+    }
+    /** Take a new pose: the old one becomes where this frame's steps start from. */
+    pose(globals, model) {
+        this.from.set(this.to);
+        this.modelFrom.set(this.modelTo);
+        this.modelTo.set(model);
+        this.skinAt(globals, model);
+        if (this.colliders.length > 0) {
+            placeColliders(this.colliders, globals, model, this.scratch, this.colliderEnds);
+        }
+        this.posed = true;
+    }
+    /** Forget the pose before the latest: steps start where the latest one is. */
+    settle() {
+        this.from.set(this.to);
+        this.position.set(this.to);
+        this.modelFrom.set(this.modelTo);
+        this.modelNow.set(this.modelTo);
+        this.modelBefore.set(this.modelTo);
+    }
+    /**
+     * The steps of a frame have run: the next frame's start from this pose, not the one before it, or
+     * a frame given no new pose would interpolate back from the old one and jump the cloth.
+     */
+    consume() {
+        this.from.set(this.to);
+        this.modelFrom.set(this.modelTo);
+    }
+    /** The skinned positions and the model matrix `fraction` of the way from the last pose to this one. */
+    at(fraction) {
+        const { from, to, position } = this;
+        if (this.particlesOnCpu) {
+            for (let i = 0; i < to.length; i++) {
+                const a = from[i];
+                position[i] = a + (to[i] - a) * fraction;
+            }
+        }
+        this.modelBefore.set(this.modelNow);
+        for (let i = 0; i < 16; i++) {
+            const a = this.modelFrom[i];
+            this.modelNow[i] = a + (this.modelTo[i] - a) * fraction;
+        }
+    }
+    /** The latest skinned positions, which `reset` puts every particle at. */
+    get latest() {
+        return this.to;
+    }
+    skinAt(globals, model) {
+        const { setup, skin } = this;
+        if (skin !== null && setup.inverseBind !== undefined) {
+            skinMatrices(globals, setup.inverseBind, model, this.scratch, skin);
+        }
+        if (!this.particlesOnCpu)
+            return;
+        skinParticles(setup.positions, setup.normals ?? null, setup.joints ?? null, setup.weights ?? null, setup.joints2 ?? null, setup.weights2 ?? null, skin, model, this.to, this.normal);
+    }
+}

package/dist/exact.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/** `Math.sin`, reproducibly. NaN in, NaN out; an infinity answers NaN, as `Math.sin` does. */
+export declare function exactSin(x: number): number;
+/** `Math.cos`, reproducibly. */
+export declare function exactCos(x: number): number;
+/**
+ * `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 declare function exactExp(x: number): number;
+/**
+ * `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 declare function exactLog(x: number): number;
+/**
+ * `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 declare function exactAcos(x: number): number;