@woosh/meep-engine 3.60.3 → 3.60.5

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

@@ -1,109 +1,82 @@
-import { clamp } from "../../../core/math/clamp.js";
+import { assert } from "../../../core/assert.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import Script from "../../ecs/components/Script.js";
 import Entity from "../../ecs/Entity.js";
-import { decodeMouseEventButtons } from "../../input/devices/mouse/decodeMouseEventButtons.js";
+import { MouseEventButtons } from "../../input/devices/mouse/MouseEventButtons.js";
 import InputController from "../../input/ecs/components/InputController.js";
 import { Camera } from "../ecs/camera/Camera.js";
-import TopDownCameraController, { rotate_from_view } from "../ecs/camera/topdown/TopDownCameraController.js";
+import TopDownCameraController from "../ecs/camera/topdown/TopDownCameraController.js";
+import { OrbitalCameraRig } from "./orbital/OrbitalCameraRig.js";
 
 /**
+ * Pointer navigation for a camera entity's {@link TopDownCameraController}: drag with the primary
+ * button (or a touch) to orbit, with the secondary to pan, the wheel to zoom. A drag moves the camera
+ * as it happens and throws on release; see {@link OrbitalCameraRig}.
+ *
+ * The orbit swings all the way round, under the target included, short of turning over at the poles.
  *
  * @param {Object} options
- * @param {number} options.camera_entity
+ * @param {number} options.camera_entity carries the {@link TopDownCameraController} and {@link Camera}
  * @param {EntityComponentDataset} options.ecd
- * @param {HTMLElement} options.dom_element
- * @param {number} [options.sensitivity]
- * @return {Entity}
+ * @param {HTMLElement} options.dom_element the viewport, measured for its height
+ * @return {Entity} transient, to be built into the dataset
  */
 export function makeOrbitalCameraController({
                                                 camera_entity,
                                                 ecd,
                                                 dom_element,
-                                                sensitivity = 1
                                             }) {
-    /**
-     *
-     * @returns {TopDownCameraController}
-     */
-    function getCameraController() {
-        return ecd.getComponent(camera_entity, TopDownCameraController)
-    }
-
-    function getCamera() {
-        return ecd.getComponent(camera_entity, Camera)
-    }
-
-    /**
-     *
-     * @param {Vector2} delta
-     */
-    function orbit(delta) {
-
-        const cameraController = getCameraController();
-
-        const scale = sensitivity * 2 * Math.PI / dom_element.clientHeight;
-
-        rotate_from_view(delta.x * scale, delta.y * scale, cameraController, cameraController);
-    }
-
-    /**
-     *
-     * @param {Vector2} delta
-     */
-    function pan(delta) {
-
-        const cameraController = getCameraController();
-        const camera = getCamera();
-
-        TopDownCameraController.pan(delta, cameraController, dom_element.clientHeight, camera.fov.getValue());
+    const controller = ecd.getComponent(camera_entity, TopDownCameraController);
+    const camera = ecd.getComponent(camera_entity, Camera);
 
-    }
+    assert.defined(controller, 'controller');
+    assert.defined(camera, 'camera');
 
-    function zoom(delta) {
-        const cameraController = getCameraController();
-
-        const new_distance = cameraController.distance + delta;
-        cameraController.distance = clamp(new_distance, cameraController.distanceMin, cameraController.distanceMax);
-    }
+    const rig = new OrbitalCameraRig(controller, {
+        orbit_buttons: MouseEventButtons.primary,
+        pan_buttons: MouseEventButtons.secondary,
+        pitch_min: -Math.PI / 2,
+        pitch_max: Math.PI / 2,
+        pan_axes: Vector3.one
+    });
 
     const inputController = new InputController([
         {
-            path: 'pointer/on/tap',
-            listener(position, event) {
-                // event.preventDefault();
-            }
-        },
-        {
-            path: 'pointer/on/down',
-            listener(position, event) {
-                // event.preventDefault();
+            path: 'pointer/on/dragStart',
+            listener(origin, event) {
+                rig.begin(event.buttons);
             }
         },
         {
             path: 'pointer/on/drag',
-            listener: function (position, origin, lastDragPosition, event) {
-                const delta = lastDragPosition.clone().sub(position);
-
-                const buttons = decodeMouseEventButtons(event.buttons);
-
-                if (buttons[0]) {
-                    pan(delta);
-                } else {
-                    orbit(delta);
-                }
+            listener(position, origin, lastDragPosition, event) {
+                rig.move(
+                    position.x - lastDragPosition.x,
+                    position.y - lastDragPosition.y,
+                    dom_element.clientHeight,
+                    camera.fov.getValue()
+                );
 
                 event.preventDefault();
             }
         },
+        {
+            path: 'pointer/on/dragEnd',
+            listener() {
+                rig.end();
+            }
+        },
         {
             path: 'pointer/on/wheel',
-            listener(delta, event) {
-                zoom(delta.y);
+            listener(delta) {
+                rig.dolly(delta.y);
             }
         }
     ]);
 
     const eb = new Entity();
     eb.add(inputController);
+    eb.add(new Script(time_delta => rig.update(time_delta)));
 
     return eb;
 }

package/src/engine/graphics/camera/orbital/MomentumAxis.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The velocity of one degree of freedom under **direct drive + release momentum** — the "throw" of
+ * Google Earth / Maps / Cesium, not a spring.
+ *
+ * The axis holds no position. While a gesture is engaged the caller applies each drag to whatever it
+ * is moving and {@link record}s it here, so the drag itself has no lag. On {@link release} the
+ * average velocity over the recent window becomes the throw; averaging the velocity rather than the
+ * position rejects one jittery last frame without adding lag to the live drag. From then on
+ * {@link update} hands back how far the coast moves each frame, decaying exponentially, and the caller
+ * adds that to the value — so anyone else writing the same value keeps their write, and the coast
+ * carries on from it.
+ *
+ * Holding still before letting go fills the window with frames that did not move, so a slow,
+ * deliberate drag stops where it was left while a flick throws — no click-versus-drag gate.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MomentumAxis {
+    /**
+     * units per second; non-zero while coasting
+     * @type {number}
+     */
+    velocity: number;
+    /**
+     * true while a gesture is driving this axis
+     * @type {boolean}
+     */
+    engaged: boolean;
+    /**
+     * Begin direct control: stop any coast and forget earlier motion.
+     */
+    engage(): void;
+    /**
+     * Note motion the caller has just applied directly, for the release estimate.
+     * @param {number} delta
+     */
+    record(delta: number): void;
+    /**
+     * End the gesture, throwing with the average velocity over the most recent `window_seconds` of it.
+     * @param {number} window_seconds
+     */
+    release(window_seconds: number): void;
+    /**
+     * No motion, no gesture, no history.
+     */
+    stop(): void;
+    /**
+     * Advance one frame.
+     *
+     * Engaged, this samples the frame's recorded motion and moves nothing, since the drag was applied
+     * when it happened. Coasting, it integrates the decaying velocity analytically — over `dt` the
+     * coast covers `v·τ·(1 − e^(−dt/τ))` and the velocity falls by `e^(−dt/τ)` — so the distance
+     * thrown is the same at any frame rate.
+     *
+     * @param {number} dt seconds
+     * @param {number} half_life seconds for the coast velocity to halve
+     * @param {number} stop_speed at or below this speed the coast ends
+     * @returns {number} how far the value moves this frame
+     */
+    update(dt: number, half_life: number, stop_speed: number): number;
+    #private;
+}
+//# sourceMappingURL=MomentumAxis.d.ts.map

package/src/engine/graphics/camera/orbital/MomentumAxis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MomentumAxis.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/camera/orbital/MomentumAxis.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;GAiBG;AACH;IACI;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,SAFU,OAAO,CAED;IA+BhB;;OAEG;IACH,eAGC;IAED;;;OAGG;IACH,cAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,wBAFW,MAAM,QAehB;IAED;;OAEG;IACH,aAMC;IAED;;;;;;;;;;;;OAYG;IACH,WALW,MAAM,aACN,MAAM,cACN,MAAM,GACJ,MAAM,CAoClB;;CAuBJ"}

package/src/engine/graphics/camera/orbital/MomentumAxis.js

@@ -0,0 +1,187 @@
+const LN2 = 0.6931471805599453;
+
+/**
+ * Frames of drag history kept for the release estimate. The estimate reads back over a window of
+ * about a tenth of a second, so this covers it at up to 900 frames a second; beyond that the oldest
+ * part of the window is simply not seen.
+ * @type {number}
+ */
+const HISTORY_CAPACITY = 90;
+
+/**
+ * The velocity of one degree of freedom under **direct drive + release momentum** — the "throw" of
+ * Google Earth / Maps / Cesium, not a spring.
+ *
+ * The axis holds no position. While a gesture is engaged the caller applies each drag to whatever it
+ * is moving and {@link record}s it here, so the drag itself has no lag. On {@link release} the
+ * average velocity over the recent window becomes the throw; averaging the velocity rather than the
+ * position rejects one jittery last frame without adding lag to the live drag. From then on
+ * {@link update} hands back how far the coast moves each frame, decaying exponentially, and the caller
+ * adds that to the value — so anyone else writing the same value keeps their write, and the coast
+ * carries on from it.
+ *
+ * Holding still before letting go fills the window with frames that did not move, so a slow,
+ * deliberate drag stops where it was left while a flick throws — no click-versus-drag gate.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MomentumAxis {
+    /**
+     * units per second; non-zero while coasting
+     * @type {number}
+     */
+    velocity = 0;
+
+    /**
+     * true while a gesture is driving this axis
+     * @type {boolean}
+     */
+    engaged = false;
+
+    /**
+     * motion recorded since the last frame sample
+     * @type {number}
+     */
+    #pending = 0;
+
+    /**
+     * per-frame motion, a ring of {@link HISTORY_CAPACITY}
+     * @type {Float64Array}
+     */
+    #history_motion = new Float64Array(HISTORY_CAPACITY);
+
+    /**
+     * duration of each frame in {@link #history_motion}, seconds
+     * @type {Float64Array}
+     */
+    #history_duration = new Float64Array(HISTORY_CAPACITY);
+
+    /**
+     * slot the next frame is written to
+     * @type {number}
+     */
+    #history_head = 0;
+
+    /**
+     * @type {number}
+     */
+    #history_count = 0;
+
+    /**
+     * Begin direct control: stop any coast and forget earlier motion.
+     */
+    engage() {
+        this.stop();
+        this.engaged = true;
+    }
+
+    /**
+     * Note motion the caller has just applied directly, for the release estimate.
+     * @param {number} delta
+     */
+    record(delta) {
+        this.#pending += delta;
+    }
+
+    /**
+     * End the gesture, throwing with the average velocity over the most recent `window_seconds` of it.
+     * @param {number} window_seconds
+     */
+    release(window_seconds) {
+        if (this.#pending !== 0 && this.#history_count > 0) {
+            // motion that arrived after the last frame sample belongs to the frame that just ended
+            const last = (this.#history_head + HISTORY_CAPACITY - 1) % HISTORY_CAPACITY;
+
+            this.#history_motion[last] += this.#pending;
+        }
+
+        const velocity = this.#windowed_velocity(window_seconds);
+
+        this.stop();
+
+        this.velocity = velocity;
+    }
+
+    /**
+     * No motion, no gesture, no history.
+     */
+    stop() {
+        this.velocity = 0;
+        this.engaged = false;
+        this.#pending = 0;
+        this.#history_head = 0;
+        this.#history_count = 0;
+    }
+
+    /**
+     * Advance one frame.
+     *
+     * Engaged, this samples the frame's recorded motion and moves nothing, since the drag was applied
+     * when it happened. Coasting, it integrates the decaying velocity analytically — over `dt` the
+     * coast covers `v·τ·(1 − e^(−dt/τ))` and the velocity falls by `e^(−dt/τ)` — so the distance
+     * thrown is the same at any frame rate.
+     *
+     * @param {number} dt seconds
+     * @param {number} half_life seconds for the coast velocity to halve
+     * @param {number} stop_speed at or below this speed the coast ends
+     * @returns {number} how far the value moves this frame
+     */
+    update(dt, half_life, stop_speed) {
+        if (this.engaged) {
+            const head = this.#history_head;
+
+            this.#history_motion[head] = this.#pending;
+            this.#history_duration[head] = dt;
+
+            this.#history_head = (head + 1) % HISTORY_CAPACITY;
+
+            if (this.#history_count < HISTORY_CAPACITY) {
+                this.#history_count++;
+            }
+
+            this.#pending = 0;
+
+            return 0;
+        }
+
+        const velocity = this.velocity;
+
+        if (velocity === 0) {
+            return 0;
+        }
+
+        const tau = half_life / LN2;
+        const decay = Math.exp(-dt / tau);
+
+        this.velocity = velocity * decay;
+
+        if (Math.abs(this.velocity) <= stop_speed) {
+            this.velocity = 0;
+        }
+
+        return velocity * tau * (1 - decay);
+    }
+
+    /**
+     * @param {number} window_seconds
+     * @returns {number}
+     */
+    #windowed_velocity(window_seconds) {
+        let motion = 0;
+        let duration = 0;
+
+        for (let i = 1; i <= this.#history_count; i++) {
+            const slot = (this.#history_head + HISTORY_CAPACITY - i) % HISTORY_CAPACITY;
+
+            motion += this.#history_motion[slot];
+            duration += this.#history_duration[slot];
+
+            if (duration >= window_seconds) {
+                break;
+            }
+        }
+
+        return duration > 0 ? motion / duration : 0;
+    }
+}

package/src/engine/graphics/camera/orbital/OrbitalCameraRig.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Orbit, pan and zoom of a {@link TopDownCameraController}, with the feel of **direct drive + release
+ * momentum**: the "throw" of Google Earth / Cesium, not a spring chasing a goal.
+ *
+ * - **A drag moves the controller as it happens**, one to one, so the view keeps up with the hand.
+ * - **Letting go throws**: the average velocity over the last {@link VELOCITY_WINDOW} carries on and
+ *   decays with a half life of {@link MOMENTUM_HALF_LIFE}, at the same distance whatever the frame
+ *   rate. Holding still before letting go throws nothing. Grabbing again stops every throw.
+ * - **Zoom is instant and multiplicative**: a wheel notch is a discrete step with nothing to catch up.
+ *
+ * The rig keeps velocities, not a pose. Each frame the coast is added to the controller as it finds
+ * it, so a writer that adds to the controller composes with a throw, and one that sets its values
+ * outright wins. A teleport should {@link stop} the rig, or the remains of a throw carry on from the
+ * new pose.
+ *
+ * The rig subscribes to nothing. Its host hands it the gesture — {@link begin}, {@link move},
+ * {@link end}, {@link dolly} — from whatever input it listens to, and calls {@link update} once a frame.
+ * A drag the device abandons without an end leaves the rig engaged and still, which the next
+ * {@link begin} clears.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class OrbitalCameraRig {
+    /**
+     * @param {TopDownCameraController} controller moved by the rig; a host that filters the camera
+     * hands over the controller its input is meant to drive
+     * @param {Object} options
+     * @param {number} options.orbit_buttons {@link MouseEvent.buttons} bits that start an orbit, see
+     * {@link MouseEventButtons}
+     * @param {number} options.pan_buttons {@link MouseEvent.buttons} bits that start a pan; orbit wins
+     * when both are held
+     * @param {number} options.pitch_min radians; 0 looks along the horizon
+     * @param {number} options.pitch_max radians; π/2 looks straight down
+     * @param {Vector3} options.pan_axes per-axis scale on a pan's world displacement, as
+     * {@link TopDownCameraController.pan} takes it; zero Y to keep the target on the ground
+     */
+    constructor(controller: TopDownCameraController, { orbit_buttons, pan_buttons, pitch_min, pitch_max, pan_axes }: {
+        orbit_buttons: number;
+        pan_buttons: number;
+        pitch_min: number;
+        pitch_max: number;
+        pan_axes: Vector3;
+    });
+    /**
+     * Start a drag. Stops every throw, then takes direct control of orbit or pan, chosen by the
+     * buttons held; with neither, the drag moves nothing.
+     *
+     * @param {number} buttons {@link MouseEvent.buttons} of the event that started the drag
+     */
+    begin(buttons: number): void;
+    /**
+     * The pointer moved during a drag, applied to the controller at once.
+     *
+     * An orbit turns the view a full turn per viewport height of travel, pitch clamped to the rig's
+     * range; a pan carries the world under the pointer along with it.
+     *
+     * @param {number} delta_x pixels, the pointer's position less where it was
+     * @param {number} delta_y pixels, the pointer's position less where it was, down positive
+     * @param {number} viewport_height pixels
+     * @param {number} fov vertical field of view, in degrees
+     */
+    move(delta_x: number, delta_y: number, viewport_height: number, fov: number): void;
+    /**
+     * End the drag, throwing with its recent velocity.
+     */
+    end(): void;
+    /**
+     * Drop any drag and every throw, leaving the controller where it is.
+     */
+    stop(): void;
+    /**
+     * Zoom by wheel notches, within the controller's distance range.
+     * @param {number} notches positive away from the target, as a wheel scrolled down reports it
+     */
+    dolly(notches: number): void;
+    /**
+     * Advance one frame: sample an engaged drag for its throw, or carry a throw on.
+     * @param {number} dt seconds
+     */
+    update(dt: number): void;
+    #private;
+}
+import TopDownCameraController from "../../ecs/camera/topdown/TopDownCameraController.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+//# sourceMappingURL=OrbitalCameraRig.d.ts.map

package/src/engine/graphics/camera/orbital/OrbitalCameraRig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrbitalCameraRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/camera/orbital/OrbitalCameraRig.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA0CI;;;;;;;;;;;;OAYG;IACH,wBAZW,uBAAuB;QAGP,aAAa,EAA7B,MAAM;QAEU,WAAW,EAA3B,MAAM;QAEU,SAAS,EAAzB,MAAM;QACU,SAAS,EAAzB,MAAM;QACW,QAAQ,EAAzB,OAAO;OAkBjB;IAED;;;;;OAKG;IACH,eAFW,MAAM,QAiBhB;IAED;;;;;;;;;;OAUG;IACH,cALW,MAAM,WACN,MAAM,mBACN,MAAM,OACN,MAAM,QAQhB;IAED;;OAEG;IACH,YAWC;IAED;;OAEG;IACH,aAQC;IAED;;;OAGG;IACH,eAFW,MAAM,QAUhB;IAED;;;OAGG;IACH,WAFW,MAAM,QAyChB;;CAwDJ;oCAzTmC,qDAAqD;oBAFrE,kCAAkC"}