@yali-engine/physics 0.0.0-stage → 0.4.0

package/dist/character.d.ts

@@ -0,0 +1,129 @@
+import { type ComponentValues } from '@yali-engine/core';
+/** `physics.CharacterController`'s fields (ADR-0091), as the core declares them. */
+export declare const CHARACTER_FIELDS: {
+    readonly radius: "f32";
+    readonly height: "f32";
+    readonly crouchHeight: "f32";
+    readonly stepHeight: "f32";
+    readonly maxSlope: "f32";
+    readonly snapDistance: "f32";
+    readonly skin: "f32";
+    readonly gravity: "vec3<f32>";
+    readonly jumpSpeed: "f32";
+    readonly accel: "f32";
+    readonly airControl: "f32";
+    readonly pushForce: "f32";
+    readonly mode: "u8";
+    readonly crouch: "u8";
+    readonly wishVel: "vec3<f32>";
+    readonly jump: "u8";
+    readonly velocity: "vec3<f32>";
+    readonly grounded: "u8";
+    readonly groundNormal: "vec3<f32>";
+    readonly groundEntity: "entity";
+    readonly crouched: "u8";
+    readonly handle: "u32";
+};
+/** `physics.ForceField`'s fields. */
+export declare const FIELD_FIELDS: {
+    readonly kind: "u8";
+    readonly strength: "f32";
+    readonly radius: "f32";
+    readonly falloff: "f32";
+    readonly dir: "vec3<f32>";
+    readonly halfExtents: "vec3<f32>";
+    readonly density: "f32";
+    readonly drag: "f32";
+    readonly mask: "u32";
+};
+/** What `characterController` takes; every field optional (the defaults: a 1.8 m, 0.3 m capsule). */
+export interface CharacterOptions {
+    readonly radius?: number;
+    readonly height?: number;
+    readonly crouchHeight?: number;
+    /** Highest step it walks up (default 0.35 m). */
+    readonly stepHeight?: number;
+    /** Steepest walkable slope, radians (default 50°). */
+    readonly maxSlope?: number;
+    /** How far down it snaps to ground while walking (default 0.3 m). */
+    readonly snapDistance?: number;
+    readonly gravity?: readonly [number, number, number];
+    readonly jumpSpeed?: number;
+    /** Acceleration towards `wishVel` (m/s², default 40). */
+    readonly accel?: number;
+    /** Share of `accel` in the air (default 0.3). */
+    readonly airControl?: number;
+    /** Newtons per m/s it wants to go into a dynamic body (default 400). */
+    readonly pushForce?: number;
+    /** `'fly'`: no gravity, 3D `wishVel`. */
+    readonly mode?: 'walk' | 'fly';
+}
+/**
+ * `physics.CharacterController` values (ADR-0091): a kinematic capsule moved by sweeps, before the
+ * physics step. Its `Transform` is the feet. Steer it by writing `wishVel` (m/s; horizontal when
+ * walking), `jump` (1 for one step) and `crouch`; read `velocity`, `grounded`, `groundNormal`,
+ * `groundEntity`, `crouched`.
+ *
+ * @example
+ * world.insert(player, CharacterController, characterController({ stepHeight: 0.4 }));
+ * world.insert(player, CharacterController, { ...current, wishVel: [2, 0, 0], jump: 1 });
+ */
+export declare function characterController(o?: CharacterOptions): ComponentValues;
+/** `physics.ForceField.kind`. */
+export declare const FieldKind: {
+    readonly Directional: 0;
+    readonly Point: 1;
+    readonly Vortex: 2;
+    readonly Drag: 3;
+    readonly Buoyancy: 4;
+};
+/** A force field's shape and strength (ADR-0091). */
+export type ForceFieldOptions = 
+/** An acceleration (m/s²) along `dir`, within `radius`. */
+{
+    readonly directional: {
+        readonly dir: readonly [number, number, number];
+        readonly strength: number;
+        readonly radius: number;
+    };
+}
+/** Towards the field's centre (negative: away), within `radius`, falling off by `falloff`. */
+ | {
+    readonly point: {
+        readonly strength: number;
+        readonly radius: number;
+        readonly falloff?: number;
+    };
+}
+/** Around `axis` through the centre. */
+ | {
+    readonly vortex: {
+        readonly axis: readonly [number, number, number];
+        readonly strength: number;
+        readonly radius: number;
+        readonly falloff?: number;
+    };
+}
+/** Against the velocity, `strength` per second. */
+ | {
+    readonly drag: {
+        readonly strength: number;
+        readonly radius: number;
+    };
+}
+/** Water: a box of `halfExtents` around the field's centre (its top is the surface). */
+ | {
+    readonly buoyancy: {
+        readonly halfExtents: readonly [number, number, number];
+        readonly density?: number;
+        readonly drag?: number;
+    };
+};
+/**
+ * `physics.ForceField` values: put on an entity with a `Transform` (its centre); it acts on the
+ * dynamic bodies in its region every step.
+ *
+ * @example
+ * world.insert(pool, ForceField, forceField({ buoyancy: { halfExtents: [10, 2, 10], drag: 3 } }));
+ */
+export declare function forceField(o: ForceFieldOptions, mask?: number): ComponentValues;

