@woosh/meep-engine 3.24.0 → 3.26.0

package/src/engine/physics/cloth/solver/cloth_step_instance.js

@@ -0,0 +1,284 @@
+import { cloth_contact_find } from "./cloth_contact_find.js";
+import { cloth_self_find } from "./cloth_self_find.js";
+import { cloth_step } from "./cloth_step.js";
+import { cloth_wind_accelerate } from "./cloth_wind_accelerate.js";
+import { ClothStepResult } from "./ClothState.js";
+
+/**
+ * # One cloth, one step, over nothing but memory
+ *
+ * Everything between the broadphase and the write-back: the velocity damping,
+ * the contact search, the self-collision pair search, the solve, and the
+ * velocity clamp. It reads a {@link ClothState} and a block of \`Float64\`
+ * parameters and it writes the state and three result words. It touches no
+ * component, no entity, no index, and no clock.
+ *
+ * **That is the whole of what crosses to the worker**, and the parameters are a
+ * block of words rather than a dozen arguments for exactly that reason: the
+ * block *is* the command region. \`ClothSystem\` fills a private copy of it and
+ * calls this inline; \`WorkerClothSystem\` fills a slice of the shared command
+ * region and the worker calls this with the same words. The two paths cannot
+ * drift because there is one function and one layout — which is what §12's
+ * bit-parity gate asks for, expressed as code rather than as a test.
+ *
+ * \`Float64\` throughout the block, and that is load-bearing rather than
+ * incidental. Every number here — \`dt\`, the local gravity, the retention, the
+ * clamp — is computed on the main thread in double and consumed here in double,
+ * so the round trip through shared memory is exact. An \`f32\` command region
+ * would round the clamp, and a clamp that rounds is a velocity that rounds, and
+ * a velocity that rounds is a cloth that diverges over six hundred steps.
+ *
+ * ## What is deliberately *not* here
+ *
+ * The leash centres (they come from the animated pose, which lives on the
+ * instance), the collider gather (it needs the world's index), the frame move
+ * (it needs the anchor's pose), and — M6 — the **air sample**, which needs a
+ * fluid field and a world position. Those are §12's "arbitrary user-facing
+ * work" and they stay on the main thread in both systems.
+ *
+ * What is *here* is the aerodynamic term itself, which is the M6 decision worth
+ * naming: the air crosses as three floats a particle in the state's own buffer,
+ * and everything built from it — the relative flow, the normal-facing factor,
+ * the acceleration — is computed on this side, by this function, once. Putting
+ * the drag arithmetic on the main thread instead would have given back a share
+ * of what M5 bought and would have made the wind a parameter each system
+ * computed for itself, which is exactly the shape `MEASUREMENTS.md` §40 says
+ * breaks the parity gate. It is one per cent of a step
+ * (\`MEASUREMENTS.md\` §49).
+ *
+ * What is left here either way is the part the budget is spent on:
+ * \`MEASUREMENTS.md\` §7 puts 69% of a frame in the stretch rows alone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Words of one cloth's parameter block.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ClothStepParam = {
+    /**
+     * Which cloth this block is for. Meaningless to the step itself — the
+     * worker reads it to find the state, and it lives in the block rather than
+     * in a parallel list so that one stride is the whole per-cloth record.
+     */
+    ID: 0,
+    /**
+     * Seconds of the fixed step.
+     */
+    DT: 1,
+    /**
+     * Gravity, already rotated into the cloth's local frame.
+     */
+    GRAVITY_X: 2,
+    GRAVITY_Y: 3,
+    GRAVITY_Z: 4,
+    /**
+     * `ClothDynamics#substeps`.
+     */
+    SUBSTEPS: 5,
+    /**
+     * `ClothDynamics#iterations`.
+     */
+    ITERATIONS: 6,
+    /**
+     * Per-step velocity retention in `[0, 1]`, from `ClothDynamics#damping`.
+     */
+    RETENTION: 7,
+    /**
+     * Speed ceiling in m/s, §7 P1's clamp — already scaled by whatever is left
+     * of a stabilisation window, because the ramp is the caller's bookkeeping
+     * and the clamp is only the number.
+     */
+    VELOCITY_LIMIT: 8,
+    /**
+     * `ClothDynamics#thickness`, metres.
+     */
+    CONTACT_RADIUS: 9,
+    /**
+     * The self-collision row's radius, metres. Read only when
+     * {@link ClothStepParam.SELF_COLLISION} is set — a cloth with the flag
+     * clear keeps whatever radius it last had, because the row that would read
+     * it does not run.
+     */
+    SELF_RADIUS: 10,
+    /**
+     * Live records in the state's collider table, as the gather left it.
+     */
+    COLLIDER_COUNT: 11,
+    /**
+     * Non-zero when `ClothDynamicsFlags.SelfCollision` is set.
+     */
+    SELF_COLLISION: 12,
+    /**
+     * §10's aerodynamic coupling, as the **per-step response**
+     * `(1 − e^(−rate·dt))/dt` in 1/s rather than as a rate — see
+     * `cloth_wind_accelerate` for why that form cannot overshoot at any `dt`.
+     *
+     * Zero means there is no air to feel: no fabric drag, or an ambient of
+     * exactly nothing. The step then skips the aerodynamic term altogether and
+     * takes `cloth_step`'s uniform-gravity path, which is the path M0 through
+     * M5 measured.
+     */
+    DRAG_RESPONSE: 13
+};
+
+/**
+ * `Float64` words one cloth's parameter block occupies.
+ * @type {number}
+ */
+export const CLOTH_STEP_PARAM_STRIDE = 14;
+
+/**
+ * Step one cloth.
+ *
+ * @param {ClothState} state the cloth, with its collider table already gathered
+ * @param {{offset: Int32Array, partner: Int32Array}|null} self_exclusions pairs
+ *   a persistent row already governs; `null` when the cloth never self-collides
+ * @param {Float64Array} params
+ * @param {number} offset first word of this cloth's block in `params`
+ * @returns {void}
+ */
+export function cloth_step_instance(state, self_exclusions, params, offset) {
+    const dt = params[offset + ClothStepParam.DT];
+
+    const collider_count = params[offset + ClothStepParam.COLLIDER_COUNT];
+
+    const gravity_x = params[offset + ClothStepParam.GRAVITY_X];
+    const gravity_y = params[offset + ClothStepParam.GRAVITY_Y];
+    const gravity_z = params[offset + ClothStepParam.GRAVITY_Z];
+
+    const drag_response = params[offset + ClothStepParam.DRAG_RESPONSE];
+
+    state.contact_radius = params[offset + ClothStepParam.CONTACT_RADIUS];
+    state.collider_count = collider_count;
+
+    damp(state, params[offset + ClothStepParam.RETENTION]);
+
+    const contact_count = cloth_contact_find(
+        state, state.collider_table, state.collider_key, collider_count, dt
+    );
+
+    let self_pairs = 0;
+
+    if (params[offset + ClothStepParam.SELF_COLLISION] !== 0) {
+        state.self_radius = params[offset + ClothStepParam.SELF_RADIUS];
+
+        self_pairs = cloth_self_find(state, self_exclusions);
+    } else {
+        state.self_count = 0;
+    }
+
+    let external = null;
+
+    if (drag_response !== 0) {
+        // §10, and once per step rather than once per iteration. The air itself
+        // was sampled on the main thread into `state.air_velocity`; what is
+        // left is arithmetic over positions and velocities this state already
+        // holds, so it runs here with the rest of the arithmetic and neither
+        // system computes it separately.
+        cloth_wind_accelerate(state, drag_response, gravity_x, gravity_y, gravity_z);
+
+        external = state.external_acceleration;
+    }
+
+    cloth_step(
+        state, dt,
+        gravity_x, gravity_y, gravity_z,
+        params[offset + ClothStepParam.SUBSTEPS],
+        params[offset + ClothStepParam.ITERATIONS],
+        state.collider_table, collider_count,
+        undefined,
+        external
+    );
+
+    const result = state.result;
+
+    result[ClothStepResult.SPEED] = clamp_velocity(state, params[offset + ClothStepParam.VELOCITY_LIMIT]);
+    result[ClothStepResult.CONTACT_COUNT] = contact_count;
+    result[ClothStepResult.SELF_PAIRS] = self_pairs;
+}
+
+/**
+ * Scale every particle's velocity, which is §7 P5's other half.
+ *
+ * The multiplier decay `α·γ` bleeds accumulated force out of a **hard** row,
+ * and a soft row has no multiplier to decay — M0 measured a soft cloth landing
+ * in a bounded limit cycle that 2,000 further steps do not move. This is what
+ * reaches it, and it is why `ClothDynamics#damping` is part of the correctness
+ * argument rather than a taste control. `MEASUREMENTS.md` §6.
+ *
+ * @param {ClothState} state
+ * @param {number} retention `[0, 1]`
+ * @private
+ */
+function damp(state, retention) {
+    if (retention >= 1) {
+        return;
+    }
+
+    const velocity = state.velocity;
+
+    for (let i = 0; i < velocity.length; i++) {
+        velocity[i] *= retention;
+    }
+}
+
+/**
+ * Hold every particle's speed under the limit derived from
+ * `ClothDynamics#thickness`, and report the largest speed left afterwards so
+ * the sleep test has something to read.
+ *
+ * §7 P1 names this clamp and M0 deliberately left it out, because a clamp would
+ * have masked the property M0 existed to measure. It is here rather than inside
+ * `cloth_step` for the same reason: the solver's stability is still its own.
+ *
+ * Speed rather than displacement is what the sleep test reads, because
+ * `position_previous` after a multi-substep step holds the start of the *last*
+ * substep rather than the start of the step, and a motion measure that quietly
+ * divides by the substep count is a sleep threshold that means something
+ * different for every fabric.
+ *
+ * @param {ClothState} state
+ * @param {number} limit m/s
+ * @returns {number} largest particle speed after clamping, m/s
+ * @private
+ */
+function clamp_velocity(state, limit) {
+    const particle_count = state.particle_count;
+
+    const velocity = state.velocity;
+
+    const limit_squared = limit * limit;
+
+    let worst_squared = 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const vx = velocity[p];
+        const vy = velocity[p + 1];
+        const vz = velocity[p + 2];
+
+        let speed_squared = vx * vx + vy * vy + vz * vz;
+
+        if (speed_squared > limit_squared) {
+            const scale = limit / Math.sqrt(speed_squared);
+
+            velocity[p] = vx * scale;
+            velocity[p + 1] = vy * scale;
+            velocity[p + 2] = vz * scale;
+
+            speed_squared = limit_squared;
+        }
+
+        if (speed_squared > worst_squared) {
+            worst_squared = speed_squared;
+        }
+    }
+
+    return Math.sqrt(worst_squared);
+}

