@woosh/meep-engine 2.138.20 → 2.139.0

package/src/engine/physics/ecs/Collider.js

@@ -0,0 +1,136 @@
+import { AbstractShape3D } from "../../../core/geom/3d/shape/AbstractShape3D.js";
+import { UnitSphereShape3D } from "../../../core/geom/3d/shape/UnitSphereShape3D.js";
+import { ColliderFlags } from "./ColliderFlags.js";
+
+/**
+ * Sentinel for {@link Collider#_bvhNode} prior to insertion. Matches the BVH's
+ * own NULL_NODE convention without taking a direct import dependency on it.
+ *
+ * @type {number}
+ */
+export const COLLIDER_UNBOUND = -1;
+
+/**
+ * Collider component.
+ *
+ * Pairs a shared, immutable {@link AbstractShape3D} with a body-specific surface
+ * material. World pose comes from the entity's own {@link Transform}; for compound
+ * bodies the child collider entities are linked to the body via the existing
+ * `ParentEntity` component.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Collider {
+
+    /**
+     * Surface geometry. Shared between colliders; never mutated.
+     * @type {AbstractShape3D}
+     */
+    shape = UnitSphereShape3D.INSTANCE;
+
+    /**
+     * Coulomb friction coefficient. Combined with the other side's friction via
+     * the system-wide combine rule (default: geometric mean).
+     * @type {number}
+     */
+    friction = 0.5;
+
+    /**
+     * Coefficient of restitution. 0 = perfectly inelastic, 1 = perfectly elastic.
+     * Combined via the system-wide combine rule.
+     * @type {number}
+     */
+    restitution = 0;
+
+    /**
+     * Mass-per-unit-volume. Used by inertia-tensor helpers if the user opts in
+     * to automatic mass computation; otherwise informational.
+     * @type {number}
+     */
+    density = 1;
+
+    /**
+     * @type {ColliderFlags|number}
+     */
+    flags = ColliderFlags.None;
+
+    /**
+     * BVH node identifier assigned by {@link PhysicsSystem#link}. System-private.
+     * @type {number}
+     */
+    _bvhNode = COLLIDER_UNBOUND;
+
+    /**
+     * Packed body id of the owning body, copied from the parent's
+     * {@link RigidBody#_bodyId} at link time. System-private.
+     * @type {number}
+     */
+    _bodyId = -1;
+
+    /**
+     *
+     * @param {number|ColliderFlags} flag
+     */
+    setFlag(flag) {
+        this.flags |= flag;
+    }
+
+    /**
+     *
+     * @param {number|ColliderFlags} flag
+     */
+    clearFlag(flag) {
+        this.flags &= ~flag;
+    }
+
+    /**
+     *
+     * @param {number|ColliderFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+    /**
+     *
+     * @param {number|ColliderFlags} flag
+     * @param {boolean} value
+     */
+    writeFlag(flag, value) {
+        if (value) {
+            this.setFlag(flag);
+        } else {
+            this.clearFlag(flag);
+        }
+    }
+
+    toJSON() {
+        return {
+            friction: this.friction,
+            restitution: this.restitution,
+            density: this.density,
+            flags: this.flags,
+        };
+    }
+
+    fromJSON(json) {
+        if (json.friction !== undefined) this.friction = json.friction;
+        if (json.restitution !== undefined) this.restitution = json.restitution;
+        if (json.density !== undefined) this.density = json.density;
+        if (json.flags !== undefined) this.flags = json.flags;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+Collider.typeName = "Collider";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Collider.prototype.isCollider = true;

package/src/engine/physics/ecs/ColliderFlags.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bit-flags carried on {@link Collider }.
+ *
+ * - {@link IsSensor }: this collider produces contact events but no impulse, even if
+ *   its body is not flagged as sensor. The body-level sensor flag remains the
+ *   coarse switch; this is the per-collider opt-in for compound bodies that mix
+ *   solid and trigger parts.
+ */
+export type ColliderFlags = number;
+export namespace ColliderFlags {
+    let None: number;
+    let IsSensor: number;
+}
+//# sourceMappingURL=ColliderFlags.d.ts.map

package/src/engine/physics/ecs/ColliderFlags.d.ts.map

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

package/src/engine/physics/ecs/ColliderFlags.js

@@ -0,0 +1,15 @@
+/**
+ * Bit-flags carried on {@link Collider}.
+ *
+ * - {@link IsSensor}: this collider produces contact events but no impulse, even if
+ *   its body is not flagged as sensor. The body-level sensor flag remains the
+ *   coarse switch; this is the per-collider opt-in for compound bodies that mix
+ *   solid and trigger parts.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ColliderFlags = {
+    None: 0,
+    IsSensor: 1,
+};

package/src/engine/physics/ecs/ColliderObserverSystem.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Observes every entity that gains a `(Collider, Transform)` tuple and
+ * attaches the collider to the appropriate {@link PhysicsSystem} body:
+ *
+ *  - If the same entity also carries a {@link RigidBody}, the collider is
+ *    a same-entity attachment — body = this entity.
+ *  - Else if the entity carries a {@link ParentEntity} pointing at a body
+ *    entity (which has a `RigidBody`), the collider is a child-collider of
+ *    a compound body — body = parent entity.
+ *  - Otherwise the collider is "orphan" (no body to attach to). The
+ *    observer silently skips; a warning would just spam the console for
+ *    common authoring transients (collider component added before the
+ *    body is constructed). Add the body first, then the colliders.
+ *
+ * Pairs with {@link PhysicsSystem}: register both in the EntityManager.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ColliderObserverSystem extends System<any, any, any, any, any> {
+    /**
+     * @param {PhysicsSystem} physicsSystem
+     */
+    constructor(physicsSystem: PhysicsSystem);
+    /** @type {PhysicsSystem} */
+    __physics: PhysicsSystem;
+    dependencies: (typeof Transform | typeof Collider)[];
+    components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof ParentEntity>)[];
+    /**
+     * @param {Collider} collider
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(collider: Collider, transform: Transform, entity: number): void;
+    /**
+     * @param {Collider} collider
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(collider: Collider, transform: Transform, entity: number): void;
+    /**
+     * Walk RigidBody-on-self → ParentEntity → orphan, returning the entity
+     * that owns the body this collider belongs to.
+     *
+     * @private
+     * @param {EntityComponentDataset} ecd
+     * @param {number} entity
+     * @returns {number} body entity or -1
+     */
+    private __resolve_body_entity;
+}
+import { System } from "../../ecs/System.js";
+import { Transform } from "../../ecs/transform/Transform.js";
+import { Collider } from "./Collider.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { RigidBody } from "./RigidBody.js";
+import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+//# sourceMappingURL=ColliderObserverSystem.d.ts.map