package/dist/character.js

@@ -0,0 +1,96 @@
+import { YaliError } from '@yali-engine/core';
+/** `physics.CharacterController`'s fields (ADR-0091), as the core declares them. */
+export const CHARACTER_FIELDS = {
+    radius: 'f32',
+    height: 'f32',
+    crouchHeight: 'f32',
+    stepHeight: 'f32',
+    maxSlope: 'f32',
+    snapDistance: 'f32',
+    skin: 'f32',
+    gravity: 'vec3<f32>',
+    jumpSpeed: 'f32',
+    accel: 'f32',
+    airControl: 'f32',
+    pushForce: 'f32',
+    mode: 'u8',
+    crouch: 'u8',
+    wishVel: 'vec3<f32>',
+    jump: 'u8',
+    velocity: 'vec3<f32>',
+    grounded: 'u8',
+    groundNormal: 'vec3<f32>',
+    groundEntity: 'entity',
+    crouched: 'u8',
+    handle: 'u32',
+};
+/** `physics.ForceField`'s fields. */
+export const FIELD_FIELDS = {
+    kind: 'u8',
+    strength: 'f32',
+    radius: 'f32',
+    falloff: 'f32',
+    dir: 'vec3<f32>',
+    halfExtents: 'vec3<f32>',
+    density: 'f32',
+    drag: 'f32',
+    mask: 'u32',
+};
+/**
+ * `physics.CharacterController` values (ADR-0091): a kinematic capsule moved by sweeps, before the
+ * physics step. Its `Transform` is the feet. Steer it by writing `wishVel` (m/s; horizontal when
+ * walking), `jump` (1 for one step) and `crouch`; read `velocity`, `grounded`, `groundNormal`,
+ * `groundEntity`, `crouched`.
+ *
+ * @example
+ * world.insert(player, CharacterController, characterController({ stepHeight: 0.4 }));
+ * world.insert(player, CharacterController, { ...current, wishVel: [2, 0, 0], jump: 1 });
+ */
+export function characterController(o = {}) {
+    const radius = o.radius ?? 0.3;
+    const height = o.height ?? 1.8;
+    if (!(radius > 0) || !(height >= 2 * radius)) {
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `A controller of radius ${radius} and height ${height}.`, 'Give a positive radius and a height of at least twice it.'), { path: o.radius !== undefined && !(radius > 0) ? 'radius' : 'height' });
+    }
+    return {
+        radius,
+        height,
+        crouchHeight: o.crouchHeight ?? Math.max(2 * radius, 1),
+        stepHeight: o.stepHeight ?? 0.35,
+        maxSlope: o.maxSlope ?? (50 * Math.PI) / 180,
+        snapDistance: o.snapDistance ?? 0.3,
+        skin: 0.02,
+        gravity: o.gravity ?? [0, -9.81, 0],
+        jumpSpeed: o.jumpSpeed ?? 5,
+        accel: o.accel ?? 40,
+        airControl: o.airControl ?? 0.3,
+        pushForce: o.pushForce ?? 400,
+        mode: o.mode === 'fly' ? 2 : 0,
+        groundNormal: [0, 1, 0],
+        groundEntity: 0xffffffff,
+    };
+}
+/** `physics.ForceField.kind`. */
+export const FieldKind = { Directional: 0, Point: 1, Vortex: 2, Drag: 3, Buoyancy: 4 };
+/**
+ * `physics.ForceField` values: put on an entity with a `Transform` (its centre); it acts on the
+ * dynamic bodies in its region every step.
+ *
+ * @example
+ * world.insert(pool, ForceField, forceField({ buoyancy: { halfExtents: [10, 2, 10], drag: 3 } }));
+ */
+export function forceField(o, mask = 0xffffffff) {
+    const base = { strength: 0, radius: 0, falloff: 0, dir: [0, 0, 0], halfExtents: [0, 0, 0], density: 0, drag: 0, mask };
+    if ('directional' in o)
+        return { ...base, kind: FieldKind.Directional, dir: o.directional.dir, strength: o.directional.strength, radius: o.directional.radius };
+    if ('point' in o)
+        return { ...base, kind: FieldKind.Point, strength: o.point.strength, radius: o.point.radius, falloff: o.point.falloff ?? 1 };
+    if ('vortex' in o)
+        return { ...base, kind: FieldKind.Vortex, dir: o.vortex.axis, strength: o.vortex.strength, radius: o.vortex.radius, falloff: o.vortex.falloff ?? 1 };
+    if ('drag' in o)
+        return { ...base, kind: FieldKind.Drag, strength: o.drag.strength, radius: o.drag.radius };
+    if ('buoyancy' in o)
+        return { ...base, kind: FieldKind.Buoyancy, halfExtents: o.buoyancy.halfExtents, density: o.buoyancy.density ?? 1000, drag: o.buoyancy.drag ?? 1 };
+    throw Object.assign(new YaliError('PHYSICS_INVALID', 'A force field needs one of directional, point, vortex, drag, buoyancy.', 'Pass e.g. forceField({ point: { strength: 10, radius: 5 } }).'), { path: 'kind' });
+}
+//# sourceMappingURL=character.js.map

