@woosh/meep-engine 2.139.0 → 2.141.0

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

@@ -25,7 +25,7 @@ export class ColliderObserverSystem extends System<any, any, any, any, any> {
     /** @type {PhysicsSystem} */
     __physics: PhysicsSystem;
     dependencies: (typeof Transform | typeof Collider)[];
-    components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof ParentEntity>)[];
+    components_used: (ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof ParentEntity>)[];
     /**
      * @param {Collider} collider
      * @param {Transform} transform
@@ -52,7 +52,7 @@ export class ColliderObserverSystem extends System<any, any, any, any, any> {
 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 { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
 //# sourceMappingURL=ColliderObserverSystem.d.ts.map

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

@@ -1 +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"}
+{"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;0BACd,gBAAgB;4CAJE,oDAAoD;6BAFnE,kCAAkC"}

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

@@ -0,0 +1,179 @@
+/**
+ * Sentinel for {@link Joint#_jointId} before the joint is linked into a
+ * {@link PhysicsSystem}.
+ * @type {number}
+ */
+export const JOINT_UNALLOCATED: number;
+/**
+ * `entityB` value meaning "the world" — body A is constrained to a fixed
+ * world anchor rather than to a second body.
+ * @type {number}
+ */
+export const JOINT_WORLD: number;
+/**
+ * A configurable 6-DOF constraint between two bodies (or a body and the
+ * world). Connects body A's anchor frame to body B's; each of the 6 relative
+ * degrees of freedom (3 linear, 3 angular) is independently
+ * locked / free / limited / springy / motorised ({@link DofMode}). One
+ * constraint type expresses the whole joint taxonomy — see DofMode.
+ *
+ * The default configuration is a **ball-socket** (point-to-point): the three
+ * linear DOFs LOCKED (the two anchor points are held coincident), the three
+ * angular DOFs FREE. That alone gives chains, ropes, and pendulums.
+ *
+ * Anchors live in body-local frames. When `entityB === JOINT_WORLD`,
+ * `localAnchorB` is interpreted as a fixed **world** point instead of a
+ * local anchor on a second body.
+ *
+ * Solver state ({@link dofImpulse}, the `_*` fields) is owned by the
+ * PhysicsSystem; user code must not write it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Joint {
+    /**
+     * Entity owning body A (the constraint's first body — always a real body).
+     * @type {number}
+     */
+    entityA: number;
+    /**
+     * Entity owning body B, or {@link JOINT_WORLD} to anchor A to the world.
+     * @type {number}
+     */
+    entityB: number;
+    /**
+     * Anchor point on body A, in A's local frame.
+     * @readonly
+     * @type {Vector3}
+     */
+    readonly localAnchorA: Vector3;
+    /**
+     * Anchor point on body B in B's local frame — or, when
+     * `entityB === JOINT_WORLD`, a fixed world-space anchor point.
+     * @readonly
+     * @type {Vector3}
+     */
+    readonly localAnchorB: Vector3;
+    /**
+     * Orientation of the joint's reference frame on body A, in A's local
+     * space (a unit quaternion; identity = the joint frame is the body
+     * frame). The 3 linear and 3 angular DOFs are expressed in this frame:
+     * locked/limited/etc. axes are the frame's axes, not world axes. For a
+     * hinge, the free angular axis is one of these frame axes — orient the
+     * frame so that axis is the hinge axis.
+     * @readonly
+     * @type {Quaternion}
+     */
+    readonly localBasisA: Quaternion;
+    /**
+     * Orientation of the joint's reference frame on body B, in B's local
+     * space. At rest a fully-locked joint holds frame B aligned to frame A.
+     * When `entityB === JOINT_WORLD`, the world frame is treated as identity
+     * (angular locks hold A's frame to world axes).
+     * @readonly
+     * @type {Quaternion}
+     */
+    readonly localBasisB: Quaternion;
+    /**
+     * Per-DOF mode, 6 entries: `[lin x, lin y, lin z, ang x, ang y, ang z]`.
+     * Default = ball-socket (linear locked, angular free).
+     * @readonly
+     * @type {Uint8Array}
+     */
+    readonly dofMode: Uint8Array;
+    /**
+     * Lower / upper bounds per DOF, used by {@link DofMode.LIMITED}. Linear in
+     * metres, angular in radians. (Reserved — consumed once the LIMITED mode
+     * lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly dofLowerLimit: Float64Array;
+    /** @readonly @type {Float64Array} */
+    readonly dofUpperLimit: Float64Array;
+    /**
+     * Spring stiffness / damping per DOF, used by {@link DofMode.SPRING}.
+     * (Reserved — consumed once the SPRING mode lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly dofStiffness: Float64Array;
+    /** @readonly @type {Float64Array} */
+    readonly dofDamping: Float64Array;
+    /**
+     * Motor target velocity / max force per DOF, used by
+     * {@link DofMode.MOTOR}. (Reserved — consumed once the MOTOR mode lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly dofMotorTargetVelocity: Float64Array;
+    /** @readonly @type {Float64Array} */
+    readonly dofMotorMaxForce: Float64Array;
+    /**
+     * Accumulated constraint impulse per DOF — warm-start state carried across
+     * frames. System-owned.
+     * @readonly
+     * @type {Float64Array}
+     */
+    readonly dofImpulse: Float64Array;
+    /**
+     * Resolved packed body id of A, set at link time. System-private.
+     * @type {number}
+     */
+    _bodyIdA: number;
+    /**
+     * Resolved packed body id of B, or {@link JOINT_WORLD}. System-private.
+     * @type {number}
+     */
+    _bodyIdB: number;
+    /**
+     * Packed joint handle assigned at link. System-private.
+     * @type {number}
+     */
+    _jointId: number;
+    /**
+     * Configure this joint as a ball-socket (point-to-point) between two
+     * anchors. Linear DOFs locked, angular free — the default, provided as a
+     * named helper for clarity at call sites.
+     * @returns {Joint} this
+     */
+    asBallSocket(): Joint;
+    /**
+     * Configure as a weld (fixed) joint: all 6 DOFs locked, holding the two
+     * bodies rigidly in their relative pose.
+     * @returns {Joint} this
+     */
+    asWeld(): Joint;
+    /**
+     * Configure as a hinge (revolute): 3 linear + 2 angular locked, free to
+     * rotate about a single frame axis. Orient {@link localBasisA} /
+     * {@link localBasisB} so that frame axis is the desired hinge axis.
+     *
+     * @param {number} [freeAngularAxis] which frame axis is free: 0 = x
+     *   (default), 1 = y, 2 = z.
+     * @returns {Joint} this
+     */
+    asHinge(freeAngularAxis?: number): Joint;
+    /**
+     * Configure as a prismatic (slider): 2 linear + 3 angular locked, free to
+     * translate along a single frame axis. Orient {@link localBasisA} /
+     * {@link localBasisB} so that frame axis is the desired slide direction.
+     *
+     * @param {number} [freeLinearAxis] which frame axis is free: 0 = x
+     *   (default), 1 = y, 2 = z.
+     * @returns {Joint} this
+     */
+    asPrismatic(freeLinearAxis?: number): Joint;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isJoint: boolean;
+}
+export namespace Joint {
+    let typeName: string;
+}
+import Vector3 from "../../../core/geom/Vector3.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+//# sourceMappingURL=Joint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Joint.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Joint.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,0BAFU,MAAM,CAEc;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;OAGG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,SAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,uBAFU,OAAO,CAEmB;IAEpC;;;;;OAKG;IACH,uBAFU,OAAO,CAEmB;IAEpC;;;;;;;;;OASG;IACH,sBAFU,UAAU,CAEW;IAE/B;;;;;;;OAOG;IACH,sBAFU,UAAU,CAEW;IAE/B;;;;;OAKG;IACH,kBAFU,UAAU,CAKjB;IAEH;;;;;;OAMG;IACH,wBAFU,YAAY,CAEc;IACpC,qCAAqC;IACrC,wBADqB,YAAY,CACG;IAEpC;;;;;OAKG;IACH,uBAFU,YAAY,CAEa;IACnC,qCAAqC;IACrC,qBADqB,YAAY,CACA;IAEjC;;;;;OAKG;IACH,iCAFU,YAAY,CAEuB;IAC7C,qCAAqC;IACrC,2BADqB,YAAY,CACM;IAEvC;;;;;OAKG;IACH,qBAFU,YAAY,CAEW;IAEjC;;;OAGG;IACH,UAFU,MAAM,CAEF;IACd;;;OAGG;IACH,UAFU,MAAM,CAEO;IACvB;;;OAGG;IACH,UAFU,MAAM,CAEa;IAE7B;;;;;OAKG;IACH,gBAFa,KAAK,CAUjB;IAED;;;;OAIG;IACH,UAFa,KAAK,CAKjB;IAED;;;;;;;;OAQG;IACH,0BAJW,MAAM,GAEJ,KAAK,CAWjB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,GAEJ,KAAK,CAWjB;IASL;;;OAGG;IACH,kBAFU,OAAO,CAEM;CAZtB;;kBAIS,MAAM;;oBAjOI,+BAA+B;uBAC5B,kCAAkC"}

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