package/src/engine/physics/ecs/ColliderObserverSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColliderObserverSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ColliderObserverSystem.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEI;;OAEG;IACH,0CAcC;IAXG,4BAA4B;IAC5B,yBAA8B;IAE9B,qDAAyC;IAEzC,qNAKC;IAGL;;;;OAIG;IACH,eAJW,QAAQ,aACR,SAAS,UACT,MAAM,QAYhB;IAED;;;;OAIG;IACH,iBAJW,QAAQ,aACR,SAAS,UACT,MAAM,QAYhB;IAED;;;;;;;;OAQG;IACH,8BAUC;CACJ;uBAnGsB,qBAAqB;0BAClB,kCAAkC;yBACnC,eAAe;4CAHI,oDAAoD;0BAItE,gBAAgB;6BANb,kCAAkC"}

package/src/engine/physics/ecs/ColliderObserverSystem.js

@@ -0,0 +1,103 @@
+import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../ecs/System.js";
+import { Transform } from "../../ecs/transform/Transform.js";
+import { Collider } from "./Collider.js";
+import { RigidBody } from "./RigidBody.js";
+
+/**
+ * Observes every entity that gains a `(Collider, Transform)` tuple and
+ * attaches the collider to the appropriate {@link PhysicsSystem} body:
+ *
+ *  - If the same entity also carries a {@link RigidBody}, the collider is
+ *    a same-entity attachment — body = this entity.
+ *  - Else if the entity carries a {@link ParentEntity} pointing at a body
+ *    entity (which has a `RigidBody`), the collider is a child-collider of
+ *    a compound body — body = parent entity.
+ *  - Otherwise the collider is "orphan" (no body to attach to). The
+ *    observer silently skips; a warning would just spam the console for
+ *    common authoring transients (collider component added before the
+ *    body is constructed). Add the body first, then the colliders.
+ *
+ * Pairs with {@link PhysicsSystem}: register both in the EntityManager.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ColliderObserverSystem extends System {
+
+    /**
+     * @param {PhysicsSystem} physicsSystem
+     */
+    constructor(physicsSystem) {
+        super();
+
+        /** @type {PhysicsSystem} */
+        this.__physics = physicsSystem;
+
+        this.dependencies = [Collider, Transform];
+
+        this.components_used = [
+            ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read | ResourceAccessKind.Write),
+            ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read),
+            ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read),
+            ResourceAccessSpecification.from(ParentEntity, ResourceAccessKind.Read),
+        ];
+    }
+
+    /**
+     * @param {Collider} collider
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(collider, transform, entity) {
+        const em = this.entityManager;
+        if (em === null || em === undefined) return;
+        const ecd = em.dataset;
+        if (ecd === null || ecd === undefined) return;
+
+        const body_entity = this.__resolve_body_entity(ecd, entity);
+        if (body_entity === -1) return; // orphan — body must be added first
+
+        this.__physics.attach_collider(body_entity, collider, transform, entity);
+    }
+
+    /**
+     * @param {Collider} collider
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(collider, transform, entity) {
+        const em = this.entityManager;
+        if (em === null || em === undefined) return;
+        const ecd = em.dataset;
+        if (ecd === null || ecd === undefined) return;
+
+        const body_entity = this.__resolve_body_entity(ecd, entity);
+        if (body_entity === -1) return;
+
+        this.__physics.detach_collider(body_entity, collider);
+    }
+
+    /**
+     * Walk RigidBody-on-self → ParentEntity → orphan, returning the entity
+     * that owns the body this collider belongs to.
+     *
+     * @private
+     * @param {EntityComponentDataset} ecd
+     * @param {number} entity
+     * @returns {number} body entity or -1
+     */
+    __resolve_body_entity(ecd, entity) {
+        if (ecd.hasComponent(entity, RigidBody)) {
+            return entity;
+        }
+        const parent = ecd.getComponent(entity, ParentEntity);
+        if (parent !== undefined && parent.entity >= 0
+            && ecd.hasComponent(parent.entity, RigidBody)) {
+            return parent.entity;
+        }
+        return -1;
+    }
+}

