@woosh/meep-engine 3.44.0 → 3.45.0

package/src/engine/graphics3/AnimationSystem.js

@@ -7,7 +7,8 @@ import { System } from "../ecs/System.js";
 import { AnimationClips } from "./animation/AnimationClips.js";
 import { ClipListPlayer } from "./animation/ClipListPlayer.js";
 import { write_clip_playback } from "./animation/write_clip_playback.js";
-import { register_clips, unregister_clips } from "./register_clips.js";
+import { hold_clip_targets, register_clips, release_clip_targets, unregister_clips } from "./register_clips.js";
+import { RowChains } from "./RowChains.js";
 
 /**
  * @type {ClipPlayback[]}
@@ -27,6 +28,10 @@ const NOTHING = Object.freeze([]);
  * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
  * clips are a new component, which this system sees as the entity leaving and coming back.
  *
+ * **Every node the clips key holds a row here** ({@link hold_clip_targets}), from the clips being
+ * taken up until they go. A clip binds only once all of them do, and a keyed node outside every skin
+ * with nothing drawn under it is held by no other system.
+ *
  * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
  * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
  * clip's time is written down each frame from the player's own clock. That is I-4: the pose
@@ -51,10 +56,17 @@ export class AnimationSystem extends System {
     #scene;
 
     /**
-     * @type {Map<number, {player: ClipListPlayer, clips: ShadeAnimationClip[], bound: boolean, clip_registration: ClipRegistration|null, played_slots: Int32Array, written: Float32Array, poses: PosePlayback[]}>}
+     * @type {Map<number, {player: ClipListPlayer, clips: ShadeAnimationClip[], bound: boolean, held: boolean, clip_registration: ClipRegistration|null, played_slots: Int32Array, written: Float32Array, poses: PosePlayback[]}>}
      */
     #entries = new Map();
 
