@woosh/meep-engine 3.60.4 → 3.60.5

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

@@ -0,0 +1,319 @@
+import { assert } from "../../../../core/assert.js";
+import { normalize_angle_rad } from "../../../../core/geom/normalize_angle_rad.js";
+import Vector2 from "../../../../core/geom/Vector2.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import TopDownCameraController from "../../ecs/camera/topdown/TopDownCameraController.js";
+import { MomentumAxis } from "./MomentumAxis.js";
+
+/**
+ * Seconds for a throw's velocity to halve once the gesture lets go.
+ * @type {number}
+ */
+const MOMENTUM_HALF_LIFE = 0.1;
+
+/**
+ * Seconds of the gesture's end averaged into the throw velocity.
+ * @type {number}
+ */
+const VELOCITY_WINDOW = 0.1;
+
+/**
+ * Radians per second below which an orbit throw stops. A pan throw stops at this times the orbit
+ * distance, the same speed across the screen at any zoom.
+ * @type {number}
+ */
+const MOMENTUM_STOP_SPEED = 0.012;
+
+/**
+ * Factor on the orbit distance per wheel notch towards the target.
+ * @type {number}
+ */
+const ZOOM_STEP = 0.9;
+
+const GESTURE_NONE = 0;
+const GESTURE_ORBIT = 1;
+const GESTURE_PAN = 2;
+
+const v2_pan = new Vector2();
+
+/**
+ * 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 {
+    /**
+     * @type {TopDownCameraController}
+     */
+    #controller;
+
+    /**
+     * @type {number}
+     */
+    #orbit_buttons;
+
+    /**
+     * @type {number}
+     */
+    #pan_buttons;
+
+    /**
+     * @type {number}
+     */
+    #pitch_min;
+
+    /**
+     * @type {number}
+     */
+    #pitch_max;
+
+    /**
+     * @type {Vector3}
+     */
+    #pan_axes;
+
+    #pitch = new MomentumAxis();
+    #yaw = new MomentumAxis();
+    #target_x = new MomentumAxis();
+    #target_y = new MomentumAxis();
+    #target_z = new MomentumAxis();
+
+    /**
+     * @type {number}
+     */
+    #gesture = GESTURE_NONE;
+
+    /**
+     * @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, { orbit_buttons, pan_buttons, pitch_min, pitch_max, pan_axes }) {
+        assert.defined(controller, 'controller');
+        assert.isNonNegativeInteger(orbit_buttons, 'orbit_buttons');
+        assert.isNonNegativeInteger(pan_buttons, 'pan_buttons');
+        assert.isNumber(pitch_min, 'pitch_min');
+        assert.isNumber(pitch_max, 'pitch_max');
+        assert.lessThanOrEqual(pitch_min, pitch_max, 'pitch_min must not exceed pitch_max');
+        assert.defined(pan_axes, 'pan_axes');
+
+        this.#controller = controller;
+        this.#orbit_buttons = orbit_buttons;
+        this.#pan_buttons = pan_buttons;
+        this.#pitch_min = pitch_min;
+        this.#pitch_max = pitch_max;
+        this.#pan_axes = pan_axes;
+    }
+
+    /**
+     * 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) {
+        this.stop();
+
+        if ((buttons & this.#orbit_buttons) !== 0) {
+            this.#gesture = GESTURE_ORBIT;
+
+            this.#pitch.engage();
+            this.#yaw.engage();
+        } else if ((buttons & this.#pan_buttons) !== 0) {
+            this.#gesture = GESTURE_PAN;
+
+            this.#target_x.engage();
+            this.#target_y.engage();
+            this.#target_z.engage();
+        }
+    }
+
+    /**
+     * 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, delta_y, viewport_height, fov) {
+        if (this.#gesture === GESTURE_ORBIT) {
+            this.#orbit(delta_x, delta_y, viewport_height);
+        } else if (this.#gesture === GESTURE_PAN) {
+            this.#pan(delta_x, delta_y, viewport_height, fov);
+        }
+    }
+
+    /**
+     * End the drag, throwing with its recent velocity.
+     */
+    end() {
+        if (this.#gesture === GESTURE_ORBIT) {
+            this.#pitch.release(VELOCITY_WINDOW);
+            this.#yaw.release(VELOCITY_WINDOW);
+        } else if (this.#gesture === GESTURE_PAN) {
+            this.#target_x.release(VELOCITY_WINDOW);
+            this.#target_y.release(VELOCITY_WINDOW);
+            this.#target_z.release(VELOCITY_WINDOW);
+        }
+
+        this.#gesture = GESTURE_NONE;
+    }
+
+    /**
+     * Drop any drag and every throw, leaving the controller where it is.
+     */
+    stop() {
+        this.#gesture = GESTURE_NONE;
+
+        this.#pitch.stop();
+        this.#yaw.stop();
+        this.#target_x.stop();
+        this.#target_y.stop();
+        this.#target_z.stop();
+    }
+
+    /**
+     * 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) {
+        const controller = this.#controller;
+
+        controller.distance = clamp(
+            controller.distance * Math.pow(ZOOM_STEP, -notches),
+            controller.distanceMin,
+            controller.distanceMax
+        );
+    }
+
+    /**
+     * Advance one frame: sample an engaged drag for its throw, or carry a throw on.
+     * @param {number} dt seconds
+     */
+    update(dt) {
+        if (!(dt > 0)) {
+            return;
+        }
+
+        const controller = this.#controller;
+
+        const d_pitch = this.#pitch.update(dt, MOMENTUM_HALF_LIFE, MOMENTUM_STOP_SPEED);
+
+        if (d_pitch !== 0) {
+            const pitch = controller.pitch + d_pitch;
+
+            // a throw stops at the end of the range instead of pressing on into it
+            if (pitch <= this.#pitch_min) {
+                controller.pitch = this.#pitch_min;
+                this.#pitch.stop();
+            } else if (pitch >= this.#pitch_max) {
+                controller.pitch = this.#pitch_max;
+                this.#pitch.stop();
+            } else {
+                controller.pitch = pitch;
+            }
+        }
+
+        const d_yaw = this.#yaw.update(dt, MOMENTUM_HALF_LIFE, MOMENTUM_STOP_SPEED);
+
+        if (d_yaw !== 0) {
+            controller.yaw = normalize_angle_rad(controller.yaw + d_yaw);
+        }
+
+        const pan_stop_speed = MOMENTUM_STOP_SPEED * controller.distance;
+
+        const d_x = this.#target_x.update(dt, MOMENTUM_HALF_LIFE, pan_stop_speed);
+        const d_y = this.#target_y.update(dt, MOMENTUM_HALF_LIFE, pan_stop_speed);
+        const d_z = this.#target_z.update(dt, MOMENTUM_HALF_LIFE, pan_stop_speed);
+
+        if (d_x !== 0 || d_y !== 0 || d_z !== 0) {
+            controller.target._add(d_x, d_y, d_z);
+        }
+    }
+
+    /**
+     * @param {number} delta_x
+     * @param {number} delta_y
+     * @param {number} viewport_height
+     */
+    #orbit(delta_x, delta_y, viewport_height) {
+        if (!(viewport_height > 0)) {
+            return;
+        }
+
+        const controller = this.#controller;
+
+        const radians_per_pixel = 2 * Math.PI / viewport_height;
+
+        // a pitch found outside the range is brought into it, and the jump is no part of the gesture
+        const pitch_before = clamp(controller.pitch, this.#pitch_min, this.#pitch_max);
+        const pitch_after = clamp(pitch_before + delta_y * radians_per_pixel, this.#pitch_min, this.#pitch_max);
+
+        controller.pitch = pitch_after;
+        this.#pitch.record(pitch_after - pitch_before);
+
+        // dragging right swings the eye the other way around the target, so the world turns with the hand
+        const d_yaw = -delta_x * radians_per_pixel;
+
+        controller.yaw = normalize_angle_rad(controller.yaw + d_yaw);
+        this.#yaw.record(d_yaw);
+    }
+
+    /**
+     * @param {number} delta_x
+     * @param {number} delta_y
+     * @param {number} viewport_height
+     * @param {number} fov
+     */
+    #pan(delta_x, delta_y, viewport_height, fov) {
+        if (!(viewport_height > 0)) {
+            return;
+        }
+
+        const target = this.#controller.target;
+
+        const x = target.x;
+        const y = target.y;
+        const z = target.z;
+
+        // pan takes where the pointer was less where it is
+        v2_pan.set(-delta_x, -delta_y);
+
+        TopDownCameraController.pan(v2_pan, this.#controller, viewport_height, fov, this.#pan_axes);
+
+        this.#target_x.record(target.x - x);
+        this.#target_y.record(target.y - y);
+        this.#target_z.record(target.z - z);
+    }
+}

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraController.d.ts