@@ -0,0 +1,234 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import { DofMode } from "../constraint/DofMode.js";
+
+/**
+ * Sentinel for {@link Joint#_jointId} before the joint is linked into a
+ * {@link PhysicsSystem}.
+ * @type {number}
+ */
+export const JOINT_UNALLOCATED = -1;
+
+/**
+ * `entityB` value meaning "the world" — body A is constrained to a fixed
+ * world anchor rather than to a second body.
+ * @type {number}
+ */
+export const JOINT_WORLD = -1;
+
+/**
+ * A configurable 6-DOF constraint between two bodies (or a body and the
+ * world). Connects body A's anchor frame to body B's; each of the 6 relative
+ * degrees of freedom (3 linear, 3 angular) is independently
+ * locked / free / limited / springy / motorised ({@link DofMode}). One
+ * constraint type expresses the whole joint taxonomy — see DofMode.
+ *
+ * The default configuration is a **ball-socket** (point-to-point): the three
+ * linear DOFs LOCKED (the two anchor points are held coincident), the three
+ * angular DOFs FREE. That alone gives chains, ropes, and pendulums.
+ *
+ * Anchors live in body-local frames. When `entityB === JOINT_WORLD`,
+ * `localAnchorB` is interpreted as a fixed **world** point instead of a
+ * local anchor on a second body.
+ *
+ * Solver state ({@link dofImpulse}, the `_*` fields) is owned by the
+ * PhysicsSystem; user code must not write it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Joint {
+
+    /**
+     * Entity owning body A (the constraint's first body — always a real body).
+     * @type {number}
+     */
+    entityA = -1;
+
+    /**
+     * Entity owning body B, or {@link JOINT_WORLD} to anchor A to the world.
+     * @type {number}
+     */
+    entityB = JOINT_WORLD;
+
+    /**
+     * Anchor point on body A, in A's local frame.
+     * @readonly
+     * @type {Vector3}
+     */
+    localAnchorA = new Vector3(0, 0, 0);
+
+    /**
+     * Anchor point on body B in B's local frame — or, when
+     * `entityB === JOINT_WORLD`, a fixed world-space anchor point.
+     * @readonly
+     * @type {Vector3}
+     */
+    localAnchorB = new Vector3(0, 0, 0);
+
+    /**
+     * Orientation of the joint's reference frame on body A, in A's local
+     * space (a unit quaternion; identity = the joint frame is the body
+     * frame). The 3 linear and 3 angular DOFs are expressed in this frame:
+     * locked/limited/etc. axes are the frame's axes, not world axes. For a
+     * hinge, the free angular axis is one of these frame axes — orient the
+     * frame so that axis is the hinge axis.
+     * @readonly
+     * @type {Quaternion}
+     */
+    localBasisA = new Quaternion();
+
+    /**
+     * Orientation of the joint's reference frame on body B, in B's local
+     * space. At rest a fully-locked joint holds frame B aligned to frame A.
+     * When `entityB === JOINT_WORLD`, the world frame is treated as identity
+     * (angular locks hold A's frame to world axes).
+     * @readonly
+     * @type {Quaternion}
+     */
+    localBasisB = new Quaternion();
+
+    /**
+     * Per-DOF mode, 6 entries: `[lin x, lin y, lin z, ang x, ang y, ang z]`.
+     * Default = ball-socket (linear locked, angular free).
+     * @readonly
+     * @type {Uint8Array}
+     */
+    dofMode = Uint8Array.from([
+        DofMode.LOCKED, DofMode.LOCKED, DofMode.LOCKED,
+        DofMode.FREE, DofMode.FREE, DofMode.FREE,
+    ]);
+
+    /**
+     * Lower / upper bounds per DOF, used by {@link DofMode.LIMITED}. Linear in
+     * metres, angular in radians. (Reserved — consumed once the LIMITED mode
+     * lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofLowerLimit = new Float64Array(6);
+    /** @readonly @type {Float64Array} */
+    dofUpperLimit = new Float64Array(6);
+
+    /**
+     * Spring stiffness / damping per DOF, used by {@link DofMode.SPRING}.
+     * (Reserved — consumed once the SPRING mode lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofStiffness = new Float64Array(6);
+    /** @readonly @type {Float64Array} */
+    dofDamping = new Float64Array(6);
+
+    /**
+     * Motor target velocity / max force per DOF, used by
+     * {@link DofMode.MOTOR}. (Reserved — consumed once the MOTOR mode lands.)
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofMotorTargetVelocity = new Float64Array(6);
+    /** @readonly @type {Float64Array} */
+    dofMotorMaxForce = new Float64Array(6);
+
+    /**
+     * Accumulated constraint impulse per DOF — warm-start state carried across
+     * frames. System-owned.
+     * @readonly
+     * @type {Float64Array}
+     */
+    dofImpulse = new Float64Array(6);
+
+    /**
+     * Resolved packed body id of A, set at link time. System-private.
+     * @type {number}
+     */
+    _bodyIdA = -1;
+    /**
+     * Resolved packed body id of B, or {@link JOINT_WORLD}. System-private.
+     * @type {number}
+     */
+    _bodyIdB = JOINT_WORLD;
+    /**
+     * Packed joint handle assigned at link. System-private.
+     * @type {number}
+     */
+    _jointId = JOINT_UNALLOCATED;
+
+    /**
+     * Configure this joint as a ball-socket (point-to-point) between two
+     * anchors. Linear DOFs locked, angular free — the default, provided as a
+     * named helper for clarity at call sites.
+     * @returns {Joint} this
+     */
+    asBallSocket() {
+        this.dofMode[0] = DofMode.LOCKED;
+        this.dofMode[1] = DofMode.LOCKED;
+        this.dofMode[2] = DofMode.LOCKED;
+        this.dofMode[3] = DofMode.FREE;
+        this.dofMode[4] = DofMode.FREE;
+        this.dofMode[5] = DofMode.FREE;
+        return this;
+    }
+
+    /**
+     * Configure as a weld (fixed) joint: all 6 DOFs locked, holding the two
+     * bodies rigidly in their relative pose.
+     * @returns {Joint} this
+     */
+    asWeld() {
+        for (let i = 0; i < 6; i++) this.dofMode[i] = DofMode.LOCKED;
+        return this;
+    }
+
+    /**
+     * Configure as a hinge (revolute): 3 linear + 2 angular locked, free to
+     * rotate about a single frame axis. Orient {@link localBasisA} /
+     * {@link localBasisB} so that frame axis is the desired hinge axis.
+     *
+     * @param {number} [freeAngularAxis] which frame axis is free: 0 = x
+     *   (default), 1 = y, 2 = z.
+     * @returns {Joint} this
+     */
+    asHinge(freeAngularAxis = 0) {
+        this.dofMode[0] = DofMode.LOCKED;
+        this.dofMode[1] = DofMode.LOCKED;
+        this.dofMode[2] = DofMode.LOCKED;
+        this.dofMode[3] = DofMode.LOCKED;
+        this.dofMode[4] = DofMode.LOCKED;
+        this.dofMode[5] = DofMode.LOCKED;
+        this.dofMode[3 + freeAngularAxis] = DofMode.FREE;
+        return this;
+    }
+
+    /**
+     * Configure as a prismatic (slider): 2 linear + 3 angular locked, free to
+     * translate along a single frame axis. Orient {@link localBasisA} /
+     * {@link localBasisB} so that frame axis is the desired slide direction.
+     *
+     * @param {number} [freeLinearAxis] which frame axis is free: 0 = x
+     *   (default), 1 = y, 2 = z.
+     * @returns {Joint} this
+     */
+    asPrismatic(freeLinearAxis = 0) {
+        this.dofMode[0] = DofMode.LOCKED;
+        this.dofMode[1] = DofMode.LOCKED;
+        this.dofMode[2] = DofMode.LOCKED;
+        this.dofMode[freeLinearAxis] = DofMode.FREE;
+        this.dofMode[3] = DofMode.LOCKED;
+        this.dofMode[4] = DofMode.LOCKED;
+        this.dofMode[5] = DofMode.LOCKED;
+        return this;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+Joint.typeName = "Joint";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Joint.prototype.isJoint = true;