@woosh/meep-engine 2.169.4 → 2.170.0

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

@@ -116,284 +116,285 @@ const scratch_prox_sleeper = new Float64Array(6);
  */
 export class PhysicsSystem extends System {
 
-    constructor() {
-        super();
-
-        this.dependencies = [RigidBody, Transform];
+    dependencies = [RigidBody, Transform];
+    components_used = [
+        ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read | ResourceAccessKind.Write),
+    ];
 
-        this.components_used = [
-            ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read | ResourceAccessKind.Write),
-            ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
-            ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read | ResourceAccessKind.Write),
-        ];
+    /**
+     * @type {BodyStorage}
+     * @readonly
+     */
+    storage = new BodyStorage();
 
-        /**
-         * @type {BodyStorage}
-         * @readonly
-         */
-        this.storage = new BodyStorage();
+    /**
+     * @type {BVH}
+     */
+    staticBvh = new BVH();
 
-        /**
-         * @type {BVH}
-         */
-        this.staticBvh = new BVH();
+    /**
+     * @type {BVH}
+     */
+    dynamicBvh = new BVH();
 
-        /**
-         * @type {BVH}
-         */
-        this.dynamicBvh = new BVH();
+    /**
+     * Persistent contact-manifold cache. One slot per active pair.
+     * @type {ManifoldStore}
+     * @readonly
+     */
+    manifolds = new ManifoldStore();
 
-        /**
-         * Persistent contact-manifold cache. One slot per active pair.
-         * @type {ManifoldStore}
-         * @readonly
-         */
-        this.manifolds = new ManifoldStore();
+    /**
+     * Per-frame list of broadphase-overlapping pairs, each in
+     * entity-canonical role order (A = the smaller entity id — see
+     * generate_pairs). Cleared at the top of each step; purely
+     * intra-step state.
+     * @type {PairList}
+     */
+    pairs = new PairList();
 
-        /**
-         * Per-frame list of broadphase-overlapping pairs, each in
-         * entity-canonical role order (A = the smaller entity id — see
-         * generate_pairs). Cleared at the top of each step; purely
-         * intra-step state.
-         * @type {PairList}
-         */
-        this.pairs = new PairList();
+    /**
+     * Per-frame contact-event buffer. Populated by the manifold diff
+     * pass at end-of-step and consumed by the dispatch pass.
+     * @type {ContactEventBuffer}
+     */
+    contactEvents = new ContactEventBuffer();
 
-        /**
-         * Per-frame contact-event buffer. Populated by the manifold diff
-         * pass at end-of-step and consumed by the dispatch pass.
-         * @type {ContactEventBuffer}
-         */
-        this.contactEvents = new ContactEventBuffer();
+    /**
+     * Per-frame island partitioning of the awake-body + contact graph.
+     * Rebuilt after narrowphase, consumed by the solver (and, in the
+     * follow-up slice, by the per-island atomic sleep test). Bodies
+     * static and kinematic act as constraint anchors and do not enlarge
+     * islands.
+     * @type {IslandBuilder}
+     */
+    islands = new IslandBuilder();
 
-        /**
-         * Per-frame island partitioning of the awake-body + contact graph.
-         * Rebuilt after narrowphase, consumed by the solver (and, in the
-         * follow-up slice, by the per-island atomic sleep test). Bodies
-         * static and kinematic act as constraint anchors and do not enlarge
-         * islands.
-         * @type {IslandBuilder}
-         */
-        this.islands = new IslandBuilder();
+    /**
+     * Data-oriented mirror of the per-body solver hot state (velocity,
+     * inverse mass / inertia, orientation), packed into one ArrayBuffer
+     * and indexed by body slot. Gathered from the `RigidBody` /
+     * `Transform` components once per step (after islands are built),
+     * mutated in place by the TGS substep loop, and the persistent
+     * velocity scattered back at the end. Keeps the solver's hottest inner
+     * loop free of component-object dereferences.
+     * @type {SolverBodyState}
+     */
+    __solver_state = new SolverBodyState();
 
