@woosh/meep-engine 3.23.0 → 3.25.0

package/src/engine/physics/cloth/wind/AbstractClothWind.d.ts

@@ -0,0 +1,88 @@
+/**
+ * # Where the air comes from — one interface, two answers
+ *
+ * §10's design in one sentence: this engine has something better than a wind
+ * zone, so cloth should **sample** the air rather than invent it. Two things can
+ * answer "how fast is the air at this point": a running fluid simulation
+ * ({@link ClothFluidWind}), and an ambient model for everywhere a simulation is
+ * not ({@link ClothAmbientWind}). §10 asks for both to be read "through *the
+ * same interface*, so the cloth code has one path and does not branch on whether
+ * a simulation is present", and this is that interface.
+ *
+ * It is two questions rather than one, and the second is what makes the feature
+ * affordable:
+ *
+ * - {@link sample} answers the air's **world** velocity at a world point, in
+ *   metres per second.
+ * - {@link varies} answers whether it is worth asking {@link sample} more than
+ *   once for a given box. An ambient source answers `false` for every box and a
+ *   whole garment costs one sample; a fluid source answers `true` only where one
+ *   of its fields actually reaches, which is §10's "a cloth outside every fluid
+ *   field's bounds skips it entirely" expressed as a question the cloth can ask.
+ *
+ * ## Determinism, because two systems share one of these
+ *
+ * `ClothSystem` and `WorkerClothSystem` share a {@link ClothWorld} and therefore
+ * share its wind source, and §12's bit-parity gate is over the whole
+ * `ClothState` buffer at every step. The air is sampled **once**, by the world,
+ * into that buffer — so the two systems do not agree about the wind, they read
+ * the same bytes of it. What this interface has to promise is only that
+ * {@link sample} is a pure function of ({@link begin}'s `time`, the point), with
+ * no wall clock and no random source: a gust that consulted `Date.now()` would
+ * make two runs of the same scene differ and would take the parity spec's
+ * guarantee with it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AbstractClothWind {
+    /**
+     * Called once per fixed step, before any cloth is advanced, so a source that
+     * moves with time or with the scene can refresh itself once rather than once
+     * a cloth.
+     *
+     * `time` is the cloth world's own accumulated fixed-step clock rather than a
+     * wall clock, which is what keeps a gust reproducible — see the note above.
+     *
+     * @param {number} time seconds since the cloth world started stepping
+     * @param {EntityComponentDataset} ecd for a source that reads components
+     * @returns {void}
+     */
+    begin(time: number, ecd: EntityComponentDataset): void;
+    /**
+     * Whether the air could differ from point to point inside this box — and so
+     * whether a caller has to sample per particle instead of once.
+     *
+     * Answering `false` is a promise rather than a hint: the caller will sample
+     * one point and apply the answer to every particle of the cloth.
+     *
+     * @param {number} min_x world-space, metres
+     * @param {number} min_y
+     * @param {number} min_z
+     * @param {number} max_x
+     * @param {number} max_y
+     * @param {number} max_z
+     * @returns {boolean}
+     */
+    varies(min_x: number, min_y: number, min_z: number, max_x: number, max_y: number, max_z: number): boolean;
+    /**
+     * The air's velocity at a world point, **metres per second**.
+     *
+     * The units are worth stating because the field this is most often reading
+     * does not use them: `FluidField#sampleVelocity` answers in *grid cells* per
+     * second and documents that it deliberately does not rescale, on the
+     * assumption that its callers want a direction times a magnitude. Cloth is
+     * not such a caller — its drag row is an acceleration toward a velocity, and
+     * a velocity in cells is a garment that blows differently depending on how
+     * finely someone voxelised the room. {@link ClothFluidWind} multiplies by
+     * `cell_size`. `MEASUREMENTS.md` §45.
+     *
+     * @param {Float64Array|number[]} out length 3
+     * @param {number} x world-space, metres
+     * @param {number} y
+     * @param {number} z
+     * @returns {Float64Array|number[]} `out`, for chaining
+     */
+    sample(out: Float64Array | number[], x: number, y: number, z: number): Float64Array | number[];
+}
+//# sourceMappingURL=AbstractClothWind.d.ts.map