package/src/engine/physics/cloth/solver/cloth_wind_accelerate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Write the whole external acceleration — gravity plus §10's aerodynamic drag —
+ * into {@link ClothState#external_acceleration}.
+ *
+ * @param {ClothState} state with {@link ClothState#air_velocity} already filled
+ *   in the cloth's own frame
+ * @param {number} response `(1 − e^(−rate·dt))/dt`, 1/s; `0` means no wind and
+ *   this function should not have been called
+ * @param {number} gravity_x cloth-local gravity, m/s²
+ * @param {number} gravity_y
+ * @param {number} gravity_z
+ * @returns {void}
+ */
+export function cloth_wind_accelerate(state: ClothState, response: number, gravity_x: number, gravity_y: number, gravity_z: number): void;
+/**
+ * How much of a unit flow the particle's own incident rows cannot let past,
+ * `[0, 1]`. The table in this module's header is what the three cases mean.
+ *
+ * Exported because it is the whole of what M6 added to the physics and a spec
+ * that can only reach it through a step is a spec measuring six other things at
+ * once.
+ *
+ * @param {Float32Array} position particle positions, 3 each
+ * @param {Int32Array} offset `ClothState#stretch_adjacency_offset`
+ * @param {Int32Array} adjacency `ClothState#stretch_adjacency`, `(row << 1) | slot`
+ * @param {Int32Array} row_particle `ClothState#stretch_particle`
+ * @param {number} particle
+ * @param {number} unit_x flow direction, unit length
+ * @param {number} unit_y
+ * @param {number} unit_z
+ * @returns {number}
+ */
+export function cloth_wind_facing(position: Float32Array, offset: Int32Array, adjacency: Int32Array, row_particle: Int32Array, particle: number, unit_x: number, unit_y: number, unit_z: number): number;
+/**
+ * # The aerodynamic term, and the factor that makes a flag a flag
+ *
+ * §10's model: a particle in moving air feels
+ *
+ *     a_drag = response · facing · (u_air − v)
+ *
+ * where `u_air` is what the main thread sampled into
+ * {@link ClothState#air_velocity} and `facing` is how much of the flow the
+ * particle's own local geometry cannot let through. Gravity is added to the
+ * same word, so what comes out is the **whole** external acceleration and
+ * `cloth_step` reads one array instead of a vector plus a special case.
+ *
+ * Once per particle per **step**, never per iteration, which is §10's own cost
+ * rule. A cloth with `response = 0` — no fabric drag, or no air moving — does
+ * not run this at all and `cloth_step` takes its uniform-gravity path, so a
+ * scene with no wind in it pays nothing and produces the bytes M5 measured.
+ *
+ * ## `response` rather than a rate, and why it cannot overshoot
+ *
+ * The caller hands in `(1 − e^(−rate·dt))/dt` rather than `rate`
+ * (`cloth_drag_response`), so the velocity change across the step is
+ *
+ *     Δv = a_drag · dt = (1 − e^(−rate·dt)) · facing · (u_air − v)
+ *
+ * — a fraction of the gap to the air that is **strictly below one** for any
+ * `rate`, any `dt` and any `facing ≤ 1`. An explicit drag written as `rate`
+ * instead overshoots once `rate·dt > 1` and diverges past 2, which at §1's "not
+ * at 5 fps" is a 0.2 s step and a rate of 10. This is the same exact-ODE step
+ * `GlobalFluidEffector` takes for the air itself, which is a pleasant symmetry
+ * rather than a coincidence: both are relaxations toward a velocity.
+ *
+ * ## The facing factor: §10 asked for `|n·û|` and a rope has no `n`
+ *
+ * §10 writes the factor as `|n·û|` — "the difference between a flag and a
+ * rope". The normal is the half a **rope** does not have: a chain's particles
+ * span a line, every direction perpendicular to it is equally a normal, and any
+ * one this code picked would be a fabrication of the kind §7 P4(a) exists to
+ * keep out. A rope also wants the *opposite* dependence — it catches the flow
+ * across it and slices along it, where a sheet catches it along the normal and
+ * slices across.
+ *
+ * Both are one quantity: **the part of the flow the particle's incident rows
+ * cannot let past**. Take the span `T` of the directions to the particle's
+ * stretch-row neighbours in the current configuration and the factor is
+ * `‖û − proj_T(û)‖`:
+ *
+ * | rank of `T` | what the particle is | the factor |
+ * |---|---|---|
+ * | 2 | a point on a surface | `\|û·n‖` with `n = b₁×b₂` — §10's own expression |
+ * | 1 | a link of a chain | `√(1 − (û·t)²)` — cross-flow, the rope's answer |
+ * | 0 | an isolated particle | `1` — a bead has no preferred direction |
+ *
+ * One expression, three topologies, no stored normal, no orientation, no sign,
+ * and nothing carried between steps — recomputed from the configuration every
+ * step, which is exactly what P4(a) asks of a normal. `MEASUREMENTS.md` §46.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * How much of a second incident direction has to survive projection out of the
+ * first before it counts as spanning a plane with it.
+ *
+ * A quarter is about fourteen degrees. Below it the two rows describe the same
+ * line as far as a normal is concerned, and the cross product of two nearly
+ * parallel directions is a normal built almost entirely out of rounding — which
+ * on a sheet under tension is every pair of rows on the same edge (the fabric
+ * row and the strain-limit row backing it up) and on a chain is every skip row
+ * beside the link it skips.
+ * @type {number}
+ */
+export const CLOTH_WIND_SPAN_MIN: number;
+//# sourceMappingURL=cloth_wind_accelerate.d.ts.map

package/src/engine/physics/cloth/solver/cloth_wind_accelerate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_wind_accelerate.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_wind_accelerate.js"],"names":[],"mappings":"AA2EA;;;;;;;;;;;;GAYG;AACH,mEAPW,MAAM,aAEN,MAAM,aACN,MAAM,aACN,MAAM,GACJ,IAAI,CA4DhB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAVW,YAAY,UACZ,UAAU,aACV,UAAU,gBACV,UAAU,YACV,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAkGlB;AAtQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH;;;;;;;;;;;GAWG;AACH,kCAFU,MAAM,CAEwB"}

package/src/engine/physics/cloth/solver/cloth_wind_accelerate.js

@@ -0,0 +1,263 @@
+/**
+ * # The aerodynamic term, and the factor that makes a flag a flag
+ *
+ * §10's model: a particle in moving air feels
+ *
+ *     a_drag = response · facing · (u_air − v)
+ *
+ * where `u_air` is what the main thread sampled into
+ * {@link ClothState#air_velocity} and `facing` is how much of the flow the
+ * particle's own local geometry cannot let through. Gravity is added to the
+ * same word, so what comes out is the **whole** external acceleration and
+ * `cloth_step` reads one array instead of a vector plus a special case.
+ *
+ * Once per particle per **step**, never per iteration, which is §10's own cost
+ * rule. A cloth with `response = 0` — no fabric drag, or no air moving — does
+ * not run this at all and `cloth_step` takes its uniform-gravity path, so a
+ * scene with no wind in it pays nothing and produces the bytes M5 measured.
+ *
+ * ## `response` rather than a rate, and why it cannot overshoot
+ *
+ * The caller hands in `(1 − e^(−rate·dt))/dt` rather than `rate`
+ * (`cloth_drag_response`), so the velocity change across the step is
+ *
+ *     Δv = a_drag · dt = (1 − e^(−rate·dt)) · facing · (u_air − v)
+ *
+ * — a fraction of the gap to the air that is **strictly below one** for any
+ * `rate`, any `dt` and any `facing ≤ 1`. An explicit drag written as `rate`
+ * instead overshoots once `rate·dt > 1` and diverges past 2, which at §1's "not
+ * at 5 fps" is a 0.2 s step and a rate of 10. This is the same exact-ODE step
+ * `GlobalFluidEffector` takes for the air itself, which is a pleasant symmetry
+ * rather than a coincidence: both are relaxations toward a velocity.
+ *
+ * ## The facing factor: §10 asked for `|n·û|` and a rope has no `n`
+ *
+ * §10 writes the factor as `|n·û|` — "the difference between a flag and a
+ * rope". The normal is the half a **rope** does not have: a chain's particles
+ * span a line, every direction perpendicular to it is equally a normal, and any
+ * one this code picked would be a fabrication of the kind §7 P4(a) exists to
+ * keep out. A rope also wants the *opposite* dependence — it catches the flow
+ * across it and slices along it, where a sheet catches it along the normal and
+ * slices across.
+ *
+ * Both are one quantity: **the part of the flow the particle's incident rows
+ * cannot let past**. Take the span `T` of the directions to the particle's
+ * stretch-row neighbours in the current configuration and the factor is
+ * `‖û − proj_T(û)‖`:
+ *
+ * | rank of `T` | what the particle is | the factor |
+ * |---|---|---|
+ * | 2 | a point on a surface | `\|û·n‖` with `n = b₁×b₂` — §10's own expression |
+ * | 1 | a link of a chain | `√(1 − (û·t)²)` — cross-flow, the rope's answer |
+ * | 0 | an isolated particle | `1` — a bead has no preferred direction |
+ *
+ * One expression, three topologies, no stored normal, no orientation, no sign,
+ * and nothing carried between steps — recomputed from the configuration every
+ * step, which is exactly what P4(a) asks of a normal. `MEASUREMENTS.md` §46.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * How much of a second incident direction has to survive projection out of the
+ * first before it counts as spanning a plane with it.
+ *
+ * A quarter is about fourteen degrees. Below it the two rows describe the same
+ * line as far as a normal is concerned, and the cross product of two nearly
+ * parallel directions is a normal built almost entirely out of rounding — which
+ * on a sheet under tension is every pair of rows on the same edge (the fabric
+ * row and the strain-limit row backing it up) and on a chain is every skip row
+ * beside the link it skips.
+ * @type {number}
+ */
+export const CLOTH_WIND_SPAN_MIN = 0.25;
+
+/**
+ * Write the whole external acceleration — gravity plus §10's aerodynamic drag —
+ * into {@link ClothState#external_acceleration}.
+ *
+ * @param {ClothState} state with {@link ClothState#air_velocity} already filled
+ *   in the cloth's own frame
+ * @param {number} response `(1 − e^(−rate·dt))/dt`, 1/s; `0` means no wind and
+ *   this function should not have been called
+ * @param {number} gravity_x cloth-local gravity, m/s²
+ * @param {number} gravity_y
+ * @param {number} gravity_z
+ * @returns {void}
+ */
+export function cloth_wind_accelerate(state, response, gravity_x, gravity_y, gravity_z) {
+    const particle_count = state.particle_count;
+
+    const air = state.air_velocity;
+    const out = state.external_acceleration;
+    const velocity = state.velocity;
+    const position = state.position;
+    const mass_inverse = state.mass_inverse;
+
+    const offset = state.stretch_adjacency_offset;
+    const adjacency = state.stretch_adjacency;
+    const row_particle = state.stretch_particle;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        out[p] = gravity_x;
+        out[p + 1] = gravity_y;
+        out[p + 2] = gravity_z;
+
+        if (mass_inverse[i] === 0) {
+            // Pinned. `cloth_predict` holds it exactly and never reads its
+            // acceleration, so the facing walk would be work for nothing —
+            // and a pin is the whole edge of a flag, which is a real share of
+            // a banner's particles.
+            continue;
+        }
+
+        const flow_x = air[p] - velocity[p];
+        const flow_y = air[p + 1] - velocity[p + 1];
+        const flow_z = air[p + 2] - velocity[p + 2];
+
+        const speed = Math.sqrt(flow_x * flow_x + flow_y * flow_y + flow_z * flow_z);
+
+        if (speed === 0) {
+            // Moving exactly with the air. No flow, no direction to face, and
+            // the factor would be a division by zero rather than a small
+            // number.
+            continue;
+        }
+
+        const inverse_speed = 1 / speed;
+
+        const facing = cloth_wind_facing(
+            position, offset, adjacency, row_particle, i,
+            flow_x * inverse_speed, flow_y * inverse_speed, flow_z * inverse_speed
+        );
+
+        if (facing === 0) {
+            continue;
+        }
+
+        const scale = response * facing;
+
+        out[p] += scale * flow_x;
+        out[p + 1] += scale * flow_y;
+        out[p + 2] += scale * flow_z;
+    }
+}
+
+/**
+ * How much of a unit flow the particle's own incident rows cannot let past,
+ * `[0, 1]`. The table in this module's header is what the three cases mean.
+ *
+ * Exported because it is the whole of what M6 added to the physics and a spec
+ * that can only reach it through a step is a spec measuring six other things at
+ * once.
+ *
+ * @param {Float32Array} position particle positions, 3 each
+ * @param {Int32Array} offset `ClothState#stretch_adjacency_offset`
+ * @param {Int32Array} adjacency `ClothState#stretch_adjacency`, `(row << 1) | slot`
+ * @param {Int32Array} row_particle `ClothState#stretch_particle`
+ * @param {number} particle
+ * @param {number} unit_x flow direction, unit length
+ * @param {number} unit_y
+ * @param {number} unit_z
+ * @returns {number}
+ */
+export function cloth_wind_facing(
+    position, offset, adjacency, row_particle, particle,
+    unit_x, unit_y, unit_z
+) {
+    const p = particle * 3;
+
+    const x = position[p];
+    const y = position[p + 1];
+    const z = position[p + 2];
+
+    const end = offset[particle + 1];
+
+    let b1x = 0;
+    let b1y = 0;
+    let b1z = 0;
+
+    let rank = 0;
+
+    for (let a = offset[particle]; a < end; a++) {
+        const entry = adjacency[a];
+
+        // `(row << 1) | slot` for a two-particle row, so the partner is the
+        // other slot of the same row.
+        const other = row_particle[(entry >> 1) * 2 + (1 - (entry & 1))] * 3;
+
+        let dx = position[other] - x;
+        let dy = position[other + 1] - y;
+        let dz = position[other + 2] - z;
+
+        const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+        if (length === 0) {
+            // Two particles on top of each other. The row itself is degenerate
+            // and every other row kind guards it the same way.
+            continue;
+        }
+
+        const inverse_length = 1 / length;
+
+        dx *= inverse_length;
+        dy *= inverse_length;
+        dz *= inverse_length;
+
+        if (rank === 0) {
+            b1x = dx;
+            b1y = dy;
+            b1z = dz;
+
+            rank = 1;
+
+            continue;
+        }
+
+        // Reject the first basis direction and see whether anything is left.
+        const along = dx * b1x + dy * b1y + dz * b1z;
+
+        let rx = dx - along * b1x;
+        let ry = dy - along * b1y;
+        let rz = dz - along * b1z;
+
+        const residual = Math.sqrt(rx * rx + ry * ry + rz * rz);
+
+        if (residual < CLOTH_WIND_SPAN_MIN) {
+            continue;
+        }
+
+        const inverse_residual = 1 / residual;
+
+        rx *= inverse_residual;
+        ry *= inverse_residual;
+        rz *= inverse_residual;
+
+        // `b1 × b2` is a unit normal because the two are orthonormal by
+        // construction, so the facing factor needs no second normalise.
+        const nx = b1y * rz - b1z * ry;
+        const ny = b1z * rx - b1x * rz;
+        const nz = b1x * ry - b1y * rx;
+
+        const facing = unit_x * nx + unit_y * ny + unit_z * nz;
+
+        return facing < 0 ? -facing : facing;
+    }
+
+    if (rank === 0) {
+        // Nothing incident: a bead, and a bead faces every direction equally.
+        return 1;
+    }
+
+    // A line. What it blocks is the flow *across* it, which is the sine of the
+    // angle between the two — the rope's answer, and the complement of the
+    // sheet's.
+    const along = unit_x * b1x + unit_y * b1y + unit_z * b1z;
+
+    const across = 1 - along * along;
+
+    return across <= 0 ? 0 : Math.sqrt(across);
+}

package/src/engine/physics/cloth/solver/constraint/cloth_backstop_row.d.ts

@@ -36,8 +36,15 @@
  * garment's own skinned surface — `b` a short way inside along the vertex
  * normal, `r_b` that distance again — and a skinned garment is M3. M2's entity
  * path has a chain rather than a surface, so it has no normal to offer: a rope
- * has no inside. So the row ships with storage, a spec and a playground demo
- * driving it directly, and `cloth_proxy_build` is what will fill it.
+ * has no inside. So the row ships with storage and a spec, and
+ * `cloth_proxy_build` is what will fill it.
+ *
+ * **Nothing drives it in a scene.** This docblock used to say "and a playground
+ * demo driving it directly", and no page under `playground/` writes
+ * {@link ClothState#backstop_plane} — M3 arrived and filled nothing in either.
+ * What holds the row up is `cloth_backstop_row.spec.js` alone, which is the
+ * honest status of a row with no author: the arithmetic is gated, the
+ * integration is not.
  *
  * ## No trust region, and no geometric stiffness
  *

package/src/engine/physics/cloth/solver/constraint/cloth_backstop_row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_backstop_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_backstop_row.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;;;;;;;;GAWG;AACH,kDANW,YAAY,GAAC,MAAM,EAAE,mBACrB,MAAM,0BAEN,MAAM,GACJ,MAAM,CAuBlB;AAED;;;;;;GAMG;AACH,uDAJW,YAAY,+BAEZ,MAAM,QA8EhB;AAED;;;;;;;;;;GAUG;AACH,oEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QAuChB;AAED;;;;;;;GAOG;AACH,oEAJW,MAAM,eACN,MAAM,qBACN,MAAM,QA2ChB"}
+{"version":3,"file":"cloth_backstop_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_backstop_row.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH;;;;;;;;;;;GAWG;AACH,kDANW,YAAY,GAAC,MAAM,EAAE,mBACrB,MAAM,0BAEN,MAAM,GACJ,MAAM,CAuBlB;AAED;;;;;;GAMG;AACH,uDAJW,YAAY,+BAEZ,MAAM,QA8EhB;AAED;;;;;;;;;;GAUG;AACH,oEANW,MAAM,SACN,MAAM,eACN,MAAM,eACN,MAAM,qBACN,MAAM,QAuChB;AAED;;;;;;;GAOG;AACH,oEAJW,MAAM,eACN,MAAM,qBACN,MAAM,QA2ChB"}