+    /**
+     * The chains of the nodes the clips key. Null until the system has a dataset.
+     *
+     * @type {RowChains|null}
+     */
+    #chains = null;
+
     /**
      * @param {GraphicsEngine} graphics
      * @param {Scene} scene
@@ -169,6 +181,7 @@ export class AnimationSystem extends System {
             player: ClipListPlayer.from(component),
             clips: clips.clips,
             bound: false,
+            held: false,
             clip_registration: null,
             played_slots: new Int32Array(0),
             written: new Float32Array(0),
@@ -186,17 +199,41 @@ export class AnimationSystem extends System {
 
         if (entry !== undefined) {
             this.#release_clips(entry);
+
+            if (entry.held) {
+                release_clip_targets(this.#chains, entry.clips);
+
+                entry.held = false;
+            }
         }
 
         this.#entries.delete(entity);
     }
 
+    async startup(entityManager) {
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        const dataset = entityManager.dataset;
+        const scene = this.#scene;
+
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        scene.dataset = dataset;
+
+        this.#chains = new RowChains(dataset);
+    }
+
     async shutdown(entityManager) {
         for (const entry of this.#entries.values()) {
             this.#release_clips(entry);
         }
 
         this.#entries.clear();
+
+        this.#chains.destroy();
+        this.#chains = null;
     }
 
     /**
@@ -328,6 +365,11 @@ export class AnimationSystem extends System {
         entry.poses = clips.map(() => new PosePlayback());
 
         entry.bound = true;
+
+        // before anything registers, so the clips bind in the update that registers them
+        hold_clip_targets(this.#chains, clips);
+
+        entry.held = true;
     }
 
     /**
@@ -342,6 +384,9 @@ export class AnimationSystem extends System {
         // that ends while the renderer is being replaced still says so.
         const manager = context === null ? null : context.animation_manager;
 
+        // a new context after a restart is acquired in whole; until there is one, holds are recorded
+        this.#chains.bind(context === null ? null : context.rows);
+
         for (const [entity, entry] of this.#entries) {
             if (!entry.bound) {
                 this.#bind(entry, entity, ecd);

package/src/engine/graphics3/register_clips.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Hold a row, with the chain above it, for every entity the clips key.
+ *
+ * **A clip binds only once every node it keys holds a row**, and until then it is queued and moves
+ * nothing. A skin holds its joints' chains and a primitive its own, but a keyed node that is neither
+ * — a leaf an exporter left out of the skin, a socket nothing is attached to yet, an animated empty
+ * — is held by nothing else, and one such node keeps the whole clip from playing. So the driver that
+ * plays the clips holds every node they key, for as long as it has the clips.
+ *
+ * Every clip of the set, not only the ones registered: the set is replaced and never edited, so its
+ * targets are settled once, while which of its clips are registered moves with the list or the graph.
+ *
+ * One hold per channel, given back one per channel by {@link release_clip_targets}: the chains count
+ * holds, so a node keyed by several channels is held until the last of them is released.
+ *
+ * @param {RowChains} chains
+ * @param {ShadeAnimationClip[]} clips their channels target entities
+ */
+export function hold_clip_targets(chains: RowChains, clips: ShadeAnimationClip[]): void;
+/**
+ * Give back what {@link hold_clip_targets} took for the same clips. Released after the clips are
+ * unregistered, so no binding outlives the row it writes.
+ *
+ * @param {RowChains} chains
+ * @param {ShadeAnimationClip[]} clips
+ */
+export function release_clip_targets(chains: RowChains, clips: ShadeAnimationClip[]): void;
 /**
  * Make some of an entity's clips playable — the ones a driver actually plays, and no others.
  *
@@ -28,6 +55,7 @@ export function unregister_clips(registration: ClipRegistration): void;
 /**
  * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
  * @typedef {import("../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("./RowChains.js").RowChains} RowChains
  */
 /**
  * The id a clip has when nobody registered it.
@@ -61,4 +89,5 @@ export class ClipRegistration {
 }
 export type GPUSceneContext = import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
 export type ShadeAnimationClip = import("../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip;
+export type RowChains = import("./RowChains.js").RowChains;
 //# sourceMappingURL=register_clips.d.ts.map

package/src/engine/graphics3/register_clips.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register_clips.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/register_clips.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;GAgBG;AACH,wCALW,eAAe,SACf,kBAAkB,EAAE,SACpB,UAAU,MAAM,CAAC,GACf,gBAAgB,CA6B5B;AAED;;;;;;;GAOG;AACH,+CAFW,gBAAgB,QAqB1B;AA/GD;;;GAGG;AAEH;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH;IACI;;;;;;;;;OASG;IACH,SAFU,eAAe,GAAC,IAAI,CAEf;IAEf;;OAEG;IACH,KAFU,UAAU,CAEI;CAC3B;8BAnCY,OAAO,+CAA+C,EAAE,eAAe;iCACvE,OAAO,sDAAsD,EAAE,kBAAkB"}
+{"version":3,"file":"register_clips.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/register_clips.js"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAHW,SAAS,SACT,kBAAkB,EAAE,QAa9B;AAED;;;;;;GAMG;AACH,6CAHW,SAAS,SACT,kBAAkB,EAAE,QAa9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wCALW,eAAe,SACf,kBAAkB,EAAE,SACpB,UAAU,MAAM,CAAC,GACf,gBAAgB,CA6B5B;AAED;;;;;;;GAOG;AACH,+CAFW,gBAAgB,QAqB1B;AAnKD;;;;GAIG;AAEH;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH;IACI;;;;;;;;;OASG;IACH,SAFU,eAAe,GAAC,IAAI,CAEf;IAEf;;OAEG;IACH,KAFU,UAAU,CAEI;CAC3B;8BApCY,OAAO,+CAA+C,EAAE,eAAe;iCACvE,OAAO,sDAAsD,EAAE,kBAAkB;wBACjF,OAAO,gBAAgB,EAAE,SAAS"}

package/src/engine/graphics3/register_clips.js

@@ -3,6 +3,7 @@ import { assert } from "../../core/assert.js";
 /**
  * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
  * @typedef {import("../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("./RowChains.js").RowChains} RowChains
  */
 
 /**
@@ -38,6 +39,57 @@ export class ClipRegistration {
     ids = new Int32Array(0);
 }
 
+/**
+ * Hold a row, with the chain above it, for every entity the clips key.
+ *
+ * **A clip binds only once every node it keys holds a row**, and until then it is queued and moves
+ * nothing. A skin holds its joints' chains and a primitive its own, but a keyed node that is neither
+ * — a leaf an exporter left out of the skin, a socket nothing is attached to yet, an animated empty
+ * — is held by nothing else, and one such node keeps the whole clip from playing. So the driver that
+ * plays the clips holds every node they key, for as long as it has the clips.
+ *
+ * Every clip of the set, not only the ones registered: the set is replaced and never edited, so its
+ * targets are settled once, while which of its clips are registered moves with the list or the graph.
+ *
+ * One hold per channel, given back one per channel by {@link release_clip_targets}: the chains count
+ * holds, so a node keyed by several channels is held until the last of them is released.
+ *
+ * @param {RowChains} chains
+ * @param {ShadeAnimationClip[]} clips their channels target entities
+ */
+export function hold_clip_targets(chains, clips) {
+    assert.defined(chains, 'chains');
+    assert.isArray(clips, 'clips');
+
+    for (let i = 0; i < clips.length; i++) {
+        const channels = clips[i].channels;
+
+        for (let j = 0; j < channels.length; j++) {
+            chains.hold(channels[j].target);
+        }
+    }
+}
+
+/**
+ * Give back what {@link hold_clip_targets} took for the same clips. Released after the clips are
+ * unregistered, so no binding outlives the row it writes.
+ *
+ * @param {RowChains} chains
+ * @param {ShadeAnimationClip[]} clips
+ */
+export function release_clip_targets(chains, clips) {
+    assert.defined(chains, 'chains');
+    assert.isArray(clips, 'clips');
+
+    for (let i = 0; i < clips.length; i++) {
+        const channels = clips[i].channels;
+
+        for (let j = 0; j < channels.length; j++) {
+            chains.release(channels[j].target);
+        }
+    }
+}
+
 /**
  * Make some of an entity's clips playable — the ones a driver actually plays, and no others.
  *

package/src/engine/physics/broadphase/compute_fat_world_aabb.d.ts

@@ -50,4 +50,13 @@ export function fatten_world_aabb_array(aabb: number[] | Float32Array | Float64A
  * @param {number} dt step size
  */
 export function compute_fat_world_aabb(result: number[] | Float32Array | Float64Array, result_offset: number, shape: AbstractShape3D, transform: Transform64, vx: number, vy: number, vz: number, dt: number): void;