package/src/engine/physics/cloth/wind/AbstractClothWind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractClothWind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/wind/AbstractClothWind.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IAEI;;;;;;;;;;;OAWG;IACH,YAJW,MAAM,gCAEJ,IAAI,CAIhB;IAED;;;;;;;;;;;;;;OAcG;IACH,cARW,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,YANW,YAAY,GAAC,MAAM,EAAE,KACrB,MAAM,KACN,MAAM,KACN,MAAM,GACJ,YAAY,GAAC,MAAM,EAAE,CAQjC;CACJ"}

package/src/engine/physics/cloth/wind/AbstractClothWind.js

@@ -0,0 +1,100 @@
+/**
+ * # Where the air comes from — one interface, two answers
+ *
+ * §10's design in one sentence: this engine has something better than a wind
+ * zone, so cloth should **sample** the air rather than invent it. Two things can
+ * answer "how fast is the air at this point": a running fluid simulation
+ * ({@link ClothFluidWind}), and an ambient model for everywhere a simulation is
+ * not ({@link ClothAmbientWind}). §10 asks for both to be read "through *the
+ * same interface*, so the cloth code has one path and does not branch on whether
+ * a simulation is present", and this is that interface.
+ *
+ * It is two questions rather than one, and the second is what makes the feature
+ * affordable:
+ *
+ * - {@link sample} answers the air's **world** velocity at a world point, in
+ *   metres per second.
+ * - {@link varies} answers whether it is worth asking {@link sample} more than
+ *   once for a given box. An ambient source answers `false` for every box and a
+ *   whole garment costs one sample; a fluid source answers `true` only where one
+ *   of its fields actually reaches, which is §10's "a cloth outside every fluid
+ *   field's bounds skips it entirely" expressed as a question the cloth can ask.
+ *
+ * ## Determinism, because two systems share one of these
+ *
+ * `ClothSystem` and `WorkerClothSystem` share a {@link ClothWorld} and therefore
+ * share its wind source, and §12's bit-parity gate is over the whole
+ * `ClothState` buffer at every step. The air is sampled **once**, by the world,
+ * into that buffer — so the two systems do not agree about the wind, they read
+ * the same bytes of it. What this interface has to promise is only that
+ * {@link sample} is a pure function of ({@link begin}'s `time`, the point), with
+ * no wall clock and no random source: a gust that consulted `Date.now()` would
+ * make two runs of the same scene differ and would take the parity spec's
+ * guarantee with it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AbstractClothWind {
+
+    /**
+     * Called once per fixed step, before any cloth is advanced, so a source that
+     * moves with time or with the scene can refresh itself once rather than once
+     * a cloth.
+     *
+     * `time` is the cloth world's own accumulated fixed-step clock rather than a
+     * wall clock, which is what keeps a gust reproducible — see the note above.
+     *
+     * @param {number} time seconds since the cloth world started stepping
+     * @param {EntityComponentDataset} ecd for a source that reads components
+     * @returns {void}
+     */
+    begin(time, ecd) {
+        // A constant atmosphere has nothing to refresh.
+    }
+
+    /**
+     * Whether the air could differ from point to point inside this box — and so
+     * whether a caller has to sample per particle instead of once.
+     *
+     * Answering `false` is a promise rather than a hint: the caller will sample
+     * one point and apply the answer to every particle of the cloth.
+     *
+     * @param {number} min_x world-space, metres
+     * @param {number} min_y
+     * @param {number} min_z
+     * @param {number} max_x
+     * @param {number} max_y
+     * @param {number} max_z
+     * @returns {boolean}
+     */
+    varies(min_x, min_y, min_z, max_x, max_y, max_z) {
+        return false;
+    }
+
+    /**
+     * The air's velocity at a world point, **metres per second**.
+     *
+     * The units are worth stating because the field this is most often reading
+     * does not use them: `FluidField#sampleVelocity` answers in *grid cells* per
+     * second and documents that it deliberately does not rescale, on the
+     * assumption that its callers want a direction times a magnitude. Cloth is
+     * not such a caller — its drag row is an acceleration toward a velocity, and
+     * a velocity in cells is a garment that blows differently depending on how
+     * finely someone voxelised the room. {@link ClothFluidWind} multiplies by
+     * `cell_size`. `MEASUREMENTS.md` §45.
+     *
+     * @param {Float64Array|number[]} out length 3
+     * @param {number} x world-space, metres
+     * @param {number} y
+     * @param {number} z
+     * @returns {Float64Array|number[]} `out`, for chaining
+     */
+    sample(out, x, y, z) {
+        out[0] = 0;
+        out[1] = 0;
+        out[2] = 0;
+
+        return out;
+    }
+}

