@woosh/meep-engine 3.38.0 → 3.40.0

package/src/engine/control/first-person/collision/KinematicMover.js

@@ -1,10 +1,12 @@
+import { assert } from "../../../../core/assert.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
 import { v3_add } from "../../../../core/geom/vec3/v3_add.js";
 import { v3_set } from "../../../../core/geom/vec3/v3_set.js";
-import { Transform64 } from "../../../ecs/transform/Transform64.js";
 import { Collider } from "../../../physics/ecs/Collider.js";
+import { is_sensor } from "../../../physics/ecs/is_sensor.js";
 import { compute_penetration } from "../../../physics/narrowphase/compute_penetration.js";
+import { convex_overlaps_shape } from "../../../physics/queries/convex_overlaps_shape.js";
 import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
 
 /**
@@ -19,12 +21,21 @@ const MAX_CLIP_PLANES = 5;
 /** Below this speed/length we treat the remaining motion as spent. */
 const MIN_MOVE = 1e-6;
 
+/**
+ * A resting body this close to the height the ground stick would put it at is already there. The
+ * footprint shape cast parks 1e-5 to 1.25e-5 m short of a touch, so two probes of one resting pose
+ * can disagree by up to 2.5e-6 m; a standing capsule measured 2.3e-8 to 4.6e-8 m a move on a box,
+ * a mesh and a 20° slope. A two-thousandth of the default skin.
+ * @type {number}
+ */
+const REST_TOLERANCE = 1e-5;
+
 /**
  * Kinematic character collision solver. See DESIGN_COLLISION.md.
  *
  * **The mover is controller-agnostic, and the path it lives at says otherwise.** It imports
- * `Vector3`, `Ray3`, `Transform64`, `Collider`, `compute_penetration` and `PhysicsSurfacePoint` —
- * nothing from `FirstPersonPlayerController`. If you have your own movement model and have decided
+ * `assert`, `Vector3`, `Ray3`, `v3_add`, `v3_set`, `Collider`, `is_sensor`, `compute_penetration`,
+ * `convex_overlaps_shape` and `PhysicsSurfacePoint` — nothing from `FirstPersonPlayerController`. If you have your own movement model and have decided
  * that controller is not for you, **this class still is**: it carries the standoff (`skin`), the
  * start-solid depenetration pass, Quake's five-plane crease handling and `MIN_WALK_NORMAL`, and it
  * is the thing to build a character on. It sits under `control/first-person/` because that is where
@@ -57,11 +68,20 @@ export class KinematicMover {
     _ray = new Ray3();
 
     _hit = new PhysicsSurfacePoint();
+    /**
+     * Overlap query output. Grown by {@link _overlapAll} whenever a query fills it, and the
+     * high-water mark kept: the query caps its count at the buffer and drops the rest without a
+     * word, and the body it drops can be the one the capsule is deepest in.
+     * @type {Uint32Array}
+     */
     _overlapBuf = new Uint32Array(16);
     _penDir = new Float64Array(3); // compute_penetration out
+    _otherPosition = new Float64Array(3); // pose of the collider recovery is testing, see _readPose
+    _otherRotation = new Float64Array(4);
     _planes = new Float64Array(MAX_CLIP_PLANES * 3);
     _cand = new Float64Array(3); // clipped-velocity candidate
     _support = new Float64Array(3); // shape support point (forward extent)