-        /**
-         * Data-oriented mirror of the per-body solver hot state (velocity,
-         * inverse mass / inertia, orientation), packed into one ArrayBuffer
-         * and indexed by body slot. Gathered from the `RigidBody` /
-         * `Transform` components once per step (after islands are built),
-         * mutated in place by the TGS substep loop, and the persistent
-         * velocity scattered back at the end. Keeps the solver's hottest inner
-         * loop free of component-object dereferences.
-         * @type {SolverBodyState}
-         */
-        this.__solver_state = new SolverBodyState();
+    /**
+     * Velocity-squared threshold below which a body is eligible to start
+     * accumulating sleep time. Combined linear + angular kinetic-ish
+     * metric: `vx²+vy²+vz² + ωx²+ωy²+ωz²`. Default 0.01 corresponds to
+     * ~0.1 m/s linear or ~0.1 rad/s angular.
+     * @type {number}
+     */
+    sleepVelocitySqrThreshold = 0.01;
 
-        /**
-         * Velocity-squared threshold below which a body is eligible to start
-         * accumulating sleep time. Combined linear + angular kinetic-ish
-         * metric: `vx²+vy²+vz² + ωx²+ωy²+ωz²`. Default 0.01 corresponds to
-         * ~0.1 m/s linear or ~0.1 rad/s angular.
-         * @type {number}
-         */
-        this.sleepVelocitySqrThreshold = 0.01;
+    /**
+     * Seconds of below-threshold motion before a body is moved to the
+     * sleeping set. Box2D default is 0.5 s.
+     * @type {number}
+     */
+    sleepTimeThreshold = 0.5;
 
-        /**
-         * Seconds of below-threshold motion before a body is moved to the
-         * sleeping set. Box2D default is 0.5 s.
-         * @type {number}
-         */
-        this.sleepTimeThreshold = 0.5;
+    /**
+     * Number of TGS substeps per `fixedUpdate`. Each substep re-runs the
+     * velocity + position solve at `dt / substeps` against contacts whose
+     * penetration is re-derived analytically from the bodies' moved poses
+     * — narrowphase still runs once per outer step. Higher counts buy
+     * stack stability, high-mass-ratio robustness, and smoother
+     * trajectories at a near-linear solver cost (sleeping islands are
+     * unaffected — they never enter the loop).
+     *
+     * `1` reproduces the non-substepped (single-step) solve.
+     * @type {number}
+     */
+    substeps = 4;
 
-        /**
-         * Number of TGS substeps per `fixedUpdate`. Each substep re-runs the
-         * velocity + position solve at `dt / substeps` against contacts whose
-         * penetration is re-derived analytically from the bodies' moved poses
-         * — narrowphase still runs once per outer step. Higher counts buy
-         * stack stability, high-mass-ratio robustness, and smoother
-         * trajectories at a near-linear solver cost (sleeping islands are
-         * unaffected — they never enter the loop).
-         *
-         * `1` reproduces the non-substepped (single-step) solve.
-         * @type {number}
-         */
-        this.substeps = 4;
+    /**
+     * Velocity iterations per substep. Lower than a single-step solver
+     * would need, because the substep loop revisits the contact set
+     * `substeps` times.
+     * @type {number}
+     */
+    velocityIterations = 4;
 
-        /**
-         * Velocity iterations per substep. Lower than a single-step solver
-         * would need, because the substep loop revisits the contact set
-         * `substeps` times.
-         * @type {number}
-         */
-        this.velocityIterations = 4;
+    /**
+     * Position (split-impulse) iterations per substep.
+     * @type {number}
+     */
+    positionIterations = 1;
 
