@woosh/meep-engine 2.138.19 → 2.139.0

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

@@ -0,0 +1,58 @@
+/**
+ * Single spatial-query result. Set fields when `hit` is true; ignore them
+ * otherwise. `surfaceTag` is optional — populated by future surface-tag
+ * systems (grass/wood/metal/etc.) so abilities and audio can react to the
+ * material.
+ */
+export class SensorHit {
+    hit: boolean;
+    /** Distance from query origin to contact point (meters). */
+    distance: number;
+    /** World-space contact point. */
+    point: Vector3;
+    /** Surface normal at contact (unit vector, points away from surface). */
+    normal: Vector3;
+    /** Optional material/surface tag — e.g. "grass", "metal". */
+    surfaceTag: any;
+    /** Reset to "no hit" — call before re-using the slot each tick. */
+    clear(): void;
+}
+/**
+ * Cached spatial-query results for one first-person controller. Populated
+ * by {@link FirstPersonSensorsSystem} once per fixed step, read by
+ * abilities and (where useful) by the base controller.
+ *
+ * The point of cacheing is dedup: mantle and ledge-grab both want a
+ * "forward + up obstacle probe". Compute once, both read the cached hit.
+ *
+ * Sensor slots cleared each tick before population. Abilities should
+ * treat any `hit === false` slot as "absent" — never read distance/point
+ * when hit is false (they're stale or zero, depending on clear-mode).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FirstPersonSensors {
+    /** Wall to the body-local left, probed at chest height. */
+    wallLeft: SensorHit;
+    /** Wall to the body-local right, probed at chest height. */
+    wallRight: SensorHit;
+    /** Wall directly in front of the body. */
+    wallFront: SensorHit;
+    /**
+     * Obstacle ahead at chest/waist height — used by mantle/vault.
+     * Distance is along the body's forward direction; normal is the
+     * face of the obstacle the player is approaching.
+     */
+    obstacleAhead: SensorHit;
+    /**
+     * Ledge edge ahead — for ledge grab. Populated when the forward
+     * obstacle probe hits and a downward probe just past the
+     * obstacle's top finds empty space, indicating a grabbable edge.
+     */
+    ledgeAhead: SensorHit;
+    /** Clear all sensor slots — call at the start of each tick. */
+    clearAll(): void;
+}
+import Vector3 from "../../../../core/geom/Vector3.js";
+//# sourceMappingURL=FirstPersonSensors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FirstPersonSensors.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/sensors/FirstPersonSensors.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IAEQ,aAAgB;IAChB,4DAA4D;IAC5D,iBAAiB;IACjB,iCAAiC;IACjC,eAA0B;IAC1B,yEAAyE;IACzE,gBAAkC;IAClC,6DAA6D;IAC7D,gBAAsB;IAG1B,mEAAmE;IACnE,cAMC;CACJ;AAED;;;;;;;;;;;;;;GAcG;AACH;IAEQ,2DAA2D;IAC3D,oBAA+B;IAC/B,4DAA4D;IAC5D,qBAAgC;IAChC,0CAA0C;IAC1C,qBAAgC;IAChC;;;;OAIG;IACH,yBAAoC;IACpC;;;;OAIG;IACH,sBAAiC;IAGrC,+DAA+D;IAC/D,iBAMC;CACJ;oBA5EmB,kCAAkC"}

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