+    _supportDir = new Float64Array(3); // the direction it is asked along
     /**
      * Reused result.
      *
@@ -111,11 +131,25 @@ export class KinematicMover {
     _wasGrounded = false;
 
     /**
-     * @param {import("../../../physics/ecs/PhysicsSystem.js").PhysicsSystem} physicsSystem
-     * @param {import("../../../ecs/EntityComponentDataset.js").EntityComponentDataset} ecd
-     *   used to resolve an overlapping `body_id` (via
-     *   `physicsSystem.entityOf`) back to its {@link Transform64} +
-     *   {@link Collider} for `compute_penetration`.
+     * The filter of the {@link move} in progress, for {@link _solidCast}, which the shape cast
+     * calls back without it. `null` between moves.
+     * @private
+     * @type {((entity:number, collider:Collider)=>boolean)|null}
+     */
+    _filter = null;
+
+    /**
+     * Shape-cast filter for the move in progress: {@link _isSolid} with the move's filter. Made once
+     * per mover, so a cast allocates no closure.
+     * @private
+     * @type {(entity:number, collider:Collider, body_id:number)=>boolean}
+     */
+    _solidCast = (entity, collider, body_id) => this._isSolid(this._filter, body_id, entity, collider);
+
+    /**
+     * @param {import("../../../physics/ecs/PhysicsSystem.js").PhysicsSystem} physicsSystem the
+     *   world the mover queries; recovery also takes an overlapping body's colliders, each at its
+     *   own world transform, from it ({@link PhysicsSystem#collidersOf})
      * @param {object} [options]
      * @param {number} [options.skin=0.005] clearance left after each
      *   sweep stop / push-out so the next query doesn't start in contact.
@@ -141,9 +175,8 @@ export class KinematicMover {
      *   Source `sv_stepsize` is ~0.34 m; the default is just under the
      *   capsule radius so low ledges don't feel "magnetic".
      */