-        /**
-         * Position (split-impulse) iterations per substep.
-         * @type {number}
-         */
-        this.positionIterations = 1;
+    /**
+     * Contact softness frequency, Hz (Box2D-v3 soft step, hybrid form:
+     * the velocity rows get the hertz/ζ-derived mass + impulse-decay
+     * scales; penetration recovery stays in the split-impulse position
+     * pass). The decay term is what lets resting stacks converge
+     * asymptotically instead of ringing in the hard form's limit cycle
+     * just above the sleep threshold. Clamped per step to an eighth of
+     * the substep rate. `0` = hard contacts (bit-exact legacy rows).
+     * Pairs with a non-dynamic side use 2× this frequency (stiffer, so
+     * piles don't sag into the ground). @type {number}
+     */
+    contactHertz = 30;
 
-        /**
-         * Contact softness frequency, Hz (Box2D-v3 soft step, hybrid form:
-         * the velocity rows get the hertz/ζ-derived mass + impulse-decay
-         * scales; penetration recovery stays in the split-impulse position
-         * pass). The decay term is what lets resting stacks converge
-         * asymptotically instead of ringing in the hard form's limit cycle
-         * just above the sleep threshold. Clamped per step to an eighth of
-         * the substep rate. `0` = hard contacts (bit-exact legacy rows).
-         * Pairs with a non-dynamic side use 2× this frequency (stiffer, so
-         * piles don't sag into the ground). @type {number}
-         */
-        this.contactHertz = 30;
+    /**
+     * Contact damping ratio ζ for the soft scales — heavily over-damped
+     * by design (Box2D v3 default), so contacts never oscillate.
+     * @type {number}
+     */
+    contactDampingRatio = 10;
 
-        /**
-         * Contact damping ratio ζ for the soft scales — heavily over-damped
-         * by design (Box2D v3 default), so contacts never oscillate.
-         * @type {number}
-         */
-        this.contactDampingRatio = 10;
+    /**
+     * Reusable contact-event payload. Listeners must copy any fields they
+     * intend to retain past their own scope. Reset before each dispatch.
+     * @private
+     */
+    __contact_payload = {
+        entityA: -1,
+        entityB: -1,
+        kind: 0,
+        depth: 0,
+        normal: new Vector3(),
+        point: new Vector3(),
+    };
 
-        /**
-         * Reusable contact-event payload. Listeners must copy any fields they
-         * intend to retain past their own scope. Reset before each dispatch.
-         * @private
-         */
-        this.__contact_payload = {
-            entityA: -1,
-            entityB: -1,
-            kind: 0,
-            depth: 0,
-            normal: new Vector3(),
-            point: new Vector3(),
-        };
+    /**
+     * World gravity, m/s². Applied each step scaled by per-body gravityScale.
+     * @readonly
+     * @type {Vector3}
+     */
+    gravity = new Vector3(0, -9.81, 0);
 
-        /**
-         * World gravity, m/s². Applied each step scaled by per-body gravityScale.
-         * @readonly
-         * @type {Vector3}
-         */
-        this.gravity = new Vector3(0, -9.81, 0);
+    /**
+     * Optional global contact filter. Called for each surviving broadphase
+     * pair; returning `false` discards the pair.
+     * @type {((entityA: number, entityB: number, colliderA: Collider, colliderB: Collider) => boolean) | null}
+     * @private
+     */
+    __contact_filter = null;
 
-        /**
-         * Optional global contact filter. Called for each surviving broadphase
-         * pair; returning `false` discards the pair.
-         * @type {((entityA: number, entityB: number, colliderA: Collider, colliderB: Collider) => boolean) | null}
-         * @private
-         */
-        this.__contact_filter = null;
+    /**
+     * Per-body component side-tables indexed by body index (NOT packed id).
+     * Sparse arrays — populated at link, cleared at unlink. The hot loop
+     * iterates `storage.awake_at(i)` and dereferences these.
+     * @type {RigidBody[]}
+     */
+    __bodies = [];
 
-        /**
-         * Per-body component side-tables indexed by body index (NOT packed id).
-         * Sparse arrays — populated at link, cleared at unlink. The hot loop
-         * iterates `storage.awake_at(i)` and dereferences these.
-         * @type {RigidBody[]}
-         */
-        this.__bodies = [];
+    /**
+     * @type {Transform[]}
+     * @readonly
+     */
+    __transforms = [];
 