@@ -0,0 +1,77 @@
+import Vector3 from "../../../../core/geom/Vector3.js";
+
+/**
+ * Single spatial-query result. Set fields when `hit` is true; ignore them
+ * otherwise. `surfaceTag` is optional — populated by future surface-tag
+ * systems (grass/wood/metal/etc.) so abilities and audio can react to the
+ * material.
+ */
+export class SensorHit {
+    constructor() {
+        this.hit = false;
+        /** Distance from query origin to contact point (meters). */
+        this.distance = 0;
+        /** World-space contact point. */
+        this.point = new Vector3();
+        /** Surface normal at contact (unit vector, points away from surface). */
+        this.normal = new Vector3(0, 1, 0);
+        /** Optional material/surface tag — e.g. "grass", "metal". */
+        this.surfaceTag = null;
+    }
+
+    /** Reset to "no hit" — call before re-using the slot each tick. */
+    clear() {
+        this.hit = false;
+        this.distance = 0;
+        this.point.set(0, 0, 0);
+        this.normal.set(0, 1, 0);
+        this.surfaceTag = null;
+    }
+}
+
+/**
+ * Cached spatial-query results for one first-person controller. Populated
+ * by {@link FirstPersonSensorsSystem} once per fixed step, read by
+ * abilities and (where useful) by the base controller.
+ *
+ * The point of cacheing is dedup: mantle and ledge-grab both want a
+ * "forward + up obstacle probe". Compute once, both read the cached hit.
+ *
+ * Sensor slots cleared each tick before population. Abilities should
+ * treat any `hit === false` slot as "absent" — never read distance/point
+ * when hit is false (they're stale or zero, depending on clear-mode).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FirstPersonSensors {
+    constructor() {
+        /** Wall to the body-local left, probed at chest height. */
+        this.wallLeft = new SensorHit();
+        /** Wall to the body-local right, probed at chest height. */
+        this.wallRight = new SensorHit();
+        /** Wall directly in front of the body. */
+        this.wallFront = new SensorHit();
+        /**
+         * Obstacle ahead at chest/waist height — used by mantle/vault.
+         * Distance is along the body's forward direction; normal is the
+         * face of the obstacle the player is approaching.
+         */
+        this.obstacleAhead = new SensorHit();
+        /**
+         * Ledge edge ahead — for ledge grab. Populated when the forward
+         * obstacle probe hits and a downward probe just past the
+         * obstacle's top finds empty space, indicating a grabbable edge.
+         */
+        this.ledgeAhead = new SensorHit();
+    }
+
+    /** Clear all sensor slots — call at the start of each tick. */
+    clearAll() {
+        this.wallLeft.clear();
+        this.wallRight.clear();
+        this.wallFront.clear();
+        this.obstacleAhead.clear();
+        this.ledgeAhead.clear();
+    }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Populates the {@link FirstPersonSensors} struct on each controller
+ * entity, once per fixed step. Designed to run BEFORE the main
+ * {@link FirstPersonPlayerControllerSystem} `fixedUpdate` so abilities
+ * see fresh sensor data on the same tick.
+ *
+ * Raycasts go through {@link PhysicsSystem.raycast} — BVH-backed,
+ * static + dynamic broadphase. The player's own body is excluded via a
+ * per-call filter so downward probes don't collide with the player's
+ * own capsule.
+ *
+ * BVH raycasts are cheap (~1000/frame at 60Hz is comfortable), so this
+ * system doesn't aggressively optimize. NPC controllers that don't
+ * need sensors can simply not have this system attached.
+ *
+ * Sensor data lives at `runtime.sensors` on the
+ * {@link FirstPersonPlayerControllerSystem}'s per-entity runtime.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FirstPersonSensorsSystem extends System<any, any, any, any, any> {
+    constructor();
+    dependencies: (typeof Transform | typeof FirstPersonPlayerController)[];
+    /**
+     * Reference to the controller system — needed to look up each
+     * entity's per-controller runtime (which owns the sensors slot).
+     * Auto-acquired in startup; can be overridden by the caller.
+     * @type {FirstPersonPlayerControllerSystem|null}
+     */
+    controllerSystem: FirstPersonPlayerControllerSystem | null;
+    /**
+     * Physics system used as the spatial-query backend. Auto-acquired
+     * in startup; can be overridden. Required — sensors are unusable
+     * without it.
+     * @type {PhysicsSystem|null}
+     */
+    physicsSystem: PhysicsSystem | null;
+    /**
+     * Pre-allocated raycast query primitive. Refilled in place per
+     * {@link _probeRay} call so the system doesn't allocate a new
+     * `Ray3` every probe.
+     * @private
+     * @type {Ray3}
+     */
+    private _probe_ray;
+    /**
+     * Pre-allocated raycast result. Refilled in place per probe;
+     * gameplay-visible sensor fields are copied out before the next
+     * probe overwrites it.
+     * @private
+     * @type {PhysicsSurfacePoint}
+     */
+    private _probe_hit;
+    startup(entityManager: any): Promise<void>;
+    fixedUpdate(dt: any): void;
+    /**
+     * @private
+     */
+    private _populateForEntity;
+    /**
+     * Raycast through {@link PhysicsSystem.raycast}, populating the slot
+     * if anything is hit. Direction is assumed unit (the controller's
+     * callers pass body-local unit axes).
+     *
+     * The raycast now writes the AABB face normal into `_probe_hit.normal`,
+     * which is exact for AABB-shaped colliders (the common case in our gym)
+     * and a stable approximation elsewhere. Future narrowphase refinement
+     * will replace this with the true shape normal at the same call site.
+     *
+     * @private
+     */
+    private _probeRay;
+}
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { FirstPersonPlayerController } from "../FirstPersonPlayerController.js";
+import { FirstPersonPlayerControllerSystem } from "../FirstPersonPlayerControllerSystem.js";
+import { PhysicsSystem } from "../../../physics/ecs/PhysicsSystem.js";
+//# sourceMappingURL=FirstPersonSensorsSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FirstPersonSensorsSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/sensors/FirstPersonSensorsSystem.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IACI,cAsCC;IAnCG,wEAA4D;IAE5D;;;;;OAKG;IACH,kBAFU,iCAAiC,GAAC,IAAI,CAEpB;IAE5B;;;;;OAKG;IACH,eAFU,aAAa,GAAC,IAAI,CAEH;IAEzB;;;;;;OAMG;IACH,mBAA4B;IAE5B;;;;;;OAMG;IACH,mBAA2C;IAG/C,2CAaC;IAED,2BAIC;IAED;;OAEG;IACH,2BAoEC;IAED;;;;;;;;;;;OAWG;IACH,kBAiBC;CACJ;uBA/LsB,wBAAwB;0BACrB,qCAAqC;4CACnB,mCAAmC;kDAC7B,yCAAyC;8BAL7D,uCAAuC"}

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