+/**
+ * Constant inflation applied to a world AABB so a small motion doesn't churn
+ * the broadphase. Tuned to Box2D / Bullet conventions. Symmetric: jitter has
+ * no preferred direction.
+ *
+ * Exported because `ClothColliderIndex` fattens its leaves by the same slack, for the same reason.
+ * @type {number}
+ */
+export const FAT_LINEAR: number;
 //# sourceMappingURL=compute_fat_world_aabb.d.ts.map

package/src/engine/physics/broadphase/compute_fat_world_aabb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute_fat_world_aabb.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/compute_fat_world_aabb.js"],"names":[],"mappings":"AAuBA;;;;;;;;GAQG;AACH,2CALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,wDAchB;AAED;;;;;;;;;;;;;GAaG;AACH,wCAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAUhB;AAKD;;;;;;;;;;GAUG;AACH,8CANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UAClC,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,mBAClC,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;GAaG;AACH,+CATW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,sDAGN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAShB"}
+{"version":3,"file":"compute_fat_world_aabb.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/compute_fat_world_aabb.js"],"names":[],"mappings":"AAyBA;;;;;;;;GAQG;AACH,2CALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,wDAchB;AAED;;;;;;;;;;;;;GAaG;AACH,wCAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAUhB;AAKD;;;;;;;;;;GAUG;AACH,8CANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UAClC,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,mBAClC,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;GAaG;AACH,+CATW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,sDAGN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAShB;AAvHD;;;;;;;GAOG;AACH,yBAFU,MAAM,CAEe"}

package/src/engine/physics/broadphase/compute_fat_world_aabb.js

@@ -6,9 +6,11 @@ const scratch_local = new Float64Array(6);
  * Constant inflation applied to a world AABB so a small motion doesn't churn
  * the broadphase. Tuned to Box2D / Bullet conventions. Symmetric: jitter has
  * no preferred direction.
+ *
+ * Exported because `ClothColliderIndex` fattens its leaves by the same slack, for the same reason.
  * @type {number}
  */