-        /**
-         * @type {Transform[]}
-         * @readonly
-         */
-        this.__transforms = [];
+    /**
+     * Per-body list of attached colliders. Each entry stores the
+     * Collider component, its world Transform, the entity that owns
+     * it (the body entity for same-entity attachments, a child entity
+     * for compound bodies), and the BVH leaf id assigned at attach
+     * time. A body may have zero or more attached colliders.
+     *
+     * @type {Array<Array<{collider: Collider, transform: Transform, entity: number, bvhNode: number}>>}
+     */
+    __body_collider_lists = [];
 
-        /**
-         * Per-body list of attached colliders. Each entry stores the
-         * Collider component, its world Transform, the entity that owns
-         * it (the body entity for same-entity attachments, a child entity
-         * for compound bodies), and the BVH leaf id assigned at attach
-         * time. A body may have zero or more attached colliders.
-         *
-         * @type {Array<Array<{collider: Collider, transform: Transform, entity: number, bvhNode: number}>>}
-         */
-        this.__body_collider_lists = [];
+    /**
+     * Live {@link Joint} (6-DOF constraint) instances, in a sparse array
+     * indexed by joint id. Solved alongside contacts inside the TGS
+     * substep loop. Holes (unlinked joints) are `undefined`.
+     * @type {Joint[]}
+     */
+    __joints = [];
 
-        /**
-         * Live {@link Joint} (6-DOF constraint) instances, in a sparse array
-         * indexed by joint id. Solved alongside contacts inside the TGS
-         * substep loop. Holes (unlinked joints) are `undefined`.
-         * @type {Joint[]}
-         */
-        this.__joints = [];
+    /**
+     * Lowest free index in {@link __joints} for slot reuse on link.
+     * @private
+     * @type {number}
+     */
+    __joint_free = [];
 
-        /**
-         * Lowest free index in {@link __joints} for slot reuse on link.
-         * @private
-         * @type {number}
-         */
-        this.__joint_free = [];
+    /**
+     * Live joints in CANONICAL SOLVE ORDER: ascending `(entityA,
+     * entityB)`, equal keys in link order. The id-indexed
+     * {@link __joints} registry reflects link/unlink HISTORY (slot
+     * reuse), which two engines holding identical joints need not
+     * share — the joint solver's Gauss-Seidel sweep must consume
+     * joints in an order derivable from state alone or the engines
+     * diverge. Maintained by {@link link_joint} / {@link unlink_joint};
+     * consumed by the substep loop. Multiple joints between the SAME
+     * entity pair keep their relative link order — reconstruction
+     * replays links in the same order, so that too is state-derived.
+     * @private
+     * @type {Joint[]}
+     */
+    __joints_sorted = [];
 
-        /**
-         * Live joints in CANONICAL SOLVE ORDER: ascending `(entityA,
-         * entityB)`, equal keys in link order. The id-indexed
-         * {@link __joints} registry reflects link/unlink HISTORY (slot
-         * reuse), which two engines holding identical joints need not
-         * share — the joint solver's Gauss-Seidel sweep must consume
-         * joints in an order derivable from state alone or the engines
-         * diverge. Maintained by {@link link_joint} / {@link unlink_joint};
-         * consumed by the substep loop. Multiple joints between the SAME
-         * entity pair keep their relative link order — reconstruction
-         * replays links in the same order, so that too is state-derived.
-         * @private
-         * @type {Joint[]}
-         */
-        this.__joints_sorted = [];
+    /**
+     * Velocity iterations per substep for the joint solver. Joints (and
+     * especially joint chains) want a few more iterations than contacts to
+     * propagate impulses along the chain; cheap because joints are far
+     * fewer than contacts.
+     * @type {number}
+     */
+    jointIterations = 8;
 