@@ -0,0 +1,196 @@
+import { assert } from "../../../../core/assert.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { PhysicsSystem } from "../../../physics/ecs/PhysicsSystem.js";
+import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { FirstPersonPlayerController } from "../FirstPersonPlayerController.js";
+import { FirstPersonPlayerControllerSystem } from "../FirstPersonPlayerControllerSystem.js";
+
+/**
+ * Populates the {@link FirstPersonSensors} struct on each controller
+ * entity, once per fixed step. Designed to run BEFORE the main
+ * {@link FirstPersonPlayerControllerSystem} `fixedUpdate` so abilities
+ * see fresh sensor data on the same tick.
+ *
+ * Raycasts go through {@link PhysicsSystem.raycast} — BVH-backed,
+ * static + dynamic broadphase. The player's own body is excluded via a
+ * per-call filter so downward probes don't collide with the player's
+ * own capsule.
+ *
+ * BVH raycasts are cheap (~1000/frame at 60Hz is comfortable), so this
+ * system doesn't aggressively optimize. NPC controllers that don't
+ * need sensors can simply not have this system attached.
+ *
+ * Sensor data lives at `runtime.sensors` on the
+ * {@link FirstPersonPlayerControllerSystem}'s per-entity runtime.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FirstPersonSensorsSystem extends System {
+    constructor() {
+        super();
+
+        this.dependencies = [FirstPersonPlayerController, Transform];
+
+        /**
+         * Reference to the controller system — needed to look up each
+         * entity's per-controller runtime (which owns the sensors slot).
+         * Auto-acquired in startup; can be overridden by the caller.
+         * @type {FirstPersonPlayerControllerSystem|null}
+         */
+        this.controllerSystem = null;
+
+        /**
+         * Physics system used as the spatial-query backend. Auto-acquired
+         * in startup; can be overridden. Required — sensors are unusable
+         * without it.
+         * @type {PhysicsSystem|null}
+         */
+        this.physicsSystem = null;
+
+        /**
+         * Pre-allocated raycast query primitive. Refilled in place per
+         * {@link _probeRay} call so the system doesn't allocate a new
+         * `Ray3` every probe.
+         * @private
+         * @type {Ray3}
+         */
+        this._probe_ray = new Ray3();
+
+        /**
+         * Pre-allocated raycast result. Refilled in place per probe;
+         * gameplay-visible sensor fields are copied out before the next
+         * probe overwrites it.
+         * @private
+         * @type {PhysicsSurfacePoint}
+         */
+        this._probe_hit = new PhysicsSurfacePoint();
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        // Auto-acquire collaborators if they're already in the world.
+        // Caller can still override either field before fixedUpdate runs.
+        if (this.controllerSystem === null) {
+            const cs = entityManager.getSystem(FirstPersonPlayerControllerSystem);
+            if (cs !== null) this.controllerSystem = cs;
+        }
+        if (this.physicsSystem === null) {
+            const ps = entityManager.getSystem(PhysicsSystem);
+            if (ps !== null) this.physicsSystem = ps;
+        }
+    }
+
+    fixedUpdate(dt) {
+        const ecd = this.entityManager.dataset;
+        if (ecd === null) return;
+        ecd.traverseComponents(FirstPersonPlayerController, this._populateForEntity, this);
+    }
+
+    /**
+     * @private
+     */
+    _populateForEntity(controller, entity) {
+        // Sensors live on the per-entity runtime owned by the
+        // controller's own system. Look it up by entity — no leakage
+        // through the controller component itself.
+        if (this.controllerSystem === null) return; // not wired up
+        const runtime = this.controllerSystem.getRuntime(entity);
+        if (runtime === undefined) return;
+        const sensors = runtime.sensors;
+        if (sensors === undefined || sensors === null) return;
+
+        // Sensors are useless without physics. Assert at the first
+        // populate; the misconfiguration would otherwise show up as
+        // mysteriously inert abilities.
+        assert.notEqual(this.physicsSystem, null,
+            "FirstPersonSensorsSystem requires a PhysicsSystem to be in the world. "
+            + "Add it before this system, or set `sensorsSystem.physicsSystem` "
+            + "explicitly.");
+
+        const ecd = this.entityManager.dataset;
+        const transform = ecd.getComponent(entity, Transform);
+        if (transform === undefined) return;
+
+        sensors.clearAll();
+
+        // Probe origin: at chest height (approx body height × 0.65).
+        const cfg = controller.config;
+        const chestY = cfg.body.height * 0.65;
+        const ox = transform.position.x;
+        const oy = transform.position.y + chestY;
+        const oz = transform.position.z;
+
+        // Body-local forward + right (engine-local axes — see DESIGN.md
+        // §5.3 for the conventions). bodyYaw lives on the runtime.
+        const yaw = runtime.bodyYaw;
+        const fx = Math.sin(yaw);
+        const fz = Math.cos(yaw);
+        const rx = Math.cos(yaw);
+        const rz = -Math.sin(yaw);
+
+        const wallProbeDist = cfg.body.radius * 2 + 0.05; // just past the capsule
+        const obstacleProbeDist = 1.2; // ~one stride
+
+        // Wall left: probe along -right.
+        this._probeRay(sensors.wallLeft, ox, oy, oz, -rx, 0, -rz, wallProbeDist, entity);
+        // Wall right: probe along +right.
+        this._probeRay(sensors.wallRight, ox, oy, oz, rx, 0, rz, wallProbeDist, entity);
+        // Wall front: probe along +forward.
+        this._probeRay(sensors.wallFront, ox, oy, oz, fx, 0, fz, wallProbeDist, entity);
+        // 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);
+
+        // Ledge ahead — only meaningful if obstacleAhead hit something
+        // around chest height: probe down from just past the top of the
+        // obstacle, look for ground.
+        if (sensors.obstacleAhead.hit) {
+            const topY = transform.position.y + cfg.body.height + 0.1;
+            const px = sensors.obstacleAhead.point.x + fx * 0.3;
+            const pz = sensors.obstacleAhead.point.z + fz * 0.3;
+            this._probeRay(
+                sensors.ledgeAhead,
+                px, topY, pz,
+                0, -1, 0,
+                cfg.body.height * 0.5,
+                entity,
+            );
+        }
+    }
+
+    /**
+     * Raycast through {@link PhysicsSystem.raycast}, populating the slot
+     * if anything is hit. Direction is assumed unit (the controller's
+     * callers pass body-local unit axes).
+     *
+     * The raycast now writes the AABB face normal into `_probe_hit.normal`,
+     * which is exact for AABB-shaped colliders (the common case in our gym)
+     * and a stable approximation elsewhere. Future narrowphase refinement
+     * will replace this with the true shape normal at the same call site.
+     *
+     * @private
+     */
+    _probeRay(slot, ox, oy, oz, dx, dy, dz, maxDist, excludeEntity) {
+        // 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.
+        const ray = this._probe_ray;
+        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;
+
+        slot.hit = true;
+        slot.distance = out.t;
+        slot.point.set(out.position.x, out.position.y, out.position.z);
+        slot.normal.set(out.normal.x, out.normal.y, out.normal.z);
+        slot.surfaceTag = null; // future: surface-tag lookup
+    }
+}