-const FAT_LINEAR = 0.05;
+export const FAT_LINEAR = 0.05;
 
 /**
  * Per-second-of-velocity inflation. Two seconds of motion is a generous

package/src/engine/physics/cloth/PLAN.md

@@ -270,7 +270,7 @@ export class ClothCollider {
     friction_scale = 1;  // multiplies the entity's Collider#friction
     layer = 1;           // RigidBody semantics, and see below
     mask = 0xFFFFFFFF;
-    flags = 0;           // ClothColliderFlags.Static
+    flags = 0;           // ClothColliderFlags: none defined; bit 0 was Static, retired
 }
 ```
 
@@ -675,10 +675,12 @@ bundles — the engine ships raw source, and a check moved out of `assert.*` sto
 ### 5.4 Colouring
 
 The particle graph is coloured so no constraint touches two particles of the same colour, using the
-existing `core/graph/coloring/colorizeGraphGreedy.js` and checked by the existing
-`validateGraphColoring.js`. Bending stencils span four particles, so the graph is the mesh graph plus
-the bend diagonals — around 8–10 colours for typical garment topology. Colouring runs once, on a
-`Graph` object, and is baked into the `ClothProxy` as colour ranges over a permuted particle order;
+greedy colouring in `core/graph/csr/csr_graph_color_greedy.js` and checked by
+`csr_graph_validate_coloring.js`, over the deduplicated particle-coupling CSR that
+`solver/cloth_particle_coupling.js` builds (the object `Graph` route was O(n²·degree): 134 ms → 3.5 ms
+on a 64×64 sheet, same colours). Bending stencils span four particles, so the graph is the mesh graph plus
+the bend diagonals — around 8–10 colours for typical garment topology. Colouring runs once, on that
+CSR, and is baked into the `ClothProxy` as colour ranges over a permuted particle order;
 for a chain it runs at link time on a graph of a few dozen nodes. Nothing colours per step and the
 runtime never sees a graph object.
 
@@ -1620,7 +1622,7 @@ For a **rigged** garment, only steps 5–8 run, over the joint graph rather than
    (`cloth_rig.spec.js`).
 6. Bake `d_geo` — geodesic distance from every particle to the fixed set. This one array drives the
    tether row, the slack profile, and the pinning, so the three cannot disagree.
-7. Colour the particle graph (`colorizeGraphGreedy`, checked by `validateGraphColoring`), and permute
+7. Colour the particle graph (`csr_graph_color_greedy`, checked by `csr_graph_validate_coloring`), and permute
    the particle order so each colour is a contiguous range.
 8. Resolve joint **names to indices** into `Skin#joints`, using `SceneBundleInstance#nodes`. This is
    the only place a name appears anywhere in the system.
@@ -1803,9 +1805,9 @@ What this design takes from the engine rather than building:
 | Mesh topology, adjacency, bending stencils | `core/geom/3d/topology/struct/binary/` — `BinaryTopology`, `bt_edge_read_diamond`, `bt_edge_is_boundary`, `bt_collect_boundary_segments` |
 | Proxy decimation | `bt_mesh_simplify_by_error`, `bt_mesh_compute_vertex_quadrics` |
 | Mesh cleanup | `geometry_deduplicate_vertices` |
-| Graph colouring | `core/graph/coloring/colorizeGraphGreedy.js`, `validateGraphColoring.js` |
+| Graph colouring | `core/graph/csr/csr_graph_color_greedy.js`, `csr_graph_validate_coloring.js` |
 | Collider shapes and their SDFs | `core/geom/3d/shape/*` — closed-form `signed_distance_at_point` on every primitive |
-| Collider AABBs, pose caching | `core/geom/3d/aabb/*`, `aabb3_matrix4_project` |
+| Collider AABBs, pose caching | `core/geom/3d/aabb/*`, `aabb3_transform_oriented_array` |
 | Collider ECS wiring | `Collider`, `ColliderFlags`, `ColliderObserverSystem` (as the pattern) |
 | "Opt a collider into a second simulation" | `FluidObstacle` + `FluidObstacleSystem`, `AcousticBody` |
 | Collider index shape | `AcousticOccluderIndex` + `OccluderBody` |

package/src/engine/physics/cloth/build/cloth_bind_in_frame.d.ts

@@ -10,6 +10,12 @@
  * bind pose — so that a re-seed reads what was authored rather than what the
  * solver left on the joints.
  *
+ * Rigid, as every pose cloth holds is: a local scale is not applied. That is
+ * not a convention this can opt out of alone — the write-back is rigid too,
+ * and the GPU applies a parent's scale on top of what cloth writes, so a
+ * scaled bake would draw a scaled link twice over. A builder refuses a rig
+ * where it would matter, with {@link cloth_bind_scaled_above}.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  *
@@ -18,5 +24,21 @@
  * @returns {function(number): Float64Array}
  */
 export function cloth_bind_in_frame(prefab: Prefab, frame: number): (arg0: number) => Float64Array;
