@woosh/meep-engine 3.49.0 → 3.50.0

package/src/engine/graphics3/WaterSystem.js

@@ -20,12 +20,14 @@ import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
 import { generate_record_writer } from "../../shade/renderer/buffer/table/serde/generate_record_writer.js";
 import { WATER_WAVE_IMPULSE_LIMIT, WATER_WAVE_RECORD_STRUCT } from "../../shade/renderer/water/surface/WATER_WAVE_RECORD_STRUCT.js";
 import { WATER_SPECTRUM_BAND_COUNT } from "../../shade/renderer/water/surface/spectrum/WATER_SPECTRUM.js";
+import { GPUFluidComponent } from "../physics/fluid/ecs/GPUFluidComponent.js";
+import { GPUFluidSystem } from "./GPUFluidSystem.js";
 
 // Only the authored fields: a whole-record write would undo what the GPU derives into the row.
-const AUTHORED_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['wind', 'upwind_fetch', 'node', 'geometry', 'simulate_hidden']);
+const AUTHORED_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['upwind_fetch', 'shore_reflection', 'node', 'geometry', 'simulate_hidden']);
 const IMPULSE_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['impulses', 'impulse_count']);
 /** The WaterWaves fields a body's row follows. */
-const WAVE_FIELDS = ['windSpeed', 'windDirection', 'upwindFetch', 'shoreReflection'];
+const WAVE_FIELDS = ['upwindFetch', 'shoreReflection'];
 /** A splash's world-to-local matrix: rain can splash hundreds of times a second. */
 const SPLASH_INVERSE = new Float64Array(16);
 
@@ -34,14 +36,22 @@ const SPLASH_INVERSE = new Float64Array(16);
  * edits queue writes; idle frames never walk bodies. Transform rows follow the same change events
  * and GPU hierarchy as shaded geometry. Water does not enter the opaque mesh table or its TLAS.
  *