package/src/engine/control/first-person/test/buildTestPlayer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Spec-side helper: build the RigidBody + Collider pair the controller's
+ * link() expects. Each test's makeWorld() can call this after
+ * constructing the controller + transform, adding both components to
+ * the entity builder before `.build(ecd)`.
+ *
+ * Capsule dimensions are loose — the prototype sizes them from
+ * `cfg.body` but tests don't exercise the actual collision shape; what
+ * matters for the controller's assert is that a RigidBody of the right
+ * kind is present.
+ *
+ * @returns {{ rigidBody: RigidBody, collider: Collider }}
+ */
+export function buildTestPlayerBody(): {
+    rigidBody: RigidBody;
+    collider: Collider;
+};
+import { RigidBody } from "../../../physics/ecs/RigidBody.js";
+import { Collider } from "../../../physics/ecs/Collider.js";
+//# sourceMappingURL=buildTestPlayer.d.ts.map

package/src/engine/control/first-person/test/buildTestPlayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildTestPlayer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/test/buildTestPlayer.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH;eAF0B,SAAS;cAAY,QAAQ;EAWtD;0BAxByB,mCAAmC;yBADpC,kCAAkC"}

package/src/engine/control/first-person/test/buildTestPlayer.js

@@ -0,0 +1,28 @@
+import { CapsuleShape3D } from "../../../../core/geom/3d/shape/CapsuleShape3D.js";
+import { BodyKind } from "../../../physics/ecs/BodyKind.js";
+import { Collider } from "../../../physics/ecs/Collider.js";
+import { RigidBody } from "../../../physics/ecs/RigidBody.js";
+
+/**
+ * Spec-side helper: build the RigidBody + Collider pair the controller's
+ * link() expects. Each test's makeWorld() can call this after
+ * constructing the controller + transform, adding both components to
+ * the entity builder before `.build(ecd)`.
+ *
+ * Capsule dimensions are loose — the prototype sizes them from
+ * `cfg.body` but tests don't exercise the actual collision shape; what
+ * matters for the controller's assert is that a RigidBody of the right
+ * kind is present.
+ *
+ * @returns {{ rigidBody: RigidBody, collider: Collider }}
+ */
+export function buildTestPlayerBody() {
+    const rigidBody = new RigidBody();
+    rigidBody.kind = BodyKind.KinematicPosition;
+    rigidBody.mass = 1;
+
+    const collider = new Collider();
+    collider.shape = CapsuleShape3D.from(0.34, 1.12);
+
+    return { rigidBody, collider };
+}