@@ -1,11 +1,3 @@
-/**
- *
- * @param {number} displacement_x
- * @param {number} displacement_y
- * @param {TopDownCameraController} input source thing being rotated
- * @param {TopDownCameraController} output target thing where the result is written to
- */
-export function rotate_from_view(displacement_x: number, displacement_y: number, input: TopDownCameraController, output: TopDownCameraController): void;
 /**
  * The orientation a controller looks along. The camera's transform is built from this and the
  * distance, so anything that needs the view's own axes takes them from here rather than from
@@ -15,7 +7,41 @@ export function rotate_from_view(displacement_x: number, displacement_y: number,
  * @param {TopDownCameraController} controller
  */
 export function top_down_view_rotation(result: Quaternion, controller: TopDownCameraController): void;
+/**
+ * Write a controller's pose onto a camera transform: the view rotation, and the eye its distance back
+ * from the target along it, the distance held within the controller's range.
+ *
+ * @param {TopDownCameraController} control
+ * @param {Transform64} result
+ */
+export function computeTopDownTransform(control: TopDownCameraController, result: Transform64): void;
+/**
+ * Move a controller's target `distance` world units along where its view faces: `right` and
+ * `forward` pick the direction in the view's own frame, so a target can be flown up or down a slope.
+ * A diagonal travels the same distance as a straight move.
+ *
+ * The viewer's right is the negated X axis of the view rotation, as {@link pan} explains.
+ *
+ * @param {TopDownCameraController} controller its {@link TopDownCameraController#target} is moved
+ * @param {number} right −1 to 1, positive to the viewer's right
+ * @param {number} forward −1 to 1, positive into the screen
+ * @param {number} distance world units
+ */
+export function top_down_truck_in_view(controller: TopDownCameraController, right: number, forward: number, distance: number): void;
+/**
+ * Move a controller's target `distance` world units across the ground, along the way its view is
+ * turned: `forward` is the view's heading with the pitch taken out, so it keeps its full speed
+ * however steeply the view looks down, straight down included, and never moves the target off the
+ * ground. A diagonal travels the same distance as a straight move.
+ *
+ * @param {TopDownCameraController} controller its {@link TopDownCameraController#target} is moved
+ * @param {number} right −1 to 1, positive to the viewer's right
+ * @param {number} forward −1 to 1, positive along the view's heading
+ * @param {number} distance world units
+ */
+export function top_down_truck_on_ground(controller: TopDownCameraController, right: number, forward: number, distance: number): void;
 export default TopDownCameraController;