package/dist/character.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character.js","sourceRoot":"","sources":["../src/character.ts"],"names":[],"mappings":"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"}

package/dist/cloth-asset.d.ts

@@ -0,0 +1,296 @@
+/** A cloth's rest mesh, in its entity's mesh space. */
+export interface ClothMesh {
+    /** xyz per vertex. */
+    readonly positions: Float32Array;
+    /** Triangles, counter-clockwise from the front. */
+    readonly indices: Uint32Array;
+    /** uv per vertex (default 0). */
+    readonly uvs?: Float32Array;
+    /** Vertices held to the entity (they follow its pose). */
+    readonly pinned?: ArrayLike<number>;
+}
+/** The solver's view of a cloth mesh (`clothTopology`). */
+export interface ClothTopology {
+    readonly mesh: ClothMesh;
+    readonly vertices: number;
+    readonly triangles: number;
+    /** 1 for a pinned vertex. */
+    readonly pinned: Uint8Array;
+    /** A third of the area of the triangles around each vertex (m², unscaled): its share of the mass. */
+    readonly area: Float64Array;
+    /** Vertex → triangles (CSR): `adjacency[adjOffsets[v] .. adjOffsets[v + 1]]`. */
+    readonly adjOffsets: Uint32Array;
+    readonly adjacency: Uint32Array;
+    /** Constraints: `kinds[c]` 0 stretch (edge), 1 bending (stencil); four vertices each (stretch: the last two unused). */
+    readonly kinds: Uint8Array;
+    readonly vertexIds: Uint32Array;
+    /** Stretch: the rest length; bending: Bergou's four cotangent weights, scaled by √κ (`κ = 3 / (A0 + A1)`). Unscaled mesh units. */
+    readonly rest: Float32Array;
+    /** Constraint ids in colour order, and where each colour starts (`colourOffsets[k] .. [k + 1]`). */
+    readonly order: Uint32Array;
+    readonly colourOffsets: Uint32Array;
+    /** How many of the colour ranges are stretch constraints (the rest, one range, the bending stencils; ADR-0110). */
+    readonly stretchColours: number;
+    /**
+     * VBD (ADR-0105): the free vertices in colour order (no two of a colour share a triangle or a
+     * bending stencil), and where each colour starts (`vertexColourOffsets[k] .. [k + 1]`).
+     */
+    readonly vertexOrder: Uint32Array;
+    readonly vertexColourOffsets: Uint32Array;
+    /**
+     * Each triangle's rest frame for the membrane (ADR-0105): the inverse of its 2 × 2 rest edge
+     * matrix in the pattern frame (warp along +u, weft across it), row-major, then its area: five
+     * floats a triangle, unscaled mesh units.
+     */
+    readonly restFrames: Float32Array;
+    /** Tethers (ADR-0105): each vertex's nearest pinned vertex over the mesh (NO_VERTEX: none) and that geodesic length (unscaled). */
+    readonly tetherAnchor: Uint32Array;
+    readonly tetherLength: Float32Array;
+}
+/** Marks a constraint's unused vertex slots. */
+export declare const NO_VERTEX = 4294967295;
+/** Words per packed constraint (`solve` in shaders/kanduka/cloth.wesl). */
+export declare const CONSTRAINT_WORDS = 12;
+/**
+ * A fabric: what the solver needs to know about a material (ADR-0101). Compliances are XPBD's
+ * (the inverse of a stiffness): 0 is perfectly stiff.
+ */
+export interface ClothFabric {
+    /** Mass per area, kg/m². */
+    readonly density: number;
+    /** Stretch compliance (m/N), and the far softer compression compliance (cloth buckles instead). */
+    readonly stretch: number;
+    readonly compression: number;
+    /** Bending compliance (1/(N·m)): the inverse of the bending stiffness. */
+    readonly bend: number;
+    /** Velocity damping, 1/s (the air does most of it). */
+    readonly damping: number;
+    /** Friction against colliders (combined with theirs as √(μa μb)). */
+    readonly friction: number;
+    /** How far from a collider the cloth stays, m. */
+    readonly thickness: number;
+    /** Drag coefficients across the surface (pressure) and along it (skin friction). */
+    readonly drag: number;
+    readonly skinDrag: number;
+    /**
+     * The VBD membrane (ADR-0105, orthotropic StVK in the pattern frame), N/m: stiffness along the
+     * warp (+u), along the weft (+v), and in shear; `poisson` couples warp and weft. Defaults:
+     * warp 1 / `stretch`, weft = warp, shear a tenth of it, poisson 0.2. XPBD ignores them.
+     */
+    readonly warp?: number;
+    readonly weft?: number;
+    readonly shear?: number;
+    readonly poisson?: number;
+}
+/**
+ * A fabric's KES-F (Kawabata) measurements, as textile papers report them. A pair is (warp, weft);
+ * one number is both.
+ */
+export interface KesFabric {
+    /** Areal weight W, g/m² (KES-F's mg/cm² × 10). */
+    readonly weight: number;
+    /** Bending rigidity B, gf·cm²/cm. */
+    readonly bending: number | readonly [number, number];
+    /** Shear rigidity G, gf/(cm·degree). */
+    readonly shear: number | readonly [number, number];
+    /** The tensile test: extension at the maximum load EMT (%), its linearity LT, the load (gf/cm, KES-F's default 500). */
+    readonly tensile?: {
+        readonly emt: number | readonly [number, number];
+        readonly lt: number | readonly [number, number];
+        readonly load?: number;
+    };
+}
+/**
+ * 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 declare const STENCIL_BEND = 3.69;
+/**
+ * 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 declare function fabricFromKes(kes: KesFabric, base: ClothFabric): ClothFabric;
+/**
+ * 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 declare 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). */
+    readonly silk: {
+        readonly weight: 72.067;
+        readonly bending: readonly [0.019, 0.063];
+        readonly shear: readonly [0.23, 0.26];
+        readonly tensile: {
+            readonly emt: readonly [7.11, 1.723];
+            readonly lt: readonly [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. */
+    readonly cotton: {
+        readonly weight: 138.6;
+        readonly bending: 0.07;
+        readonly 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). */
+    readonly denim: {
+        readonly weight: 246;
+        readonly bending: 0.172;
+        readonly shear: 2.18;
+        readonly tensile: {
+            readonly emt: 5.515;
+            readonly 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). */
+    readonly canvas: {
+        readonly weight: 279;
+        readonly bending: readonly [0.33, 0.275];
+        readonly shear: readonly [4.58, 4.41];
+        readonly tensile: {
+            readonly emt: readonly [4.16, 8.03];
+            readonly lt: readonly [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. */
+    readonly leather: {
+        readonly weight: 706.47;
+        readonly bending: 2.67;
+        readonly 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 declare const FABRICS: {
+    readonly silk: ClothFabric;
+    readonly cotton: ClothFabric;
+    readonly canvas: {
+        readonly density: 0.22;
+        readonly stretch: 0.00005;
+        readonly compression: 0.002;
+        readonly bend: 5000;
+        readonly damping: 0.05;
+        readonly friction: 0.5;
+        readonly thickness: 0.008;
+        readonly drag: 1.2;
+        readonly skinDrag: 0.03;
+        readonly warp: 20000;
+        readonly weft: 18000;
+        readonly shear: 2500;
+        readonly poisson: 0.2;
+    };
+    readonly denim: ClothFabric;
+    readonly leather: {
+        readonly density: 0.9;
+        readonly stretch: 0.00001;
+        readonly compression: 0.0005;
+        readonly bend: 300;
+        readonly damping: 0.1;
+        readonly friction: 0.7;
+        readonly thickness: 0.012;
+        readonly drag: 1;
+        readonly skinDrag: 0.05;
+        readonly warp: 100000;
+        readonly weft: 100000;
+        readonly shear: 35000;
+        readonly poisson: 0.4;
+    };
+};
+/** A preset's name. */
+export type FabricName = keyof typeof FABRICS;
+/** What `clothGrid` takes. */
+export interface ClothGridOptions {
+    /** Size in metres (along X, then along Y or Z). */
+    readonly width: number;
+    readonly height: number;
+    /** Quads along each side (default about 32 per metre, at least 2). */
+    readonly segments?: readonly [number, number];
+    /** `xy`: hanging, facing +Z (a flag, a curtain); `xz`: lying flat, facing +Y (a sheet). Default `xy`. */
+    readonly plane?: 'xy' | 'xz';
+    /**
+     * Which vertices hold: `top` (the edge at +Y, or −Z for `xz`), `left` (the edge at −X),
+     * `corners` (the two top corners), `none`, or a test on (u, v), each 0–1 from the left and top.
+     */
+    readonly pin?: 'top' | 'left' | 'corners' | 'none' | ((u: number, v: number) => boolean);
+}
+/**
+ * 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 declare function clothGrid(o: ClothGridOptions): ClothMesh;
+/**
+ * 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 declare function clothTopology(mesh: ClothMesh): ClothTopology;
+/** Where each part of a packed cloth starts, in words from its base (the `Cloth` struct's offsets). */
+export interface PackedCloth {
+    readonly words: Uint32Array;
+    readonly tris: number;
+    readonly adj: number;
+    readonly colours: number;
+    readonly ncolours: number;
+    readonly cons: number;
+    /** The inverse mass of each vertex (0: pinned). */
+    readonly invMass: Float32Array;
+    /** Where each triangle's three edge constraints are listed (words from the base): tearing (ADR-0104). */
+    readonly triEdges: number;
+    /** Where the VBD section's header starts (words from the base; ADR-0105, `VBD_HEADER`). */
+    readonly vbd: number;
+}
+/**
+ * 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 declare 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 declare function packCloth(topo: ClothTopology, fabric: ClothFabric, scale: number, tether?: number, anchors?: Uint32Array | null): PackedCloth;
+/**
+ * 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 declare function splitTorn(mesh: ClothMesh, torn: Iterable<readonly [number, number]>): {
+    mesh: ClothMesh;
+    source: Uint32Array;
+} | null;
+/**
+ * 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 declare function bendWeights(p: Float32Array, i0: number, i1: number, i2: number, i3: number): [number, number, number, number] | null;