package/src/engine/physics/ecs/ColliderSerializationAdapter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Binary serialization for {@link Collider}. The `shape` reference is not part
+ * of the stream — shapes are shared, immutable assets and are wired up
+ * separately by the loader.
+ */
+export class ColliderSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof Collider;
+    version: number;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Collider} value
+     */
+    serialize(buffer: BinaryBuffer, value: Collider): void;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Collider} value
+     */
+    deserialize(buffer: BinaryBuffer, value: Collider): void;
+}
+import { BinaryClassSerializationAdapter } from "../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { Collider } from "./Collider.js";
+//# sourceMappingURL=ColliderSerializationAdapter.d.ts.map

package/src/engine/physics/ecs/ColliderSerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColliderSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ColliderSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;;IAEI,uBAAiB;IACjB,gBAAY;IAEZ;;;;OAIG;IACH,uCAFW,QAAQ,QAOlB;IAED;;;;OAIG;IACH,yCAFW,QAAQ,QAOlB;CACJ;gDApC+C,6DAA6D;yBACpF,eAAe"}

package/src/engine/physics/ecs/ColliderSerializationAdapter.js

@@ -0,0 +1,37 @@
+import { BinaryClassSerializationAdapter } from "../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { Collider } from "./Collider.js";
+
+/**
+ * Binary serialization for {@link Collider}. The `shape` reference is not part
+ * of the stream — shapes are shared, immutable assets and are wired up
+ * separately by the loader.
+ */
+export class ColliderSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = Collider;
+    version = 0;
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Collider} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.friction);
+        buffer.writeFloat64(value.restitution);
+        buffer.writeFloat64(value.density);
+        buffer.writeUint32(value.flags >>> 0);
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Collider} value
+     */
+    deserialize(buffer, value) {
+        value.friction = buffer.readFloat64();
+        value.restitution = buffer.readFloat64();
+        value.density = buffer.readFloat64();
+        value.flags = buffer.readUint32();
+    }
+}

package/src/engine/physics/ecs/PhysicsEvents.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Entity-level event names emitted by {@link PhysicsSystem } via
+ * `entity.sendEvent(...)`. Listeners receive a contact payload that is **only valid
+ * for the dispatch** — copy any field you need to retain.
+ *
+ * The same events are also dispatched through the system-level Signals
+ * {@link PhysicsSystemonContactBegin }, etc., for global listeners.
+ */
+export type PhysicsEvents = string;
+export namespace PhysicsEvents {
+    let ContactBegin: string;
+    let ContactStay: string;
+    let ContactEnd: string;
+}
+//# sourceMappingURL=PhysicsEvents.d.ts.map

package/src/engine/physics/ecs/PhysicsEvents.d.ts.map

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

package/src/engine/physics/ecs/PhysicsEvents.js

@@ -0,0 +1,16 @@
+/**
+ * Entity-level event names emitted by {@link PhysicsSystem} via
+ * `entity.sendEvent(...)`. Listeners receive a contact payload that is **only valid
+ * for the dispatch** — copy any field you need to retain.
+ *
+ * The same events are also dispatched through the system-level Signals
+ * {@link PhysicsSystem#onContactBegin}, etc., for global listeners.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const PhysicsEvents = {
+    ContactBegin: '@ecd-component-RigidBody/contact-begin',
+    ContactStay: '@ecd-component-RigidBody/contact-stay',
+    ContactEnd: '@ecd-component-RigidBody/contact-end',
+};