@woosh/meep-engine 3.44.0 → 3.46.0

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"}

package/src/engine/physics/cloth/collider/ClothColliderIndex.js

@@ -1,8 +1,15 @@
 import { assert } from "../../../../core/assert.js";
 import { BVH, NULL_NODE } from "../../../../core/bvh2/bvh3/BVH.js";
+import { number_compare_ascending } from "../../../../core/primitives/numbers/number_compare_ascending.js";
 import {
     bvh_query_user_data_intersects_aabb
 } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
+import { array_copy } from "../../../../core/collection/array/array_copy.js";
+import { array_range_equal_strict } from "../../../../core/collection/array/array_range_equal_strict.js";
+import { array_remove_first } from "../../../../core/collection/array/array_remove_first.js";
+import { array_sort_insertion_ascending } from "../../../../core/collection/array/array_sort_insertion_ascending.js";
+import { aabb3_array_round_outward_f32 } from "../../../../core/geom/3d/aabb/aabb3_array_round_outward_f32.js";
+import { FAT_LINEAR } from "../../broadphase/compute_fat_world_aabb.js";
 import {
     CCR_AABB_MAX_X,
     CCR_AABB_MAX_Y,
@@ -341,11 +348,9 @@ export class ClothColliderIndex {
         const node = this.#node[handle];
 
         if (node === NULL_NODE) {
-            const at = this.#planes.indexOf(handle);
+            const planes = this.#planes;
 
-            if (at >= 0) {
-                this.#planes.splice(at, 1);
-            }
+            array_remove_first(planes, handle, 0, planes.length);
         } else {
             this.#bvh.remove_leaf(node);
             this.#bvh.release_node(node);
@@ -419,22 +424,11 @@ export class ClothColliderIndex {
                 this.max_inflation = table[r + CCR_INFLATION];
             }
 
-            const moved = table[r + CCR_PREV_TX] !== table[r + CCR_TX]
-                || table[r + CCR_PREV_TY] !== table[r + CCR_TY]
-                || table[r + CCR_PREV_TZ] !== table[r + CCR_TZ]
-                || table[r + CCR_PREV_QX] !== table[r + CCR_QX]
-                || table[r + CCR_PREV_QY] !== table[r + CCR_QY]
-                || table[r + CCR_PREV_QZ] !== table[r + CCR_QZ]
-                || table[r + CCR_PREV_QW] !== table[r + CCR_QW];
-
-            table[r + CCR_PREV_TX] = table[r + CCR_TX];
-            table[r + CCR_PREV_TY] = table[r + CCR_TY];
-            table[r + CCR_PREV_TZ] = table[r + CCR_TZ];
+            // A pose is seven contiguous slots, translation then rotation, in
+            // both the current and the previous half of the record.
+            const moved = !array_range_equal_strict(table, r + CCR_PREV_TX, table, r + CCR_TX, POSE_SLOTS);
 
-            table[r + CCR_PREV_QX] = table[r + CCR_QX];
-            table[r + CCR_PREV_QY] = table[r + CCR_QY];
-            table[r + CCR_PREV_QZ] = table[r + CCR_QZ];
-            table[r + CCR_PREV_QW] = table[r + CCR_QW];
+            array_copy(table, r + CCR_TX, table, r + CCR_PREV_TX, POSE_SLOTS);
 
             if (moved) {
                 cloth_collider_refit_bounds(table, handle, CCR_STRIDE);
@@ -451,6 +445,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
@@ -471,6 +472,35 @@ export class ClothColliderIndex {
 
         const r = handle * CCR_STRIDE;
 
+        if (table[r + CCR_TX] === tx && table[r + CCR_TY] === ty && table[r + CCR_TZ] === tz
+            && table[r + CCR_QX] === qx && table[r + CCR_QY] === qy
+            && table[r + CCR_QZ] === qz && table[r + CCR_QW] === qw
+            // no leaf — never posed, or a plane, which is never in the tree — refits regardless
+            && this.#node[handle] !== NULL_NODE) {
+            return;
+        }
+
+        this.#pose(handle, tx, ty, tz, qx, qy, qz, qw);
+    }
+
+    /**
+     * Write the current pose and refit, unconditionally.
+     *
+     * @param {number} handle
+     * @param {number} tx
+     * @param {number} ty
+     * @param {number} tz
+     * @param {number} qx
+     * @param {number} qy
+     * @param {number} qz
+     * @param {number} qw
+     * @private
+     */
+    #pose(handle, tx, ty, tz, qx, qy, qz, qw) {
+        const table = this.table;
+
+        const r = handle * CCR_STRIDE;
+
         if (table[r + CCR_TX] !== tx || table[r + CCR_TY] !== ty || table[r + CCR_TZ] !== tz
             || table[r + CCR_QX] !== qx || table[r + CCR_QY] !== qy
             || table[r + CCR_QZ] !== qz || table[r + CCR_QW] !== qw) {
@@ -561,9 +591,15 @@ export class ClothColliderIndex {
             if (lower < STORED_AABB[axis] || upper > STORED_AABB[axis + 3]) contained = false;
             // A one-step outlier must not leave a scene-sized leaf behind once
             // motion stops. Allow ordinary jitter to keep spending the slack.
+            // The yardstick is twice what a store would write now: the slack
+            // on both sides plus the outward rounding, which grows each side by
+            // under one float32 step of its magnitude. Without that term a leaf
+            // far enough out that a step outgrows the slack — past about four
+            // hundred kilometres — would read as oversized straight after being
+            // stored, and be re-homed every step.
             if (STORED_AABB[axis + 3] - STORED_AABB[axis]
-                > 2 * (upper - lower + 2 * BVH_LEAF_SLACK
-                    + (Math.abs(lower) + Math.abs(upper)) * FLOAT32_ROUNDING)) oversized = true;
+                > 2 * (upper - lower + 2 * FAT_LINEAR
+                    + (Math.abs(lower) + Math.abs(upper) + 2 * FAT_LINEAR) * FLOAT32_STEP)) oversized = true;
         }
 
         if (contained && !oversized) {
@@ -589,18 +625,18 @@ export class ClothColliderIndex {
      * Write a record's swept bounds plus its contact reach into {@link FAT_AABB}
      * with the slack the refit skip spends, and store them on the leaf.
      *
-     * The slack is also what makes the tree's `Float32` nodes safe to hold a
-     * `Float64` world, and it has two terms because one is not enough. The
-     * constant covers jitter. The relative term covers the rounding
-     * {@link BVH#node_set_aabb} does on the way in: a bound can move by an ulp,
-     * and `Float32`'s ulp is a *proportion* of the magnitude — a millimetre at
-     * ten kilometres out, but **a whole metre at ten thousand**, which is well
-     * past the constant: measured, a leaf there comes back 45 cm inside its own
-     * record. A bound that rounds inward past its slack is a leaf
-     * smaller than the record it stands for, and that is a collider the tree
-     * stops answering with — silently, and only far from the origin, which is
-     * the worst shape a bug can have. Two ulps of the magnitude puts it back
-     * outside at every scale the `Float64` table is kept for.
+     * The slack covers jitter; it does not cover the tree's `Float32` nodes
+     * holding a `Float64` world. {@link BVH#node_set_aabb} rounds each bound to
+     * the nearest `Float32`, and `Float32`'s step is a *proportion* of the
+     * magnitude — a millimetre at ten kilometres out, but **a whole metre at
+     * ten thousand**, which is well past any constant: measured, a leaf there
+     * fattened by 5 cm came back 45 cm inside its own record. A bound that
+     * rounds inward past its slack is a leaf smaller than the record it stands
+     * for, and that is a collider the tree stops answering with — silently,
+     * and only far from the origin, which is the worst shape a bug can have.
+     * So the fattened box is rounded outward to `Float32` before it is stored,
+     * which makes the store exact at every scale and leaves the constant to do
+     * only its own job.
      *
      * The exact test in {@link query} reads the `Float64` record, so the tree
      * only ever has to avoid a false **negative**; being generous here costs a
@@ -618,10 +654,12 @@ export class ClothColliderIndex {
             const lower = table[r + CCR_AABB_MIN_X + axis] - reach;
             const upper = table[r + CCR_AABB_MAX_X + axis] + reach;
 
-            FAT_AABB[axis] = lower - BVH_LEAF_SLACK - Math.abs(lower) * FLOAT32_ROUNDING;
-            FAT_AABB[axis + 3] = upper + BVH_LEAF_SLACK + Math.abs(upper) * FLOAT32_ROUNDING;
+            FAT_AABB[axis] = lower - FAT_LINEAR;
+            FAT_AABB[axis + 3] = upper + FAT_LINEAR;
         }
 
+        aabb3_array_round_outward_f32(FAT_AABB, 0, FAT_AABB, 0);
+
         this.#bvh.node_set_aabb(node, FAT_AABB);
     }
 
@@ -657,7 +695,9 @@ export class ClothColliderIndex {
         this.table[r + CCR_PREV_QZ] = qz;
         this.table[r + CCR_PREV_QW] = qw;
 
-        this.setPose(handle, tx, ty, tz, qx, qy, qz, qw);
+        // Not {@link setPose}: the previous pose has just changed, so the
+        // bounds are stale even when the current one has not.
+        this.#pose(handle, tx, ty, tz, qx, qy, qz, qw);
     }
 
     /**
@@ -926,21 +966,19 @@ export class ClothColliderIndex {
 }
 
 /**
- * How far past a record's swept bounds its leaf is stored, metres. The same
- * constant `compute_fat_world_aabb` spends on a rigid body, and for the same
- * reason: a collider jittering inside its own slack must not cost a refit.
+ * One `Float32` step as a proportion of a value's magnitude, an upper bound
+ * for every normal `Float32`: 23 fraction bits, so a step is at most `2^-23`
+ * of the magnitude. The most an outward rounding can widen a bound by.
  * @type {number}
  */
-const BVH_LEAF_SLACK = 0.05;
+const FLOAT32_STEP = 2 ** -23;
 
 /**
- * Two `Float32` ulps as a proportion of a value's magnitude — what a bound has
- * to be widened by to survive being stored in a `Float32` leaf whatever the
- * rounding does. `Float32` carries 23 fraction bits, so one ulp is `2^-23` of
- * the magnitude and two is the first multiple that is unconditionally outside.
+ * Slots in one pose, `[tx, ty, tz, qx, qy, qz, qw]`: {@link CCR_TX} to {@link CCR_QW}, and the same
+ * from {@link CCR_PREV_TX}.
  * @type {number}
  */
-const FLOAT32_ROUNDING = 2 ** -22;
+const POSE_SLOTS = 7;
 
 /**
  * The box being queried, `[min_x, min_y, min_z, max_x, max_y, max_z]`: what the tree is walked with
@@ -972,23 +1010,12 @@ function sort_handles(handles) {
     const n = handles.length;
 
     if (n > INSERTION_SORT_LIMIT) {
-        handles.sort(ASCENDING);
+        handles.sort(number_compare_ascending);
 
         return;
     }
 
-    for (let i = 1; i < n; i++) {
-        const handle = handles[i];
-
-        let j = i - 1;
-
-        while (j >= 0 && handles[j] > handle) {
-            handles[j + 1] = handles[j];
-            j--;
-        }
-
-        handles[j + 1] = handle;
-    }
+    array_sort_insertion_ascending(handles, 0, n);
 }
 
 /**
@@ -1002,12 +1029,3 @@ const FAT_AABB = new Float64Array(6);
  * @type {Float32Array}
  */
 const STORED_AABB = new Float32Array(6);
-
-/**
- * @param {number} a
- * @param {number} b
- * @returns {number}
- */
-function ASCENDING(a, b) {
-    return a - b;
-}

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_collider_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_bounds.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oDAJW,MAAM,eACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,mDALW,YAAY,GAAC,YAAY,UACzB,MAAM,UACN,MAAM,GACJ,IAAI,CAoBhB"}
+{"version":3,"file":"cloth_collider_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_bounds.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oDAJW,MAAM,eACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,mDALW,YAAY,GAAC,YAAY,UACzB,MAAM,UACN,MAAM,GACJ,IAAI,CA2BhB"}