-    constructor(physicsSystem, ecd, options = {}) {
+    constructor(physicsSystem, options = {}) {
         this.physicsSystem = physicsSystem;
-        this.ecd = ecd;
         this.skin = options.skin !== undefined ? options.skin : 0.005;
         this.maxSlideIterations = options.maxSlideIterations !== undefined ? options.maxSlideIterations : 4;
         this.maxRecoverIterations = options.maxRecoverIterations !== undefined ? options.maxRecoverIterations : 4;
@@ -156,17 +189,38 @@ export class KinematicMover {
      * Resolve one move. Mutates `position` to the resolved location and
      * `velocity` to the corrected value.
      *
-     * @param {Vector3} position in/out — current pose, written to the resolved pose
+     * @param {Vector3|Float64Array} position in/out, `[x, y, z]` — current pose, written to the
+     *   resolved pose. The caller's own array: hand it a body's live translation and the move lands
+     *   in the body as it is resolved
      * @param {ArrayLike<number>} rotation capsule orientation as `[x, y, z, w]` (read) - a
-     *   Quaternion is one, and so is a Transform64's rotation
+     *   Quaternion is one. A Transform64's `rotation` is one too, but its getter builds a new view
+     *   on every read; copy the four components into a retained array instead
      * @param {import("../../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} shape convex capsule
      * @param {Vector3} velocity in/out — desired velocity, written to the corrected velocity
      * @param {number} dt
-     * @param {(entity:number, collider:Collider)=>boolean} filter excludes
-     *   the player's own body in integration; accept-all in isolation
+     * @param {(entity:number, collider:Collider)=>boolean} filter required: which colliders the
+     *   move collides with, asked with the owning body's entity — exclude the moving body's own
+     *   colliders here; pass an accept-all function to collide with everything. Sensors (a
+     *   collider or body flagged IsSensor) are never solid to the mover, whatever this says: the
+     *   capsule passes through a trigger and is never pushed out of one
      * @returns {{hit:boolean, grounded:boolean, groundNormal:Vector3, groundBody:number, groundEntity:number, stepUp:number, landed:boolean, landingSpeed:number}} reused result — see {@link _result} for what each field is for
      */
     move(position, rotation, shape, velocity, dt, filter) {
+        assert.isFunction(filter, 'filter');
+
+        this._filter = filter;
+        const result = this._move(position, rotation, shape, velocity, dt, filter);
+        this._filter = null;
+
+        return result;
+    }
+
+    /**
+     * {@link move}, with {@link _filter} set for the shape casts.
+     * @private
+     */
+    _move(position, rotation, shape, velocity, dt, filter) {
+
         const result = this._result;
         result.hit = false;
         result.grounded = false;
@@ -314,7 +368,11 @@ export class KinematicMover {
         // banned speed coupling: the climb-or-block DECISION is the
         // step-height plane alone; the reach only governs how far ahead we
         // look for the thing the slide already hit.
-        shape.support(this._support, 0, bdx, 0, bdz);
+        const supportDir = this._supportDir;
+        supportDir[0] = bdx;
+        supportDir[1] = 0;
+        supportDir[2] = bdz;
+        shape.support(this._support, 0, supportDir, 0);
         const lead = this._support[0] * bdx + this._support[2] * bdz; // extent toward the wall (capsule radius)
         const ray = this._ray;
         ray.setOrigin(sx, sy + this.stepHeight + this.skin, sz);
@@ -341,7 +399,7 @@ export class KinematicMover {
         // destination is the tell that we climbed onto a wall, not a step.
         const stepProg = (position[0] - sx) * (position[0] - sx) + (position[2] - sz) * (position[2] - sz);
         const heightGain = position[1] - sy;
-        const overlaps = this.physicsSystem.overlap(shape, position, rotation, this._overlapBuf, 0, filter) > 0;
+        const overlaps = this._overlapsSolid(position, rotation, shape, filter);
         if (stepProg > slideProg + 1e-8 && heightGain <= this.stepHeight + this.skin && !overlaps) {
             velocity.set(svx, svy, svz); // restore horizontal; vertical settled by categorize
 
@@ -367,7 +425,7 @@ export class KinematicMover {
         ray.setOrigin(position[0], position[1], position[2]);
         ray.setDirection(dx, dy, dz);
         ray.tMax = maxDist;
-        if (!this.physicsSystem.shapeCast(ray, shape, rotation, this._hit, filter)) return maxDist;
+        if (!this.physicsSystem.shapeCast(ray, shape, rotation, this._hit, this._solidCast)) return maxDist;
         const t = this._hit.t - this.skin;
         return t > 0 ? t : 0;
     }
@@ -396,18 +454,25 @@ export class KinematicMover {
      * cap is hit. Deepest-first converges multi-body resting contact
      * (each pass removes the worst offender) without solving a system.
      *
+     * The query reports BODIES, and a body is every collider attached to it, each at its own world
+     * transform - a compound body's colliders live on child entities, away from the body's pose.
+     * The query stops at the first of a body's colliders it finds overlapping, so the rest are
+     * tested again here, one by one ({@link convex_overlaps_shape}), and the depth is measured only
+     * against those the `filter` accepts AND the capsule overlaps; the body entity's own `Collider`
+     * component, when it has one, is only one of them.
+     *
      * @private
      */
     _recover(position, rotation, shape, filter) {
         const physics = this.physicsSystem;
-        const ecd = this.ecd;
-        const buf = this._overlapBuf;
         const dir = this._penDir;
 
         for (let iter = 0; iter < this.maxRecoverIterations; iter++) {
-            const n = physics.overlap(shape, position, rotation, buf, 0, filter);
+            const n = this._overlapAll(position, rotation, shape, filter);
             if (n === 0) return;
 
+            const buf = this._overlapBuf;
+
             let bestDepth = 0;
             let bestX = 0, bestY = 0, bestZ = 0;
 
@@ -415,19 +480,37 @@ export class KinematicMover {
                 const bodyId = buf[i];
                 const entity = physics.entityOf(bodyId);
                 if (entity < 0) continue;
-                const otherT = ecd.getComponent(entity, Transform64);
-                const otherC = ecd.getComponent(entity, Collider);
-                if (otherT === undefined || otherC === undefined) continue;
-
-                // depth + unit B→A separation (A = our capsule, B = other).
-                const depth = compute_penetration(
-                    dir,
-                    shape, position, rotation,
-                    otherC.shape, otherT.translation, otherT.rotation,
-                );
-                if (depth > bestDepth) {
-                    bestDepth = depth;
-                    bestX = dir[0]; bestY = dir[1]; bestZ = dir[2];
+                const colliders = physics.collidersOf(bodyId);
+
+                const sole = colliders.length === 1;
+
+                for (let k = 0; k < colliders.length; k++) {
+                    const entry = colliders[k];
+                    const collider = entry.collider;
+                    if (!this._isSolid(filter, bodyId, entity, collider)) continue;
+                    const otherPosition = this._otherPosition, otherRotation = this._otherRotation;
+                    this._readPose(entry.transform);
+
+                    // Only a collider the capsule overlaps has a depth to measure. The query
+                    // reported the body on its first overlapping collider; the rest may be
+                    // anywhere, and a depth taken against one the capsule does not touch is a
+                    // push toward something it is not in. A body's sole collider is the one the
+                    // query found overlapping, so it needs no second test.
+                    if (!sole && !convex_overlaps_shape(
+                        shape, position, rotation,
+                        collider.shape, otherPosition, otherRotation,
+                    )) continue;
+
+                    // depth + unit B→A separation (A = our capsule, B = other).
+                    const depth = compute_penetration(
+                        dir,
+                        shape, position, rotation,
+                        collider.shape, otherPosition, otherRotation,
+                    );
+                    if (depth > bestDepth) {
+                        bestDepth = depth;
+                        bestX = dir[0]; bestY = dir[1]; bestZ = dir[2];
+                    }
                 }
             }
 
@@ -440,6 +523,95 @@ export class KinematicMover {
         }
     }
 
+    /**
+     * Whether a collider is something the capsule collides with: not a sensor — a trigger is not a
+     * solid surface, by its own flag or its body's ({@link is_sensor}) — and accepted by the move's
+     * `filter`. The raycast already passes through sensors by itself; the shape cast and the overlap
+     * query report them, and other callers may want them reported, so the mover drops them here.
+     *
+     * @private
+     * @param {(entity:number, collider:Collider)=>boolean} filter
+     * @param {number} body_id the body the collider belongs to
+     * @param {number} entity that body's entity
+     * @param {Collider} collider
+     * @returns {boolean}
+     */
+    _isSolid(filter, body_id, entity, collider) {
+        const body = this.physicsSystem.bodyOf(body_id);
+        if (body === undefined || is_sensor(body, collider)) return false;
+        return filter(entity, collider);
+    }
+
+    /**
+     * Whether the shape overlaps any solid collider ({@link _isSolid}), each collider of an
+     * overlapping body tested on its own.
+     *
+     * @private
+     * @returns {boolean}
+     */
+    _overlapsSolid(position, rotation, shape, filter) {
+        const physics = this.physicsSystem;
+        const n = this._overlapAll(position, rotation, shape, filter);
+        const buf = this._overlapBuf;
+
+        for (let i = 0; i < n; i++) {
+            const bodyId = buf[i];
+            const entity = physics.entityOf(bodyId);
+            if (entity < 0) continue;
+            const colliders = physics.collidersOf(bodyId);
+            const sole = colliders.length === 1;
+
+            for (let k = 0; k < colliders.length; k++) {
+                const entry = colliders[k];
+                if (!this._isSolid(filter, bodyId, entity, entry.collider)) continue;
+                // a body's sole collider is the one the query found overlapping
+                if (sole) return true;
+                this._readPose(entry.transform);
+                if (convex_overlaps_shape(shape, position, rotation, entry.collider.shape, this._otherPosition, this._otherRotation)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Copy a collider's world pose into {@link _otherPosition} / {@link _otherRotation}. A
+     * Transform64's `translation` and `rotation` getters build a new view on every read; recovery
+     * reads one pose per collider per pass, and that was the allocation it made.
+     *
+     * @private
+     * @param {import("../../../ecs/transform/Transform64.js").Transform64} transform
+     */
+    _readPose(transform) {
+        const p = this._otherPosition, q = this._otherRotation;
+        p[0] = transform.translation_x;
+        p[1] = transform.translation_y;
+        p[2] = transform.translation_z;
+        q[0] = transform.rotation_x;
+        q[1] = transform.rotation_y;
+        q[2] = transform.rotation_z;
+        q[3] = transform.rotation_w;
+    }
+
+    /**
+     * Every body the shape overlaps, into {@link _overlapBuf}; returns the count. The query caps
+     * its count at the buffer's capacity and drops the rest silently, so a full buffer is grown
+     * (doubled) and the query run again until the count fits.
+     *
+     * @private
+     * @returns {number}
+     */
+    _overlapAll(position, rotation, shape, filter) {
+        for (; ;) {
+            const buf = this._overlapBuf;
+            const n = this.physicsSystem.overlap(shape, position, rotation, buf, 0, filter);
+            if (n < buf.length) return n;
+            this._overlapBuf = new Uint32Array(buf.length * 2);
+        }
+    }
+
     /**
      * Unified 3D collide-and-slide. Faithful to Quake's `SV_FlyMove`:
      * sweep the velocity for the remaining time, stop at contact, clip
@@ -478,7 +650,7 @@ export class KinematicMover {
             ray.setDirection(ndx, ndy, ndz);
             ray.tMax = len;
 
-            const didHit = physics.shapeCast(ray, shape, rotation, hit, filter);
+            const didHit = physics.shapeCast(ray, shape, rotation, hit, this._solidCast);
 
             if (!didHit) {
                 // Clear path — consume the whole remaining move.
@@ -655,7 +827,7 @@ export class KinematicMover {
         ray.setOrigin(position[0], position[1] + lift, position[2]);
         ray.setDirection(0, -1, 0);
         ray.tMax = reach;
-        if (this.physicsSystem.shapeCast(ray, shape, rotation, hit, filter) && hit.t > this.skin) {
+        if (this.physicsSystem.shapeCast(ray, shape, rotation, hit, this._solidCast) && hit.t > this.skin) {
             const stepY = position[1] + lift - hit.t;
             // With a centre surface the centre ray already vouched for
             // walkability, so mount any step. With NONE, the footprint is the
@@ -685,8 +857,17 @@ export class KinematicMover {
         result.groundEntity = hit.entity;
 
         // Stick: rest the feet `skin` above the surface (snaps down for a
-        // descent, up onto a step / out of a grazing contact).
-        position[1] = surfaceY + this.skin;
+        // descent, up onto a step / out of a grazing contact). A body already
+        // resting there, to within what the probes can tell, is left exactly
+        // where it is: they re-derive the height on every move and land a few
+        // 1e-8 m either side of the last answer, and a body moved by that much
+        // on every move never holds still. Driven by a target pose, it carries
+        // that as a velocity, and a support with any velocity at all keeps what
+        // rests on it awake.
+        const rest = surfaceY + this.skin;
+        if (Math.abs(rest - position[1]) > REST_TOLERANCE) {
+            position[1] = rest;
+        }
 
         // Clip the into-ground velocity component (gravity on flat ground;
         // the into-slope part on a ramp), leaving tangential motion.

package/src/engine/control/first-person/sensors/FirstPersonSensorsSystem.d.ts

@@ -64,6 +64,10 @@ export class FirstPersonSensorsSystem extends System<any> {
      * standing capsule. A miss (or a much-lower hit) means the surface dropped
      * away: a thin wall / lip you can only hang from, not stand on.
      * @private
+     * @param {number} px
+     * @param {number} edgeY
+     * @param {number} pz
+     * @param {(entity:number)=>boolean} filter leaves out the player's own body
      */
     private _probeStandable;
     /**
@@ -77,6 +81,7 @@ export class FirstPersonSensorsSystem extends System<any> {
      * will replace this with the true shape normal at the same call site.
      *
      * @private
+     * @param {(entity:number)=>boolean} filter leaves out the player's own body
      */
     private _probeRay;
 }

package/src/engine/control/first-person/sensors/FirstPersonSensorsSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonSensorsSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/sensors/FirstPersonSensorsSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;IACI,0EAA0D;IAE1D;;;;;OAKG;IACH,kBAFU,iCAAiC,GAAC,IAAI,CAExB;IAExB;;;;;OAKG;IACH,eAFU,aAAa,GAAC,IAAI,CAEP;IAErB;;;;;;OAMG;IACH,mBAAwB;IAExB;;;;;;OAMG;IACH,mBAAuC;IAEvC,2CAaC;IAED,2BAIC;IAED;;OAEG;IACH,2BAsFC;IAED;;;;;;OAMG;IACH,wBASC;IAED;;;;;;;;;;;OAWG;IACH,kBAiBC;CACJ;uBA/NsB,wBAAwB;4BACnB,uCAAuC;4CACvB,mCAAmC;kDAC7B,yCAAyC;8BAL7D,uCAAuC"}
+{"version":3,"file":"FirstPersonSensorsSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/sensors/FirstPersonSensorsSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;IACI,0EAA0D;IAE1D;;;;;OAKG;IACH,kBAFU,iCAAiC,GAAC,IAAI,CAExB;IAExB;;;;;OAKG;IACH,eAFU,aAAa,GAAC,IAAI,CAEP;IAErB;;;;;;OAMG;IACH,mBAAwB;IAExB;;;;;;OAMG;IACH,mBAAuC;IAEvC,2CAaC;IAED,2BAIC;IAED;;OAEG;IACH,2BA0FC;IAED;;;;;;;;;;OAUG;IACH,wBAQC;IAED;;;;;;;;;;;;OAYG;IACH,kBAgBC;CACJ;uBAtOsB,wBAAwB;4BACnB,uCAAuC;4CACvB,mCAAmC;kDAC7B,yCAAyC;8BAL7D,uCAAuC"}

package/src/engine/control/first-person/sensors/FirstPersonSensorsSystem.js

@@ -135,16 +135,20 @@ export class FirstPersonSensorsSystem extends System {
         const wallProbeDist = cfg.body.radius * 2 + 0.05; // just past the capsule
         const obstacleProbeDist = 1.2; // ~one stride
 
+        // Every collider of the player's own body is left out; the controller made the filter at
+        // link, so a probe allocates no closure.
+        const notSelf = runtime.notSelf;
+
         // Wall left: probe along -right.
-        this._probeRay(sensors.wallLeft, ox, oy, oz, -rx, 0, -rz, wallProbeDist, entity);
+        this._probeRay(sensors.wallLeft, ox, oy, oz, -rx, 0, -rz, wallProbeDist, notSelf);
         // Wall right: probe along +right.
-        this._probeRay(sensors.wallRight, ox, oy, oz, rx, 0, rz, wallProbeDist, entity);
+        this._probeRay(sensors.wallRight, ox, oy, oz, rx, 0, rz, wallProbeDist, notSelf);
         // Wall front: probe along +forward.
-        this._probeRay(sensors.wallFront, ox, oy, oz, fx, 0, fz, wallProbeDist, entity);
+        this._probeRay(sensors.wallFront, ox, oy, oz, fx, 0, fz, wallProbeDist, notSelf);
         // Obstacle ahead: same direction as wallFront but longer reach.
         // Used by mantle/vault; the consumer compares the hit altitude to
         // the body height to decide vault vs. mantle vs. neither.
-        this._probeRay(sensors.obstacleAhead, ox, oy, oz, fx, 0, fz, obstacleProbeDist, entity);
+        this._probeRay(sensors.obstacleAhead, ox, oy, oz, fx, 0, fz, obstacleProbeDist, notSelf);
 
         // Ledge ahead — only meaningful if obstacleAhead hit something
         // around chest height: probe down from just past the top of the
@@ -158,7 +162,7 @@ export class FirstPersonSensorsSystem extends System {
                 px, topY, pz,
                 0, -1, 0,
                 cfg.body.height * 0.5,
-                entity,
+                notSelf,
             );
         }
 
@@ -173,7 +177,7 @@ export class FirstPersonSensorsSystem extends System {
                 sensors.ledgeAhead.point[0] + fx * reach,
                 sensors.ledgeAhead.point[1],
                 sensors.ledgeAhead.point[2] + fz * reach,
-                entity,
+                notSelf,
             );
         }
     }
@@ -184,13 +188,16 @@ export class FirstPersonSensorsSystem extends System {
      * standing capsule. A miss (or a much-lower hit) means the surface dropped
      * away: a thin wall / lip you can only hang from, not stand on.
      * @private
+     * @param {number} px
+     * @param {number} edgeY
+     * @param {number} pz
+     * @param {(entity:number)=>boolean} filter leaves out the player's own body
      */
-    _probeStandable(px, edgeY, pz, excludeEntity) {
+    _probeStandable(px, edgeY, pz, filter) {
         const ray = this._probe_ray;
         ray.setOrigin(px, edgeY + 0.2, pz);
         ray.setDirection(0, -1, 0);
         ray.tMax = 0.4;
-        const filter = (e) => e !== excludeEntity;
         const out = this._probe_hit;
         if (!this.physicsSystem.raycast(ray, out, filter)) return false;
         return out.position[1] > edgeY - 0.15; // surface still up near the edge height
@@ -207,8 +214,9 @@ export class FirstPersonSensorsSystem extends System {
      * will replace this with the true shape normal at the same call site.
      *
      * @private
+     * @param {(entity:number)=>boolean} filter leaves out the player's own body
      */
-    _probeRay(slot, ox, oy, oz, dx, dy, dz, maxDist, excludeEntity) {
+    _probeRay(slot, ox, oy, oz, dx, dy, dz, maxDist, filter) {
         // Exclude the player's own body from the result — downward
         // probes from chest start inside the capsule, would otherwise
         // hit the capsule's bottom hemisphere.
@@ -216,7 +224,6 @@ export class FirstPersonSensorsSystem extends System {
         ray.setOrigin(ox, oy, oz);
         ray.setDirection(dx, dy, dz);
         ray.tMax = maxDist;
-        const filter = (e) => e !== excludeEntity;
         const out = this._probe_hit;
         if (!this.physicsSystem.raycast(ray, out, filter)) return;
 

package/src/engine/ecs/EntityComponentDataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityComponentDataset.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityComponentDataset.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"EntityComponentDataset.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityComponentDataset.js"],"names":[],"mappings":"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"}

package/src/engine/ecs/EntityComponentDataset.js

@@ -21,6 +21,19 @@ import { EventType } from "./EventType.js";
  * @typedef {import("./EntityObserver.js").EntityObserver} EntityObserver
  */
 
+/**
+ * Throw an assertion's message, built from the values it checks. Written
+ * `assert.ok(condition || assertion_failed(`... ${value} ...`))`, the template is evaluated only once
+ * the condition has failed. As `assert.ok`'s second argument it was built on every call that passed:
+ * on {@link EntityComponentDataset#getComponent}, every call any system makes. It is only ever
+ * reached from inside an `assert.*` argument, so a consumer that strips the assert strips it too.
+ * @param {string} message
+ * @returns {never}
+ */
+function assertion_failed(message) {
+    throw new Error(message);
+}
+
 /**
  *
  * @param {number} entityIndex
@@ -257,7 +270,7 @@ export class EntityComponentDataset {
      */
     promiseComponent(entity, component_type) {
 
-        assert.ok(this.entityExists(entity), `Entity ${entity} doesn't exist`);
+        assert.ok(this.entityExists(entity) || assertion_failed(`Entity ${entity} doesn't exist`));
 
         const self = this;
         return new Promise(function (resolve, reject) {
@@ -440,7 +453,7 @@ export class EntityComponentDataset {
      * @returns {Array}
      */
     getComponents(entity, component_classes) {
-        assert.ok(this.entityExists(entity), `Entity ${entity} doesn't exist`);
+        assert.ok(this.entityExists(entity) || assertion_failed(`Entity ${entity} doesn't exist`));
 
         assert.notNull(component_classes, "component_classes");
         assert.defined(component_classes, "component_classes");
@@ -488,7 +501,7 @@ export class EntityComponentDataset {
     ) {
 
         assert.isNonNegativeInteger(entity_id, 'entity_id');
-        assert.ok(this.entityExists(entity_id), `Entity ${entity_id} doesn't exist`);
+        assert.ok(this.entityExists(entity_id) || assertion_failed(`Entity ${entity_id} doesn't exist`));
         assert.isArray(output, "output");
         assert.isNonNegativeInteger(output_offset, 'output_offset');
 
@@ -526,7 +539,7 @@ export class EntityComponentDataset {
      */
     getAllComponents(entity_id) {
         assert.isNonNegativeInteger(entity_id, 'entity_id');
-        assert.ok(this.entityExists(entity_id), `Entity ${entity_id} doesn't exist`);
+        assert.ok(this.entityExists(entity_id) || assertion_failed(`Entity ${entity_id} doesn't exist`));
 
         const ret = [];
 
@@ -934,7 +947,7 @@ export class EntityComponentDataset {
      */
     getEntityGeneration(entity_id) {
         assert.isNonNegativeInteger(entity_id, 'entity_id');
-        assert.ok(this.entityExists(entity_id), `Entity ${entity_id} does not exist`);
+        assert.ok(this.entityExists(entity_id) || assertion_failed(`Entity ${entity_id} does not exist`));
 
         return this.entityGeneration[entity_id];
     }
@@ -1093,8 +1106,8 @@ export class EntityComponentDataset {
      * @returns {void}
      */
     removeComponentFromEntityByIndex(entity_id, component_index) {
-        assert.ok(this.entityExists(entity_id), `entity ${entity_id} does not exist`);
-        assert.ok(this.componentIndexExists(component_index), `componentIndex ${component_index} is out of bounds`);
+        assert.ok(this.entityExists(entity_id) || assertion_failed(`entity ${entity_id} does not exist`));
+        assert.ok(this.componentIndexExists(component_index) || assertion_failed(`componentIndex ${component_index} is out of bounds`));
 
         //check if component exists
         const componentOccupancyIndex = entity_id * this.componentTypeCount + component_index;
@@ -1243,12 +1256,13 @@ export class EntityComponentDataset {
      */
     addComponentToEntityByIndex(entity_id, component_index, component_instance) {
 
-        assert.ok(this.entityExists(entity_id), `entity ${entity_id} does not exist`);
-        assert.ok(this.componentIndexExists(component_index), `component_index ${component_index} is out of bounds`);
+        assert.ok(this.entityExists(entity_id) || assertion_failed(`entity ${entity_id} does not exist`));
+        assert.ok(this.componentIndexExists(component_index) || assertion_failed(`component_index ${component_index} is out of bounds`));
 
         assert.defined(component_instance, "component_instance");
 
-        assert.equal(this.getComponentByIndex(entity_id, component_index), undefined, `entity ${entity_id} already has component ${component_index}`);
+        assert.ok(this.getComponentByIndex(entity_id, component_index) === undefined
+            || assertion_failed(`entity ${entity_id} already has component ${component_index}. ${this.getComponentByIndex(entity_id, component_index)} !== undefined`));
 
 
         const componentOccupancyIndex = entity_id * this.componentTypeCount + component_index;
@@ -1287,8 +1301,8 @@ export class EntityComponentDataset {
      */
     getComponentByIndex(entity_id, component_index) {
 
-        assert.ok(this.entityExists(entity_id), `entity ${entity_id} does not exist`);
-        assert.ok(this.componentIndexExists(component_index), `component_index ${component_index} is out of bounds`);
+        assert.ok(this.entityExists(entity_id) || assertion_failed(`entity ${entity_id} does not exist`));
+        assert.ok(this.componentIndexExists(component_index) || assertion_failed(`component_index ${component_index} is out of bounds`));
 
 
         return this.components[component_index][entity_id];
@@ -1313,7 +1327,7 @@ export class EntityComponentDataset {
      */
     getComponent(entity_id, klass) {
         assert.isNonNegativeInteger(entity_id, 'entity_id');
-        assert.ok(this.entityExists(entity_id), `entity ${entity_id} does not exist`);
+        assert.ok(this.entityExists(entity_id) || assertion_failed(`entity ${entity_id} does not exist`));
         assert.defined(klass, "klass");
 
         const componentIndex = this.computeComponentTypeIndex(klass);

package/src/engine/ecs/storage/populateEngineSerializationRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAgLA;;;;;;;;GAQG;AACH,iGA0GC"}
+{"version":3,"file":"populateEngineSerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/storage/populateEngineSerializationRegistry.js"],"names":[],"mappings":"AAoLA;;;;;;;;GAQG;AACH,iGA8GC"}