@woosh/meep-engine 3.24.0 → 3.26.0

package/src/engine/physics/cloth/ecs/ClothWorkerCore.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Worker-side logic for {@link WorkerClothSystem}: holds one {@link ClothState}
+ * view per registered cloth and steps the ones the main thread nominates.
+ *
+ * The states are not copies. Each is a {@link ClothState} whose views are cut
+ * over the very memory the main thread's `ClothInstance` holds, so a step
+ * mutates that cloth in place and there is nothing to send back — the result is
+ * published by the {@link SystemWorkerHost} advancing `DONE`, and the three
+ * scalars a caller needs from a step are in the buffer too
+ * (`ClothState#result`).
+ *
+ * The exclusion set travels with the registration and *is* copied, because it is
+ * the one thing here that the step only reads: built once from the row tables
+ * when the cloth seeds, replaced by a re-seed, and never written by either side.
+ * A shared buffer for it would buy nothing and cost a region.
+ *
+ * Deliberately free of worker globals (`self`, `postMessage`, `Worker`) so it is
+ * ordinary node-testable code; {@link SystemWorkerHost} owns everything that
+ * needs a real worker.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothWorkerCore {
+    /**
+     * @param {*} data
+     */
+    handleMessage(data: any): void;
+    /**
+     * @returns {number} how many cloths are currently registered
+     */
+    get cloth_count(): number;
+    /**
+     * @param {number} id
+     * @returns {ClothState|undefined} the worker's view of that cloth
+     */
+    stateOf(id: number): ClothState | undefined;
+    /**
+     * Step every cloth the main thread nominated for this tick.
+     *
+     * @param {number} tick
+     * @param {Float64Array} command
+     */
+    step(tick: number, command: Float64Array): void;
+    #private;
+}
+import { ClothState } from "../solver/ClothState.js";
+//# sourceMappingURL=ClothWorkerCore.d.ts.map

package/src/engine/physics/cloth/ecs/ClothWorkerCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClothWorkerCore.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorkerCore.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAQI;;OAEG;IACH,+BAiBC;IAED;;OAEG;IACH,0BAEC;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,UAAU,GAAC,SAAS,CAMhC;IAED;;;;;OAKG;IACH,WAHW,MAAM,WACN,YAAY,QA2BtB;;CACJ;2BA1G0B,yBAAyB"}

package/src/engine/physics/cloth/ecs/ClothWorkerCore.js

@@ -0,0 +1,107 @@
+import { ClothState } from "../solver/ClothState.js";
+import { ClothStepParam, cloth_step_instance } from "../solver/cloth_step_instance.js";
+import { ClothCommand, cloth_command_offset } from "./cloth_worker_protocol.js";
+
+/**
+ * Worker-side logic for {@link WorkerClothSystem}: holds one {@link ClothState}
+ * view per registered cloth and steps the ones the main thread nominates.
+ *
+ * The states are not copies. Each is a {@link ClothState} whose views are cut
+ * over the very memory the main thread's `ClothInstance` holds, so a step
+ * mutates that cloth in place and there is nothing to send back — the result is
+ * published by the {@link SystemWorkerHost} advancing `DONE`, and the three
+ * scalars a caller needs from a step are in the buffer too
+ * (`ClothState#result`).
+ *
+ * The exclusion set travels with the registration and *is* copied, because it is
+ * the one thing here that the step only reads: built once from the row tables
+ * when the cloth seeds, replaced by a re-seed, and never written by either side.
+ * A shared buffer for it would buy nothing and cost a region.
+ *
+ * Deliberately free of worker globals (`self`, `postMessage`, `Worker`) so it is
+ * ordinary node-testable code; {@link SystemWorkerHost} owns everything that
+ * needs a real worker.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothWorkerCore {
+
+    /**
+     * Registered cloths by id, populated over the cold plane.
+     * @type {Map<number, {state: ClothState, exclusions: {offset: Int32Array, partner: Int32Array}}>}
+     */
+    #cloths = new Map();
+
+    /**
+     * @param {*} data
+     */
+    handleMessage(data) {
+        if (data.type === "add_cloth") {
+            this.#cloths.set(data.id, {
+                state: ClothState.fromSharedDescriptor(data.state),
+                exclusions: data.self_exclusions
+            });
+
+            return;
+        }
+
+        if (data.type === "remove_cloth") {
+            this.#cloths.delete(data.id);
+
+            return;
+        }
+
+        throw new Error(`ClothWorkerCore: unknown message type '${data.type}'`);
+    }
+
+    /**
+     * @returns {number} how many cloths are currently registered
+     */
+    get cloth_count() {
+        return this.#cloths.size;
+    }
+
+    /**
+     * @param {number} id
+     * @returns {ClothState|undefined} the worker's view of that cloth
+     */
+    stateOf(id) {
+        const entry = this.#cloths.get(id);
+
+        return entry === undefined ? undefined : entry.state;
+    }
+
+    /**
+     * Step every cloth the main thread nominated for this tick.
+     *
+     * @param {number} tick
+     * @param {Float64Array} command
+     */
+    step(tick, command) {
+        const cloth_count = command[ClothCommand.CLOTH_COUNT];
+
+        for (let i = 0; i < cloth_count; i++) {
+            const offset = cloth_command_offset(i);
+
+            const entry = this.#cloths.get(command[offset + ClothStepParam.ID]);
+
+            if (entry === undefined) {
+                // The cloth was removed — or re-seeded, which retires its id —
+                // after this step was dispatched. An ordinary despawn or a
+                // structure change, not a protocol error: `remove_cloth` travels
+                // on the cold plane and can be delivered before the pump runs a
+                // step that was published earlier.
+                //
+                // Skipping is correct, because the main thread drops a cloth
+                // from the nomination list the moment it unlinks and never joins
+                // a result it did not nominate. Throwing here instead would fail
+                // the whole bridge — and with it every other cloth in the scene
+                // — every time a garment is despawned at the wrong moment.
+                continue;
+            }
+
+            cloth_step_instance(entry.state, entry.exclusions, command, offset);
+        }
+    }
+}

