@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -0,0 +1,578 @@
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { WorkerSystem } from "../../../ecs/async/WorkerSystem.js";
+import {
+    TransformAttachment
+} from "../../../ecs/transform-attachment/TransformAttachment.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { ClothStepParam } from "../solver/cloth_step_instance.js";
+import { Cloth } from "./Cloth.js";
+import { ClothCollider } from "./ClothCollider.js";
+import { ClothExclude } from "./ClothExclude.js";
+import { ClothRig } from "./ClothRig.js";
+import { ClothWorld } from "./ClothWorld.js";
+import {
+    ClothCommand,
+    cloth_command_offset,
+    cloth_command_word_count
+} from "./cloth_worker_protocol.js";
+
+/**
+ * Default ceiling on simultaneously stepped cloths. Sizes the command region,
+ * which is allocated once at startup and cannot grow.
+ * @type {number}
+ */
+const DEFAULT_MAX_CLOTH_COUNT = 64;
+
+/**
+ * Drop-in alternative to {@link ClothSystem} that runs the solve on a worker
+ * thread.
+ *
+ * ## What moves, and what does not
+ *
+ * A cloth's fixed step is "work that needs the world" followed by "arithmetic
+ * over typed arrays", and `MEASUREMENTS.md` §7 puts 69% of the frame in the
+ * stretch rows alone — so the split is where §12 drew it:
+ *
+ *   - **main thread**: seeding, the anchor's pose, the local-frame carry, the
+ *     leash centres, the collider broadphase, the sleep test and the write-back.
+ *     All of it reads components, walks hierarchies or queries an index, and
+ *     none of it is where the time goes.
+ *   - **worker**: `cloth_step_instance(state, exclusions, params, offset)` — the
+ *     damping, the contact search, the self-collision pair search, the solve and
+ *     the velocity clamp.
+ *
+ * Both sides call {@link ClothWorld}, and both hand `cloth_step_instance` the
+ * *same* `Float64` parameter block — {@link ClothSystem} in a private scratch
+ * array, this one in a slice of the shared command region. Identical code over
+ * identical data in an identical order, so results are bit-for-bit equal to
+ * {@link ClothSystem}'s (`WorkerClothSystem.spec.js` holds that as a standing
+ * gate).
+ *
+ * Nothing is copied. A cloth's `ClothState` lives in a {@link SharedArrayBuffer}
+ * and the worker steps it in place; a completed step is published by advancing a
+ * single atomic.
+ *
+ * ## Using it
+ *
+ * ```js
+ * entityManager.addSystem(new WorkerClothSystem({ worker_factory: makeClothWorker }));
+ * ```
+ *
+ * There is no per-component opt-in, unlike {@link WorkerFluidSystem}'s
+ * `field.shared_memory`: a cloth's state does not exist until the cloth seeds,
+ * and seeding is this system's own work, so it simply builds them shared.
+ *
+ * Requires a cross-origin isolated page (`Cross-Origin-Opener-Policy:
+ * same-origin` + `Cross-Origin-Embedder-Policy: require-corp`) — without it
+ * `SharedArrayBuffer` does not exist and startup throws.
+ *
+ * ## Ownership — the one behavioural difference
+ *
+ * {@link ClothSystem} leaves every cloth consistent at all times. Here a cloth's
+ * `ClothState` is **owned by the worker** from the moment this system's
+ * `fixedUpdate` dispatches until the next tick joins the result. Concretely:
+ *
+ *   - The `Transform64`/`Node3D` poses this system writes are *not* affected:
+ *     the write-back happens at join, on this thread, inside the fixed pass. A
+ *     renderer reading a cloth's transforms reads them exactly as it always did.
+ *   - What must not be read outside the fixed pass is `ClothInstance#state` —
+ *     particle positions, velocities, the contact slots. Nothing in the engine
+ *     does; the playgrounds' diagnostics run inside the fixed pass.
+ *   - {@link ClothColliderSystem} is refreshed from inside this system's own
+ *     `collect`, as it is under {@link ClothSystem}, so the index is never read
+ *     while a step is in flight.
+ *
+ * Two further differences from {@link ClothSystem}:
+ *
+ *   - Results lag by one tick: the pose written at tick `T` is step `T - 1`'s.
+ *     The *sequence* of states is unchanged — it is observed one tick later.
+ *   - A newly seeded cloth is not stepped until the worker acknowledges its
+ *     registration (a cold-plane round trip, so at least one tick and in
+ *     practice a few). Until then it is not advanced either — not stepped, not
+ *     carried across anchor motion, not written back — which is what keeps the
+ *     step *sequence* identical to {@link ClothSystem}'s rather than merely
+ *     similar. A garment therefore holds its bind pose for a few ticks after it
+ *     spawns, and a re-seed does the same, because a re-seed builds a new buffer
+ *     and the worker has to be told about it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WorkerClothSystem extends WorkerSystem {
+
+    dependencies = [Cloth, Transform64];
+
+    components_used = [
+        ResourceAccessSpecification.from(Cloth, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(ClothExclude, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(ClothCollider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(ClothRig, ResourceAccessKind.Read)
+    ];
+
+    /**
+     * The cloths, and everything about stepping one that is not arithmetic.
+     * Shared with {@link ClothSystem}, which is what makes the two systems one
+     * implementation.
+     * @type {ClothWorld}
+     */
+    world = new ClothWorld();
+
+    /**
+     * @type {(() => Worker)|null}
+     */
+    #worker_factory = null;
+
+    /**
+     * @type {number}
+     */
+    #max_cloth_count = DEFAULT_MAX_CLOTH_COUNT;
+
+    /**
+     * The cold-plane message that announced each registered cloth, the state it
+     * announced, and whether the worker has acknowledged it.
+     *
+     * Keyed by instance, and carrying the `ClothState` rather than trusting the
+     * instance still to hold it: a re-seed replaces the state with a new buffer,
+     * and the registration the worker holds then names memory nobody writes to
+     * any more. Comparing identity is how that is noticed without a dirty flag.
+     * @type {Map<ClothInstance, {id: number, sequence: number, state: ClothState, acknowledged: boolean}>}
+     */
+    #registrations = new Map();
+
+    /**
+     * Cloths announced but not yet acknowledged.
+     * @type {ClothInstance[]}
+     */
+    #pending = [];
+
+    /**
+     * Cloths dispatched at the tick now in flight, in nomination order — the
+     * ones {@link apply} will finish.
+     * @type {ClothInstance[]}
+     */
+    #dispatched = [];
+
+    /**
+     * @type {number}
+     */
+    #next_cloth_id = 1;
+
+    /**
+     * Latches the max_cloth_count overflow report so a persistent
+     * misconfiguration warns once instead of once per tick.
+     * @type {boolean}
+     */
+    #cloth_overflow_reported = false;
+
+    /**
+     * @param {object} options
+     * @param {() => Worker} options.worker_factory spawns the worker. Supplied
+     *        rather than hard-coded because the spawn expression needs
+     *        `import.meta.url`, which cannot be parsed by the CommonJS transform
+     *        the test runner uses — see `makeClothWorker.js`.
+     * @param {number} [options.max_cloth_count] ceiling on simultaneously
+     *        stepped cloths; sizes the fixed command region.
+     */
+    constructor({ worker_factory, max_cloth_count = DEFAULT_MAX_CLOTH_COUNT } = {}) {
+        super();
+
+        this.#worker_factory = worker_factory;
+        this.#max_cloth_count = max_cloth_count;
+
+        this.world.shared_state = true;
+
+        this.command_word_count = cloth_command_word_count(max_cloth_count);
+    }
+
+    /**
+     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @returns {Float64Array}
+     */
+    get gravity() {
+        return this.world.gravity;
+    }
+
+    /**
+     * @param {Float64Array} value
+     */
+    set gravity(value) {
+        this.world.gravity = value;
+    }
+
+    /**
+     * Where the air comes from — see {@link ClothWorld#wind}. Sampled on **this**
+     * thread even under the worker, because a fluid field cannot cross and its
+     * answer can: `cloth_sample_air.js` is the argument, and it lands in a region
+     * of the cloth's own shared buffer.
+     * @returns {AbstractClothWind|null}
+     */
+    get wind() {
+        return this.world.wind;
+    }
+
+    /**
+     * @param {AbstractClothWind|null} value
+     */
+    set wind(value) {
+        this.world.wind = value;
+    }
+
+    /**
+     * @returns {ClothInstance[]}
+     */
+    get instances() {
+        return this.world.instances;
+    }
+
+    /**
+     * @returns {{instance_of: function(number): (PrefabInstance|null)}|null}
+     */
+    get models() {
+        return this.world.models;
+    }
+
+    /**
+     * @param {{instance_of: function(number): (PrefabInstance|null)}|null} value
+     */
+    set models(value) {
+        this.world.models = value;
+    }
+
+    /**
+     * @returns {Worker}
+     */
+    createWorker() {
+        if (typeof this.#worker_factory !== "function") {
+            throw new Error(
+                "WorkerClothSystem requires a worker factory:"
+                + " new WorkerClothSystem({ worker_factory: makeClothWorker })"
+            );
+        }
+
+        return this.#worker_factory();
+    }
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async startup(entityManager) {
+        this.world.attach(entityManager);
+
+        await super.startup(entityManager);
+    }
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    handleDatasetAttached(dataset) {
+        this.world.attach_dataset(dataset);
+    }
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    handleDatasetDetached(dataset) {
+        this.world.detach_dataset(dataset);
+    }
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async shutdown(entityManager) {
+        await super.shutdown(entityManager);
+
+        this.#registrations.clear();
+        this.#pending.length = 0;
+        this.#dispatched.length = 0;
+    }
+
+    /**
+     * @param {Cloth} cloth
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(cloth, transform, entity) {
+        this.world.link(cloth, transform, entity);
+    }
+
+    /**
+     * @param {Cloth} cloth
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(cloth, transform, entity) {
+        const instance = this.world.unlink(entity);
+
+        if (instance !== undefined) {
+            this.#retire(instance);
+        }
+    }
+
+    /**
+     * Throw away a cloth's binding so the next step walks its subtree again.
+     * @param {number} entity
+     * @returns {void}
+     */
+    reseed(entity) {
+        this.world.reseed(entity);
+    }
+
+    /**
+     * Wake a sleeping cloth.
+     * @param {number} entity
+     * @returns {void}
+     */
+    wake(entity) {
+        this.world.wake(entity);
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {ClothInstance|undefined}
+     */
+    instanceOf(entity) {
+        return this.world.instanceOf(entity);
+    }
+
+    /**
+     * @returns {boolean} whether cloth *particle state* may currently be read
+     *          from the main thread. False while a step is in flight. The poses
+     *          on the scene are always readable — they are written at join.
+     */
+    get is_state_readable() {
+        return !this.is_step_in_flight;
+    }
+
+    /**
+     * @param {Float64Array} command
+     * @param {number} tick
+     * @param {number} time_delta_seconds
+     * @returns {boolean}
+     */
+    collect(command, tick, time_delta_seconds) {
+        const em = this.entityManager;
+
+        if (em === null) {
+            return false;
+        }
+
+        const ecd = em.dataset;
+
+        if (ecd === null || ecd === undefined) {
+            return false;
+        }
+
+        this.#promote_acknowledged_cloths();
+
+        const world = this.world;
+
+        world.begin(ecd, time_delta_seconds);
+
+        const instances = world.instances;
+
+        const max_cloth_count = this.#max_cloth_count;
+
+        const dispatched = this.#dispatched;
+
+        dispatched.length = 0;
+
+        let cloth_count = 0;
+
+        for (let i = 0; i < instances.length; i++) {
+            const instance = instances[i];
+
+            if (!world.ensure_seeded(instance, ecd, time_delta_seconds)) {
+                continue;
+            }
+
+            const registration = this.#registrations.get(instance);
+
+            if (registration === undefined || registration.state !== instance.state) {
+                // Either the cloth has just seeded, or a re-seed built it a new
+                // buffer. Announce the current one and wait — nominating memory
+                // the worker has not attached to is a protocol error, and
+                // advancing the cloth without stepping it would put its step
+                // sequence out of step with ClothSystem's for the rest of the
+                // run.
+                this.#register(instance);
+
+                continue;
+            }
+
+            if (!registration.acknowledged) {
+                continue;
+            }
+
+            if (cloth_count === max_cloth_count) {
+                if (!this.#cloth_overflow_reported) {
+                    this.#cloth_overflow_reported = true;
+
+                    console.error(
+                        `WorkerClothSystem: more live cloths than max_cloth_count (${max_cloth_count});`
+                        + ` the remainder will not be simulated. Raise max_cloth_count in the constructor.`
+                    );
+                }
+
+                break;
+            }
+
+            const offset = cloth_command_offset(cloth_count);
+
+            if (!world.advance(instance, time_delta_seconds, command, offset)) {
+                // Asleep. §7 P5: not stepped, not written back, and costing
+                // nothing but its absence from this list.
+                continue;
+            }
+
+            command[offset + ClothStepParam.ID] = registration.id;
+
+            dispatched.push(instance);
+
+            cloth_count++;
+        }
+
+        if (cloth_count === 0) {
+            // Nothing to do. Skipping the dispatch also keeps the fixed-step
+            // gate open, since there is no result to wait for.
+            return false;
+        }
+
+        command[ClothCommand.CLOTH_COUNT] = cloth_count;
+
+        return true;
+    }
+
+    /**
+     * The worker stepped each nominated cloth in place, so joining is the sleep
+     * test and the write-back — the half of `ClothSystem`'s loop that needs the
+     * scene rather than the arithmetic.
+     *
+     * @param {number} tick
+     */
+    apply(tick) {
+        const ecd = this.entityManager.dataset;
+
+        if (ecd === null || ecd === undefined) {
+            return;
+        }
+
+        const dispatched = this.#dispatched;
+
+        const world = this.world;
+
+        for (let i = 0; i < dispatched.length; i++) {
+            const instance = dispatched[i];
+
+            if (!this.#registrations.has(instance)) {
+                // Unlinked between dispatch and join. Its entity is gone, so
+                // there is nothing to write the pose onto.
+                continue;
+            }
+
+            world.finish(instance, ecd);
+        }
+
+        dispatched.length = 0;
+    }
+
+    /**
+     * Announce a cloth's current `ClothState` to the worker, retiring whatever
+     * it was registered with before.
+     *
+     * @param {ClothInstance} instance
+     * @private
+     */
+    #register(instance) {
+        const state = instance.state;
+
+        if (!state.isSharedMemory()) {
+            // Not an assert: asserts are stripped from a production build, and a
+            // non-shared buffer does not fail loudly on its own — `postMessage`
+            // structured-clones it, both threads get a private copy of a cloth,
+            // and each simulates a garment the other cannot see. A cloth built
+            // through this system is always shared (`ClothWorld#shared_state`),
+            // so reaching here means someone handed it a world that is not.
+            throw new Error(
+                `WorkerClothSystem: the ClothState of entity ${instance.entity} is not shared-memory backed,`
+                + ` so the worker would step a copy of it. Build the world with shared_state set, or use`
+                + ` ClothSystem, which is the same solver on this thread.`
+            );
+        }
+
+        this.#retire(instance);
+
+        const id = this.#next_cloth_id++;
+
+        const sequence = this.postToWorker({
+            type: "add_cloth",
+            id,
+            state: state.getSharedDescriptor(),
+            self_exclusions: instance.self_exclusions
+        });
+
+        this.#registrations.set(instance, { id, sequence, state, acknowledged: false });
+        this.#pending.push(instance);
+    }
+
+    /**
+     * Drop a cloth's registration, telling the worker to forget it.
+     *
+     * @param {ClothInstance} instance
+     * @private
+     */
+    #retire(instance) {
+        const registration = this.#registrations.get(instance);
+
+        if (registration === undefined) {
+            return;
+        }
+
+        this.#registrations.delete(instance);
+
+        const pending_index = this.#pending.indexOf(instance);
+
+        if (pending_index !== -1) {
+            this.#pending.splice(pending_index, 1);
+        }
+
+        // Safe even mid-step: the worker may still be stepping this cloth, and
+        // will simply finish. It is dropped from the next dispatch regardless of
+        // when the message lands, and the shared buffer outlives both sides'
+        // references.
+        this.postToWorker({ type: "remove_cloth", id: registration.id });
+    }
+
+    /**
+     * Move cloths whose registration message the worker has consumed into the
+     * dispatchable set. Until then the worker has no view of their memory and
+     * nominating them would be a protocol error.
+     *
+     * @private
+     */
+    #promote_acknowledged_cloths() {
+        let write = 0;
+
+        for (let i = 0; i < this.#pending.length; i++) {
+            const instance = this.#pending[i];
+
+            const registration = this.#registrations.get(instance);
+
+            if (registration !== undefined && this.isMessageHandled(registration.sequence)) {
+                registration.acknowledged = true;
+
+                continue;
+            }
+
+            this.#pending[write++] = instance;
+        }
+
+        this.#pending.length = write;
+    }
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cloth.worker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth.worker.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth.worker.js"],"names":[],"mappings":""}

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