-        /**
-         * Velocity iterations per substep for the joint solver. Joints (and
-         * especially joint chains) want a few more iterations than contacts to
-         * propagate impulses along the chain; cheap because joints are far
-         * fewer than contacts.
-         * @type {number}
-         */
-        this.jointIterations = 8;
+    /**
+     * Per-body pseudo-velocity for the Catto split-impulse position
+     * pass (TGS Phase 1). Flat layout, 6 doubles per body slot index:
+     * `[lin.x, lin.y, lin.z, ang.x, ang.y, ang.z]`. Sized to
+     * `storage.high_water_mark * 6` at the top of each fixedUpdate
+     * and zeroed in place so unwritten slots contribute nothing to
+     * `integrate_position`.
+     *
+     * The solver writes during its position pass; `integrate_position`
+     * reads and folds into the pose update on the same tick, then
+     * the next tick's zero-pass wipes the state. It NEVER lands in
+     * `linearVelocity` / `angularVelocity` — that's the point of
+     * split impulse: depth correction does not contaminate persistent
+     * velocity (so a `restitution = 0` impact stops cleanly).
+     *
+     * @type {Float64Array}
+     */
+    __pseudo_velocity = new Float64Array(0);
 
-        /**
-         * Per-body pseudo-velocity for the Catto split-impulse position
-         * pass (TGS Phase 1). Flat layout, 6 doubles per body slot index:
-         * `[lin.x, lin.y, lin.z, ang.x, ang.y, ang.z]`. Sized to
-         * `storage.high_water_mark * 6` at the top of each fixedUpdate
-         * and zeroed in place so unwritten slots contribute nothing to
-         * `integrate_position`.
-         *
-         * The solver writes during its position pass; `integrate_position`
-         * reads and folds into the pose update on the same tick, then
-         * the next tick's zero-pass wipes the state. It NEVER lands in
-         * `linearVelocity` / `angularVelocity` — that's the point of
-         * split impulse: depth correction does not contaminate persistent
-         * velocity (so a `restitution = 0` impact stops cleanly).
-         *
-         * @type {Float64Array}
-         */
-        this.__pseudo_velocity = new Float64Array(0);
+    /**
+     * Master switch for the continuous-collision pass. When false the
+     * {@link RigidBodyFlags.CCD} flag is ignored and no swept queries run.
+     * @type {boolean}
+     */
+    ccdEnabled = true;
 
-        /**
-         * Master switch for the continuous-collision pass. When false the
-         * {@link RigidBodyFlags.CCD} flag is ignored and no swept queries run.
-         * @type {boolean}
-         */
-        this.ccdEnabled = true;
+    /**
+     * Start-of-step world positions for CCD-flagged bodies — 3 doubles per
+     * body slot index (`[x, y, z]`). Captured in Stage 1 before the substep
+     * loop integrates poses; the CCD pass ({@link ccd_resolve}) sweeps from
+     * here to the final pose. Grows to `storage.high_water_mark * 3`; only
+     * CCD-flagged slots are written each step.
+     * @type {Float64Array}
+     */
+    __ccd_start_pos = new Float64Array(0);
 
-        /**
-         * Start-of-step world positions for CCD-flagged bodies — 3 doubles per
-         * body slot index (`[x, y, z]`). Captured in Stage 1 before the substep
-         * loop integrates poses; the CCD pass ({@link ccd_resolve}) sweeps from
-         * here to the final pose. Grows to `storage.high_water_mark * 3`; only
-         * CCD-flagged slots are written each step.
-         * @type {Float64Array}
-         */
-        this.__ccd_start_pos = new Float64Array(0);
+    /**
+     * Optional shared interpolation log to produce per-step pose snapshots
+     * into (the {@link InterpolationSystem}'s log). When set — and only then —
+     * each fixedUpdate restores every awake {@link Interpolated} body's live
+     * components from the previous tick (undoing render-time interpolation so
+     * the sim reads authoritative state), then records the post-step state
+     * under the current `entityManager.fixedStepTick`. Null on a headless /
+     * non-rendering world, where the producer work is skipped entirely.
+     * @type {InterpolationLog|null}
+     */
+    interpolationLog = null;
 