+import Quaternion from "../../../../../core/geom/Quaternion.js";
 declare class TopDownCameraController {
     static fromJSON(j: any): TopDownCameraController;
     constructor(options: any);
@@ -86,9 +112,7 @@ declare class TopDownCameraController {
 declare namespace TopDownCameraController {
     export let typeName: string;
     export { pan };
-    export { rotate_from_view as rotate };
 }
-import Quaternion from "../../../../../core/geom/Quaternion.js";
 import Vector3 from '../../../../../core/geom/Vector3.js';
 /**
  * Move a controller's target across the view plane it is looking at, by a displacement given in

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TopDownCameraController.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/topdown/TopDownCameraController.js"],"names":[],"mappings":"AAyBA;;;;;;GAMG;AACH,iDALW,MAAM,kBACN,MAAM,SACN,uBAAuB,UACvB,uBAAuB,QAiBjC;AAED;;;;;;;GAOG;AACH,+CAHW,UAAU,cACV,uBAAuB,QAIjC;;AAkED;IA+JI,iDAMC;IA5JD,0BAKC;IAbD,gBAAuB;IACvB,cAAU;IACV,YAAQ;IACR,aAAS;IACT,iBAAa;IACb,oBAAgB;IAChB,oBAAkB;IASlB;;;;;;;;;OASG;IACH,yBAJW,OAAO,UACP,OAAO,OACP,OAAO,QAgCjB;IAED;;;;OAIG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAWnB;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAYjC;IAED;;;OAGG;IACH,SAFa,uBAAuB,CAQnC;IAED;;;;;OAKG;IACH,QAJW,uBAAuB,KACvB,uBAAuB,KACvB,MAAM,QAahB;IAED;;;;;;;;;;;;MAYC;IAED;;;;;;;;aAsBC;CASJ;;;;;;uBA7RsB,wCAAwC;oBAC3C,qCAAqC;AAsEzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iDAPW,uBAAuB,sBACvB,MAAM,OAEN,MAAM,eACN,OAAO,QA2BjB"}
+{"version":3,"file":"TopDownCameraController.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/topdown/TopDownCameraController.js"],"names":[],"mappings":"AAyBA;;;;;;;GAOG;AACH,+CAHW,UAAU,cACV,uBAAuB,QAIjC;AAiED;;;;;;GAMG;AACH,iDAHW,uBAAuB,6BA2BjC;AAED;;;;;;;;;;;GAWG;AACH,mDALW,uBAAuB,SACvB,MAAM,WACN,MAAM,YACN,MAAM,QAMhB;AAED;;;;;;;;;;GAUG;AACH,qDALW,uBAAuB,SACvB,MAAM,WACN,MAAM,YACN,MAAM,QAMhB;;uBAhKsB,wCAAwC;AAoM/D;IAyKI,iDAMC;IAtKD,0BAKC;IAbD,gBAAuB;IACvB,cAAU;IACV,YAAQ;IACR,aAAS;IACT,iBAAa;IACb,oBAAgB;IAChB,oBAAkB;IASlB;;;;;;;;;OASG;IACH,yBAJW,OAAO,UACP,OAAO,OACP,OAAO,QA0CjB;IAED;;;;OAIG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAWnB;IAED;;;OAGG;IACH,YAFW,uBAAuB,QAYjC;IAED;;;OAGG;IACH,SAFa,uBAAuB,CAQnC;IAED;;;;;OAKG;IACH,QAJW,uBAAuB,KACvB,uBAAuB,KACvB,MAAM,QAahB;IAED;;;;;;;;;;;;MAYC;IAED;;;;;;;;aAsBC;CASJ;;;;;oBAnXmB,qCAAqC;AA8CzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iDAPW,uBAAuB,sBACvB,MAAM,OAEN,MAAM,eACN,OAAO,QA2BjB"}

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraController.js

@@ -6,9 +6,9 @@ import {
 import { normalize_angle_rad } from "../../../../../core/geom/normalize_angle_rad.js";
 import Quaternion from "../../../../../core/geom/Quaternion.js";
 import Vector3 from '../../../../../core/geom/Vector3.js';
+import { clamp } from "../../../../../core/math/clamp.js";
 import { lerp } from "../../../../../core/math/lerp.js";
 import { max2 } from "../../../../../core/math/max2.js";
-import { sign_not_zero } from "../../../../../core/math/sign_not_zero.js";
 import { v3_distance } from "../../../../../core/geom/vec3/v3_distance.js";
 
 const m4 = [];
@@ -21,31 +21,7 @@ const q_view = new Quaternion();
 
 const v3_view_right = new Vector3();
 const v3_view_up = new Vector3();
-
-
-/**
- *
- * @param {number} displacement_x
- * @param {number} displacement_y
- * @param {TopDownCameraController} input source thing being rotated
- * @param {TopDownCameraController} output target thing where the result is written to
- */
-export function rotate_from_view(displacement_x, displacement_y, input, output) {
-    // crop yaw and pitch to safe range of -PI to PI
-    const i_pitch = normalize_angle_rad(input.pitch);
-    const i_yaw = normalize_angle_rad(input.yaw);
-    const i_roll = normalize_angle_rad(input.roll);
-
-    const quaternion = Quaternion.fromEulerAngles(i_pitch, i_yaw, i_roll);
-    const forward = Vector3.up.clone();
-    forward.applyQuaternion(quaternion);
-
-    // flip rotation axis when pitch is over 90deg in either direction, that is UP vector is pointing down
-    const d_yaw = sign_not_zero(forward.y) * displacement_x;
-
-    output.yaw = i_yaw + d_yaw;
-    output.pitch = i_pitch - displacement_y;
-}
+const v3_view_forward = new Vector3();
 
 /**
  * The orientation a controller looks along. The camera's transform is built from this and the
@@ -122,6 +98,107 @@ function pan(delta, controller, viewport_height_px, fov, multiplier = Vector3.on
     move_along(target, v3_view_up, -delta.y * m, multiplier);
 }
 
+/**
+ * Write a controller's pose onto a camera transform: the view rotation, and the eye its distance back
+ * from the target along it, the distance held within the controller's range.
+ *
+ * @param {TopDownCameraController} control
+ * @param {Transform64} result
+ */
+export function computeTopDownTransform(control, result) {
+
+    //clamp the distance
+    const distance = clamp(control.distance, control.distanceMin, control.distanceMax);
+    const target = control.target;
+
+    // compute rotation. The transform holds its rotation as four numbers rather than a Quaternion,
+    // so the euler composition runs in a scratch and lands in the transform afterwards.
+    top_down_view_rotation(q_view, control);
+
+    result.setRotation(q_view.x, q_view.y, q_view.z, q_view.w);
+
+    // compute camera position
+    v3_view_forward.copy(Vector3.forward);
+    v3_view_forward.applyQuaternion(q_view);
+
+    v3_view_forward.multiplyScalar(-distance);
+
+    v3_view_forward.add(target);
+
+    result.setTranslation(v3_view_forward.x, v3_view_forward.y, v3_view_forward.z);
+
+    // the rotation moved, so the matrix owes an update
+    result.updateMatrix();
+}
+
+/**
+ * Move a controller's target `distance` world units along where its view faces: `right` and
+ * `forward` pick the direction in the view's own frame, so a target can be flown up or down a slope.
+ * A diagonal travels the same distance as a straight move.
+ *
+ * The viewer's right is the negated X axis of the view rotation, as {@link pan} explains.
+ *
+ * @param {TopDownCameraController} controller its {@link TopDownCameraController#target} is moved
+ * @param {number} right −1 to 1, positive to the viewer's right
+ * @param {number} forward −1 to 1, positive into the screen
+ * @param {number} distance world units
+ */
+export function top_down_truck_in_view(controller, right, forward, distance) {
+    top_down_view_rotation(q_view, controller);
+
+    truck_in_rotation(controller.target, q_view, right, forward, distance);
+}
+
+/**
+ * Move a controller's target `distance` world units across the ground, along the way its view is
+ * turned: `forward` is the view's heading with the pitch taken out, so it keeps its full speed
+ * however steeply the view looks down, straight down included, and never moves the target off the
+ * ground. A diagonal travels the same distance as a straight move.
+ *
+ * @param {TopDownCameraController} controller its {@link TopDownCameraController#target} is moved
+ * @param {number} right −1 to 1, positive to the viewer's right
+ * @param {number} forward −1 to 1, positive along the view's heading
+ * @param {number} distance world units
+ */
+export function top_down_truck_on_ground(controller, right, forward, distance) {
+    q_view.fromEulerAnglesZYX(0, controller.yaw, 0);
+
+    truck_in_rotation(controller.target, q_view, right, forward, distance);
+}
+
+/**
+ * @param {Vector3} target
+ * @param {Quaternion} rotation
+ * @param {number} right
+ * @param {number} forward
+ * @param {number} distance
+ */
+function truck_in_rotation(target, rotation, right, forward, distance) {
+    const length = Math.hypot(right, forward);
+
+    if (length === 0) {
+        return;
+    }
+
+    const step = distance / length;
+
+    v3_view_right.copy(Vector3.right);
+    v3_view_right.applyQuaternion(rotation);
+
+    v3_view_forward.copy(Vector3.forward);
+    v3_view_forward.applyQuaternion(rotation);
+
+    // the viewer's right is the negated X axis
+    const along_right = -right * step;
+    const along_forward = forward * step;
+
+    target._add(
+        v3_view_right.x * along_right + v3_view_forward.x * along_forward,
+        v3_view_right.y * along_right + v3_view_forward.y * along_forward,
+        v3_view_right.z * along_right + v3_view_forward.z * along_forward
+    );
+}
+
 
 class TopDownCameraController {
     target = new Vector3();
@@ -169,9 +246,19 @@ class TopDownCameraController {
 
         m4_euler_angles(angles, m4, 2, 1, 0)
 
-        this.pitch = angles[2];
-        this.yaw = angles[1];
-        this.roll = angles[0];
+        if (Math.abs(angles[2]) > Math.PI / 2) {
+            // The decomposition holds yaw within ±π/2 and, for about half of all views, answers with the
+            // view turned over — pitched past the vertical and rolled half a turn. That is the same
+            // rotation as the upright one, half a turn of yaw away, which is the pose an orbit expects:
+            // pitch within ±π/2 and, for an up of +Y, no roll.
+            this.pitch = normalize_angle_rad(angles[2] + Math.PI);
+            this.yaw = normalize_angle_rad(Math.PI - angles[1]);
+            this.roll = normalize_angle_rad(angles[0] + Math.PI);
+        } else {
+            this.pitch = angles[2];
+            this.yaw = angles[1];
+            this.roll = angles[0];
+        }
 
         this.distance = v3_distance(eye[0], eye[1], eye[2], target[0], target[1], target[2]);
 
@@ -294,7 +381,6 @@ class TopDownCameraController {
 TopDownCameraController.typeName = "TopDownCameraController";
 
 TopDownCameraController.pan = pan;
-TopDownCameraController.rotate = rotate_from_view;
 
 export default TopDownCameraController;
 

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.d.ts

@@ -1,9 +1,3 @@
-/**
- *
- * @param {TopDownCameraController} control
- * @param {Transform64} result
- */
-export function computeTopDownTransform(control: TopDownCameraController, result: Transform64): void;
 /**
  *
  * @param {Transform64} transform
@@ -12,8 +6,8 @@ export function computeTopDownTransform(control: TopDownCameraController, result
  */
 export function setCameraControllerFromTransform(transform: Transform64, controller: TopDownCameraController, distance?: number): void;
 export default TopDownCameraControllerSystem;
-import TopDownCameraController from './TopDownCameraController.js';
 import { Transform64 } from '../../../../ecs/transform/Transform64.js';
+import TopDownCameraController from './TopDownCameraController.js';
 declare class TopDownCameraControllerSystem extends System<any> {
     constructor();
     enabled: ObservedValue<boolean>;

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TopDownCameraControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js"],"names":[],"mappings":"AAqFA;;;;GAIG;AACH,iDAHW,uBAAuB,UACvB,WAAW,QA0BrB;AAED;;;;;GAKG;AACH,4DAJW,WAAW,cACX,uBAAuB,aACvB,MAAM,QAahB;;oCA1H+D,8BAA8B;4BAHlE,0CAA0C;AAoBtE;;IACI,gCAAkC;IAClC,iDAAyC;IACzC,mEAEE;IAEF;;;;;OAKG;IACH,8BA0BC;IAED,6BAaC;CACJ;uBA9EsB,2BAA2B;0BAHxB,4CAA4C;4CAE1B,0DAA0D"}
+{"version":3,"file":"TopDownCameraControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js"],"names":[],"mappings":"AAgFA;;;;;GAKG;AACH,4DAJW,WAAW,cACX,uBAAuB,aACvB,MAAM,QAahB;;4BA1F2B,0CAA0C;oCAGL,8BAA8B;AAa/F;;IACI,gCAAkC;IAClC,iDAAyC;IACzC,mEAEE;IAEF;;;;;OAKG;IACH,8BA0BC;IAED,6BAaC;CACJ;uBA1EsB,2BAA2B;0BAHxB,4CAA4C;4CAE1B,0DAA0D"}

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js

@@ -1,5 +1,4 @@
 import Vector3 from "../../../../../core/geom/Vector3.js";
-import { clamp } from "../../../../../core/math/clamp.js";
 import ObservedValue from "../../../../../core/model/ObservedValue.js";
 import { ResourceAccessKind } from "../../../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../../../core/model/ResourceAccessSpecification.js";
@@ -9,14 +8,10 @@ import { t64_read_pose_array } from "../../../../ecs/transform/t64_read_pose_arr
 import { Transform64 } from '../../../../ecs/transform/Transform64.js';
 
 
-import TopDownCameraController, { top_down_view_rotation } from './TopDownCameraController.js';
-import Quaternion from "../../../../../core/geom/Quaternion.js";
+import TopDownCameraController, { computeTopDownTransform } from './TopDownCameraController.js';
 import { v3_quaternion_apply } from "../../../../../core/geom/vec3/v3_quaternion_apply.js";
 
 
-const v3_scratch = new Vector3();
-const q_scratch = new Quaternion();
-
 /**
  * A camera's translation and rotation before and after its controller rewrites them, to tell a move from
  * a rewrite of the same pose.
@@ -83,37 +78,6 @@ class TopDownCameraControllerSystem extends System {
     }
 }
 
-/**
- *
- * @param {TopDownCameraController} control
- * @param {Transform64} result
- */
-export function computeTopDownTransform(control, result) {
-
-    //clamp the distance
-    const distance = clamp(control.distance, control.distanceMin, control.distanceMax);
-    const target = control.target;
-
-    // compute rotation. The transform holds its rotation as four numbers rather than a Quaternion,
-    // so the euler composition runs in a scratch and lands in the transform afterwards.
-    top_down_view_rotation(q_scratch, control);
-
-    result.setRotation(q_scratch.x, q_scratch.y, q_scratch.z, q_scratch.w);
-
-    // compute camera position
-    v3_scratch.copy(Vector3.forward);
-    v3_scratch.applyQuaternion(q_scratch);
-
-    v3_scratch.multiplyScalar(-distance);
-
-    v3_scratch.add(target);
-
-    result.setTranslation(v3_scratch.x, v3_scratch.y, v3_scratch.z);
-
-    // the rotation moved, so the matrix owes an update
-    result.updateMatrix();
-}
-
 /**
  *
  * @param {Transform64} transform

package/src/engine/graphics/ecs/water/Water.d.ts

@@ -3,6 +3,14 @@ export default Water;
  * Optical properties of an authored water surface. MeshletGeometry supplies its shape and
  * Transform64 supplies its placement.
  *
+ * **The geometry is the body's area: author it with the fewest triangles that cover it.** The renderer tessellates
+ * the surface on the GPU from the view, so subdividing a flat area adds no detail to the waves, and it costs every
+ * frame. The lattice is cut against each authored triangle: every lattice cell an internal edge crosses is clipped
+ * and drawn once per triangle it touches, and no 8 × 8 patch spans an internal edge. Measured on an integrated GPU
+ * (the many-waters example at 1280 × 720), a pond and a stream authored as six-segment grids (3,012 triangles) drew
+ * 669,324 lattice vertices a pass where two triangles each drew 146,772, and cost 11.65 ms more a frame. Use more
+ * triangles only where the area needs them: its outline, a hole, a crease, a change of normal.
+ *
  * Everything optical here is physical and in SI units (WATER_OPTICS_PLAN_2026_10_02.md §7.1): the
  * index of refraction, the micro-roughness of the surface, and what fills the body — a
  * {@link ParticipatingMedium}, the same description the path tracer, fog and glass read. Presets

package/src/engine/graphics/ecs/water/Water.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Water.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/Water.js"],"names":[],"mappings":";AAUA;;;;;;;;;;;;;;;GAeG;AACH;IA6CI,0BASC;IArDD;;;OAGG;IACH,KAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,WAFU,OAAO,CAEa;IAE9B;;;;;;;OAOG;IACH,oBAFU,eAAe,CAEuB;IAEhD,8CAA8C;IAC9C,kBAAyB;IAWzB,yCAAyC;IACzC,uCAMC;IAbD;;;;OAIG;IACH,kCAAqC;IAqBrC,0BAoBC;IAED;;;;;MAOC;;CACJ;;;;oBA/GmB,kCAAkC;4BAC1B,2CAA2C;mBAFpD,0CAA0C;oCAGzB,0DAA0D"}
+{"version":3,"file":"Water.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/water/Water.js"],"names":[],"mappings":";AAUA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA6CI,0BASC;IArDD;;;OAGG;IACH,KAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,WAFU,OAAO,CAEa;IAE9B;;;;;;;OAOG;IACH,oBAFU,eAAe,CAEuB;IAEhD,8CAA8C;IAC9C,kBAAyB;IAWzB,yCAAyC;IACzC,uCAMC;IAbD;;;;OAIG;IACH,kCAAqC;IAqBrC,0BAoBC;IAED;;;;;MAOC;;CACJ;;;;oBAvHmB,kCAAkC;4BAC1B,2CAA2C;mBAFpD,0CAA0C;oCAGzB,0DAA0D"}