package/src/engine/physics/cloth/ecs/ClothWorld.d.ts

@@ -0,0 +1,323 @@
+/**
+ * # Every cloth in a scene, and everything a step needs that is not arithmetic
+ *
+ * One {@link ClothInstance} per {@link Cloth} component, stepped at the fixed
+ * rate. Per step, per cloth: move the local frame with the anchor, point the
+ * leash rows at where they measure from, gather the colliders that could touch
+ * it, step, and put the result back on the subtree. The animated pose the
+ * leashes are measured against is not recomposed per step — in the entity path
+ * it is constant in the anchor's own frame, and `cloth_seed_subtree.js` bakes
+ * it.
+ *
+ * ## Why this is not a `System`
+ *
+ * Because two of them drive it. {@link ClothSystem} steps every cloth inline;
+ * {@link WorkerClothSystem} hands the arithmetic to a worker and joins it on the
+ * next tick. §12 asks those two to produce **bit-identical** results, and the
+ * cheapest way to be sure of that is for there to be one copy of everything
+ * except the dispatch — so the registry, the seeding, the frame handling, the
+ * broadphase and the write-back live here, and the two systems differ only in
+ * where {@link ClothWorld#prepare} and {@link ClothWorld#finish} are separated
+ * by a thread.
+ *
+ * That split is also exactly §12's: "arbitrary user-facing work — component
+ * reads, `Transform64` sync, index queries — stays on the main thread; the pure
+ * numeric step crosses". {@link ensure_seeded} and {@link advance} are the first
+ * half, `cloth_step_instance` is the second, {@link finish} is what the result
+ * is worth.
+ *
+ * Seeding is its own call rather than the top of {@link advance} because the
+ * worker needs to get between them: a cloth's `ClothState` is what it registers
+ * with the worker, so it has to exist — and be acknowledged — before the cloth
+ * can be nominated for a step, and a re-seed replaces it and starts that again.
+ *
+ * ## The parameter block
+ *
+ * {@link prepare} does not call the step and does not return its arguments; it
+ * **writes them into a `Float64` block** the caller supplies. For
+ * {@link ClothSystem} that block is a private scratch array and the step follows
+ * immediately; for {@link WorkerClothSystem} it is a slice of the shared command
+ * region and the step happens on another thread. Neither system ever computes a
+ * step parameter of its own, so neither can compute one differently.
+ *
+ * ## The local frame and the inertia model — §7 P7
+ *
+ * Particles live in the anchor's own frame. When the anchor moves, the cloth is
+ * asked how much of that motion it would like to feel:
+ * `ClothDynamics#inertia = 1` keeps every particle's **world** position and
+ * velocity, so a cape trails a sprinting character; `0` keeps their **local**
+ * ones, so the cloth rides the anchor as though it were standing still. The
+ * blend between the two is a lerp in the local frame, which is all the frame
+ * change is.
+ *
+ * The felt motion is limited before the blend, which is what makes "character
+ * sprints, cape behaves" a default rather than a tuning exercise, and the limits
+ * are derived from the cloth's own reach rather than authored.
+ *
+ * ## The wind — §10
+ *
+ * {@link wind} is a source of air and {@link advance} samples it into the
+ * cloth's own buffer, once per particle per step. That is the one piece of M6
+ * that stays on this thread: a fluid field is an ECS component holding a
+ * hundred thousand floats that its own solver rewrites every step, and the
+ * *answer* is three floats a particle. `cloth_sample_air.js` carries the
+ * decision; the aerodynamic arithmetic built on top of it lives in
+ * `cloth_step_instance` with everything else the budget is spent on.
+ *
+ * A source is optional and additive, like the collider index. With none, the
+ * step's drag response is zero, `cloth_step` takes the uniform-gravity path,
+ * and a scene produces the bytes M5 measured.
+ *
+ * ## Teleport — §7 P6
+ *
+ * Anchor motion past a threshold is not locomotion and is not treated as any
+ * amount of it. `ClothFlags.TeleportKeep` carries the shape across, which in a
+ * local frame is literally doing nothing; the default re-seeds at the animated
+ * pose with zero velocity and opens a stabilisation window in which the
+ * velocity limit ramps back from nothing, so the first steps after a reset
+ * cannot produce a whip.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothWorld {
+    /**
+     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @type {Float64Array}
+     */
+    gravity: Float64Array;
+    /**
+     * Live cloths, in the order they were linked.
+     *
+     * **Not sorted by hierarchy depth**, and it used to be. The sort existed so
+     * that a nested cloth advanced against an anchor the cloth above it had
+     * already written this step — which `WorkerClothSystem` cannot do, because
+     * the step it is writing back happened on another thread a tick ago. Both
+     * systems now advance every cloth, then step every cloth, then finish every
+     * cloth, so a nested cloth reads its parent one fixed step stale on both
+     * sides and the sort has nothing left to decide. `ClothSystem#fixedUpdate`
+     * carries the argument; `MEASUREMENTS.md` §56 carries the measurement.
+     * @type {ClothInstance[]}
+     */
+    instances: ClothInstance[];
+    /**
+     * Where a skinned model instance comes from. Anything that answers
+     * `instance_of(entity)` with a `PrefabInstance` — skins whose joints
+     * are entities — will do, and {@link MeshSystem} is what does in a
+     * running engine.
+     *
+     * Public and assignable because a garment's joints are a *rendering*
+     * structure and `MeshSystem` needs a graphics engine, a scene and a loader
+     * to exist — so a spec that wants joints without a renderer sets this
+     * instead, and gets exactly the interface the system uses.
+     *
+     * `null` means no rig can seed, which is the same additive shape the
+     * collider index has: a scene without one gets M1's cloth rather than an
+     * error.
+     * @type {{instance_of: function(number): (PrefabInstance|null)}|null}
+     */
+    models: {
+        instance_of: (arg0: number) => (PrefabInstance | null);
+    } | null;
+    /**
+     * @type {EntityManager|null}
+     */
+    entityManager: EntityManager | null;
+    /**
+     * @type {TransformAttachmentSystem|null}
+     */
+    attachments: TransformAttachmentSystem | null;
+    /**
+     * The collider index's owner, or `null` when the manager has none — in
+     * which case cloth simply does not collide, which is exactly M1's
+     * behaviour and is what makes the collision layer additive rather than a
+     * new requirement on every scene.
+     * @type {ClothColliderSystem|null}
+     */
+    colliders: ClothColliderSystem | null;
+    /**
+     * Where the air comes from — §10. `null` means no air, which is the
+     * default and is **additive** in exactly the way the collider index is: a
+     * scene without one gets M5's cloth rather than an error, and adding one is
+     * the whole of turning wind on.
+     *
+     * Null rather than a still-air ambient, and the distinction is real. A
+     * source that answers zero everywhere is not "no wind": the drag row is a
+     * relaxation toward the air, so still air still resists a *moving* cloth,
+     * with the normal-facing factor making that resistance anisotropic. That is
+     * better physics than `ClothDynamics#damping`'s isotropic decay and it is
+     * not free — so it is a thing a scene asks for. What a cloth does in air
+     * that is not moving is `damping`'s job (§7 P5, where it is load-bearing);
+     * what it does in air that *is* is this.
+     *
+     * Assign {@link ClothAmbientWind} for weather, {@link ClothFluidWind} to
+     * read the fluid simulation and fall back to weather outside it.
+     * @type {AbstractClothWind|null}
+     */
+    wind: AbstractClothWind | null;
+    /**
+     * Seconds of fixed step this world has **stepped**, which is the clock a
+     * wind source's gust is a function of.
+     *
+     * Accumulated from `dt` rather than read from a wall clock, because
+     * {@link ClothSystem} and {@link WorkerClothSystem} share this object and
+     * §12's parity gate is over every byte of every step: two runs of the same
+     * scene have the same `dt` sequence and therefore the same weather.
+     *
+     * **Stepped rather than ticked**, and that distinction is load-bearing
+     * rather than pedantic. A cloth under the worker is not advanced until its
+     * registration is acknowledged (§39), so the two systems reach a cloth's
+     * *first* step at different tick counts — and a clock that counted ticks
+     * would hand that cloth a different gust on the same step under the two
+     * systems, which is a divergence the parity gate would report and the design
+     * would deserve. So the clock moves when {@link advance} first runs in a
+     * tick: the world's weather is a function of how much cloth time has
+     * passed, not of how long something has been asking.
+     * @type {number}
+     */
+    time: number;
+    /**
+     * Fixed-step seconds this tick owes the clock, consumed by the first
+     * {@link advance} — see {@link time}. Zero once spent.
+     * @type {number}
+     * @private
+     */
+    private __wind_pending;
+    /**
+     * Whether a cloth's {@link ClothState} must be backed by a
+     * `SharedArrayBuffer`. Stamped onto every instance as it is linked;
+     * {@link WorkerClothSystem} sets it, {@link ClothSystem} leaves it alone.
+     * @type {boolean}
+     */
+    shared_state: boolean;
+    /**
+     * @type {Map<number, ClothInstance>}
+     * @private
+     */
+    private __by_entity;
+    /**
+     * Watches `Cloth` + {@link ClothRig} so the rig path is a **live**
+     * discriminator rather than one read once.
+     *
+     * `ClothSystem#dependencies` is `[Cloth, Transform64]` — the tuple that
+     * makes something a cloth — so a `ClothRig` added to a live cloth completes
+     * no tuple the system observes and a `ClothRig` removed from one breaks
+     * none. §3.1's "the discriminator is a component's presence" then holds only
+     * for a character spawned whole, which is the one case a spec constructs and
+     * the least likely one in a scene where a model loads asynchronously.
+     *
+     * Both edges re-seed. The removing edge also gives the joints back first,
+     * because the instance that knows which they were is about to stop being a
+     * rig.
+     * @type {EntityObserver}
+     * @private
+     */
+    private __rig_observer;
+    /**
+     * Resolve the systems a cloth world reads. Called from the owning system's
+     * `startup`.
+     *
+     * @param {EntityManager} entityManager
+     */
+    attach(entityManager: EntityManager): void;
+    /**
+     * @param {Cloth} cloth
+     * @param {Transform64} transform
+     * @param {number} entity
+     * @returns {ClothInstance}
+     */
+    link(cloth: Cloth, transform: Transform64, entity: number): ClothInstance;
+    /**
+     * Watch this dataset for a {@link ClothRig} arriving at or leaving a live
+     * cloth. Called from the owning system's `handleDatasetAttached`; see
+     * {@link ClothWorld#__rig_observer} for why the system's own dependency
+     * tuple cannot answer this.
+     *
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    attach_dataset(dataset: EntityComponentDataset): void;
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    detach_dataset(dataset: EntityComponentDataset): void;
+    /**
+     * @param {number} entity
+     * @returns {ClothInstance|undefined} the instance that was removed
+     */
+    unlink(entity: number): ClothInstance | undefined;
+    /**
+     * Throw away a cloth's binding so the next step walks its subtree again.
+     *
+     * The walk is done once, because a rope's links do not come and go. When
+     * they do — a chain gains a link, a rig is rebuilt — this is how you say so,
+     * and it is the same contract `TransformAttachment#parent` already carries:
+     * the structure is immutable while it is attached, and changing it is an
+     * explicit act rather than something the engine polls for.
+     *
+     * @param {number} entity
+     * @returns {ClothInstance|undefined} the instance that will re-seed
+     */
+    reseed(entity: number): ClothInstance | undefined;
+    /**
+     * Wake a sleeping cloth. Anchor motion and a `ClothDynamics` change do this
+     * on their own; a caller that has changed the world in some way the cloth
+     * cannot see — M6's wind, for one — says so here.
+     *
+     * @param {number} entity
+     * @returns {void}
+     */
+    wake(entity: number): void;
+    /**
+     * @param {number} entity
+     * @returns {ClothInstance|undefined}
+     */
+    instanceOf(entity: number): ClothInstance | undefined;
+    /**
+     * Everything that happens once per tick rather than once per cloth.
+     *
+     * @param {EntityComponentDataset} ecd
+     * @param {number} dt seconds
+     */
+    begin(ecd: EntityComponentDataset, dt: number): void;
+    /**
+     * Make sure this cloth has a `ClothState` that matches its current
+     * `ClothDynamics`, seeding or re-seeding it if not.
+     *
+     * @param {ClothInstance} instance
+     * @param {EntityComponentDataset} ecd
+     * @param {number} dt seconds
+     * @returns {boolean} whether the cloth is ready to be stepped — `false` for
+     *   one that has been refused, or a rig whose model has not loaded yet
+     */
+    ensure_seeded(instance: ClothInstance, ecd: EntityComponentDataset, dt: number): boolean;
+    /**
+     * Take what the step produced: the sleep test, and the pose onto whichever
+     * hierarchy this cloth was built on.
+     *
+     * @param {ClothInstance} instance
+     * @param {EntityComponentDataset} ecd
+     * @returns {void}
+     */
+    finish(instance: ClothInstance, ecd: EntityComponentDataset): void;
+    /**
+     * Carry one seeded cloth to the edge of its step and write the parameters
+     * the step will run on: whatever the anchor did to the local frame, where
+     * the leash rows measure from, and the colliders within reach.
+     *
+     * @param {ClothInstance} instance
+     * @param {number} dt seconds
+     * @param {Float64Array} params
+     * @param {number} offset first word of this cloth's block in `params`
+     * @returns {boolean} whether the cloth should be stepped — `false` for one
+     *   that is asleep, and then nothing has been written to `params`
+     */
+    advance(instance: ClothInstance, dt: number, params: Float64Array, offset: number): boolean;
+    #private;
+}
+import { ClothInstance } from "./ClothInstance.js";
+import { TransformAttachmentSystem } from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
+import { ClothColliderSystem } from "./ClothColliderSystem.js";
+import { Cloth } from "./Cloth.js";
+//# sourceMappingURL=ClothWorld.d.ts.map