+/**
+ * The nearest node above `node`, up to and including the prefab's root, whose
+ * rest scale is not one; or -1.
+ *
+ * Cloth simulates and writes back rigid poses, and everything under a scaled
+ * node is drawn scaled: a link below one is simulated at its authored length and
+ * drawn at that times the scale, and a scale above the frame draws the whole
+ * garment at another size than the one its colliders meet. Measured, a 10 cm
+ * chain under a joint scaled by 2: simulated links 0.1, drawn 0.2. A node's own
+ * scale moves nothing cloth places, so it is not asked about.
+ *
+ * @param {Prefab} prefab
+ * @param {number} node
+ * @returns {number}
+ */
+export function cloth_bind_scaled_above(prefab: Prefab, node: number): number;
 export type Prefab = import("../../../graphics3/prefab/Prefab.js").Prefab;
 //# sourceMappingURL=cloth_bind_in_frame.d.ts.map

package/src/engine/physics/cloth/build/cloth_bind_in_frame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_bind_in_frame.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_bind_in_frame.js"],"names":[],"mappings":"AAOA;;GAEG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,4CAJW,MAAM,SACN,MAAM,UACK,MAAM,KAAG,YAAY,CAiD1C;qBAlEY,OAAO,qCAAqC,EAAE,MAAM"}
+{"version":3,"file":"cloth_bind_in_frame.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_bind_in_frame.js"],"names":[],"mappings":"AAOA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAJW,MAAM,SACN,MAAM,UACK,MAAM,KAAG,YAAY,CAqC1C;AASD;;;;;;;;;;;;;;GAcG;AACH,gDAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAgBlB;qBAlGY,OAAO,qCAAqC,EAAE,MAAM"}

package/src/engine/physics/cloth/build/cloth_bind_in_frame.js

@@ -1,7 +1,7 @@
-import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
-import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { pose3_compose_array } from "../../../../core/geom/3d/pose/pose3_compose_array.js";
 import {
     TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
     TRANSFORM64_TRANSLATION_OFFSET
 } from "../../../ecs/transform/Transform64.js";
 