package/src/engine/physics/cloth/wind/ClothAmbientWind.d.ts

@@ -0,0 +1,85 @@
+/**
+ * # The air everywhere a fluid simulation is not
+ *
+ * §10's fallback: "a `GlobalFluidEffector`-shaped ambient term — a constant
+ * `wind` vector plus a small band-limited noise for gusting". The shape is
+ * deliberate. `GlobalFluidEffector` with a `wind` and a `drag` makes every fluid
+ * field relax *toward* `wind`, so a field with one in the scene already reads
+ * `wind` away from whatever is disturbing it — which means this is not an
+ * approximation of the simulation, it is **the same far field the simulation
+ * has**, evaluated where no simulation exists. A cloth walking out of a fluid
+ * volume walks into the volume's own ambient rather than into still air.
+ *
+ * ## The gust is three sinusoids, not a noise function
+ *
+ * "Band-limited" is exactly what a sum of sinusoids is, and the three properties
+ * that matters for here are all free: it is bounded (so `gust` is a real
+ * amplitude rather than a scale factor over an unbounded tail), it is smooth
+ * (so a settled banner is lifted rather than kicked), and it carries **no
+ * state** — `g(t)` is a pure function of the cloth world's own fixed-step clock,
+ * which is what lets two systems sharing this source produce bit-identical
+ * cloth. A value-noise lattice would need a seed and an interpolation rule to
+ * buy the same three.
+ *
+ * The three components sit at 1, 2.41 and 5.83 times the base frequency, which
+ * are mutually irrational enough that the pattern does not visibly repeat, and
+ * the three axes are offset in phase so the gust turns as well as pulses. It is
+ * the cheapest thing that reads as weather; it is not turbulence, and a scene
+ * that wants turbulence has a fluid simulator.
+ *
+ * ## Uniform in space, and that is the interesting limit
+ *
+ * {@link varies} is always `false`, so a whole garment costs **one** sample —
+ * which is what makes the no-simulation case essentially free on the main thread
+ * regardless of particle count (`MEASUREMENTS.md` §47). The cost is that the
+ * whole cloth is lifted together and a long banner does not see a gust arrive at
+ * one end before the other. Spatial structure is the thing a fluid field has and
+ * this does not, and §10's argument is that building a second, worse one here
+ * would be the duplication the design exists to avoid.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothAmbientWind extends AbstractClothWind {
+    /**
+     * Prevailing wind, world-space metres per second. The same quantity and the
+     * same units as `GlobalFluidEffector#wind`.
+     * @type {Float64Array}
+     */
+    wind: Float64Array;
+    /**
+     * Peak gust speed on top of {@link wind}, metres per second. The gust is
+     * bounded by exactly this — the component amplitudes below sum to one — so
+     * the air's speed never leaves `|wind| ± gust`.
+     * @type {number}
+     */
+    gust: number;
+    /**
+     * Period of the gust's slowest component, seconds. Four is a breeze that
+     * arrives and leaves a few times a minute; a fraction of a second is a
+     * flutter.
+     * @type {number}
+     */
+    period: number;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __time;
+    /**
+     * @param {number} time
+     * @param {EntityComponentDataset} [ecd]
+     * @returns {void}
+     */
+    begin(time: number, ecd?: EntityComponentDataset): void;
+    /**
+     * Always `false`: the ambient is one vector for the whole world at any
+     * instant, so one sample describes a garment exactly rather than
+     * approximately.
+     *
+     * @returns {boolean}
+     */
+    varies(): boolean;
+}
+import { AbstractClothWind } from "./AbstractClothWind.js";
+//# sourceMappingURL=ClothAmbientWind.d.ts.map