package/src/engine/physics/cloth/ecs/ClothWorld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClothWorld.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorld.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH;IAEI;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;;;;;;;;;OAYG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;OAEG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;OAEG;IACH,aAFU,yBAAyB,GAAC,IAAI,CAErB;IAEnB;;;;;;OAMG;IACH,WAFU,mBAAmB,GAAC,IAAI,CAEjB;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,oBAAkB,IAAI,CAEpB;IAEZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,oBAAwB;IAExB;;;;;;;;;;;;;;;;OAgBG;IACH,uBAKE;IAEF;;;;;OAKG;IACH,2CAiBC;IAED;;;;;OAKG;IACH,YALW,KAAK,kCAEL,MAAM,GACJ,aAAa,CAczB;IAED;;;;;;;;OAQG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CA0BnC;IA+CD;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAanC;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;IAED;;;;;OAKG;IACH,uCAFW,MAAM,QAgBhB;IAED;;;;;;;;;OASG;IACH,wBANW,aAAa,mCAEb,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;OAOG;IACH,iBAJW,aAAa,gCAEX,IAAI,CA2BhB;IAwFD;;;;;;;;;;;OAWG;IACH,kBAPW,aAAa,MACb,MAAM,UACN,YAAY,UACZ,MAAM,GACJ,OAAO,CAgPnB;;CA8EJ;8BAl8B6B,oBAAoB;0CAjB3C,gEAAgE;oCAcnC,0BAA0B;sBA4BxC,YAAY"}