- * Every body has a surface row (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1): its wind from an
+ * Every body has a surface row (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1): its fetch and shore from an
  * optional {@link WaterWaves}, its queued splashes, and what the GPU derives from them each frame. The GPU culls
  * every body against the frame's view before simulating; a hidden body is paused unless
  * {@link Water#simulateWhenHidden} (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3).
+ *
+ * **The wind is the scene's** (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, the Water row): the culling pass
+ * samples the published wind field 10 m above each body's origin and low-passes it per body, on the GPU. What the
+ * system decides on the CPU is only whether that field can hold wind at all ({@link GPUWaterSurface#windy}, which
+ * animates the shared bands): while any enabled {@link GPUFluidComponent} steps a fluid, or the far field
+ * ({@link GPUFluidSystem#far_field}) is not still. Asked every update, allocating nothing.
  */
 export class WaterSystem extends System {
     dependencies = [Water, MeshletGeometry, Transform64];
-    components_used = [ResourceAccessSpecification.from(WaterWaves, ResourceAccessKind.Read)];
+    components_used = [ResourceAccessSpecification.from(WaterWaves, ResourceAccessKind.Read),
+        // whether the scene's wind field has a fluid behind it
+        ResourceAccessSpecification.from(GPUFluidComponent, ResourceAccessKind.Read)];
     #graphics;
     #scene;
     #context = null;
@@ -51,8 +61,15 @@ export class WaterSystem extends System {
     #entries = new Map();
     #dirty = new Set();
     #impulses = new Set();
-    // bodies with wind: while there is none, the shared band tiles are not animated
-    #windy = new Set();
+    /** @type {GPUFluidSystem|null} the far field's source, once found */
+    #fluid = null;
+    #far = new Float64Array(3);
+    /** Whether {@link #visit_domain} met an enabled component. */
+    #enabled_found = false;
+    #visit_domain = component => {
+        if (component.enabled) { this.#enabled_found = true; return false; }
+        return true;
+    };
     #extensions = [];
     #time = 0;
     get settings() { return this.#renderer.settings; }
@@ -143,13 +160,13 @@ export class WaterSystem extends System {
             entry.context.rows.release(entity);
         }
         this.#entries.delete(entity); this.#dirty.delete(entry); this.#impulses.delete(entry);
-        this.#windy.delete(entry); this.#waves.windy = this.#windy.size > 0;
         this.#renderer.body_count--;
         if (entry.context !== null) { this.#renderer.meshlet_capacity -= entry.geometry.meshlets.count; }
     }
 
     update(dt) {
         this.#time += dt; this.#renderer.time = this.#time; this.#waves.advance(dt);
+        this.#waves.windy = this.#wind_can_blow();
         const context = this.#graphics.scene_context(this.#scene);
         if (context === null) { return; }
         if (context !== this.#context) {
@@ -170,6 +187,31 @@ export class WaterSystem extends System {
         for (const entry of this.#impulses) { this.#stage(entry, context); }
     }
 
+    /**
+     * Whether the scene's wind field can hold wind: an enabled {@link GPUFluidComponent} on any entity, or a far
+     * field that is not still. The lowest holder of the component answers without a walk; only when it is disabled
+     * are the others visited.
+     * @returns {boolean}
+     */
+    #wind_can_blow() {
+        const em = this.entityManager, dataset = em.dataset;
+        if (dataset !== null) {
+            const lowest = dataset.getAnyComponentInstance(GPUFluidComponent);
+            if (lowest !== null) {
+                if (lowest.enabled) { return true; }
+                this.#enabled_found = false;
+                dataset.traverseComponents(GPUFluidComponent, this.#visit_domain);
+                if (this.#enabled_found) { return true; }
+            }
+        }
+        // registered later than this system, or never
+        const fluid = this.#fluid ??= em.getSystem(GPUFluidSystem);
+        if (fluid === null) { return false; }
+        const far = this.#far;
+        fluid.far_field(far);
+        return far[0] !== 0 || far[1] !== 0 || far[2] !== 0;
+    }
+
     /** Top up a body's batch on its surface row from its queue, up to the row's limit. */
     #stage(entry, context) {
         const staged = entry.staged, queue = entry.queue;
@@ -197,21 +239,17 @@ export class WaterSystem extends System {
         }
         const geometry = context.geometries.getAddress(entry.geometry);
         if (entry.wave === -1) {
-            entry.wave = waves.add({ wind: [1, 0, 0, WATER_WAVES_SHORE_REFLECTION_DEFAULT], upwind_fetch: 0,
+            // the GPU seeds the wind from its first sample, and derives the weights for it
+            entry.wave = waves.add({ upwind_fetch: 0, shore_reflection: WATER_WAVES_SHORE_REFLECTION_DEFAULT,
                 impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => [0, 0, 0, 0]), impulse_count: 0,
-                node: entry.entity + 1, geometry, simulate_hidden: 0, derived_for: [-1, -1],
+                node: entry.entity + 1, geometry, simulate_hidden: 0, wind: [0, 0, 0], wind_seeded: 0, derived_for: [-1, -1, 0, 0],
                 weights: new Array(WATER_SPECTRUM_BAND_COUNT).fill(0), slope_variance: 0,
                 wind_from: [0, 0], wind_to: [0, 0], wind_blend: 1, displacement_bounds: [0, 0, 0, 0], particle_levels: 0 });
         }
         const waves_component = entry.waves;
-        const speed = Math.max(0, waves_component?.windSpeed.getValue() ?? 0);
-        const direction = waves_component?.windDirection.getValue() ?? 0;
         const reflection = Math.min(1, Math.max(0, waves_component?.shoreReflection.getValue() ?? WATER_WAVES_SHORE_REFLECTION_DEFAULT));
-        waves.set_fields(entry.wave, { wind: [Math.cos(direction), Math.sin(direction), speed, reflection],
-            upwind_fetch: Math.max(0, waves_component?.upwindFetch.getValue() ?? 0), node: entry.entity + 1, geometry,
+        waves.set_fields(entry.wave, { upwind_fetch: Math.max(0, waves_component?.upwindFetch.getValue() ?? 0), shore_reflection: reflection, node: entry.entity + 1, geometry,
             simulate_hidden: entry.water.simulateWhenHidden.getValue() ? 1 : 0 }, AUTHORED_WRITER);
-        if (speed > 0) { this.#windy.add(entry); } else { this.#windy.delete(entry); }
-        this.#waves.windy = this.#windy.size > 0;
         const water = entry.water;
         const record = { geometry, node: entry.entity + 1,
             dirty: 1,

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

@@ -5263,3 +5263,42 @@ as above, red on one radius per cloth. `check-types` 18 against 19. The A/B is `
 with `ab_scenes.mjs` in the session scratchpad, the control `ribbon_determinism.probe.js` and
 `ribbon_diff.probe.js`, and the slow spec's old arm an alias of `cloth_self_radius.js` that flattens
 (`vitest.slow_flat.config.mjs`).
+
+---
+
+## 69. The gust on the scene's clock, and the parity gate restated
+
+The GPU wind fluid's S5 (`../fluid/GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md` §12, G2, F4) took cloth's
+air off cloth's own ambient and onto the scene's one wind. `ClothAmbientWind` is retired: its gust,
+term for term, is `GlobalFluidEffector#gust`, integrated once a tick by `FluidEffectorsSystem`, and
+cloth reads it through the far field — `ClothGPUFluidWind` (lattices of the GPU wind, read back
+through `GPUFluidSystem#request`; the far field before one lands and wherever none reaches) or
+`ClothFluidWind` (the CPU fields, the far field outside them). §57's clock, each cloth's own age, is
+no longer read by any engine source.
+
+**What that costs the parity gate, measured.** The gust is now a function of the scene's tick, and
+the worker advances a cloth from the tick its registration is acknowledged (§39). Each row is a scene
+of `WorkerClothSystem.spec.js` with one line changed, the gate reading the whole `ClothState` buffer
+after every step:
+
+```
+  scene                                                   wind                        first difference
+  second cloth spawned after the first, under latency     steady (gust 0)             none in 60 steps
+    (registered 3 ticks later by the worker)              gust 3 m/s, period 0.7 s    the second cloth's step 1, byte 0 (216 against 247)
+  one cloth, both registered on the same tick             gust 3 m/s, period 0.7 s    none in 180 steps (far field moving on > 100 of them)
+    the reference spawned a tick before the worker's      gust 3 m/s, period 0.7 s    step 1, byte 0 (246 against 86)
+  §10's field scene, a garment walked out of a volume     steady far field            none in 200 steps
+                                                          far field gusting 1.5 m/s   step 1, byte 0 (27 against 30)
+```
+
+So **the gate is restated**: worker and inline cloth agree for cloths **registered on the same tick**,
+under any deterministic wind, and for any registration **under a time-invariant wind**. The specs hold
+it to those cases, through the GPU wind with no device (lattices answered from the far field) and
+through lattices a spec injects (`ClothGPUFluidWind.spec.js`, `ecs/cloth_wind.spec.js`). Under the
+GPU wind on a device, lattices land when the GPU answers, so two runs of a scene need not read the
+same air: **run-to-run repeatability under the GPU wind is given up** (F4, accepted). Every other cloth
+gate is unchanged: the parity scenes without wind, §7's table, the pathology spec.
+
+*Reproduce:* the probe that edits one line of the spec and prints the first difference is
+`s5_probe_gust.mjs` in the GPU-fluid session's scratchpad.
+

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

@@ -340,8 +340,8 @@ engine/physics/cloth/
     cloth_collider_sdf.js           pose interpolation, localisation, and the field dispatch
   wind/
     AbstractClothWind.js            §10's one interface: sample the air, and say whether it varies
-    ClothAmbientWind.js             a constant plus a band-limited gust — the air where no field is
-    ClothFluidWind.js               every live FluidComponent, with the ambient underneath it
+    ClothGPUFluidWind.js            the GPU wind: lattices read back from GPUFluidSystem, the far field elsewhere
+    ClothFluidWind.js               every live FluidComponent, with the scene's far field underneath it
     cloth_sample_air.js             the air into the cloth's own frame, on the main thread
   solver/
     ClothState.js                   SoA particle + topology + constraint storage over one buffer
@@ -1365,6 +1365,16 @@ Fallback when there is no fluid field in range: a `GlobalFluidEffector`-shaped a
 constant `wind` vector plus a small band-limited noise for gusting — read from the same interface, so
 the cloth code has one path and does not branch on whether a simulation is present.
 
+*Corrected by the GPU wind fluid's S5 (`../fluid/GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md` §12, G2):*
+the fallback is no longer cloth's own. It is the scene's **far field** — its `GlobalFluidEffector`s,
+gust included, folded by `FluidEffectorsSystem` once a tick — which is what the shape above was
+always copying. `ClothAmbientWind` is retired; `ClothGPUFluidWind` reads the GPU wind and
+`ClothFluidWind` the CPU fields, each with the far field underneath. `MEASUREMENTS.md` §69.
+And cloth reads it **by default**: with nothing assigned, `ClothWorld#wind` is a `ClothGPUFluidWind`
+while the scene has an enabled `GPUFluidComponent`, else a `ClothFluidWind` while the far field is not
+zero, else `null` as before — decided again every tick from those facts, so a scene without wind gains
+no drag. An assigned source, `null` included, always wins.
+
 Cost control: sampling is per particle per *step*, not per iteration, and a cloth outside every fluid
 field's bounds skips it entirely. Sleep (P5) wakes on a wind change so a settled banner does not stay
 asleep through a gust.
@@ -1748,6 +1758,15 @@ walk it. The visible consequence is that two garments spawned a second apart are
 the gust rather than in phase with it; for a bounded sum of sinusoids that is indistinguishable from
 weather, which is why this is free. `MEASUREMENTS.md` §57.
 
+**G2 (the GPU wind fluid's S5): the clock is the scene's, and the gate is restated.** The gust moved
+onto `GlobalFluidEffector` and runs on the scene's tick, so every consumer of the wind reads one
+weather — and a cloth steps in the weather of the tick it is advanced on. The worker advances a cloth
+from the tick its registration is acknowledged, so the gate now reads: **worker and inline agree for
+cloths registered on the same tick, and for any registration under a time-invariant wind.** Measured:
+the staggered spawn under a 3 m/s gust differs at the second cloth's step 1, byte 0; registered on
+the same tick, none in 180 steps. Under the GPU wind on a device, lattices land when the GPU answers,
+so run-to-run repeatability is given up too (F4). `MEASUREMENTS.md` §69.
+
 **And post-M6 found the other one, which is not a clock: the two systems ran a tick's phases in
 different orders.** `ClothSystem` ran advance, step and finish per cloth, in hierarchy-depth order, so
 a **nested** cloth advanced against an anchor the cloth above it had already written *this* step;

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

@@ -1 +1 @@
-{"version":3,"file":"ClothColliderKind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderKind.js"],"names":[],"mappings":";;;gCAeU,MAAM"}
+{"version":3,"file":"ClothColliderKind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderKind.js"],"names":[],"mappings":";;;gCAsBU,MAAM"}

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

@@ -1,3 +1,5 @@
+import { ShapeRecordKind } from "../../../../core/geom/3d/shape/record/ShapeRecordKind.js";
+
 /**
  * The shapes cloth collides against.
  *
@@ -9,8 +11,13 @@
  * answer is to add primitive `ClothCollider` children, which is what an author
  * would do for a character anyway.
  *
- * The values are indices into a dispatch, so they are contiguous from zero and
- * their order is the order `cloth_collider_sdf.js` branches in.
+ * A collider's kind and parameters are a core shape record
+ * (`core/geom/3d/shape/record/`), so the values are core's
+ * {@link ShapeRecordKind} and this is the subset of it cloth takes. Core also
+ * packs a rigid `TransformedShape3D` (with a pose offset), a `UnionShape3D`
+ * (as a run of records) and a `ConvexHullShape3D` (as planes in a table of
+ * their own); cloth refuses all three, as it always has, until it has somewhere
+ * to keep what each brings beyond a kind and four parameters.
  *
  * @readonly
  * @enum {number}
@@ -20,19 +27,19 @@
  */
 export const ClothColliderKind = {
     /** Radius in `CCR_PARAM_0`. */
-    Sphere: 0,
+    Sphere: ShapeRecordKind.Sphere,
 
     /** Radius in `CCR_PARAM_0`, segment length in `CCR_PARAM_1`, about local Y. */
-    Capsule: 1,
+    Capsule: ShapeRecordKind.Capsule,
 
     /** Half-extents in `CCR_PARAM_0..2`. */
-    Box: 2,
+    Box: ShapeRecordKind.Box,
 
     /** Radius in `CCR_PARAM_0`, height in `CCR_PARAM_1`, about local Y. */
-    Cylinder: 3,
+    Cylinder: ShapeRecordKind.Cylinder,
 
     /** Outward unit normal in `CCR_PARAM_0..2`, offset in `CCR_PARAM_3`. */
-    Plane: 4
+    Plane: ShapeRecordKind.Plane
 };
 
 Object.freeze(ClothColliderKind);

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

@@ -18,6 +18,13 @@
  * One layout, so the conversion between them is a loop over slots rather than
  * two structures that have to be kept in agreement.
  *
+ * ## The shape is a core shape record
+ *
+ * The kind and its four parameters are `core/geom/3d/shape/record/`'s layout,
+ * held at {@link CCR_SHAPE}, and core packs, bounds and evaluates them. What
+ * follows them — the feature size, friction, inflation, the poses and the
+ * bounds — is cloth's.
+ *
  * ## The pose is a translation and a quaternion, not a matrix
  *
  * §8.2 says swept collision comes from "interpolating the collider's pose
@@ -37,16 +44,21 @@
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
+/**
+ * Where the core shape record starts: its kind, then its four parameters. The
+ * offset core's pack, bounds and field take.
+ */
+export const CCR_SHAPE: 0;
 /** Shape kind — a {@link ClothColliderKind}. */
-export const CCR_KIND: 0;
+export const CCR_KIND: number;
 /** Shape parameter 0: radius, or half-extent x, or plane normal x. */
-export const CCR_PARAM_0: 1;
+export const CCR_PARAM_0: number;
 /** Shape parameter 1: height, or half-extent y, or plane normal y. */
-export const CCR_PARAM_1: 2;
+export const CCR_PARAM_1: number;
 /** Shape parameter 2: half-extent z, or plane normal z. */
-export const CCR_PARAM_2: 3;
+export const CCR_PARAM_2: number;
 /** Shape parameter 3: the plane's offset. Unused by every other kind. */
-export const CCR_PARAM_3: 4;
+export const CCR_PARAM_3: number;
 /**
  * The shape's smallest curvature radius, metres — `Infinity` for a plane.
  *
@@ -56,6 +68,8 @@ export const CCR_PARAM_3: 4;
  * description of a surface over the surface's own curvature radius and a poor
  * one beyond it, so this is that distance, measured from the shape rather than
  * tuned.
+ *
+ * The first of cloth's own slots, past the shape record's `SHAPE_RECORD_STRIDE`.
  */
 export const CCR_FEATURE: 5;
 /** Combined Coulomb friction coefficient for this collider against cloth. */

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

@@ -1 +1 @@
-{"version":3,"file":"ClothColliderRecord.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderRecord.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,gDAAgD;AAChD,yBAA0B;AAE1B,sEAAsE;AACtE,4BAA6B;AAE7B,sEAAsE;AACtE,4BAA6B;AAE7B,2DAA2D;AAC3D,4BAA6B;AAE7B,yEAAyE;AACzE,4BAA6B;AAE7B;;;;;;;;;GASG;AACH,4BAA6B;AAE7B,6EAA6E;AAC7E,6BAA8B;AAE9B,sEAAsE;AACtE,8BAA+B;AAE/B,iCAAiC;AACjC,uBAAwB;AACxB,uBAAwB;AACxB,wBAAyB;AAEzB,2CAA2C;AAC3C,wBAAyB;AACzB,wBAAyB;AACzB,wBAAyB;AACzB,wBAAyB;AAEzB,yCAAyC;AACzC,6BAA8B;AAC9B,6BAA8B;AAC9B,6BAA8B;AAE9B,mDAAmD;AACnD,6BAA8B;AAC9B,6BAA8B;AAC9B,6BAA8B;AAC9B,6BAA8B;AAE9B;;;;GAIG;AACH,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AAEjC;;;;GAIG;AACH,+BAAgC;AAChC,+BAAgC;AAChC,+BAAgC;AAEhC,+EAA+E;AAC/E,+BAAgC;AAChC,+BAAgC;AAChC,+BAAgC;AAChC,+BAAgC;AAEhC,4BAA4B;AAC5B,4BAA6B;AAE7B;;;;;GAKG;AACH,+BAAgC;AAChC,8BAA+B;AAC/B,gCAAiC;AAEjC,qCAAqC;AACrC,gCAAiC"}
+{"version":3,"file":"ClothColliderRecord.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderRecord.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;GAGG;AACH,0BAA2B;AAE3B,gDAAgD;AAChD,8BAAsD;AAEtD,sEAAsE;AACtE,iCAA4D;AAE5D,sEAAsE;AACtE,iCAA4D;AAE5D,2DAA2D;AAC3D,iCAA4D;AAE5D,yEAAyE;AACzE,iCAA4D;AAE5D;;;;;;;;;;;GAWG;AACH,4BAA6B;AAE7B,6EAA6E;AAC7E,6BAA8B;AAE9B,sEAAsE;AACtE,8BAA+B;AAE/B,iCAAiC;AACjC,uBAAwB;AACxB,uBAAwB;AACxB,wBAAyB;AAEzB,2CAA2C;AAC3C,wBAAyB;AACzB,wBAAyB;AACzB,wBAAyB;AACzB,wBAAyB;AAEzB,yCAAyC;AACzC,6BAA8B;AAC9B,6BAA8B;AAC9B,6BAA8B;AAE9B,mDAAmD;AACnD,6BAA8B;AAC9B,6BAA8B;AAC9B,6BAA8B;AAC9B,6BAA8B;AAE9B;;;;GAIG;AACH,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AACjC,gCAAiC;AAEjC;;;;GAIG;AACH,+BAAgC;AAChC,+BAAgC;AAChC,+BAAgC;AAEhC,+EAA+E;AAC/E,+BAAgC;AAChC,+BAAgC;AAChC,+BAAgC;AAChC,+BAAgC;AAEhC,4BAA4B;AAC5B,4BAA6B;AAE7B;;;;;GAKG;AACH,+BAAgC;AAChC,8BAA+B;AAC/B,gCAAiC;AAEjC,qCAAqC;AACrC,gCAAiC"}

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

@@ -1,3 +1,11 @@
+import {
+    SHAPE_RECORD_KIND,
+    SHAPE_RECORD_PARAM_0,
+    SHAPE_RECORD_PARAM_1,
+    SHAPE_RECORD_PARAM_2,
+    SHAPE_RECORD_PARAM_3
+} from "../../../../core/geom/3d/shape/record/ShapeRecord.js";
+
 /**
  * # One packed collider — the layout, and nothing else
  *
@@ -18,6 +26,13 @@
  * One layout, so the conversion between them is a loop over slots rather than
  * two structures that have to be kept in agreement.
  *
+ * ## The shape is a core shape record
+ *
+ * The kind and its four parameters are `core/geom/3d/shape/record/`'s layout,
+ * held at {@link CCR_SHAPE}, and core packs, bounds and evaluates them. What
+ * follows them — the feature size, friction, inflation, the poses and the
+ * bounds — is cloth's.
+ *
  * ## The pose is a translation and a quaternion, not a matrix
  *
  * §8.2 says swept collision comes from "interpolating the collider's pose
@@ -38,20 +53,26 @@
  * @copyright Company Named Limited (c) 2026
  */
 
+/**
+ * Where the core shape record starts: its kind, then its four parameters. The
+ * offset core's pack, bounds and field take.
+ */
+export const CCR_SHAPE = 0;
+
 /** Shape kind — a {@link ClothColliderKind}. */
-export const CCR_KIND = 0;
+export const CCR_KIND = CCR_SHAPE + SHAPE_RECORD_KIND;
 
 /** Shape parameter 0: radius, or half-extent x, or plane normal x. */
-export const CCR_PARAM_0 = 1;
+export const CCR_PARAM_0 = CCR_SHAPE + SHAPE_RECORD_PARAM_0;
 
 /** Shape parameter 1: height, or half-extent y, or plane normal y. */
-export const CCR_PARAM_1 = 2;
+export const CCR_PARAM_1 = CCR_SHAPE + SHAPE_RECORD_PARAM_1;
 
 /** Shape parameter 2: half-extent z, or plane normal z. */
-export const CCR_PARAM_2 = 3;
+export const CCR_PARAM_2 = CCR_SHAPE + SHAPE_RECORD_PARAM_2;
 
 /** Shape parameter 3: the plane's offset. Unused by every other kind. */
-export const CCR_PARAM_3 = 4;
+export const CCR_PARAM_3 = CCR_SHAPE + SHAPE_RECORD_PARAM_3;
 
 /**
  * The shape's smallest curvature radius, metres — `Infinity` for a plane.
@@ -62,6 +83,8 @@ export const CCR_PARAM_3 = 4;
  * description of a surface over the surface's own curvature radius and a poor
  * one beyond it, so this is that distance, measured from the shape rather than
  * tuned.
+ *
+ * The first of cloth's own slots, past the shape record's `SHAPE_RECORD_STRIDE`.
  */
 export const CCR_FEATURE = 5;
 

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

@@ -5,8 +5,9 @@
  * It runs when a `ClothCollider` is linked or its shape changes, never per step
  * and never per particle.
  *
- * Each kind is asked by its prototype marker, as the physics narrowphase asks;
- * the five are unrelated classes, so the order of the tests does not matter.
+ * The kind and parameters are a core shape record, written by core's analytic
+ * pack, which asks each kind by its prototype marker as the physics
+ * narrowphase does. What cloth adds is the feature size.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_collider_pack.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_pack.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH,2CAPW,YAAY,GAAC,YAAY,UACzB,MAAM,kCAEN,MAAM,GACJ,OAAO,CAiFnB;AAED;;;;;;;;;;;;;;GAcG;AACH,iDANW,YAAY,GAAC,MAAM,EAAE,SACrB,YAAY,GAAC,YAAY,UACzB,MAAM,UACN,MAAM,GACJ,OAAO,CAqCnB"}
+{"version":3,"file":"cloth_collider_pack.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_pack.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;GASG;AACH,2CAPW,YAAY,GAAC,YAAY,UACzB,MAAM,kCAEN,MAAM,GACJ,OAAO,CAoCnB;AAED;;;;;;;;;;;;;;GAcG;AACH,iDANW,YAAY,GAAC,MAAM,EAAE,SACrB,YAAY,GAAC,YAAY,UACzB,MAAM,UACN,MAAM,GACJ,OAAO,CAInB"}

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

@@ -1,12 +1,7 @@
+import { shape_record_local_bounds } from "../../../../core/geom/3d/shape/record/shape_record_local_bounds.js";
+import { shape_record_pack_analytic } from "../../../../core/geom/3d/shape/record/shape_record_pack.js";
 import { ClothColliderKind } from "./ClothColliderKind.js";
-import {
-    CCR_FEATURE,
-    CCR_KIND,
-    CCR_PARAM_0,
-    CCR_PARAM_1,
-    CCR_PARAM_2,
-    CCR_PARAM_3
-} from "./ClothColliderRecord.js";
+import { CCR_FEATURE, CCR_KIND, CCR_PARAM_0, CCR_PARAM_1, CCR_PARAM_2, CCR_SHAPE } from "./ClothColliderRecord.js";
 
 /**
  * # `AbstractShape3D` → a packed record's geometry
@@ -15,8 +10,9 @@ import {
  * It runs when a `ClothCollider` is linked or its shape changes, never per step
  * and never per particle.
  *
- * Each kind is asked by its prototype marker, as the physics narrowphase asks;
- * the five are unrelated classes, so the order of the tests does not matter.
+ * The kind and parameters are a core shape record, written by core's analytic
+ * pack, which asks each kind by its prototype marker as the physics
+ * narrowphase does. What cloth adds is the feature size.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -35,81 +31,36 @@ import {
 export function cloth_collider_pack(table, record, shape, stride) {
     const r = record * stride;
 
-    if (shape.isSphereShape3D === true) {
-        // Covers UnitSphereShape3D, which is a SphereShape3D of radius 1.
-        const radius = shape.radius;
-
-        table[r + CCR_KIND] = ClothColliderKind.Sphere;
-        table[r + CCR_PARAM_0] = radius;
-        table[r + CCR_PARAM_1] = 0;
-        table[r + CCR_PARAM_2] = 0;
-        table[r + CCR_PARAM_3] = 0;
-        table[r + CCR_FEATURE] = radius;
-
-        return true;
-    }
-
-    if (shape.isCapsuleShape3D === true) {
-        const radius = shape.radius;
-
-        table[r + CCR_KIND] = ClothColliderKind.Capsule;
-        table[r + CCR_PARAM_0] = radius;
-        table[r + CCR_PARAM_1] = shape.height;
-        table[r + CCR_PARAM_2] = 0;
-        table[r + CCR_PARAM_3] = 0;
-
-        // A capsule's tightest curvature is its cap, which is its own radius.
-        table[r + CCR_FEATURE] = radius;
-
-        return true;
+    // Core's analytic kinds and nothing else; see ClothColliderKind for the
+    // ones core packs and cloth does not take.
+    if (!shape_record_pack_analytic(table, r + CCR_SHAPE, shape)) {
+        return false;
     }
 
-    if (shape.isBoxShape3D === true) {
-        // Covers UnitCubeShape3D, which is a BoxShape3D pinned to 0.5.
-        const h = shape.half_extents;
-
-        table[r + CCR_KIND] = ClothColliderKind.Box;
-        table[r + CCR_PARAM_0] = h.x;
-        table[r + CCR_PARAM_1] = h.y;
-        table[r + CCR_PARAM_2] = h.z;
-        table[r + CCR_PARAM_3] = 0;
+    // The feature size is read back from the parameters just written. In a
+    // Float32 table that is the same number as from the shape: rounding is
+    // monotonic, so the smallest rounded half-extent is the rounded smallest,
+    // and halving a float is exact.
+    const kind = table[r + CCR_KIND];
 
+    if (kind === ClothColliderKind.Sphere || kind === ClothColliderKind.Capsule) {
+        // A sphere's curvature radius is its radius; a capsule's tightest
+        // curvature is its cap, which is its own radius.
+        table[r + CCR_FEATURE] = table[r + CCR_PARAM_0];
+    } else if (kind === ClothColliderKind.Box) {
         // A box has no curvature; its edges are creases, and the distance over
         // which "the nearest face's normal" describes the surface is how far
         // the nearest face extends — its smallest half-extent, conservatively.
-        table[r + CCR_FEATURE] = Math.min(h.x, Math.min(h.y, h.z));
-
-        return true;
-    }
-
-    if (shape.isCylinderShape3D === true) {
-        const radius = shape.radius;
-
-        table[r + CCR_KIND] = ClothColliderKind.Cylinder;
-        table[r + CCR_PARAM_0] = radius;
-        table[r + CCR_PARAM_1] = shape.height;
-        table[r + CCR_PARAM_2] = 0;
-        table[r + CCR_PARAM_3] = 0;
-        table[r + CCR_FEATURE] = Math.min(radius, shape.height * 0.5);
-
-        return true;
-    }
-
-    if (shape.isPlaneShape3D === true) {
-        table[r + CCR_KIND] = ClothColliderKind.Plane;
-        table[r + CCR_PARAM_0] = shape.normal_x;
-        table[r + CCR_PARAM_1] = shape.normal_y;
-        table[r + CCR_PARAM_2] = shape.normal_z;
-        table[r + CCR_PARAM_3] = shape.offset;
-
+        table[r + CCR_FEATURE] = Math.min(table[r + CCR_PARAM_0], Math.min(table[r + CCR_PARAM_1], table[r + CCR_PARAM_2]));
+    } else if (kind === ClothColliderKind.Cylinder) {
+        table[r + CCR_FEATURE] = Math.min(table[r + CCR_PARAM_0], table[r + CCR_PARAM_1] * 0.5);
+    } else {
         // A plane is flat everywhere, so its normal describes it at any
         // distance and it never narrows a trust region.
         table[r + CCR_FEATURE] = Infinity;
-
-        return true;
     }
 
-    return false;
+    return true;
 }
 
 /**
@@ -128,38 +79,5 @@ export function cloth_collider_pack(table, record, shape, stride) {
  * @returns {boolean} `false` for an unbounded kind, in which case `out` is untouched
  */
 export function cloth_collider_local_bounds(out, table, record, stride) {
-    const r = record * stride;
-
-    const kind = table[r + CCR_KIND];
-
-    let hx;
-    let hy;
-    let hz;
-
-    if (kind === ClothColliderKind.Sphere) {
-        hx = hy = hz = table[r + CCR_PARAM_0];
-    } else if (kind === ClothColliderKind.Capsule) {
-        const radius = table[r + CCR_PARAM_0];
-
-        hx = hz = radius;
-        hy = radius + table[r + CCR_PARAM_1] * 0.5;
-    } else if (kind === ClothColliderKind.Box) {
-        hx = table[r + CCR_PARAM_0];
-        hy = table[r + CCR_PARAM_1];
-        hz = table[r + CCR_PARAM_2];
-    } else if (kind === ClothColliderKind.Cylinder) {
-        hx = hz = table[r + CCR_PARAM_0];
-        hy = table[r + CCR_PARAM_1] * 0.5;
-    } else {
-        return false;
-    }
-
-    out[0] = -hx;
-    out[1] = -hy;
-    out[2] = -hz;
-    out[3] = hx;
-    out[4] = hy;
-    out[5] = hz;
-
-    return true;
+    return shape_record_local_bounds(out, table, record * stride + CCR_SHAPE);
 }

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

@@ -12,11 +12,12 @@
  * costs less than storing an inverse and is exact rather than cached.
  *
  * The fields themselves live in `core/geom/3d/shape/sdf/` as free functions,
- * so this dispatch, through their array forms, and {@link SphereShape3D} and
- * the rest, through their scalar forms, are calling one implementation
- * (§14.1). Before M2 those shapes fell back to
- * `compute_signed_distance_gradient_by_sampling` — four field evaluations and a
- * normalise, for shapes whose gradients are two lines of algebra.
+ * and the dispatch over a record's kind in `core/geom/3d/shape/record/`, so
+ * this, through their array forms, and {@link SphereShape3D} and the rest,
+ * through their scalar forms, are calling one implementation (§14.1). Before
+ * M2 those shapes fell back to `compute_signed_distance_gradient_by_sampling`
+ * — four field evaluations and a normalise, for shapes whose gradients are two
+ * lines of algebra.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_collider_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_sdf.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8CALW,YAAY,GAAC,YAAY,SACzB,MAAM,KACN,MAAM,GACJ,IAAI,CAmBhB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,mBAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;;;;;;;;;GAcG;AACH,0DATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAElC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,GACJ,IAAI,CAgChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAQhB;AAED;;;;;;;;;;;GAWG;AACH,qDARW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,GACJ,IAAI,CAMhB;AAED;;;;;;;;;;;;;GAaG;AACH,6CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAQhB;AAED;;;;;;;;;;;GAWG;AACH,mDARW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,GACJ,IAAI,CAMhB"}
+{"version":3,"file":"cloth_collider_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_sdf.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8CALW,YAAY,GAAC,YAAY,SACzB,MAAM,KACN,MAAM,GACJ,IAAI,CAmBhB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,mBAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;;;;;;;;;GAcG;AACH,0DATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAElC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,GACJ,IAAI,CAoBhB;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAQhB;AAED;;;;;;;;;;;GAWG;AACH,qDARW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,GACJ,IAAI,CAMhB;AAED;;;;;;;;;;;;;GAaG;AACH,6CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAQhB;AAED;;;;;;;;;;;GAWG;AACH,mDARW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,SACN,YAAY,GAAC,YAAY,UACzB,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,GACJ,IAAI,CAMhB"}