package/src/engine/physics/cloth/wind/ClothAmbientWind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClothAmbientWind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/wind/ClothAmbientWind.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAEI;;;;OAIG;IACH,MAFU,YAAY,CAEK;IAE3B;;;;;OAKG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,eAAW;IAEX;;;;OAIG;IACH,YAJW,MAAM,iCAEJ,IAAI,CAIhB;IAED;;;;;;OAMG;IACH,UAFa,OAAO,CAInB;CAsCJ;kCAnIiC,wBAAwB"}

package/src/engine/physics/cloth/wind/ClothAmbientWind.js

@@ -0,0 +1,182 @@
+import { AbstractClothWind } from "./AbstractClothWind.js";
+
+/**
+ * # The air everywhere a fluid simulation is not
+ *
+ * §10's fallback: "a `GlobalFluidEffector`-shaped ambient term — a constant
+ * `wind` vector plus a small band-limited noise for gusting". The shape is
+ * deliberate. `GlobalFluidEffector` with a `wind` and a `drag` makes every fluid
+ * field relax *toward* `wind`, so a field with one in the scene already reads
+ * `wind` away from whatever is disturbing it — which means this is not an
+ * approximation of the simulation, it is **the same far field the simulation
+ * has**, evaluated where no simulation exists. A cloth walking out of a fluid
+ * volume walks into the volume's own ambient rather than into still air.
+ *
+ * ## The gust is three sinusoids, not a noise function
+ *
+ * "Band-limited" is exactly what a sum of sinusoids is, and the three properties
+ * that matters for here are all free: it is bounded (so `gust` is a real
+ * amplitude rather than a scale factor over an unbounded tail), it is smooth
+ * (so a settled banner is lifted rather than kicked), and it carries **no
+ * state** — `g(t)` is a pure function of the cloth world's own fixed-step clock,
+ * which is what lets two systems sharing this source produce bit-identical
+ * cloth. A value-noise lattice would need a seed and an interpolation rule to
+ * buy the same three.
+ *
+ * The three components sit at 1, 2.41 and 5.83 times the base frequency, which
+ * are mutually irrational enough that the pattern does not visibly repeat, and
+ * the three axes are offset in phase so the gust turns as well as pulses. It is
+ * the cheapest thing that reads as weather; it is not turbulence, and a scene
+ * that wants turbulence has a fluid simulator.
+ *
+ * ## Uniform in space, and that is the interesting limit
+ *
+ * {@link varies} is always `false`, so a whole garment costs **one** sample —
+ * which is what makes the no-simulation case essentially free on the main thread
+ * regardless of particle count (`MEASUREMENTS.md` §47). The cost is that the
+ * whole cloth is lifted together and a long banner does not see a gust arrive at
+ * one end before the other. Spatial structure is the thing a fluid field has and
+ * this does not, and §10's argument is that building a second, worse one here
+ * would be the duplication the design exists to avoid.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothAmbientWind extends AbstractClothWind {
+
+    /**
+     * Prevailing wind, world-space metres per second. The same quantity and the
+     * same units as `GlobalFluidEffector#wind`.
+     * @type {Float64Array}
+     */
+    wind = new Float64Array(3);
+
+    /**
+     * Peak gust speed on top of {@link wind}, metres per second. The gust is
+     * bounded by exactly this — the component amplitudes below sum to one — so
+     * the air's speed never leaves `|wind| ± gust`.
+     * @type {number}
+     */
+    gust = 0;
+
+    /**
+     * Period of the gust's slowest component, seconds. Four is a breeze that
+     * arrives and leaves a few times a minute; a fraction of a second is a
+     * flutter.
+     * @type {number}
+     */
+    period = 4;
+
+    /**
+     * @type {number}
+     * @private
+     */
+    __time = 0;
+
+    /**
+     * @param {number} time
+     * @param {EntityComponentDataset} [ecd]
+     * @returns {void}
+     */
+    begin(time, ecd) {
+        this.__time = time;
+    }
+
+    /**
+     * Always `false`: the ambient is one vector for the whole world at any
+     * instant, so one sample describes a garment exactly rather than
+     * approximately.
+     *
+     * @returns {boolean}
+     */
+    varies() {
+        return false;
+    }
+
+    /**
+     * @param {Float64Array|number[]} out
+     * @param {number} x unused — the ambient has no spatial structure
+     * @param {number} y
+     * @param {number} z
+     * @returns {Float64Array|number[]}
+     */
+    sample(out, x, y, z) {
+        const wind = this.wind;
+
+        out[0] = wind[0];
+        out[1] = wind[1];
+        out[2] = wind[2];
+
+        const gust = this.gust;
+
+        if (gust === 0) {
+            return out;
+        }
+
+        const period = this.period > 0 ? this.period : 1;
+
+        const w = 2 * Math.PI * this.__time / period;
+
+        for (let axis = 0; axis < 3; axis++) {
+            const phase = PHASE[axis];
+
+            out[axis] += gust * (
+                AMPLITUDE_0 * Math.sin(w * RATE_0 + phase)
+                + AMPLITUDE_1 * Math.sin(w * RATE_1 + phase * 2)
+                + AMPLITUDE_2 * Math.sin(w * RATE_2 + phase * 3)
+            );
+        }
+
+        return out;
+    }
+}
+
+/**
+ * Component rates, as multiples of the base frequency. Mutually irrational
+ * enough that the sum's own period is far longer than anyone watches.
+ * @type {number}
+ * @private
+ */
+const RATE_0 = 1;
+
+/**
+ * @type {number}
+ * @private
+ */
+const RATE_1 = 2.41;
+
+/**
+ * @type {number}
+ * @private
+ */
+const RATE_2 = 5.83;
+
+/**
+ * Component amplitudes. They sum to exactly one, which is what makes
+ * {@link ClothAmbientWind#gust} a bound rather than a scale — a pink-ish
+ * `1 : 1/2 : 1/4` normalised by its own total.
+ * @type {number}
+ * @private
+ */
+const AMPLITUDE_0 = 4 / 7;
+
+/**
+ * @type {number}
+ * @private
+ */
+const AMPLITUDE_1 = 2 / 7;
+
+/**
+ * @type {number}
+ * @private
+ */
+const AMPLITUDE_2 = 1 / 7;
+
+/**
+ * Per-axis phase offsets, so the three axes are not a single pulse along the
+ * diagonal. Thirds of a turn, scaled per component so the axes stay apart at
+ * every rate rather than only at the slowest.
+ * @type {number[]}
+ * @private
+ */
+const PHASE = [0, 2 * Math.PI / 3, 4 * Math.PI / 3];