package/src/engine/ecs/EntityManager.d.ts

@@ -157,9 +157,9 @@ export class EntityManager {
     getComponentClassByName<T_2>(className: string): null | Class<T_2>;
     /**
      * Advance simulation forward by a specified amount of time
-     * @param {number} timeDelta in seconds
+     * @param {number} time_delta_seconds in seconds
      */
-    simulate(timeDelta: number): void;
+    simulate(time_delta_seconds: number): void;
     /**
      * If the {@link EntityManager} is already started, the system will be started automatically before being added
      * @param {System} system

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

@@ -1 +1 @@
-{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,oBAFW,MAAM,QAoEhB;IAED;;;;;OAKG;IACH,iEA6DC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAmCC;IAED;;;;;OAKG;IACH,oBAqFC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;OAIG;IACH,8DAFa,wCAAgB,CA0B5B;IAED;;;;;OAKG;IACH,mEAoFC;IAGL;;OAEG;IACH,yBA5rBe,sBAAsB,UA4rBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBA17BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAiBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,6BAFW,MAAM,QAyEhB;IAED;;;;;OAKG;IACH,iEA6DC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAmCC;IAED;;;;;OAKG;IACH,oBAqFC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;OAIG;IACH,8DAFa,wCAAgB,CA0B5B;IAED;;;;;OAKG;IACH,mEAoFC;IAGL;;OAEG;IACH,yBAjsBe,sBAAsB,UAisBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBA/7BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}

package/src/engine/ecs/EntityManager.js

@@ -405,13 +405,18 @@ export class EntityManager {
 
     /**
      * Advance simulation forward by a specified amount of time
-     * @param {number} timeDelta in seconds
+     * @param {number} time_delta_seconds in seconds
      */
-    simulate(timeDelta) {
-        assert.isNumber(timeDelta, 'timeDelta');
-        assert.notNaN(timeDelta, 'timeDelta');
-        assert.greaterThanOrEqual(timeDelta, 0, 'timeDelta must be >= 0');
-        assert.isFinite(timeDelta, 'timeDelta');
+    simulate(time_delta_seconds) {
+        assert.isNumber(time_delta_seconds, 'timeDelta');
+        assert.notNaN(time_delta_seconds, 'timeDelta');
+        assert.greaterThanOrEqual(time_delta_seconds, 0, 'time_delta_seconds must be >= 0');
+        assert.isFinite(time_delta_seconds, 'timeDelta');
+
+        if (this.dataset === null) {
+            // dataset is not attached
+            return;
+        }
 
         if (this.__execution_order_needs_update) {
             this.updateExecutionOrder();
@@ -437,7 +442,7 @@ export class EntityManager {
 
             // Perform fixed-step update
             if (system.fixedUpdate !== noop) {
-                let accumulated_time = accumulatedTime.get(system) + timeDelta;
+                let accumulated_time = accumulatedTime.get(system) + time_delta_seconds;
 
                 const t0 = performance.now();
 
@@ -465,7 +470,7 @@ export class EntityManager {
             if (system.update !== noop) {
 
                 try {
-                    system.update(timeDelta);
+                    system.update(time_delta_seconds);
                 } catch (e) {
                     console.error(`Failed during update of system '${computeSystemName(system)}': `, e);
                 }

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

@@ -1 +1 @@
-{"version":3,"file":"System.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/System.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAEI;;;;;OAKG;IACH,uCAAqB;IAErB;;;;OAIG;IACH,oBAA+C;IAE/C;;;;;;;OAOG;IACH,6BAAkB;IAElB;;;;;;;;;;OAUG;IACH,0BAFU,6BAA6B,CAElB;IAGrB;;OAEG;IACH,mCAcC;IAED;;;;;OAKG;IACH,oCAFY,MAAM,CA8BjB;IAED;;;;;;OAMG;IACH,uCAHa,QAAQ,IAAI,CAAC,CAKzB;IAED;;;;;;;OAOG;IACH,wCAHa,QAAQ,IAAI,CAAC,CAKzB;IAGD;;;;OAIG;IACH,wCAEC;IAED;;;;OAIG;IACH,0CAEC;IAED;;;;;;;;;;OAUG;IACH,6DAEC;IAED;;;;;;;;;;OAUG;IACH,6DAEC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,yBAA4B;IAG5B;;;;;;OAMG;IACH,oBAAuB;CAvBtB;0BA2BS,MAAM;;;;;;;;qBArOK,6BAA6B"}
+{"version":3,"file":"System.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/System.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAEI;;;;;OAKG;IACH,uCAAqB;IAErB;;;;OAIG;IACH,oBAA+C;IAE/C;;;;;;;OAOG;IACH,6BAAkB;IAElB;;;;;;;;;;OAUG;IACH,0BAFU,6BAA6B,CAElB;IAGrB;;OAEG;IACH,mCAcC;IAED;;;;;OAKG;IACH,oCAFY,MAAM,CA8BjB;IAED;;;;;;OAMG;IACH,uCAHa,QAAQ,IAAI,CAAC,CAKzB;IAED;;;;;;;OAOG;IACH,wCAHa,QAAQ,IAAI,CAAC,CAKzB;IAGD;;;;OAIG;IACH,wCAEC;IAED;;;;OAIG;IACH,0CAEC;IAED;;;;;;;;;;OAUG;IACH,6DAEC;IAED;;;;;;;;;;OAUG;IACH,6DAEC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,2CAFsC,MAAM,CAEhB;IAG5B;;;;;;OAMG;IACH,sCAFsC,MAAM,CAErB;CAvBtB;0BA2BS,MAAM"}

package/src/engine/ecs/System.js

@@ -213,7 +213,7 @@ System.prototype.isSystem = true;
 /**
  * Fixed update function, every step happens with the same exact time increment
  * useful for systems that must have a fixed time step to be predictable and stable, such as physics
- * @param {number} timeDelta in seconds, will always be the same value, controlled via {@link EntityManager.fixedUpdateStepSize}
+ * @type {function(time_delta_seconds:number)} time delta will always be the same value, controlled via {@link EntityManager.fixedUpdateStepSize}
  */
 System.prototype.fixedUpdate = noop; // by assigning NO-OP we enable a simple check, whether running the update would be useful
 
@@ -223,7 +223,7 @@ System.prototype.fixedUpdate = noop; // by assigning NO-OP we enable a simple ch
  * Note that this time step can vary depending on system conditions and hardware we are running on.
  * It is generally safe to assume that this update will happen once per frame, but it is not guaranteed.
  * Also, note that when the application window/tab is suspended, the next update step can have a very large value.
- * @param {number} timeDelta in seconds
+ * @type {function(time_delta_seconds:number)}
  */
 System.prototype.update = noop; // by assigning NO-OP we enable a simple check, whether running the update would be useful
 

package/src/engine/graphics/camera/testClippingPlaneComputation.js

@@ -19,7 +19,6 @@ import ViewportPositionSystem from "../../ecs/gui/position/ViewportPositionSyste
 import { InverseKinematicsSystem } from "../../ecs/ik/InverseKinematicsSystem.js";
 import RenderSystem from "../../ecs/renderable/RenderSystem.js";
 import AnimationSystem from "../../ecs/systems/AnimationSystem.js";
-import MotionSystem from "../../ecs/systems/MotionSystem.js";
 import ScriptSystem from "../../ecs/systems/ScriptSystem.js";
 import TimerSystem from "../../ecs/systems/TimerSystem.js";
 import ClingToTerrainSystem from "../../ecs/terrain/ecs/cling/ClingToTerrainSystem.js";
@@ -74,7 +73,6 @@ function makeConfig(engine) {
         new ScriptSystem(),
         new FacingDirectionSystem(),
         new PathFollowingSystem(),
-        new MotionSystem(),
         new SoundEmitterSystem(assetManager, sound.destination, sound.context),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),

package/src/engine/graphics/ecs/light/Light.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Light.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/light/Light.js"],"names":[],"mappings":"AASA;IA+DI;;;;OAIG;IACH,yBAFa,KAAK,CAQjB;IApEG;;;OAGG;IACH,wBAA4D;IAE5D;;;OAGG;IACH,OAFU,KAAK,CAEgB;IAE/B;;;OAGG;IACH,WAFU,OAAO,CAEc;IAE/B;;;OAGG;IACH,OAFU,OAAO,CAEoB;IAErC;;;OAGG;IACH,UAFU,OAAO,CAEe;IAEhC;;;OAGG;IACH,UAFU,OAAO,CAE4B;IAE7C;;;OAGG;IACH,YAFU,eAAe,CAEmB;IAE5C;;;;OAIG;IACH,sBAAyB;IAEzB;;;;OAIG;IACH,mBAAsB;IAgB1B,0BAqDC;IAED;;;;;MAqBC;CACJ;;;;;yBA/JwB,wCAAwC;sBAH3C,iCAAiC;oBACnC,kCAAkC;4BAC1B,2CAA2C;0BAE7C,gBAAgB"}
+{"version":3,"file":"Light.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/light/Light.js"],"names":[],"mappings":"AAUA;IAuEI;;;;OAIG;IACH,yBAFa,KAAK,CAQjB;IA5EG;;;OAGG;IACH,wBAA4D;IAE5D;;;OAGG;IACH,OAFU,KAAK,CAEgB;IAE/B;;;OAGG;IACH,WAFU,OAAO,CAEc;IAE/B;;;OAGG;IACH,OAFU,OAAO,CAEoB;IAErC;;;OAGG;IACH,UAFU,OAAO,CAEe;IAEhC;;;OAGG;IACH,UAFU,OAAO,CAE4B;IAE7C;;;;;OAKG;IACH,mBAFU,OAAO,CAEgD;IAEjE;;;OAGG;IACH,YAFU,eAAe,CAEmB;IAE5C;;;;OAIG;IACH,sBAAyB;IAEzB;;;;OAIG;IACH,mBAAsB;IAgB1B,0BA6DC;IAED;;;;;MA+BC;CACJ;;;;;yBA1LwB,wCAAwC;sBAH3C,iCAAiC;oBACnC,kCAAkC;4BAC1B,2CAA2C;0BAE7C,gBAAgB"}

package/src/engine/graphics/ecs/light/Light.js

@@ -6,6 +6,7 @@ import { LightType } from "./LightType.js";
 
 
 const DEFAULT_DISTANCE = 1;
+const DEFAULT_MAX_SHADOW_DISTANCE = Infinity;
 
 export class Light {
     /**
@@ -49,6 +50,14 @@ export class Light {
          */
         this.distance = new Vector1(DEFAULT_DISTANCE);
 
+        /**
+         * Applicable for DIRECTION light. Caps the world-space depth of the view
+         * frustum the shadow map is fit against — smaller values trade visible
+         * shadow distance for sharpness. `Infinity` fits the entire camera frustum.
+         * @type {Vector1}
+         */
+        this.maxShadowDistance = new Vector1(DEFAULT_MAX_SHADOW_DISTANCE);
+
         /**
          *
          * @type {ObservedBoolean}
@@ -135,6 +144,14 @@ export class Light {
                 this.distance.set(DEFAULT_DISTANCE);
             }
         }
+
+        if (actual_type === LightType.DIRECTION) {
+            if (json.maxShadowDistance !== undefined && json.maxShadowDistance !== null) {
+                this.maxShadowDistance.fromJSON(json.maxShadowDistance);
+            } else {
+                this.maxShadowDistance.set(DEFAULT_MAX_SHADOW_DISTANCE);
+            }
+        }
         this.__threeObject = null;
     }
 
@@ -157,6 +174,16 @@ export class Light {
             result.distance = this.distance.toJSON();
         }
 
+        if (actual_type === LightType.DIRECTION) {
+            // JSON.stringify turns Infinity into null and the rehydrated value
+            // would fail Vector1.set's number check; default is Infinity so
+            // missing-on-disk is the same as default.
+            const v = this.maxShadowDistance.getValue();
+            if (Number.isFinite(v)) {
+                result.maxShadowDistance = this.maxShadowDistance.toJSON();
+            }
+        }
+
 
         return result;
     }

package/src/engine/graphics/ecs/light/LightSystem.js

@@ -216,7 +216,7 @@ class LightSystem extends AbstractContextSystem {
                 three_update_shadow_camera_extents(
                     this.__camera_object,
                     l,
-                    this.settings.shadowDistance ?? DEFAULT_SHADOW_DISTANCE,
+                    light.maxShadowDistance.getValue(),
                     this.__graphics.layers
                 );
 

package/src/engine/graphics/ecs/path/PathDisplaySystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/path/PathDisplaySystem.js"],"names":[],"mappings":"AAoPA;IACI;;;OAGG;IACH,4BAwCC;IAnCG,mDAGC;IAED,2KAIC;IAED;;;OAGG;IACH,eAAoB;IAEpB;;;OAGG;IACH,iCAAkB;IAElB;;;;OAIG;IACH,wBAAkC;IAElC;;;OAGG;IACH,YAFU,MAAM,CAEc;IAGlC;;;;OAIG;IACH,8BAFW,MAAM,QAQhB;IAED;;;;OAIG;IACH,6BAFW,MAAM,QAIhB;IAED,2CAGC;IAED,4CAGC;IAED,8BA+BC;CACJ;sCA7VqC,8CAA8C;iBAGnE,4CAA4C;4BAKjC,kBAAkB;0BANpB,qCAAqC;4CAJnB,uDAAuD;+BAQpE,8BAA8B;6BAPhC,qCAAqC;8BAMpC,gCAAgC;mBAT3C,0CAA0C"}
+{"version":3,"file":"PathDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/path/PathDisplaySystem.js"],"names":[],"mappings":"AAoPA;IACI;;;OAGG;IACH,4BAwCC;IAnCG,mDAGC;IAED,2KAIC;IAED;;;OAGG;IACH,eAAoB;IAEpB;;;OAGG;IACH,iCAAkB;IAElB;;;;OAIG;IACH,wBAAkC;IAElC;;;OAGG;IACH,YAFU,MAAM,CAEc;IAGlC;;;;OAIG;IACH,8BAFW,MAAM,QAQhB;IAED;;;;OAIG;IACH,6BAFW,MAAM,QAIhB;IAED,2CAGC;IAED,4CAGC;IAED,8BA+BC;CACJ;sCA7VqC,8CAA8C;4BAQxD,kBAAkB;iBAL7B,4CAA4C;0BADnC,qCAAqC;4CAJnB,uDAAuD;6BACtE,qCAAqC;+BAOnC,8BAA8B;8BAD/B,gCAAgC;mBAT3C,0CAA0C"}