@yali-engine/physics 0.0.0-stage → 0.4.0

package/dist/cloth-asset.js

@@ -0,0 +1,706 @@
+// Cloth assets for Kanduka's GPU cloth (ADR-0101): a triangle mesh becomes the solver's
+// topology (stretch constraints on its edges, isometric bending stencils on its interior edges,
+// vertex → triangle adjacency) and its constraints are graph-coloured, so each colour can be
+// solved in parallel with no two constraints sharing a vertex. Pure: tested in Node.
+import { YaliError } from '@yali-engine/core';
+/** Marks a constraint's unused vertex slots. */
+export const NO_VERTEX = 0xffffffff;
+/** Words per packed constraint (`solve` in shaders/kanduka/cloth.wesl). */
+export const CONSTRAINT_WORDS = 12;
+/** Most colours a cloth may need (128 × u32 bit masks per vertex while colouring). */
+const MAX_COLOURS = 128;
+/** gf·cm²/cm in N·m (a bending rigidity per width). */
+const GF_CM = 9.80665e-5;
+/** gf/cm in N/m. */
+const GF_PER_CM = 0.980665;
+/**
+ * The isometric stencils' energy over a flat grid rolled to curvature k is
+ * `Σ ½ |Σ w x|² / compliance = ½ (r / compliance) k² × area`, where r depends on the fold's angle to
+ * the grid: 2.92 along the warp or weft, 4.46 along a cell diagonal (the grid's own anisotropy),
+ * 3.69 averaged over every angle (at 5 mm–2 cm cells). A drape folds at every angle, so a plate's
+ * bending rigidity B (N·m) is the compliance STENCIL_BEND / B with the average (ADR-0120; a test
+ * re-measures it).
+ */
+export const STENCIL_BEND = 3.69;
+const pair = (v) => (typeof v === 'number' ? [v, v] : v);
+/**
+ * A fabric from KES-F measurements (ADR-0120): density from W; XPBD's bending compliance from B
+ * (warp and weft averaged; `STENCIL_BEND`); VBD's shear modulus from G (N/m per radian); warp and
+ * weft stiffness, if measured, as the linear spring storing the tensile test's energy at EMT
+ * (`LT × load / EMT`), and XPBD's stretch compliance their geometric mean's inverse. What KES-F does
+ * not measure (damping, friction against colliders, collision thickness, the air, Poisson's ratio)
+ * comes from `base`; compression keeps `base`'s ratio to stretch.
+ *
+ * @example
+ * const habotai = fabricFromKes({ weight: 72.1, bending: [0.019, 0.063], shear: [0.23, 0.26], tensile: { emt: [7.11, 1.72], lt: [0.554, 0.867] } }, FABRICS.silk);
+ */
+export function fabricFromKes(kes, base) {
+    const [b1, b2] = pair(kes.bending);
+    const [g1, g2] = pair(kes.shear);
+    for (const [path, v] of [['weight', kes.weight], ['bending', b1], ['bending', b2], ['shear', g1], ['shear', g2]]) {
+        if (!(v > 0 && Number.isFinite(v)))
+            throw Object.assign(new YaliError('PHYSICS_INVALID', `KES-F ${path} ${v}.`, 'Give the measured value, above 0, in KES-F units (W g/m², B gf·cm²/cm, G gf/cm·deg).'), { path });
+    }
+    const bend = STENCIL_BEND / (((b1 + b2) / 2) * GF_CM);
+    const shear = ((g1 + g2) / 2) * GF_PER_CM * (180 / Math.PI);
+    const out = { ...base, density: kes.weight / 1000, bend, shear };
+    if (!kes.tensile)
+        return out;
+    const [e1, e2] = pair(kes.tensile.emt);
+    const [l1, l2] = pair(kes.tensile.lt);
+    const load = (kes.tensile.load ?? 500) * GF_PER_CM;
+    for (const [path, v] of [['tensile.emt', e1], ['tensile.emt', e2], ['tensile.lt', l1], ['tensile.lt', l2]]) {
+        if (!(v > 0 && Number.isFinite(v)))
+            throw Object.assign(new YaliError('PHYSICS_INVALID', `KES-F ${path} ${v}.`, 'Give EMT in % and LT (0–1), both above 0.'), { path });
+    }
+    const warp = (l1 * load) / (e1 / 100);
+    const weft = (l2 * load) / (e2 / 100);
+    const stretch = 1 / Math.sqrt(warp * weft);
+    return { ...out, warp, weft, stretch, compression: (base.compression / base.stretch) * stretch };
+}
+/**
+ * Published KES-F measurements behind the presets (ADR-0120, ADR-0131). `canvas` is data only: built
+ * from it, the preset drapes 0.51 against its source's 0.91 (XPBD has no shear rigidity, which is
+ * what holds a stiff weave up), so the canvas preset stays fitted. `leather` is data only too: built from it
+ * the preset drapes 0.80 against the fitted 0.98, and its source measured no drape to referee (ADR-0138).
+ */
+export const KES = {
+    /** Habotai, plain weave, 72.1 g/m² (sample 8): Hu X. et al., "Comparison of silk fabric dynamic drapability…", Industria Textila 71(1), 2020, pp. 55–61, Tables 1–5 (doi:10.35530/IT.071.01.1536). Drape coefficient 42.7% (YG811, 24 cm). */
+    silk: { weight: 72.067, bending: [0.019, 0.063], shear: [0.23, 0.26], tensile: { emt: [7.11, 1.723], lt: [0.554, 0.867] } },
+    /** 100% cotton plain weave, Ne 30, 70 ppi, 138.6 g/m² (sample 6): Alam M.S., Majumdar A., Ghosh A., Indian J. Fibre Text. Res. 44, 2019, pp. 9–15, Table 2. No tensile data. */
+    cotton: { weight: 138.6, bending: 0.07, shear: 1.75 },
+    /** 100% cotton indigo denim (sample A), 246 g/m² and 0.62 mm (Table 2; Table 5 prints W 104 mg/cm², which contradicts it): Kumari A., Khurana K., Journal of Textiles 2016, 4614168, Table 5 (doi:10.1155/2016/4614168). */
+    denim: { weight: 246, bending: 0.172, shear: 2.18, tensile: { emt: 5.515, lt: 0.712 } },
+    /** A heavy 100% cotton plain weave, 279 g/m², 16 × 23 threads/cm, 0.88 mm (sample C3; no source measures a fabric sold as canvas, ADR-0131): Kuijpers A., "Evaluation of physical and virtual fabric drape created from objective fabric properties", MPhil thesis, University of Manchester, 2017, Table 3.1 and Appendix 7 (KES-FB). Drape coefficient 91% (Cusick, 30 cm on 18 cm, Table 5.1). */
+    canvas: { weight: 279, bending: [0.33, 0.275], shear: [4.58, 4.41], tensile: { emt: [4.16, 8.03], lt: [0.905, 0.773] } },
+    /** Cowhide grain leather for bags (the butt), the mean of nine samples C1–C9, 1.21 mm: Roh E.K., "Mechanical properties and preferences of natural and artificial leathers…", J. Eng. Fibers Fabr. 15, 2020, Tables 1 and 3 (doi:10.1177/1558925020968825, CC BY). KES-FB: W 706.5 g/m², B 2.67 gf·cm²/cm (2 × 2 cm specimens), G 12.52 gf/cm·deg; the tensile test is reported as WT, RT and EM 4.13% without LT (none here); no drape measured. */
+    leather: { weight: 706.47, bending: 2.67, shear: 12.52 },
+};
+/**
+ * Fabric presets. Silk, cotton and denim are fitted to published KES-F measurements (`KES`,
+ * `fabricFromKes`, ADR-0120); their drape matches the published drape coefficients when the solve
+ * converges. Canvas is fitted to a published drape (ADR-0131: its KES-F values alone drape far too
+ * softly under XPBD); leather is fitted by eye (ADR-0101, ADR-0105) and stays so beside `KES.leather` (ADR-0138).
+ * Cotton's warp / weft stiffness is fitted too (its source has no tensile test). Woven fabrics are
+ * stiffer along the warp than the weft and far softer in shear; leather has no weave.
+ */
+export const FABRICS = {
+    silk: fabricFromKes(KES.silk, { density: 0.08, stretch: 2e-4, compression: 0.005, bend: 6e4, damping: 0.05, friction: 0.25, thickness: 0.006, drag: 1.2, skinDrag: 0.02, warp: 5000, weft: 4000, shear: 300, poisson: 0.2 }),
+    cotton: fabricFromKes(KES.cotton, { density: 0.16, stretch: 1e-4, compression: 0.002, bend: 1.5e4, damping: 0.05, friction: 0.45, thickness: 0.008, drag: 1.2, skinDrag: 0.03, warp: 10000, weft: 8000, shear: 800, poisson: 0.2 }),
+    // Fitted (ADR-0131): drapes 0.96 against the measured heavy cotton plain weave's 0.91 (`KES.canvas`).
+    canvas: { density: 0.22, stretch: 5e-5, compression: 0.002, bend: 5e3, damping: 0.05, friction: 0.5, thickness: 0.008, drag: 1.2, skinDrag: 0.03, warp: 20000, weft: 18000, shear: 2500, poisson: 0.2 },
+    denim: fabricFromKes(KES.denim, { density: 0.4, stretch: 3e-5, compression: 0.001, bend: 1.5e3, damping: 0.08, friction: 0.6, thickness: 0.01, drag: 1.1, skinDrag: 0.04, warp: 33000, weft: 24000, shear: 3000, poisson: 0.25 }),
+    leather: { density: 0.9, stretch: 1e-5, compression: 5e-4, bend: 300, damping: 0.1, friction: 0.7, thickness: 0.012, drag: 1.0, skinDrag: 0.05, warp: 100000, weft: 100000, shear: 35000, poisson: 0.4 },
+};
+/**
+ * A rectangular cloth centred on its entity's origin, its cells cut along alternating diagonals
+ * (no preferred shear direction).
+ *
+ * @example
+ * const flag = clothGrid({ width: 3, height: 2, segments: [60, 40], pin: 'left' });
+ */
+export function clothGrid(o) {
+    if (!(o.width > 0 && o.height > 0)) {
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `A ${o.width} × ${o.height} m cloth grid.`, 'Give a width and height above 0.'), { path: 'width' });
+    }
+    const nx = Math.max(2, Math.round(o.segments?.[0] ?? o.width * 32));
+    const ny = Math.max(2, Math.round(o.segments?.[1] ?? o.height * 32));
+    const flat = o.plane === 'xz';
+    const n = (nx + 1) * (ny + 1);
+    const positions = new Float32Array(n * 3);
+    const uvs = new Float32Array(n * 2);
+    const pinned = [];
+    const pin = o.pin ?? 'none';
+    for (let j = 0; j <= ny; j++) {
+        for (let i = 0; i <= nx; i++) {
+            const v = j * (nx + 1) + i;
+            const u = i / nx;
+            const w = j / ny;
+            const x = (u - 0.5) * o.width;
+            const y = (0.5 - w) * o.height;
+            positions.set(flat ? [x, 0, -y] : [x, y, 0], v * 3);
+            uvs.set([u, w], v * 2);
+            const hold = typeof pin === 'function' ? pin(u, w) : pin === 'top' ? j === 0 : pin === 'left' ? i === 0 : pin === 'corners' ? j === 0 && (i === 0 || i === nx) : false;
+            if (hold)
+                pinned.push(v);
+        }
+    }
+    const indices = new Uint32Array(nx * ny * 6);
+    let k = 0;
+    for (let j = 0; j < ny; j++) {
+        for (let i = 0; i < nx; i++) {
+            const a = j * (nx + 1) + i;
+            const b = a + 1;
+            const c = a + nx + 1;
+            const d = c + 1;
+            // Counter-clockwise seen from the front (+Z, or +Y lying flat): a top-left, b top-right, c and d below.
+            if ((i + j) % 2 === 0)
+                indices.set([a, c, d, a, d, b], k);
+            else
+                indices.set([a, c, b, b, c, d], k);
+            k += 6;
+        }
+    }
+    return { positions, indices, uvs, pinned };
+}
+/**
+ * Builds a mesh's solver topology: a stretch constraint per edge, a bending stencil per edge two
+ * triangles share (isometric bending, Bergou et al., *A Quadratic Bending Model for Inextensible
+ * Surfaces*, 2006; it assumes a flat rest shape), adjacency, per-vertex areas, and a greedy
+ * colouring of all constraints together.
+ */
+export function clothTopology(mesh) {
+    const p = mesh.positions;
+    const idx = mesh.indices;
+    const n = p.length / 3;
+    const t = idx.length / 3;
+    if (n < 3 || t < 1 || idx.length % 3 !== 0) {
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `A cloth mesh of ${n} vertices and ${idx.length} indices.`, 'Give at least one triangle (indices in threes).'), { path: 'indices' });
+    }
+    for (let i = 0; i < idx.length; i++) {
+        if (idx[i] >= n)
+            throw Object.assign(new YaliError('PHYSICS_INVALID', `Cloth index ${idx[i]} at ${i} is past the ${n} vertices.`, 'Index the positions given.'), { path: `indices[${i}]` });
+    }
+    const pinned = new Uint8Array(n);
+    for (const v of Array.from(mesh.pinned ?? [])) {
+        if (!(v >= 0 && v < n))
+            throw Object.assign(new YaliError('PHYSICS_INVALID', `Pinned vertex ${v} is not one of the ${n}.`, 'Pin vertex indices of the mesh.'), { path: 'pinned' });
+        pinned[v] = 1;
+    }
+    const area = new Float64Array(n);
+    const adjCount = new Uint32Array(n + 1);
+    // Edges: key (lo, hi) → the vertices opposite it, one per triangle.
+    const edges = new Map();
+    for (let f = 0; f < t; f++) {
+        const a = idx[f * 3];
+        const b = idx[f * 3 + 1];
+        const c = idx[f * 3 + 2];
+        const tri = triArea(p, a, b, c);
+        for (const v of [a, b, c]) {
+            area[v] += tri / 3;
+            adjCount[v + 1]++;
+        }
+        for (const [u, w, o] of [[a, b, c], [b, c, a], [c, a, b]]) {
+            const key = Math.min(u, w) * n + Math.max(u, w);
+            const opp = edges.get(key);
+            if (opp)
+                opp.push(o);
+            else
+                edges.set(key, [o]);
+        }
+    }
+    for (let v = 0; v < n; v++)
+        adjCount[v + 1] += adjCount[v];
+    const adjOffsets = adjCount;
+    const adjacency = new Uint32Array(t * 3);
+    const fill = adjOffsets.slice(0, n);
+    for (let f = 0; f < t; f++)
+        for (let k = 0; k < 3; k++)
+            adjacency[fill[idx[f * 3 + k]]++] = f;
+    // Constraints: every edge stretches; an edge with exactly two triangles also bends.
+    const kinds = [];
+    const ids = [];
+    const rest = [];
+    const bends = [];
+    for (const [key, opp] of edges) {
+        const u = Math.floor(key / n);
+        const w = key - u * n;
+        kinds.push(0);
+        ids.push(u, w, NO_VERTEX, NO_VERTEX);
+        rest.push(dist(p, u, w), 0, 0, 0);
+        if (opp.length === 2)
+            bends.push([u, w, opp[0], opp[1]]);
+    }
+    for (const s of bends) {
+        const k = bendWeights(p, s[0], s[1], s[2], s[3]);
+        if (!k)
+            continue;
+        kinds.push(1);
+        ids.push(...s);
+        rest.push(...k);
+    }
+    const m = kinds.length;
+    const vertexIds = new Uint32Array(ids);
+    // Greedy colouring of the stretch constraints: each takes the lowest colour none of its vertices
+    // has yet (8 on a grid). The bending stencils all go in one last range after them: the GPU
+    // solves them together, Jacobi (ADR-0110), and the CPU walks every range in order anyway.
+    const used = new Uint32Array(n * (MAX_COLOURS / 32));
+    const colour = new Uint8Array(m);
+    let colours = 0;
+    for (let c = 0; c < m; c++) {
+        if (kinds[c] !== 0)
+            continue;
+        const vs = [vertexIds[c * 4], vertexIds[c * 4 + 1], vertexIds[c * 4 + 2], vertexIds[c * 4 + 3]].filter((v) => v !== NO_VERTEX);
+        let k = 0;
+        while (k < MAX_COLOURS && vs.some((v) => used[v * 4 + (k >> 5)] & (1 << (k & 31))))
+            k++;
+        if (k === MAX_COLOURS) {
+            throw Object.assign(new YaliError('PHYSICS_INVALID', `A cloth vertex is in too many constraints to colour within ${MAX_COLOURS} colours.`, 'Remesh the cloth: no vertex should join more than ~20 triangles.'), { path: 'indices' });
+        }
+        for (const v of vs)
+            used[v * 4 + (k >> 5)] |= 1 << (k & 31);
+        colour[c] = k;
+        colours = Math.max(colours, k + 1);
+    }
+    const stretchColours = colours;
+    if (kinds.some((k) => k === 1)) {
+        for (let c = 0; c < m; c++)
+            if (kinds[c] === 1)
+                colour[c] = stretchColours;
+        colours++;
+    }
+    const colourOffsets = new Uint32Array(colours + 1);
+    for (let c = 0; c < m; c++)
+        colourOffsets[colour[c] + 1]++;
+    for (let k = 0; k < colours; k++)
+        colourOffsets[k + 1] += colourOffsets[k];
+    const order = new Uint32Array(m);
+    const at = colourOffsets.slice(0, colours);
+    for (let c = 0; c < m; c++)
+        order[at[colour[c]]++] = c;
+    const { vertexOrder, vertexColourOffsets } = colourVertices(n, idx, vertexIds, kinds, pinned);
+    const restFrames = membraneFrames(p, idx, mesh.uvs);
+    const { tetherAnchor, tetherLength } = tethers(n, vertexIds, kinds, rest, pinned);
+    return { mesh, vertices: n, triangles: t, pinned, area, adjOffsets, adjacency, kinds: Uint8Array.from(kinds), vertexIds, rest: Float32Array.from(rest), order, colourOffsets, stretchColours, vertexOrder, vertexColourOffsets, restFrames, tetherAnchor, tetherLength };
+}
+/**
+ * VBD's vertex colouring (ADR-0105): a vertex reads every vertex it shares a triangle or a bending
+ * stencil with, so those take different colours; pinned vertices are never solved and take none.
+ */
+function colourVertices(n, idx, ids, kinds, pinned) {
+    const near = Array.from({ length: n }, () => []);
+    const link = (vs) => {
+        for (const a of vs)
+            for (const b of vs)
+                if (a !== b && !pinned[a] && !pinned[b])
+                    near[a].push(b);
+    };
+    for (let f = 0; f < idx.length; f += 3)
+        link([idx[f], idx[f + 1], idx[f + 2]]);
+    for (let c = 0; c < kinds.length; c++)
+        if (kinds[c] === 1)
+            link([ids[c * 4], ids[c * 4 + 1], ids[c * 4 + 2], ids[c * 4 + 3]]);
+    const colour = new Int16Array(n).fill(-1);
+    const taken = new Uint8Array(MAX_COLOURS);
+    let colours = 0;
+    for (let v = 0; v < n; v++) {
+        if (pinned[v])
+            continue;
+        taken.fill(0);
+        for (const u of near[v])
+            if (colour[u] >= 0)
+                taken[colour[u]] = 1;
+        let k = 0;
+        while (k < MAX_COLOURS && taken[k])
+            k++;
+        if (k === MAX_COLOURS) {
+            throw Object.assign(new YaliError('PHYSICS_INVALID', `A cloth vertex has too many neighbours to colour within ${MAX_COLOURS} colours.`, 'Remesh the cloth: no vertex should join more than ~20 triangles.'), { path: 'indices' });
+        }
+        colour[v] = k;
+        colours = Math.max(colours, k + 1);
+    }
+    const vertexColourOffsets = new Uint32Array(colours + 1);
+    for (let v = 0; v < n; v++)
+        if (colour[v] >= 0)
+            vertexColourOffsets[colour[v] + 1]++;
+    for (let k = 0; k < colours; k++)
+        vertexColourOffsets[k + 1] += vertexColourOffsets[k];
+    const vertexOrder = new Uint32Array(vertexColourOffsets[colours]);
+    const at = vertexColourOffsets.slice(0, colours);
+    for (let v = 0; v < n; v++)
+        if (colour[v] >= 0)
+            vertexOrder[at[colour[v]]++] = v;
+    return { vertexOrder, vertexColourOffsets };
+}
+/**
+ * Each triangle's membrane rest frame (ADR-0105): its edges in a 2D frame whose first axis is the
+ * warp (the direction of increasing u, in the triangle's plane; the first edge where the uvs are
+ * degenerate), inverted; then its area.
+ */
+function membraneFrames(p, idx, uvs) {
+    const t = idx.length / 3;
+    const out = new Float32Array(t * 5);
+    const x = (i) => [p[i * 3], p[i * 3 + 1], p[i * 3 + 2]];
+    for (let f = 0; f < t; f++) {
+        const [i0, i1, i2] = [idx[f * 3], idx[f * 3 + 1], idx[f * 3 + 2]];
+        const e1 = sub(x(i1), x(i0));
+        const e2 = sub(x(i2), x(i0));
+        const nrm = cross(e1, e2);
+        const a2 = len(nrm);
+        if (!(a2 > 1e-12))
+            continue; // degenerate: zero area, no membrane
+        const nn = nrm.map((v) => v / a2);
+        let axis = e1;
+        if (uvs) {
+            const du1 = uvs[i1 * 2] - uvs[i0 * 2];
+            const dv1 = uvs[i1 * 2 + 1] - uvs[i0 * 2 + 1];
+            const du2 = uvs[i2 * 2] - uvs[i0 * 2];
+            const dv2 = uvs[i2 * 2 + 1] - uvs[i0 * 2 + 1];
+            const det = du1 * dv2 - du2 * dv1;
+            // ∂p/∂u from the uv parametrisation.
+            if (Math.abs(det) > 1e-12)
+                axis = [0, 1, 2].map((k) => (dv2 * e1[k] - dv1 * e2[k]) / det);
+        }
+        const inPlane = sub(axis, nn.map((v) => v * dot(axis, nn)));
+        const la = len(inPlane);
+        const a = la > 1e-12 ? inPlane.map((v) => v / la) : e1.map((v) => v / len(e1));
+        const b = cross(nn, a);
+        const [m00, m01, m10, m11] = [dot(e1, a), dot(e2, a), dot(e1, b), dot(e2, b)];
+        const det = m00 * m11 - m01 * m10;
+        out.set([m11 / det, -m01 / det, -m10 / det, m00 / det, 0.5 * a2], f * 5);
+    }
+    return out;
+}
+/**
+ * Tethers (ADR-0105): for each free vertex, the pinned vertex nearest along the mesh's edges and
+ * that distance (Dijkstra from every pinned vertex at once). No pins: no tethers.
+ */
+function tethers(n, ids, kinds, rest, pinned) {
+    const tetherAnchor = new Uint32Array(n).fill(NO_VERTEX);
+    const tetherLength = new Float32Array(n);
+    const dist = new Float64Array(n).fill(Infinity);
+    const nb = Array.from({ length: n }, () => []);
+    for (let c = 0; c < kinds.length; c++) {
+        if (kinds[c] !== 0)
+            continue;
+        const [u, w, l] = [ids[c * 4], ids[c * 4 + 1], rest[c * 4]];
+        nb[u].push([w, l]);
+        nb[w].push([u, l]);
+    }
+    // A binary heap of (distance, vertex).
+    const heap = [];
+    const push = (d, v) => {
+        heap.push([d, v]);
+        for (let i = heap.length - 1; i > 0;) {
+            const pa = (i - 1) >> 1;
+            if (heap[pa][0] <= heap[i][0])
+                break;
+            [heap[pa], heap[i]] = [heap[i], heap[pa]];
+            i = pa;
+        }
+    };
+    const pop = () => {
+        const top = heap[0];
+        const last = heap.pop();
+        if (heap.length > 0) {
+            heap[0] = last;
+            for (let i = 0;;) {
+                const l = i * 2 + 1;
+                const r = l + 1;
+                let s = i;
+                if (l < heap.length && heap[l][0] < heap[s][0])
+                    s = l;
+                if (r < heap.length && heap[r][0] < heap[s][0])
+                    s = r;
+                if (s === i)
+                    break;
+                [heap[s], heap[i]] = [heap[i], heap[s]];
+                i = s;
+            }
+        }
+        return top;
+    };
+    for (let v = 0; v < n; v++) {
+        if (!pinned[v])
+            continue;
+        dist[v] = 0;
+        tetherAnchor[v] = v;
+        push(0, v);
+    }
+    while (heap.length > 0) {
+        const [d, v] = pop();
+        if (d > dist[v])
+            continue;
+        for (const [u, l] of nb[v]) {
+            if (d + l < dist[u]) {
+                dist[u] = d + l;
+                tetherAnchor[u] = tetherAnchor[v];
+                push(dist[u], u);
+            }
+        }
+    }
+    for (let v = 0; v < n; v++) {
+        if (pinned[v] || !Number.isFinite(dist[v]))
+            tetherAnchor[v] = NO_VERTEX;
+        else
+            tetherLength[v] = dist[v];
+    }
+    return { tetherAnchor, tetherLength };
+}
+/**
+ * The VBD section's header (ADR-0105), words from its start: where the triangles' rest frames, the
+ * vertex colours, the per-vertex bending and edge lists and the tethers are (words from the cloth's
+ * base; tethers 0: none), the vertex colour count, then the membrane's c11, c22, c12, c33 and the
+ * compression scale (f32); word 11: where the per-vertex skinned anchors are (ADR-0108; 0: none);
+  * word 12: where the compact tear flags are, one word per constraint in colour order, which the
+ * solver sets with the constraint's own flag so a readback is small (vertex splitting, ADR-0108);
+ * word 13: how many colour ranges are stretch constraints (the bending range follows, ADR-0110).
+ */
+export const VBD_HEADER = 16;
+/**
+ * Packs a topology for the GPU with a fabric at a uniform scale (the entity's): the rest
+ * positions (unscaled, the inverse masses in w), adjacency, triangles, colour ranges and the
+ * constraints in colour order with their compliances (shaders/kanduka/cloth.wesl `solve`).
+ */
+export function packCloth(topo, fabric, scale, tether = 0, anchors = null) {
+    const n = topo.vertices;
+    const m = topo.kinds.length;
+    const ncolours = topo.colourOffsets.length - 1;
+    const adj = n * 4;
+    const tris = adj + n + 1 + topo.adjacency.length;
+    const colours = tris + topo.triangles * 3;
+    const cons = colours + ncolours + 1;
+    const triEdges = cons + m * CONSTRAINT_WORDS;
+    // VBD (ADR-0105): the header, rest frames, vertex colours, per-vertex bending and edge lists, tethers.
+    let bendEntries = 0;
+    for (let c = 0; c < m; c++)
+        bendEntries += topo.kinds[c] === 1 ? 4 : 0;
+    const stretchRefs = (m - bendEntries / 4) * 2;
+    const nvc = topo.vertexColourOffsets.length - 1;
+    const vbd = triEdges + topo.triangles * 3;
+    const trest = vbd + VBD_HEADER;
+    const vcol = trest + topo.triangles * 5;
+    const bcsr = vcol + nvc + 1 + topo.vertexOrder.length;
+    const ecsr = bcsr + n + 1 + bendEntries;
+    const teth = tether > 0 ? ecsr + n + 1 + stretchRefs : 0;
+    const vbdEnd = (teth || ecsr + n + 1 + stretchRefs) + (teth ? n * 2 : 0);
+    // Skinned anchors (ADR-0108): per vertex its anchor record's index among the cloth's (NO_VERTEX: none).
+    const anch = anchors ? vbdEnd : 0;
+    const tornList = vbdEnd + (anchors ? n : 0);
+    const words = new Uint32Array(tornList + m);
+    const f = new Float32Array(words.buffer);
+    const invMass = new Float32Array(n);
+    const p = topo.mesh.positions;
+    for (let v = 0; v < n; v++) {
+        const mass = fabric.density * topo.area[v] * scale * scale;
+        invMass[v] = topo.pinned[v] || !(mass > 0) ? 0 : 1 / mass;
+        f.set([p[v * 3], p[v * 3 + 1], p[v * 3 + 2], invMass[v]], v * 4);
+    }
+    for (let v = 0; v <= n; v++)
+        words[adj + v] = n + 1 + topo.adjOffsets[v];
+    words.set(topo.adjacency, adj + n + 1);
+    words.set(topo.mesh.indices, tris);
+    words.set(topo.colourOffsets, colours);
+    // Each edge's stretch constraint, by (lo, hi): tearing breaks it, and its triangles and bending go with it.
+    const edgeAt = new Map();
+    for (let j = 0; j < m; j++) {
+        const c = topo.order[j];
+        if (topo.kinds[c] !== 0)
+            continue;
+        const [u, v] = [topo.vertexIds[c * 4], topo.vertexIds[c * 4 + 1]];
+        edgeAt.set(Math.min(u, v) * n + Math.max(u, v), cons + j * CONSTRAINT_WORDS);
+    }
+    const edge = (u, v) => edgeAt.get(Math.min(u, v) * n + Math.max(u, v)) ?? 0;
+    for (let j = 0; j < m; j++) {
+        const c = topo.order[j];
+        const o = cons + j * CONSTRAINT_WORDS;
+        words.set(topo.vertexIds.subarray(c * 4, c * 4 + 4), o);
+        if (topo.kinds[c] === 0) {
+            f[o + 4] = topo.rest[c * 4] * scale;
+            f[o + 5] = fabric.stretch;
+            f[o + 6] = fabric.compression;
+        }
+        else {
+            // √κ scales as 1 / scale (κ = 3 / area); the weights themselves are scale-free.
+            for (let k = 0; k < 4; k++)
+                f[o + 4 + k] = topo.rest[c * 4 + k] / scale;
+            f[o + 8] = fabric.bend;
+            words[o + 9] = edge(topo.vertexIds[c * 4], topo.vertexIds[c * 4 + 1]);
+        }
+    }
+    const ix = topo.mesh.indices;
+    for (let t = 0; t < topo.triangles; t++) {
+        const [a, b, c] = [ix[t * 3], ix[t * 3 + 1], ix[t * 3 + 2]];
+        words.set([edge(a, b), edge(b, c), edge(c, a)], triEdges + t * 3);
+    }
+    // VBD's header and the membrane (orthotropic StVK; ADR-0105).
+    const c11 = fabric.warp ?? 1 / Math.max(fabric.stretch, 1e-12);
+    const c22 = fabric.weft ?? c11;
+    const c33 = fabric.shear ?? c11 * 0.1;
+    const c12 = (fabric.poisson ?? 0.2) * Math.sqrt(c11 * c22);
+    words.set([trest, vcol, nvc, bcsr, ecsr, teth], vbd);
+    words[vbd + 11] = anch;
+    words[vbd + 12] = tornList;
+    words[vbd + 13] = topo.stretchColours;
+    if (anchors)
+        words.set(anchors, anch);
+    f.set([c11, c22, c12, c33, Math.min(1, fabric.stretch / Math.max(fabric.compression, 1e-12))], vbd + 6);
+    const rf = topo.restFrames;
+    for (let t = 0; t < topo.triangles; t++) {
+        // The inverse rest matrix scales as 1 / scale, the area as scale².
+        for (let k = 0; k < 4; k++)
+            f[trest + t * 5 + k] = rf[t * 5 + k] / scale;
+        f[trest + t * 5 + 4] = rf[t * 5 + 4] * scale * scale;
+    }
+    words.set(topo.vertexColourOffsets, vcol);
+    words.set(topo.vertexOrder, vcol + nvc + 1);
+    // Per-vertex lists, CSR like the adjacency: bending entries are (constraint word << 2 | slot),
+    // edge entries the stretch constraint's word.
+    const bendCount = new Uint32Array(n + 1);
+    const edgeCount = new Uint32Array(n + 1);
+    for (let j = 0; j < m; j++) {
+        const c = topo.order[j];
+        const vs = topo.vertexIds.subarray(c * 4, c * 4 + (topo.kinds[c] === 1 ? 4 : 2));
+        for (const v of vs)
+            (topo.kinds[c] === 1 ? bendCount : edgeCount)[v + 1]++;
+    }
+    for (let v = 0; v < n; v++) {
+        bendCount[v + 1] += bendCount[v];
+        edgeCount[v + 1] += edgeCount[v];
+    }
+    for (let v = 0; v <= n; v++) {
+        words[bcsr + v] = n + 1 + bendCount[v];
+        words[ecsr + v] = n + 1 + edgeCount[v];
+    }
+    const bf = bendCount.slice(0, n);
+    const ef = edgeCount.slice(0, n);
+    for (let j = 0; j < m; j++) {
+        const c = topo.order[j];
+        const o = cons + j * CONSTRAINT_WORDS;
+        if (topo.kinds[c] === 1)
+            for (let s = 0; s < 4; s++)
+                words[bcsr + n + 1 + bf[topo.vertexIds[c * 4 + s]]++] = (o << 2) | s;
+        else
+            for (let s = 0; s < 2; s++)
+                words[ecsr + n + 1 + ef[topo.vertexIds[c * 4 + s]]++] = o;
+    }
+    if (teth) {
+        for (let v = 0; v < n; v++) {
+            words[teth + v * 2] = topo.tetherAnchor[v];
+            f[teth + v * 2 + 1] = topo.tetherLength[v] * scale * (1 + tether);
+        }
+    }
+    return { words, tris, adj, colours, ncolours, cons, invMass, triEdges, vbd };
+}
+/**
+ * Splits a cloth mesh along torn edges (ADR-0108): around each vertex on a torn edge its triangles
+ * fall into pieces that meet only across torn edges (or not at all); the first piece keeps the
+ * vertex, each other piece gets a copy of it (appended, same rest position, uv and pin), and its
+ * triangles are re-indexed to it. The torn edges become two boundary edges, one per side, so the
+ * pieces separate cleanly. Null when nothing splits. `source[k]` is the vertex copy k came from.
+ */
+export function splitTorn(mesh, torn) {
+    const n = mesh.positions.length / 3;
+    const idx = mesh.indices.slice();
+    const cut = new Set();
+    const key = (a, b) => Math.min(a, b) * n + Math.max(a, b);
+    for (const [a, b] of torn)
+        cut.add(key(a, b));
+    if (cut.size === 0)
+        return null;
+    // A triangle torn on all three edges is gone (degenerate, as tearing drew it), not confetti: it
+    // would cost a new vertex per corner. The rest go in their vertices' fans.
+    const fan = Array.from({ length: n }, () => []);
+    let dropped = 0;
+    for (let f = 0; f < idx.length / 3; f++) {
+        const [a, b, c] = [idx[f * 3], idx[f * 3 + 1], idx[f * 3 + 2]];
+        if (a !== b && cut.has(key(a, b)) && cut.has(key(b, c)) && cut.has(key(c, a))) {
+            idx[f * 3 + 1] = idx[f * 3 + 2] = a;
+            dropped++;
+            continue;
+        }
+        if (a === b && b === c)
+            continue;
+        for (let k = 0; k < 3; k++)
+            fan[idx[f * 3 + k]].push(f);
+    }
+    const onCut = new Set();
+    for (const e of cut) {
+        const a = Math.floor(e / n);
+        onCut.add(a).add(e - a * n);
+    }
+    const source = [];
+    for (const v of onCut) {
+        const tris = fan[v];
+        if (tris.length < 2)
+            continue;
+        // Union-find over v's triangles: two join across an edge (v, w) both share that is not torn.
+        const parent = tris.map((_, i) => i);
+        const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+        const others = (f) => [idx[f * 3], idx[f * 3 + 1], idx[f * 3 + 2]].filter((x) => x !== v);
+        for (let i = 0; i < tris.length; i++) {
+            for (let j = i + 1; j < tris.length; j++) {
+                const shared = others(tris[i]).filter((w) => others(tris[j]).includes(w));
+                if (shared.some((w) => !cut.has(key(v, w))))
+                    parent[find(i)] = find(j);
+            }
+        }
+        const pieces = new Map();
+        tris.forEach((f, i) => {
+            const r = find(i);
+            const list = pieces.get(r);
+            if (list)
+                list.push(f);
+            else
+                pieces.set(r, [f]);
+        });
+        let first = true;
+        for (const list of pieces.values()) {
+            if (first) {
+                first = false;
+                continue;
+            }
+            const copy = n + source.length;
+            source.push(v);
+            for (const f of list)
+                for (let k = 0; k < 3; k++)
+                    if (idx[f * 3 + k] === v)
+                        idx[f * 3 + k] = copy;
+        }
+    }
+    if (source.length === 0 && dropped === 0)
+        return null;
+    const total = n + source.length;
+    const positions = new Float32Array(total * 3);
+    positions.set(mesh.positions);
+    const uvs = mesh.uvs ? new Float32Array(total * 2) : undefined;
+    uvs?.set(mesh.uvs);
+    const pinnedIn = new Set(Array.from(mesh.pinned ?? []));
+    const pinned = Array.from(pinnedIn);
+    source.forEach((v, k) => {
+        positions.set(mesh.positions.subarray(v * 3, v * 3 + 3), (n + k) * 3);
+        if (uvs)
+            uvs.set(mesh.uvs.subarray(v * 2, v * 2 + 2), (n + k) * 2);
+        if (pinnedIn.has(v))
+            pinned.push(n + k);
+    });
+    return { mesh: { positions, indices: idx, uvs, pinned }, source: Uint32Array.from(source) };
+}
+/**
+ * Bergou's bending weights for the stencil (edge x0–x1, opposite vertices x2 and x3), scaled by
+ * √κ, κ = 3 / (A0 + A1): `Σ k_i x_i` is the stencil's discrete mean-curvature vector, zero when
+ * the two triangles are flat. Null for a degenerate pair.
+ */
+export function bendWeights(p, i0, i1, i2, i3) {
+    const x = (i) => [p[i * 3], p[i * 3 + 1], p[i * 3 + 2]];
+    const [x0, x1, x2, x3] = [x(i0), x(i1), x(i2), x(i3)];
+    const e0 = sub(x1, x0);
+    const e1 = sub(x2, x0);
+    const e2 = sub(x3, x0);
+    const e3 = sub(x2, x1);
+    const e4 = sub(x3, x1);
+    const a0 = 0.5 * len(cross(e0, e1));
+    const a1 = 0.5 * len(cross(e0, e2));
+    if (!(a0 > 1e-12 && a1 > 1e-12))
+        return null;
+    const c01 = cot(e0, e1);
+    const c02 = cot(e0, e2);
+    const c03 = cot(neg(e0), e3);
+    const c04 = cot(neg(e0), e4);
+    const s = Math.sqrt(3 / (a0 + a1));
+    return [(c03 + c04) * s, (c01 + c02) * s, (-c01 - c03) * s, (-c02 - c04) * s];
+}
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const neg = (a) => [-a[0], -a[1], -a[2]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const len = (a) => Math.hypot(a[0], a[1], a[2]);
+const cot = (a, b) => dot(a, b) / len(cross(a, b));
+function dist(p, a, b) {
+    return Math.hypot(p[a * 3] - p[b * 3], p[a * 3 + 1] - p[b * 3 + 1], p[a * 3 + 2] - p[b * 3 + 2]);
+}
+function triArea(p, a, b, c) {
+    const x = (i) => [p[i * 3], p[i * 3 + 1], p[i * 3 + 2]];
+    return 0.5 * len(cross(sub(x(b), x(a)), sub(x(c), x(a))));
+}
+//# sourceMappingURL=cloth-asset.js.map