@@ -18,6 +18,12 @@ import {
  * bind pose — so that a re-seed reads what was authored rather than what the
  * solver left on the joints.
  *
+ * Rigid, as every pose cloth holds is: a local scale is not applied. That is
+ * not a convention this can opt out of alone — the write-back is rigid too,
+ * and the GPU applies a parent's scale on top of what cloth writes, so a
+ * scaled bake would draw a scaled link twice over. A builder refuses a rig
+ * where it would matter, with {@link cloth_bind_scaled_above}.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  *
@@ -45,25 +51,13 @@ export function cloth_bind_in_frame(prefab, frame) {
 
         answer = new Float64Array(7);
 
-        v3_quaternion_apply(
+        pose3_compose_array(
             answer, 0,
-            local[TRANSFORM64_TRANSLATION_OFFSET],
-            local[TRANSFORM64_TRANSLATION_OFFSET + 1],
-            local[TRANSFORM64_TRANSLATION_OFFSET + 2],
-            above[3], above[4], above[5], above[6]
-        );
-
-        answer[0] += above[0];
-        answer[1] += above[1];
-        answer[2] += above[2];
-
-        quat3_multiply(
             answer, 3,
-            above[3], above[4], above[5], above[6],
-            local[TRANSFORM64_ROTATION_OFFSET],
-            local[TRANSFORM64_ROTATION_OFFSET + 1],
-            local[TRANSFORM64_ROTATION_OFFSET + 2],
-            local[TRANSFORM64_ROTATION_OFFSET + 3]
+            above, 0,
+            above, 3,
+            local, TRANSFORM64_TRANSLATION_OFFSET,
+            local, TRANSFORM64_ROTATION_OFFSET
         );
 
         known.set(node, answer);
@@ -73,3 +67,41 @@ export function cloth_bind_in_frame(prefab, frame) {
 
     return pose;
 }
+
+/**
+ * How far a rest scale may be from one before it is a scale: the tolerance
+ * `prefab_normalize_skin_frames` holds a skin's frame to, for the same reason.
+ * @type {number}
+ */
+const SCALE_TOLERANCE = 1e-4;
+
+/**
+ * The nearest node above `node`, up to and including the prefab's root, whose
+ * rest scale is not one; or -1.
+ *
+ * Cloth simulates and writes back rigid poses, and everything under a scaled
+ * node is drawn scaled: a link below one is simulated at its authored length and
+ * drawn at that times the scale, and a scale above the frame draws the whole
+ * garment at another size than the one its colliders meet. Measured, a 10 cm
+ * chain under a joint scaled by 2: simulated links 0.1, drawn 0.2. A node's own
+ * scale moves nothing cloth places, so it is not asked about.
+ *
+ * @param {Prefab} prefab
+ * @param {number} node
+ * @returns {number}
+ */
+export function cloth_bind_scaled_above(prefab, node) {
+    const parent = prefab.parent;
+
+    for (let above = parent[node]; above >= 0; above = parent[above]) {
+        const local = prefab.local[above];
+
+        if (Math.abs(local[TRANSFORM64_SCALE_OFFSET] - 1) > SCALE_TOLERANCE
+            || Math.abs(local[TRANSFORM64_SCALE_OFFSET + 1] - 1) > SCALE_TOLERANCE
+            || Math.abs(local[TRANSFORM64_SCALE_OFFSET + 2] - 1) > SCALE_TOLERANCE) {
+            return above;
+        }
+    }
+
+    return -1;
+}

package/src/engine/physics/cloth/build/cloth_proxy_from_joints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_proxy_from_joints.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_joints.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,gDARW,MAAM,QACN,IAAI,eAEJ,MAAM,EAAE;IAES,IAAI,GAArB,MAAM;IACJ,qBAAqB,CAgQjC;qBAjUY,OAAO,qCAAqC,EAAE,MAAM;mBACpD,OAAO,8CAA8C,EAAE,IAAI;;;;;;;;WAwC1D,MAAM;;;;eACN,UAAU;;;;;;WAKV,UAAU,GAAC,IAAI;;;;YACf,eAAe,EAAE;;;;WACjB,MAAM;;2BArDO,iBAAiB"}
+{"version":3,"file":"cloth_proxy_from_joints.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_joints.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,gDARW,MAAM,QACN,IAAI,eAEJ,MAAM,EAAE;IAES,IAAI,GAArB,MAAM;IACJ,qBAAqB,CA6QjC;qBA9UY,OAAO,qCAAqC,EAAE,MAAM;mBACpD,OAAO,8CAA8C,EAAE,IAAI;;;;;;;;WAwC1D,MAAM;;;;eACN,UAAU;;;;;;WAKV,UAAU,GAAC,IAAI;;;;YACf,eAAe,EAAE;;;;WACjB,MAAM;;2BAtDO,iBAAiB"}

package/src/engine/physics/cloth/build/cloth_proxy_from_joints.js

@@ -1,5 +1,6 @@
 import { ClothProxy } from "./ClothProxy.js";
-import { cloth_bind_in_frame } from "./cloth_bind_in_frame.js";
+import { cloth_bind_in_frame, cloth_bind_scaled_above } from "./cloth_bind_in_frame.js";
+import { number_compare_ascending } from "../../../../core/primitives/numbers/number_compare_ascending.js";
 
 /**
  * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
@@ -161,7 +162,7 @@ export function cloth_proxy_from_joints(prefab, skin, joint_names, { name = "" }
         }
     }
 
-    hung_from.sort((a, b) => a - b);
+    hung_from.sort(number_compare_ascending);
 
     // The frame: the nearest skin joint above every bone the garment hangs from
     // — for one bone, the bone itself.
@@ -236,6 +237,19 @@ export function cloth_proxy_from_joints(prefab, skin, joint_names, { name = "" }
 
     const particle_name = [];
 
+    for (let i = 0; i < particle_count; i++) {
+        const scaled = cloth_bind_scaled_above(prefab, ordered[i]);
+
+        if (scaled >= 0) {
+            const local = prefab.local[scaled];
+
+            return refuse(
+                `${name}: "${name_of[scaled]}", above "${name_of[ordered[i]]}", is scaled by (${local.scale_x}, ${local.scale_y}, ${local.scale_z}) at rest;`
+                + ` cloth poses its joints rigidly, so it would simulate a different garment from the one drawn`
+            );
+        }
+    }
+
     const pose = cloth_bind_in_frame(prefab, frame_node);
 
     for (let i = 0; i < particle_count; i++) {

package/src/engine/physics/cloth/build/cloth_proxy_from_mesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_proxy_from_mesh.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_mesh.js"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;GAUG;AACH,8CARW,MAAM,QACN,IAAI,eACJ,MAAM,EAAE,aACR,UAAU,GAAC,MAAM,EAAE;IAEF,IAAI,GAArB,MAAM;IACJ,qBAAqB,CA8LjC;qBApPY,OAAO,qCAAqC,EAAE,MAAM;mBACpD,OAAO,8CAA8C,EAAE,IAAI;oCAC3D,OAAO,8BAA8B,EAAE,qBAAqB"}
+{"version":3,"file":"cloth_proxy_from_mesh.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_mesh.js"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;GAUG;AACH,8CARW,MAAM,QACN,IAAI,eACJ,MAAM,EAAE,aACR,UAAU,GAAC,MAAM,EAAE;IAEF,IAAI,GAArB,MAAM;IACJ,qBAAqB,CA8MjC;qBApQY,OAAO,qCAAqC,EAAE,MAAM;mBACpD,OAAO,8CAA8C,EAAE,IAAI;oCAC3D,OAAO,8BAA8B,EAAE,qBAAqB"}

package/src/engine/physics/cloth/build/cloth_proxy_from_mesh.js

@@ -1,5 +1,6 @@
+import { tri3_area } from "../../../../core/geom/3d/triangle/tri3_area.js";
 import { ClothProxy } from "./ClothProxy.js";
-import { cloth_bind_in_frame } from "./cloth_bind_in_frame.js";
+import { cloth_bind_in_frame, cloth_bind_scaled_above } from "./cloth_bind_in_frame.js";
 
 /**
  * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
@@ -140,6 +141,18 @@ export function cloth_proxy_from_mesh(prefab, skin, joint_names, triangles, { na
         return refuse(`${name}: ${triangles.length} triangle indices is not a whole number of triangles`);
     }
 
+    // Every vertex joint hangs from the frame, so one walk up from any of them asks the lot.
+    const scaled = cloth_bind_scaled_above(prefab, node[0]);
+
+    if (scaled >= 0) {
+        const local = prefab.local[scaled];
+
+        return refuse(
+            `${name}: "${name_of[scaled]}", above "${name_of[node[0]]}", is scaled by (${local.scale_x}, ${local.scale_y}, ${local.scale_z}) at rest;`
+            + ` cloth poses its joints rigidly, so it would simulate a different garment from the one drawn`
+        );
+    }
+
     const pose = cloth_bind_in_frame(prefab, frame_node);
 
     const rest_position = new Float32Array(particle_count * 3);
@@ -176,7 +189,11 @@ export function cloth_proxy_from_mesh(prefab, skin, joint_names, triangles, { na
             }
         }
 
-        if (twice_area(rest_position, i0, i1, i2) <= 0) {
+        if (tri3_area(
+            rest_position[i0 * 3], rest_position[i0 * 3 + 1], rest_position[i0 * 3 + 2],
+            rest_position[i1 * 3], rest_position[i1 * 3 + 1], rest_position[i1 * 3 + 2],
+            rest_position[i2 * 3], rest_position[i2 * 3 + 1], rest_position[i2 * 3 + 2]
+        ) <= 0) {
             return refuse(
                 `${name}: triangle ${t} ("${joint_names[i0]}", "${joint_names[i1]}", "${joint_names[i2]}") has no area,`
                 + ` so no normal and no hinge across it`
@@ -248,28 +265,6 @@ export function cloth_proxy_from_mesh(prefab, skin, joint_names, triangles, { na
     };
 }
 
-/**
- * Twice the area of a triangle of the rest pose.
- *
- * @param {Float32Array} position
- * @param {number} a
- * @param {number} b
- * @param {number} c
- * @returns {number}
- * @private
- */
-function twice_area(position, a, b, c) {
-    const ux = position[b * 3] - position[a * 3];
-    const uy = position[b * 3 + 1] - position[a * 3 + 1];
-    const uz = position[b * 3 + 2] - position[a * 3 + 2];
-
-    const vx = position[c * 3] - position[a * 3];
-    const vy = position[c * 3 + 1] - position[a * 3 + 1];
-    const vz = position[c * 3 + 2] - position[a * 3 + 2];
-
-    return Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx);
-}
-
 /**
  * @param {string} error
  * @returns {ClothProxyBuildResult}

package/src/engine/physics/cloth/collider/ClothColliderIndex.d.ts

@@ -164,6 +164,13 @@ export class ClothColliderIndex {
      * ignores it, so a distance in the shape's local frame is a distance in
      * world space.
      *
+     * A pose equal to the one the record already holds is not refit: its
+     * bounds were fit to exactly this pair of poses when either last changed —
+     * here, in {@link placePose}, or in {@link advance} — so the refit would
+     * write what is there. That is what a collider that never moves costs, and
+     * why nothing has to say it will not: 1.43 µs per collider per step
+     * refitting, 0.42 µs skipping, of which {@link advance} is 0.32.
+     *
      * @param {number} handle
      * @param {number} tx
      * @param {number} ty

package/src/engine/physics/cloth/collider/ClothColliderIndex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClothColliderIndex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderIndex.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH;IAEI;;;;;;OAMG;IACH,OAFU,YAAY,CAEM;IAE5B;;;;;OAKG;IACH,MAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;OAMG;IACH,qBAFU,MAAM,CAEQ;IAoFxB;;;;;;;;;;;OAWG;IACH,sCAPW,MAAM,aACN,MAAM,SACN,MAAM,QACN,MAAM,UACN,MAAM,GACJ,MAAM,CA8DlB;IAED;;;;;;;OAOG;IACH,eAHW,MAAM,GACJ,IAAI,CAoChB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAuDhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CA8BhB;IAwID;;;;;;;;;;;;;;;OAeG;IACH,kBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAmBhB;IAED;;;;;;;;OAQG;IACH,mBALW,MAAM,YACN,MAAM,aACN,MAAM,GACJ,IAAI,CAoBhB;IAED;;;;;OAKG;IACH,kBALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,IAAI,CAWhB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAdW,MAAM,EAAE,SACR,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,QACN,MAAM,YACN,OAAO,GAGL,MAAM,CAWlB;IAED;;;;;;;;;;;OAWG;IACH,gBARW,MAAM,EAAE,OACR,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,SACN,MAAM,QACN,MAAM,WACN,OAAO,GACL,MAAM,CA6DlB;;CAyGJ"}
+{"version":3,"file":"ClothColliderIndex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderIndex.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH;IAEI;;;;;;OAMG;IACH,OAFU,YAAY,CAEM;IAE5B;;;;;OAKG;IACH,MAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;OAMG;IACH,qBAFU,MAAM,CAEQ;IAoFxB;;;;;;;;;;;OAWG;IACH,sCAPW,MAAM,aACN,MAAM,SACN,MAAM,QACN,MAAM,UACN,MAAM,GACJ,MAAM,CA8DlB;IAED;;;;;;;OAOG;IACH,eAHW,MAAM,GACJ,IAAI,CAkChB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,IAAI,CA4ChB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAqBhB;IAsLD;;;;;;;;;;;;;;;OAeG;IACH,kBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;;;;;OAQG;IACH,mBALW,MAAM,YACN,MAAM,aACN,MAAM,GACJ,IAAI,CAoBhB;IAED;;;;;OAKG;IACH,kBALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,IAAI,CAWhB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAdW,MAAM,EAAE,SACR,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,QACN,MAAM,YACN,OAAO,GAGL,MAAM,CAWlB;IAED;;;;;;;;;;;OAWG;IACH,gBARW,MAAM,EAAE,OACR,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,SACN,MAAM,QACN,MAAM,WACN,OAAO,GACL,MAAM,CA6DlB;;CAyGJ"}