+    /** @private @type {number} valid entries in {@link __interp_recorded} */
+    __interp_recorded_count = 0;
 
-        /**
-         * Optional shared interpolation log to produce per-step pose snapshots
-         * into (the {@link InterpolationSystem}'s log). When set — and only then —
-         * each fixedUpdate restores every awake {@link Interpolated} body's live
-         * components from the previous tick (undoing render-time interpolation so
-         * the sim reads authoritative state), then records the post-step state
-         * under the current `entityManager.fixedStepTick`. Null on a headless /
-         * non-rendering world, where the producer work is skipped entirely.
-         * @type {InterpolationLog|null}
-         */
-        this.interpolationLog = null;
+    constructor() {
+        super();
 
         /**
          * Reusable decode buffer for restoring interpolated snapshots.
@@ -413,8 +414,6 @@ export class PhysicsSystem extends System {
          * @type {Uint32Array}
          */
         this.__interp_recorded = new Uint32Array(16);
-        /** @private @type {number} valid entries in {@link __interp_recorded} */
-        this.__interp_recorded_count = 0;
     }
 
     /**

package/src/engine/physics/events/ContactEventBuffer.d.ts

@@ -24,8 +24,8 @@ export class ContactEventBuffer {
      * @param {number} [initial_capacity] events
      */
     constructor(initial_capacity?: number);
-    __capacity: number;
     __count: number;
+    __capacity: number;
     __data: Int32Array;
     /**
      * @returns {number}

package/src/engine/physics/events/ContactEventBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContactEventBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/events/ContactEventBuffer.js"],"names":[],"mappings":";;;+BAGU,MAAM;;;;;;AAoBhB;;;;;;;;;;;GAWG;AACH;IACI;;OAEG;IACH,+BAFW,MAAM,EAOhB;IAJG,mBAA+C;IAC/C,gBAAgB;IAEhB,mBAA4D;IAGhE;;OAEG;IACH,oBAEC;IAED,cAEC;IAED;;;;;OAKG;IACH,WALW,gBAAgB,GAAC,MAAM,WACvB,MAAM,WACN,MAAM,QACN,MAAM,QAgBhB;IAED,wBAAoD;IACpD,2BAA2D;IAC3D,2BAA2D;IAC3D,wBAAwD;IAExD;;;;;;;;;OASG;IACH,uBA4BC;CACJ"}
+{"version":3,"file":"ContactEventBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/events/ContactEventBuffer.js"],"names":[],"mappings":";;;+BAGU,MAAM;;;;;;AAoBhB;;;;;;;;;;;GAWG;AACH;IAGI;;OAEG;IACH,+BAFW,MAAM,EAMhB;IATD,gBAAY;IAMR,mBAA+C;IAE/C,mBAA4D;IAGhE;;OAEG;IACH,oBAEC;IAED,cAEC;IAED;;;;;OAKG;IACH,WALW,gBAAgB,GAAC,MAAM,WACvB,MAAM,WACN,MAAM,QACN,MAAM,QAgBhB;IAED,wBAAoD;IACpD,2BAA2D;IAC3D,2BAA2D;IAC3D,wBAAwD;IAExD;;;;;;;;;OASG;IACH,uBA4BC;CACJ"}

package/src/engine/physics/events/ContactEventBuffer.js

@@ -34,12 +34,13 @@ const EVENT_STRIDE = 4;
  * @copyright Company Named Limited (c) 2026
  */
 export class ContactEventBuffer {
+    __count = 0;
+
     /**
      * @param {number} [initial_capacity] events
      */
     constructor(initial_capacity = DEFAULT_INITIAL_CAPACITY) {
         this.__capacity = Math.max(1, initial_capacity);
-        this.__count = 0;
         // Int32 so entity ids may legitimately store -1 (stale body after free).
         this.__data = new Int32Array(this.__capacity * EVENT_STRIDE);
     }