package/src/engine/physics/cloth/wind/ClothFluidWind.d.ts

@@ -0,0 +1,79 @@
+/**
+ * # The air, read out of the fluid simulation that is already running
+ *
+ * §10's whole argument: this engine has a fluid simulator, `FluidObstacle`
+ * already voxelises physics colliders into it, so a character running past a
+ * cape gets a **wake** without anything cloth-specific being authored. This is
+ * the source that reads it — every enabled {@link FluidComponent} in the scene,
+ * sampled trilinearly where a particle actually is.
+ *
+ * Where no field reaches, {@link ambient} answers instead, so this is the one
+ * source a scene needs rather than a thing to switch between: a banner inside a
+ * wind tunnel volume reads the tunnel, the same banner carried outside reads the
+ * prevailing weather, and the cloth never learns which happened.
+ *
+ * ## Two units problems, and they are the reason this class exists at all
+ *
+ * A caller cannot simply forward `FluidComponent#sampleVelocityAtWorld`:
+ *
+ * - **Cells, not metres.** `FluidField#sampleVelocity` answers in *grid cells*
+ *   per second and says so — it "does NOT rescale them, on the assumption that
+ *   callers (vegetation sway, dust drift) interpret the field as a direction ×
+ *   magnitude wind". Cloth's drag row is a relaxation toward a **velocity**, so
+ *   the same wind voxelised at 0.25 m instead of 1 m would blow a garment four
+ *   times as hard. The multiply by `cell_size` is here. `MEASUREMENTS.md` §45.
+ * - **Unbuilt fields read as null.** A `FluidComponent` exists from the moment
+ *   the entity is spawned and its field's buffers arrive at `build()`. Sampling
+ *   before that is a null dereference rather than a zero, so an unbuilt field is
+ *   skipped exactly like a disabled one.
+ *
+ * ## The field list is rebuilt once a step, not once a cloth
+ *
+ * {@link begin} walks the dataset and caches each live field with its world
+ * box. Every cloth's {@link varies} and every particle's {@link sample} then
+ * read that cache, so a scene with twenty garments and one wind volume walks the
+ * dataset once. `FluidSystem` does the equivalent per field for its effectors
+ * and notes the same trade.
+ *
+ * ## What it does not do
+ *
+ * **It does not blend at a field's edge.** A point inside a field's box reads
+ * the field and a point outside reads the ambient, so a garment straddling the
+ * boundary sees a step in the air rather than a ramp. In a scene where the
+ * ambient is the far field the volume relaxes toward — `GlobalFluidEffector`'s
+ * `wind` — the step is small and mostly the disturbance the volume exists to
+ * carry; where it is not, it is visible, and the answer is a volume large enough
+ * to hold what moves through it. **Overlapping fields are resolved by order**,
+ * first match wins, which is the same arbitrary-but-deterministic rule
+ * `FluidSystem` applies when it steps them independently.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothFluidWind extends AbstractClothWind {
+    /**
+     * What the air is where no field reaches. Present rather than optional
+     * because "outside every fluid volume" is most of the world.
+     * @type {ClothAmbientWind}
+     */
+    ambient: ClothAmbientWind;
+    /**
+     * Live fields this step: the component and its world box, six words each.
+     * @type {FluidComponent[]}
+     * @private
+     */
+    private __components;
+    /**
+     * @type {number[]}
+     * @private
+     */
+    private __bounds;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __count;
+}
+import { AbstractClothWind } from "./AbstractClothWind.js";
+import { ClothAmbientWind } from "./ClothAmbientWind.js";
+//# sourceMappingURL=ClothFluidWind.d.ts.map

package/src/engine/physics/cloth/wind/ClothFluidWind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClothFluidWind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/wind/ClothFluidWind.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH;IAEI;;;;OAIG;IACH,SAFU,gBAAgB,CAEO;IAEjC;;;;OAIG;IACH,qBAAkB;IAElB;;;OAGG;IACH,iBAAc;IAEd;;;OAGG;IACH,gBAAY;CA+Hf;kCAhNiC,wBAAwB;iCACzB,uBAAuB"}