@woosh/meep-engine 3.24.0 → 3.25.0

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

@@ -0,0 +1,182 @@
+/**
+ * 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 {
+    /**
+     * @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 }?: {
+        worker_factory: () => Worker;
+        max_cloth_count?: number;
+    });
+    dependencies: (typeof Transform64 | typeof Cloth)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof ClothCollider> | ResourceAccessSpecification<typeof Cloth> | ResourceAccessSpecification<typeof ClothExclude> | ResourceAccessSpecification<typeof ClothRig>)[];
+    /**
+     * 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: ClothWorld;
+    /**
+     * @param {Float64Array} value
+     */
+    set gravity(value: Float64Array);
+    /**
+     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @returns {Float64Array}
+     */
+    get gravity(): Float64Array;
+    /**
+     * @param {AbstractClothWind|null} value
+     */
+    set wind(value: any);
+    /**
+     * 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(): any;
+    /**
+     * @returns {ClothInstance[]}
+     */
+    get instances(): ClothInstance[];
+    /**
+     * @param {{instance_of: function(number): (PrefabInstance|null)}|null} value
+     */
+    set models(value: {
+        instance_of: (arg0: number) => (PrefabInstance | null);
+    });
+    /**
+     * @returns {{instance_of: function(number): (PrefabInstance|null)}|null}
+     */
+    get models(): {
+        instance_of: (arg0: number) => (PrefabInstance | null);
+    };
+    /**
+     * @param {Cloth} cloth
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(cloth: Cloth, transform: Transform64, entity: number): void;
+    /**
+     * @param {Cloth} cloth
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(cloth: Cloth, transform: Transform64, entity: number): void;
+    /**
+     * Throw away a cloth's binding so the next step walks its subtree again.
+     * @param {number} entity
+     * @returns {void}
+     */
+    reseed(entity: number): void;
+    /**
+     * Wake a sleeping cloth.
+     * @param {number} entity
+     * @returns {void}
+     */
+    wake(entity: number): void;
+    /**
+     * @param {number} entity
+     * @returns {ClothInstance|undefined}
+     */
+    instanceOf(entity: number): ClothInstance | undefined;
+    /**
+     * @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(): boolean;
+    #private;
+}
+import { WorkerSystem } from "../../../ecs/async/WorkerSystem.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { Cloth } from "./Cloth.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
+import { ClothCollider } from "./ClothCollider.js";
+import { ClothExclude } from "./ClothExclude.js";
+import { ClothRig } from "./ClothRig.js";
+import { ClothWorld } from "./ClothWorld.js";
+//# sourceMappingURL=WorkerClothSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/WorkerClothSystem.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH;IAoEI;;;;;;;;OAQG;IACH;QAPiC,cAAc,EAApC,MAAM,MAAM;QAIK,eAAe,GAAhC,MAAM;OAYhB;IApFD,oDAAoC;IAEpC,iUAOE;IAEF;;;;;OAKG;IACH,OAFU,UAAU,CAEK;IA6EzB;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAoBD;;OAEG;IACH,qBAEC;IAhBD;;;;;;OAMG;IACH,gBAEC;IASD;;OAEG;IACH,iCAEC;IASD;;OAEG;IACH;4BAToC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;OAWjE;IAZD;;OAEG;IACH;4BAFoC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;MAIjE;IA6CD;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAQhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;IAED;;;;OAIG;IACH,iCAEC;;CAmOJ;6BA/iB4B,oCAAoC;4BAIrC,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;8BAInC,oBAAoB;6BACrB,mBAAmB;yBACvB,eAAe;2BACb,iBAAiB"}