@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -0,0 +1,199 @@
+import { assert } from "../../../../core/assert.js";
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { ClothColliderFlags } from "./ClothColliderFlags.js";
+
+/**
+ * # The marker that opts a collider into cloth
+ *
+ * Put this beside an existing `(Collider, Transform64)` and cloth collides
+ * against it. That is the whole of the component's job, and it is the third
+ * instance of a pattern the engine already has twice: `AcousticBody` opts a
+ * collider into the acoustic simulation and carries an `AcousticMaterial`,
+ * `FluidObstacle` opts a collider into the fluid simulation and carries an
+ * inflation radius. This should read as a sibling of those two rather than as a
+ * new invention.
+ *
+ * Everything not here is read from components the entity already has: geometry
+ * and friction from `Collider`, pose from `Transform64`.
+ *
+ * ## No `RigidBody` required
+ *
+ * A deliberate divergence from `FluidObstacle`, which requires one because it
+ * needs a wall velocity. Cloth's colliders are overwhelmingly character bones —
+ * ordinary entities in a `TransformAttachment` hierarchy — and making each of
+ * them a physics body to be seen by cloth would tax the common case. Collider
+ * velocity is derived from the pose delta between fixed steps, which the index
+ * caches anyway for swept collision (§8.2). A world prop that *does* carry a
+ * `RigidBody` adds a `ClothCollider` the same way and lands in the same index;
+ * the two cases are not distinguished.
+ *
+ * ## Layer and mask, which §3.5 did not have
+ *
+ * §3.5 gives this component three fields and says layer filtering comes "from
+ * the `Cloth` side". It cannot: `Cloth#mask` is a mask *of collider layers*,
+ * and with no `RigidBody` required there is nowhere else for a collider's layer
+ * to live. So the pair is here, with `RigidBody`'s own semantics — a cloth and
+ * a collider interact when each is in the other's mask — which is what
+ * `Cloth.js` already says it means by "`RigidBody` semantics".
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothCollider {
+
+    /**
+     * Extra thickness in metres, on top of `ClothDynamics#thickness`.
+     *
+     * The contact row holds cloth at `thickness + inflation` from the surface,
+     * so this is how a garment is kept off a body it would otherwise graze —
+     * the same idea as `FluidObstacle#inflation`, and useful for the same
+     * reason: a collider that approximates a limb loosely wants the cloth held
+     * a little further out than the approximation.
+     * @type {number}
+     */
+    inflation = 0;
+
+    /**
+     * Multiplies the entity's `Collider#friction` before it is combined with
+     * the cloth's own. `0` makes the surface frictionless to cloth without
+     * making it frictionless to rigid bodies, which is the case this exists
+     * for: a character's collision capsules are tuned for footing, and a cape
+     * that grips them the same way reads as glued.
+     * @type {number}
+     */
+    friction_scale = 1;
+
+    /**
+     * Collision layer this collider belongs to, `RigidBody` semantics.
+     * @type {number}
+     */
+    layer = 1;
+
+    /**
+     * Which `Cloth` layers this collider acts on.
+     * @type {number}
+     */
+    mask = 0xFFFFFFFF;
+
+    /**
+     * @see ClothColliderFlags
+     * @type {number}
+     */
+    flags = ClothColliderFlags.None;
+
+    /**
+     * @param {object} [spec]
+     * @param {number} [spec.inflation]
+     * @param {number} [spec.friction_scale]
+     * @param {number} [spec.layer]
+     * @param {number} [spec.mask]
+     * @param {number} [spec.flags]
+     * @returns {ClothCollider}
+     */
+    static from(spec = {}) {
+        const r = new ClothCollider();
+
+        const {
+            inflation = r.inflation,
+            friction_scale = r.friction_scale,
+            layer = r.layer,
+            mask = r.mask,
+            flags = r.flags
+        } = spec;
+
+        assert.isNumber(inflation, 'inflation');
+        assert.isNumber(friction_scale, 'friction_scale');
+        assert.isNonNegativeInteger(layer, 'layer');
+        assert.isNonNegativeInteger(mask, 'mask');
+        assert.isNonNegativeInteger(flags, 'flags');
+
+        r.inflation = inflation;
+        r.friction_scale = friction_scale;
+        r.layer = layer;
+        r.mask = mask;
+        r.flags = flags;
+
+        return r;
+    }
+
+    /**
+     * @param {number|ClothColliderFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+    /**
+     * @param {ClothCollider} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+
+        if (other === null || other === undefined || other.isClothCollider !== true) {
+            return false;
+        }
+
+        return this.inflation === other.inflation
+            && this.friction_scale === other.friction_scale
+            && this.layer === other.layer
+            && this.mask === other.mask
+            && this.flags === other.flags;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.inflation),
+            computeHashFloat(this.friction_scale),
+            this.layer,
+            this.mask,
+            this.flags
+        );
+    }
+
+    toJSON() {
+        return {
+            inflation: this.inflation,
+            friction_scale: this.friction_scale,
+            layer: this.layer,
+            mask: this.mask,
+            flags: this.flags
+        };
+    }
+
+    /**
+     * @param {object} json
+     */
+    fromJSON({
+        inflation = 0,
+        friction_scale = 1,
+        layer = 1,
+        mask = 0xFFFFFFFF,
+        flags = ClothColliderFlags.None
+    }) {
+        this.inflation = inflation;
+        this.friction_scale = friction_scale;
+        this.layer = layer;
+        this.mask = mask;
+        this.flags = flags;
+    }
+
+    toString() {
+        return `ClothCollider${JSON.stringify(this.toJSON())}`;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ClothCollider.prototype.isClothCollider = true;
+
+ClothCollider.typeName = "ClothCollider";

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

@@ -0,0 +1,9 @@
+/**
+ * *
+ */
+export type ClothColliderFlags = number;
+export namespace ClothColliderFlags {
+    let None: number;
+    let Static: number;
+}
+//# sourceMappingURL=ClothColliderFlags.d.ts.map

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * Switches on {@link ClothCollider}.
+ *
+ * @readonly
+ * @enum {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const ClothColliderFlags = {
+    None: 0,
+
+    /**
+     * The collider never moves, so it is placed once and never swept.
+     *
+     * §8.2's swept collision interpolates each collider's pose between the
+     * previous step's and this one's, and rolling one pose into the other and
+     * refitting the swept bounds is the per-collider, per-step cost of that. A
+     * ground plane, a wall, a rock pays it for nothing, and a large static
+     * collider pays the most because its bounds are the biggest thing the
+     * broadphase tests against.
+     *
+     * Set this and the pose is written once, at link, into **both** slots, so
+     * the sweep degenerates to the pose it already had. Move the entity anyway
+     * and the cloth will not notice: that is the trade, and it is why this is
+     * an author's assertion rather than something derived from a pose that
+     * happens not to have changed yet.
+     */
+    Static: 1
+};
+
+Object.freeze(ClothColliderFlags);

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

@@ -0,0 +1,114 @@
+/**
+ * # The index's owner
+ *
+ * Observes `(ClothCollider, Collider, Transform64)` and maintains a
+ * {@link ClothColliderIndex}. The same shape as
+ * `AcousticOccluderIndex`/`OccluderBody` in the sound simulation, and for the
+ * same reason: the consumer needs a compact, pose-cached, broadphase-able view
+ * of a set of colliders that is deliberately not the physics BVH, because
+ * `ColliderObserverSystem` skips colliders with no owning body and a
+ * character's bone colliders have none.
+ *
+ * ## It has no `fixedUpdate`, and that is §4.1 applied a second time
+ *
+ * The index has to be refreshed from the world's transforms **before** any
+ * cloth reads it, and the engine's two ordering mechanisms cannot express that:
+ * `updateExecutionOrder` scores a system as a sum over the components it
+ * references and sorts descending, so a system can only be moved *earlier* by
+ * touching more, and `ClothSystem` — which reads and writes `Transform64` and
+ * `TransformAttachment` — outscores a system that only reads. Registration
+ * order does not break a non-tie.
+ *
+ * §4.1's conclusion applies unchanged: the answer is not a third mechanism, it
+ * is not needing one. So this system does not step at all. {@link refresh} is
+ * called once, at the top of `ClothSystem#fixedUpdate`, before any cloth is
+ * advanced — one call site, no flag to keep true, and the collider poses are
+ * read at exactly the moment the anchor poses are, which is what makes a
+ * contact consistent rather than merely fresh.
+ *
+ * The consequence, stated: with no `ClothSystem` in the manager the index is
+ * never refreshed. Nothing reads it either, so the cost of that is zero and the
+ * alternative — refreshing on a schedule nobody consumes — is worse.
+ *
+ * ## A mesh collider is skipped, once, loudly
+ *
+ * §8.2 restricts cloth to analytic primitives, which is universal in shipping
+ * cloth systems and is what makes the inner loop arithmetic rather than a BVH
+ * descent. A `Collider` carrying a mesh or a heightmap is skipped with one
+ * warning naming the entity, and the documented answer is to add primitive
+ * `ClothCollider` children — which is what an author would do for a character
+ * anyway.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothColliderSystem extends System<any> {
+    constructor();
+    dependencies: (typeof Transform64 | typeof Collider | typeof ClothCollider)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof ClothCollider>)[];
+    /**
+     * @type {ClothColliderIndex}
+     */
+    index: ClothColliderIndex;
+    /**
+     * Handle in {@link index} per linked entity. An entity whose shape cloth
+     * cannot collide against is absent rather than present with `-1`, so the
+     * refresh loop iterates only over colliders that exist.
+     * @type {Map<number, number>}
+     * @private
+     */
+    private __handles;
+    /**
+     * Live `(ClothCollider, Collider, Transform64)` per handle, in the order
+     * they were linked. Held rather than looked up per step for the same reason
+     * `ClothInstance` holds its transforms: a refresh is a loop over live
+     * colliders, not a query.
+     * @type {{collider: ClothCollider, transform: Transform64, entity: number, handle: number}[]}
+     * @private
+     */
+    private __linked;
+    /**
+     * @param {ClothCollider} cloth_collider
+     * @param {Collider} collider
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(cloth_collider: ClothCollider, collider: Collider, transform: Transform64, entity: number): void;
+    /**
+     * @param {ClothCollider} cloth_collider
+     * @param {Collider} collider
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(cloth_collider: ClothCollider, collider: Collider, transform: Transform64, entity: number): void;
+    /**
+     * Roll every collider's pose forward one fixed step and re-read it from the
+     * world. Called by `ClothSystem` at the top of its own fixed update; see the
+     * class docblock for why it is a call rather than an ordering.
+     *
+     * @returns {void}
+     */
+    refresh(): void;
+    /**
+     * Re-read a collider's surface and filter from its components. An author
+     * changing `inflation` or a layer at runtime says so here; nothing polls
+     * for it, which is the same contract `ClothSystem#reseed` carries for a
+     * structural change.
+     *
+     * @param {number} entity
+     * @returns {void}
+     */
+    refreshSurface(entity: number): void;
+    /**
+     * @param {number} entity
+     * @returns {number} the index handle, or `undefined` if the entity is not indexed
+     */
+    handleOf(entity: number): number;
+}
+import { System } from "../../../ecs/System.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { Collider } from "../../ecs/Collider.js";
+import { ClothCollider } from "./ClothCollider.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { ClothColliderIndex } from "../collider/ClothColliderIndex.js";
+//# sourceMappingURL=ClothColliderSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ClothColliderSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothColliderSystem.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;;IAEI,8EAAsD;IAEtD,wKAIE;IAEF;;OAEG;IACH,OAFU,kBAAkB,CAEK;IAEjC;;;;;;OAMG;IACH,kBAAsB;IAEtB;;;;;;;OAOG;IACH,iBAAc;IAEd;;;;;OAKG;IACH,qBALW,aAAa,YACb,QAAQ,aACR,WAAW,UACX,MAAM,QAsChB;IAED;;;;;OAKG;IACH,uBALW,aAAa,YACb,QAAQ,aACR,WAAW,UACX,MAAM,QAmBhB;IAED;;;;;;OAMG;IACH,WAFa,IAAI,CAkChB;IAED;;;;;;;;OAQG;IACH,uBAHW,MAAM,GACJ,IAAI,CAyBhB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ;uBAhPsB,wBAAwB;4BAKxC,uCAAuC;yBACrB,uBAAuB;8BAElB,oBAAoB;4CATN,uDAAuD;mCAQhE,mCAAmC"}

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

@@ -0,0 +1,243 @@
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../../ecs/System.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET,
+    Transform64
+} from "../../../ecs/transform/Transform64.js";
+import { Collider } from "../../ecs/Collider.js";
+import { ClothColliderIndex } from "../collider/ClothColliderIndex.js";
+import { ClothCollider } from "./ClothCollider.js";
+import { ClothColliderFlags } from "./ClothColliderFlags.js";
+
+/**
+ * # The index's owner
+ *
+ * Observes `(ClothCollider, Collider, Transform64)` and maintains a
+ * {@link ClothColliderIndex}. The same shape as
+ * `AcousticOccluderIndex`/`OccluderBody` in the sound simulation, and for the
+ * same reason: the consumer needs a compact, pose-cached, broadphase-able view
+ * of a set of colliders that is deliberately not the physics BVH, because
+ * `ColliderObserverSystem` skips colliders with no owning body and a
+ * character's bone colliders have none.
+ *
+ * ## It has no `fixedUpdate`, and that is §4.1 applied a second time
+ *
+ * The index has to be refreshed from the world's transforms **before** any
+ * cloth reads it, and the engine's two ordering mechanisms cannot express that:
+ * `updateExecutionOrder` scores a system as a sum over the components it
+ * references and sorts descending, so a system can only be moved *earlier* by
+ * touching more, and `ClothSystem` — which reads and writes `Transform64` and
+ * `TransformAttachment` — outscores a system that only reads. Registration
+ * order does not break a non-tie.
+ *
+ * §4.1's conclusion applies unchanged: the answer is not a third mechanism, it
+ * is not needing one. So this system does not step at all. {@link refresh} is
+ * called once, at the top of `ClothSystem#fixedUpdate`, before any cloth is
+ * advanced — one call site, no flag to keep true, and the collider poses are
+ * read at exactly the moment the anchor poses are, which is what makes a
+ * contact consistent rather than merely fresh.
+ *
+ * The consequence, stated: with no `ClothSystem` in the manager the index is
+ * never refreshed. Nothing reads it either, so the cost of that is zero and the
+ * alternative — refreshing on a schedule nobody consumes — is worse.
+ *
+ * ## A mesh collider is skipped, once, loudly
+ *
+ * §8.2 restricts cloth to analytic primitives, which is universal in shipping
+ * cloth systems and is what makes the inner loop arithmetic rather than a BVH
+ * descent. A `Collider` carrying a mesh or a heightmap is skipped with one
+ * warning naming the entity, and the documented answer is to add primitive
+ * `ClothCollider` children — which is what an author would do for a character
+ * anyway.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothColliderSystem extends System {
+
+    dependencies = [ClothCollider, Collider, Transform64];
+
+    components_used = [
+        ResourceAccessSpecification.from(ClothCollider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read)
+    ];
+
+    /**
+     * @type {ClothColliderIndex}
+     */
+    index = new ClothColliderIndex();
+
+    /**
+     * Handle in {@link index} per linked entity. An entity whose shape cloth
+     * cannot collide against is absent rather than present with `-1`, so the
+     * refresh loop iterates only over colliders that exist.
+     * @type {Map<number, number>}
+     * @private
+     */
+    __handles = new Map();
+
+    /**
+     * Live `(ClothCollider, Collider, Transform64)` per handle, in the order
+     * they were linked. Held rather than looked up per step for the same reason
+     * `ClothInstance` holds its transforms: a refresh is a loop over live
+     * colliders, not a query.
+     * @type {{collider: ClothCollider, transform: Transform64, entity: number, handle: number}[]}
+     * @private
+     */
+    __linked = [];
+
+    /**
+     * @param {ClothCollider} cloth_collider
+     * @param {Collider} collider
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(cloth_collider, collider, transform, entity) {
+        const handle = this.index.add(
+            collider.shape,
+            collider.friction * cloth_collider.friction_scale,
+            cloth_collider.inflation,
+            cloth_collider.layer,
+            cloth_collider.mask,
+            entity
+        );
+
+        if (handle < 0) {
+            console.warn(
+                `ClothColliderSystem: entity ${entity} carries a ${collider.shape.constructor.name}, `
+                + `which cloth does not collide against (§8.2 — analytic primitives only). `
+                + `Add primitive ClothCollider children instead.`
+            );
+
+            return;
+        }
+
+        this.__handles.set(entity, handle);
+
+        this.__linked.push({ collider: cloth_collider, transform, entity, handle });
+
+        // Placed rather than posed, so its first step sweeps nothing. A
+        // collider that has just appeared did not move.
+        this.index.placePose(
+            handle,
+            transform[TRANSFORM64_TRANSLATION_OFFSET],
+            transform[TRANSFORM64_TRANSLATION_OFFSET + 1],
+            transform[TRANSFORM64_TRANSLATION_OFFSET + 2],
+            transform[TRANSFORM64_ROTATION_OFFSET],
+            transform[TRANSFORM64_ROTATION_OFFSET + 1],
+            transform[TRANSFORM64_ROTATION_OFFSET + 2],
+            transform[TRANSFORM64_ROTATION_OFFSET + 3]
+        );
+    }
+
+    /**
+     * @param {ClothCollider} cloth_collider
+     * @param {Collider} collider
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(cloth_collider, collider, transform, entity) {
+        const handle = this.__handles.get(entity);
+
+        if (handle === undefined) {
+            return;
+        }
+
+        this.__handles.delete(entity);
+        this.index.remove(handle);
+
+        for (let i = 0; i < this.__linked.length; i++) {
+            if (this.__linked[i].entity === entity) {
+                this.__linked.splice(i, 1);
+
+                break;
+            }
+        }
+    }
+
+    /**
+     * Roll every collider's pose forward one fixed step and re-read it from the
+     * world. Called by `ClothSystem` at the top of its own fixed update; see the
+     * class docblock for why it is a call rather than an ordering.
+     *
+     * @returns {void}
+     */
+    refresh() {
+        const index = this.index;
+
+        index.advance();
+
+        const linked = this.__linked;
+
+        for (let i = 0; i < linked.length; i++) {
+            const entry = linked[i];
+
+            const cloth_collider = entry.collider;
+
+            if ((cloth_collider.flags & ClothColliderFlags.Static) !== 0) {
+                // Placed once at link and never swept. `advance` has just made
+                // its previous pose equal to its current one, which is exactly
+                // the state a static collider wants and costs nothing to leave.
+                continue;
+            }
+
+            const transform = entry.transform;
+
+            index.setPose(
+                entry.handle,
+                transform[TRANSFORM64_TRANSLATION_OFFSET],
+                transform[TRANSFORM64_TRANSLATION_OFFSET + 1],
+                transform[TRANSFORM64_TRANSLATION_OFFSET + 2],
+                transform[TRANSFORM64_ROTATION_OFFSET],
+                transform[TRANSFORM64_ROTATION_OFFSET + 1],
+                transform[TRANSFORM64_ROTATION_OFFSET + 2],
+                transform[TRANSFORM64_ROTATION_OFFSET + 3]
+            );
+        }
+    }
+
+    /**
+     * Re-read a collider's surface and filter from its components. An author
+     * changing `inflation` or a layer at runtime says so here; nothing polls
+     * for it, which is the same contract `ClothSystem#reseed` carries for a
+     * structural change.
+     *
+     * @param {number} entity
+     * @returns {void}
+     */
+    refreshSurface(entity) {
+        const handle = this.__handles.get(entity);
+
+        if (handle === undefined) {
+            return;
+        }
+
+        const ecd = this.entityManager.dataset;
+
+        const cloth_collider = ecd.getComponent(entity, ClothCollider);
+        const collider = ecd.getComponent(entity, Collider);
+
+        if (cloth_collider === undefined || collider === undefined) {
+            return;
+        }
+
+        this.index.setSurface(
+            handle,
+            collider.friction * cloth_collider.friction_scale,
+            cloth_collider.inflation
+        );
+
+        this.index.setFilter(handle, cloth_collider.layer, cloth_collider.mask);
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {number} the index handle, or `undefined` if the entity is not indexed
+     */
+    handleOf(entity) {
+        return this.__handles.get(entity);
+    }
+}