@@ -0,0 +1,12 @@
+import { SystemWorkerHost } from "../../../ecs/async/SystemWorkerHost.js";
+import { ClothWorkerCore } from "./ClothWorkerCore.js";
+
+/**
+ * Worker entry point for {@link WorkerClothSystem}.
+ *
+ * A real module worker rather than a generated blob, so the solver it pulls in
+ * is the ordinary `cloth_step_instance` — same source, same bundler treatment,
+ * same source maps — which is what makes bit-parity with the main-thread
+ * {@link ClothSystem} a property of the build rather than a coincidence.
+ */
+SystemWorkerHost.serve(new ClothWorkerCore());

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_build_rows.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_build_rows.js"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH,+DAFa,IAAI,CAyBhB;AAID;;;;;;;GAOG;AACH,8DAHW,MAAM,GACJ,IAAI,CA4LhB;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,kEAHW,MAAM,GACJ,IAAI,CAoChB;AAED;;;;;;;;;;;GAWG;AACH,iGAFa,OAAO,CAkBnB;AAhXD;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,kCAFU,MAAM,CAEwB;AAIxC;;;;;;;;;;;;;;;;GAgBG;AACH,gCAFU,MAAM,CAEmB"}
+{"version":3,"file":"cloth_build_rows.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_build_rows.js"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH,+DAFa,IAAI,CAyBhB;AAID;;;;;;;GAOG;AACH,8DAHW,MAAM,GACJ,IAAI,CA6LhB;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,kEAHW,MAAM,GACJ,IAAI,CAoChB;AAED;;;;;;;;;;;GAWG;AACH,iGAFa,OAAO,CAkBnB;AAjXD;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,kCAFU,MAAM,CAEwB;AAIxC;;;;;;;;;;;;;;;;GAgBG;AACH,gCAFU,MAAM,CAEmB"}

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

@@ -249,7 +249,8 @@ export function cloth_build_rows(instance, dt) {
         stretch_force_min: Float32Array.from(stretch_force_min),
         stretch_force_max: Float32Array.from(stretch_force_max),
         leash_particle: Int32Array.from(leash_particle),
-        leash_radius: Float32Array.from(leash_radius)
+        leash_radius: Float32Array.from(leash_radius),
+        shared: instance.shared_state
     });
 
     const particle_of_node = new Int32Array(node_count);