@terraware/web-components 5.0.27-rc.0 → 5.0.27

package/components/VirtualWalkthrough/vr-annotation-scroll.js

@@ -1,15 +1,33 @@
+/** Deflection the stick must pass before the text moves, so a resting thumb doesn't drift it. */
 const SCROLL_DEADZONE = 0.15;
+
+/** Canvas px per second at full deflection. */
 const SCROLL_SPEED = 1200;
-const readScrollAxis = (inputSource)=>{
-    const axes = inputSource.gamepad?.axes;
-    if ('right' !== inputSource.handedness || !axes || axes.length < 4) return 0;
-    return axes[3];
+/**
+ * Thumbstick Y for a source that can scroll the panel. Only the right hand scrolls: the left
+ * stick drives locomotion, and right-stick Y is free because snap-vertical is turned off.
+ * Hand-tracked sources report a gamepad with no axes, which would read as NaN.
+ */
+const readScrollAxis = inputSource => {
+  const axes = inputSource.gamepad?.axes;
+  if (inputSource.handedness !== 'right' || !axes || axes.length < 4) {
+    return 0;
+  }
+  return axes[3];
 };
-const nextScrollY = (scrollY, axisY, dt, maxScroll)=>{
-    const magnitude = Math.abs(axisY);
-    if (magnitude <= SCROLL_DEADZONE) return Math.min(Math.max(scrollY, 0), maxScroll);
-    const ramped = (magnitude - SCROLL_DEADZONE) / (1 - SCROLL_DEADZONE);
-    const delta = -Math.sign(axisY) * ramped * SCROLL_SPEED * dt;
-    return Math.min(Math.max(scrollY + delta, 0), maxScroll);
+
+/**
+ * Advances the scroll position for one frame of stick deflection, ramping from a standstill at
+ * the deadzone edge. A forward push reports negative Y and moves further into the text.
+ */
+const nextScrollY = (scrollY, axisY, dt, maxScroll) => {
+  const magnitude = Math.abs(axisY);
+  if (magnitude <= SCROLL_DEADZONE) {
+    return Math.min(Math.max(scrollY, 0), maxScroll);
+  }
+  const ramped = (magnitude - SCROLL_DEADZONE) / (1 - SCROLL_DEADZONE);
+  const delta = -Math.sign(axisY) * ramped * SCROLL_SPEED * dt;
+  return Math.min(Math.max(scrollY + delta, 0), maxScroll);
 };
+
 export { SCROLL_DEADZONE, SCROLL_SPEED, nextScrollY, readScrollAxis };

package/components/VirtualWalkthrough/walkthrough-camera.js

@@ -1,223 +1,348 @@
-import { Quat, Script, Vec3, math } from "playcanvas";
-import { computeGroundPlane, yOnPlane } from "./groundPlane.js";
+import { Quat, Vec3, Script, math } from 'playcanvas';
+import { computeGroundPlane, yOnPlane } from './groundPlane.js';
+
+/**
+ * First-person walkthrough camera for Gaussian Splat scenes.
+ *
+ * - Pointer drag (mouse or touch) rotates the camera (pitch + yaw) with damping
+ *   matching PlayCanvas CameraControls' rotateDamping=0.98.
+ * - WASD / arrow keys move along the XZ plane using yaw-only direction, so
+ *   movement is always horizontal regardless of where the camera is pointing.
+ * - Mouse wheel moves forward/backward along the XZ plane.
+ * - Y position is clamped between boundsMin.y and boundsMax.y; set them equal
+ *   to lock vertical position entirely.
+ * - Exposes reset() and focusPoint to stay compatible with useCameraPosition.
+ *
+ * The pose is written to the camera under this script's entity rather than to the entity itself, so
+ * mounting it on the walkthrough's rig drives whichever camera the rig is holding — one the viewer
+ * brought, or one it adopted from the host scene. Mounted straight onto a camera entity it still
+ * drives that entity, which `findComponent` resolves to itself.
+ */
+
 const _quat = new Quat();
 const _flatForward = new Vec3();
 const _flatRight = new Vec3();
-const dampRate = (damping, dt)=>1 - Math.pow(damping, 1000 * dt);
+
+/** Frame-rate-independent damping lerp rate — matches PlayCanvas CameraControls. */
+const dampRate = (damping, dt) => 1 - Math.pow(damping, dt * 1000);
+
+/** Below this angular delta (degrees) the damped lerp snaps to its target and stops writing. */
 const ANGLE_EPSILON = 1e-3;
+
+/** Below this positional delta (world units) an idle frame skips the transform write. */
 const POSITION_EPSILON = 1e-5;
 class WalkthroughCamera extends Script {
-    static scriptName = 'walkthroughCamera';
-    moveSpeed = 4.5;
-    moveFastSpeed = 7.5;
-    moveSlowSpeed = 2.25;
-    lookSensitivity = 0.1;
-    rotateDamping = 0.98;
-    pitchMin = -85;
-    pitchMax = 85;
-    scrollSpeed = 0.001;
-    boundsCenter = new Vec3(0, 0, 0);
-    boundsRadius = 10;
-    freeFly = false;
-    enableFly = true;
-    averageCameraHeight = 0;
-    groundPlane = [];
-    _pitch = 0;
-    _yaw = 0;
-    _targetPitch = 0;
-    _targetYaw = 0;
-    _isDragging = false;
-    _lastX = 0;
-    _lastY = 0;
-    _scrollDelta = 0;
-    _keys = {};
-    _removeListeners = [];
-    _camera = null;
-    _planeNormal = new Vec3(0, 1, 0);
-    _planePoint = new Vec3(0, 0, 0);
-    _hasGroundPlane = false;
-    _posedCamera() {
-        this._camera ??= this.entity.findComponent('camera')?.entity ?? null;
-        return this._camera;
+  static scriptName = 'walkthroughCamera';
+  moveSpeed = 4.5;
+
+  /** @attribute */
+  moveFastSpeed = 7.5;
+
+  /** @attribute */
+  moveSlowSpeed = 2.25;
+
+  /** @attribute */
+  lookSensitivity = 0.1;
+
+  /** @attribute */
+  rotateDamping = 0.98;
+
+  /** @attribute */
+  pitchMin = -85;
+
+  /** @attribute */
+  pitchMax = 85;
+
+  /** @attribute */
+  scrollSpeed = 0.001;
+
+  /** @attribute */
+  boundsCenter = new Vec3(0, 0, 0);
+
+  /** @attribute */
+  boundsRadius = 10;
+
+  /** @attribute */
+  freeFly = false;
+
+  /** @attribute */
+  enableFly = true;
+
+  /** @attribute */
+  averageCameraHeight = 0;
+
+  /**
+   * Three world-space points defining the ground plane.
+   * When provided, the camera Y position is derived from this plane during non-freeFly movement.
+   *
+   * Not a React prop — must be set directly on the script instance via useEffect. The @playcanvas/react
+   * Script component is wrapped in memo() whose shallowEquals comparator returns early on the first prop
+   * with a .equals() method (Vec3), so any prop listed after boundsCenter is never compared and the
+   * component won't re-render when it changes. Set via:
+   *   cameraRoot.script.walkthroughCamera.groundPlane = points
+   * Should be updated if shallowEquals is fixed (see https://github.com/playcanvas/react/pull/298)
+   */
+  groundPlane = [];
+
+  // Current (damped) angles applied to the entity each frame.
+  _pitch = 0;
+  _yaw = 0;
+
+  // Target angles — updated immediately on pointer move, entity lerps toward them.
+  _targetPitch = 0;
+  _targetYaw = 0;
+  _isDragging = false;
+  _lastX = 0;
+  _lastY = 0;
+  _scrollDelta = 0;
+  _keys = {};
+  _removeListeners = [];
+
+  // The camera being posed, resolved lazily. Held until it exists: a camera adopted from the host
+  // scene is reparented into the rig by an effect that runs after the scripts are mounted.
+  _camera = null;
+
+  // Cached plane derived from groundPlane attribute. Computed once when 3 points become available.
+  _planeNormal = new Vec3(0, 1, 0);
+  _planePoint = new Vec3(0, 0, 0);
+  _hasGroundPlane = false;
+
+  /**
+   * The camera to pose, or null while there is none to pose. The entity this script is mounted on is
+   * never posed in its place: on the walkthrough that is the rig, which is the frame an XR session
+   * is measured from and whose height the session's floor is taken from.
+   */
+  _posedCamera() {
+    this._camera ??= this.entity.findComponent('camera')?.entity ?? null;
+    return this._camera;
+  }
+  _syncGroundPlane() {
+    if (this._hasGroundPlane || this.groundPlane.length < 3) {
+      return;
     }
-    _syncGroundPlane() {
-        if (this._hasGroundPlane || this.groundPlane.length < 3) return;
-        const plane = computeGroundPlane(this.groundPlane);
-        if (!plane) return;
-        this._planeNormal.copy(plane.normal);
-        this._planePoint.copy(plane.point);
-        this._hasGroundPlane = true;
+    const plane = computeGroundPlane(this.groundPlane);
+    if (!plane) {
+      return;
     }
-    initialize() {
-        this._pitch = 0;
-        this._yaw = 0;
-        this._targetPitch = 0;
-        this._targetYaw = 0;
-        const canvas = this.app.graphicsDevice.canvas;
-        const onPointerDown = (e)=>{
-            this._isDragging = true;
-            this._lastX = e.clientX;
-            this._lastY = e.clientY;
-            try {
-                canvas.setPointerCapture(e.pointerId);
-            } catch  {}
-        };
-        const onPointerMove = (e)=>{
-            if (!this._isDragging) return;
-            const dx = e.clientX - this._lastX;
-            const dy = e.clientY - this._lastY;
-            this._lastX = e.clientX;
-            this._lastY = e.clientY;
-            this._targetYaw -= dx * this.lookSensitivity;
-            this._targetPitch = math.clamp(this._targetPitch - dy * this.lookSensitivity, this.pitchMin, this.pitchMax);
-        };
-        const onPointerUp = (e)=>{
-            this._isDragging = false;
-            try {
-                canvas.releasePointerCapture(e.pointerId);
-            } catch  {}
-        };
-        const onWheel = (e)=>{
-            e.preventDefault();
-            this._scrollDelta += e.deltaY;
-        };
-        const onContextMenu = (e)=>e.preventDefault();
-        const onKeyDown = (e)=>{
-            this._keys[e.code] = true;
-        };
-        const onKeyUp = (e)=>{
-            this._keys[e.code] = false;
-        };
-        const onBlur = ()=>{
-            this._keys = {};
-            this._isDragging = false;
-        };
-        canvas.addEventListener('pointerdown', onPointerDown);
-        canvas.addEventListener('pointermove', onPointerMove);
-        canvas.addEventListener('pointerup', onPointerUp);
-        canvas.addEventListener('pointercancel', onPointerUp);
-        canvas.addEventListener('wheel', onWheel, {
-            passive: false
-        });
-        canvas.addEventListener('contextmenu', onContextMenu);
-        window.addEventListener('keydown', onKeyDown);
-        window.addEventListener('keyup', onKeyUp);
-        window.addEventListener('blur', onBlur);
-        this._removeListeners = [
-            ()=>canvas.removeEventListener('pointerdown', onPointerDown),
-            ()=>canvas.removeEventListener('pointermove', onPointerMove),
-            ()=>canvas.removeEventListener('pointerup', onPointerUp),
-            ()=>canvas.removeEventListener('pointercancel', onPointerUp),
-            ()=>canvas.removeEventListener('wheel', onWheel),
-            ()=>canvas.removeEventListener('contextmenu', onContextMenu),
-            ()=>window.removeEventListener('keydown', onKeyDown),
-            ()=>window.removeEventListener('keyup', onKeyUp),
-            ()=>window.removeEventListener('blur', onBlur)
-        ];
+    this._planeNormal.copy(plane.normal);
+    this._planePoint.copy(plane.point);
+    this._hasGroundPlane = true;
+  }
+  initialize() {
+    // Start horizontal; reset() will set the correct pose once splat data loads.
+    this._pitch = 0;
+    this._yaw = 0;
+    this._targetPitch = 0;
+    this._targetYaw = 0;
+    const canvas = this.app.graphicsDevice.canvas;
+    const onPointerDown = e => {
+      this._isDragging = true;
+      this._lastX = e.clientX;
+      this._lastY = e.clientY;
+      try {
+        canvas.setPointerCapture(e.pointerId);
+      } catch {
+        // ignore — canvas may not be focusable yet
+      }
+    };
+    const onPointerMove = e => {
+      if (!this._isDragging) {
+        return;
+      }
+      const dx = e.clientX - this._lastX;
+      const dy = e.clientY - this._lastY;
+      this._lastX = e.clientX;
+      this._lastY = e.clientY;
+      this._targetYaw -= dx * this.lookSensitivity;
+      this._targetPitch = math.clamp(this._targetPitch - dy * this.lookSensitivity, this.pitchMin, this.pitchMax);
+    };
+    const onPointerUp = e => {
+      this._isDragging = false;
+      try {
+        canvas.releasePointerCapture(e.pointerId);
+      } catch {
+        // ignore
+      }
+    };
+    const onWheel = e => {
+      e.preventDefault();
+      this._scrollDelta += e.deltaY;
+    };
+    const onContextMenu = e => e.preventDefault();
+    const onKeyDown = e => {
+      this._keys[e.code] = true;
+    };
+    const onKeyUp = e => {
+      this._keys[e.code] = false;
+    };
+    const onBlur = () => {
+      this._keys = {};
+      this._isDragging = false;
+    };
+    canvas.addEventListener('pointerdown', onPointerDown);
+    canvas.addEventListener('pointermove', onPointerMove);
+    canvas.addEventListener('pointerup', onPointerUp);
+    canvas.addEventListener('pointercancel', onPointerUp);
+    canvas.addEventListener('wheel', onWheel, {
+      passive: false
+    });
+    canvas.addEventListener('contextmenu', onContextMenu);
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+    window.addEventListener('blur', onBlur);
+    this._removeListeners = [() => canvas.removeEventListener('pointerdown', onPointerDown), () => canvas.removeEventListener('pointermove', onPointerMove), () => canvas.removeEventListener('pointerup', onPointerUp), () => canvas.removeEventListener('pointercancel', onPointerUp), () => canvas.removeEventListener('wheel', onWheel), () => canvas.removeEventListener('contextmenu', onContextMenu), () => window.removeEventListener('keydown', onKeyDown), () => window.removeEventListener('keyup', onKeyUp), () => window.removeEventListener('blur', onBlur)];
+  }
+
+  /**
+   * Position the camera at `position` looking toward `focus`.
+   * Compatible with the useCameraPosition hook's reset() call.
+   */
+  reset(focus, position) {
+    const camera = this._posedCamera();
+    camera?.setPosition(position);
+    const dx = focus.x - position.x;
+    const dy = focus.y - position.y;
+    const dz = focus.z - position.z;
+    const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (len > 0) {
+      // PlayCanvas uses right-handed CCW Y rotation: forward = (-sinθ, 0, -cosθ),
+      // so to look toward (dx, 0, dz): θ = atan2(-dx, -dz).
+      this._yaw = Math.atan2(-dx, -dz) * (180 / Math.PI);
+      this._pitch = Math.atan2(-dy, Math.sqrt(dx * dx + dz * dz)) * (180 / Math.PI);
+      this._pitch = math.clamp(this._pitch, this.pitchMin, this.pitchMax);
     }
-    reset(focus, position) {
-        const camera = this._posedCamera();
-        camera?.setPosition(position);
-        const dx = focus.x - position.x;
-        const dy = focus.y - position.y;
-        const dz = focus.z - position.z;
-        const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
-        if (len > 0) {
-            this._yaw = 180 / Math.PI * Math.atan2(-dx, -dz);
-            this._pitch = 180 / Math.PI * Math.atan2(-dy, Math.sqrt(dx * dx + dz * dz));
-            this._pitch = math.clamp(this._pitch, this.pitchMin, this.pitchMax);
-        }
-        this._targetPitch = this._pitch;
-        this._targetYaw = this._yaw;
-        camera?.setEulerAngles(this._pitch, this._yaw, 0);
+
+    // Snap targets so there's no damped drift from the previous pose.
+    this._targetPitch = this._pitch;
+    this._targetYaw = this._yaw;
+    camera?.setEulerAngles(this._pitch, this._yaw, 0);
+  }
+  get currentYaw() {
+    return this._targetYaw;
+  }
+  get currentPitch() {
+    return this._targetPitch;
+  }
+
+  /**
+   * Orbit the camera by `yawDelta` degrees around `boundsCenter`.
+   * Called by AutoRotator
+   */
+  orbitStep(yawDelta) {
+    this._syncGroundPlane();
+    const camera = this._posedCamera();
+    if (!camera) {
+      return;
     }
-    get currentYaw() {
-        return this._targetYaw;
+    const pos = camera.getPosition();
+    const dx = pos.x - this.boundsCenter.x;
+    const dz = pos.z - this.boundsCenter.z;
+    const radius = Math.sqrt(dx * dx + dz * dz) || this.boundsRadius * 0.5;
+    const currentAngle = Math.atan2(dz, dx);
+    const newAngle = currentAngle + yawDelta * Math.PI / 180;
+    const nx = this.boundsCenter.x + radius * Math.cos(newAngle);
+    const nz = this.boundsCenter.z + radius * Math.sin(newAngle);
+    const ny = this._hasGroundPlane ? yOnPlane(nx, nz, this._planeNormal, this._planePoint, this.boundsCenter.y) + this.averageCameraHeight : this.boundsCenter.y;
+    camera.setPosition(nx, ny, nz);
+    const faceDx = this.boundsCenter.x - nx;
+    const faceDz = this.boundsCenter.z - nz;
+    this._yaw = Math.atan2(-faceDx, -faceDz) * (180 / Math.PI);
+    this._targetYaw = this._yaw;
+    camera.setEulerAngles(this._pitch, this._yaw, 0);
+  }
+
+  /**
+   * Returns the point directly in front of the camera.
+   * Compatible with the useCameraPosition hook's focusPoint read.
+   */
+  get focusPoint() {
+    const pos = (this._posedCamera() ?? this.entity).getPosition();
+    _quat.setFromEulerAngles(this._pitch, this._yaw, 0);
+    _quat.transformVector(Vec3.FORWARD, _flatForward);
+    return new Vec3(pos.x + _flatForward.x, pos.y + _flatForward.y, pos.z + _flatForward.z);
+  }
+  update(dt) {
+    this._syncGroundPlane();
+    const camera = this._posedCamera();
+    if (!camera) {
+      return;
     }
-    get currentPitch() {
-        return this._targetPitch;
+
+    // Lerp current angles toward targets using the same damping as CameraControls.
+    // Snap to the target once within ANGLE_EPSILON so the asymptotic lerp actually
+    // settles instead of emitting ever-smaller micro-rotations for ~0.4s after each
+    // drag. The gsplat sorter guards its own re-sorts with an epsilon, so this mainly
+    // trims that sort tail; it does not affect per-frame rendering (autoRender does).
+    const r = dampRate(this.rotateDamping, dt);
+    let nextPitch = this._pitch + (this._targetPitch - this._pitch) * r;
+    let nextYaw = this._yaw + (this._targetYaw - this._yaw) * r;
+    if (Math.abs(this._targetPitch - nextPitch) < ANGLE_EPSILON) {
+      nextPitch = this._targetPitch;
     }
-    orbitStep(yawDelta) {
-        this._syncGroundPlane();
-        const camera = this._posedCamera();
-        if (!camera) return;
-        const pos = camera.getPosition();
-        const dx = pos.x - this.boundsCenter.x;
-        const dz = pos.z - this.boundsCenter.z;
-        const radius = Math.sqrt(dx * dx + dz * dz) || 0.5 * this.boundsRadius;
-        const currentAngle = Math.atan2(dz, dx);
-        const newAngle = currentAngle + yawDelta * Math.PI / 180;
-        const nx = this.boundsCenter.x + radius * Math.cos(newAngle);
-        const nz = this.boundsCenter.z + radius * Math.sin(newAngle);
-        const ny = this._hasGroundPlane ? yOnPlane(nx, nz, this._planeNormal, this._planePoint, this.boundsCenter.y) + this.averageCameraHeight : this.boundsCenter.y;
-        camera.setPosition(nx, ny, nz);
-        const faceDx = this.boundsCenter.x - nx;
-        const faceDz = this.boundsCenter.z - nz;
-        this._yaw = 180 / Math.PI * Math.atan2(-faceDx, -faceDz);
-        this._targetYaw = this._yaw;
-        camera.setEulerAngles(this._pitch, this._yaw, 0);
+    if (Math.abs(this._targetYaw - nextYaw) < ANGLE_EPSILON) {
+      nextYaw = this._targetYaw;
     }
-    get focusPoint() {
-        const pos = (this._posedCamera() ?? this.entity).getPosition();
-        _quat.setFromEulerAngles(this._pitch, this._yaw, 0);
-        _quat.transformVector(Vec3.FORWARD, _flatForward);
-        return new Vec3(pos.x + _flatForward.x, pos.y + _flatForward.y, pos.z + _flatForward.z);
+    nextPitch = math.clamp(nextPitch, this.pitchMin, this.pitchMax);
+
+    // Only write the rotation when it actually changed, to avoid needlessly dirtying
+    // the scene node once the angles have settled.
+    const anglesChanged = nextPitch !== this._pitch || nextYaw !== this._yaw;
+    this._pitch = nextPitch;
+    this._yaw = nextYaw;
+    if (anglesChanged) {
+      camera.setEulerAngles(this._pitch, this._yaw, 0);
     }
-    update(dt) {
-        this._syncGroundPlane();
-        const camera = this._posedCamera();
-        if (!camera) return;
-        const r = dampRate(this.rotateDamping, dt);
-        let nextPitch = this._pitch + (this._targetPitch - this._pitch) * r;
-        let nextYaw = this._yaw + (this._targetYaw - this._yaw) * r;
-        if (Math.abs(this._targetPitch - nextPitch) < ANGLE_EPSILON) nextPitch = this._targetPitch;
-        if (Math.abs(this._targetYaw - nextYaw) < ANGLE_EPSILON) nextYaw = this._targetYaw;
-        nextPitch = math.clamp(nextPitch, this.pitchMin, this.pitchMax);
-        const anglesChanged = nextPitch !== this._pitch || nextYaw !== this._yaw;
-        this._pitch = nextPitch;
-        this._yaw = nextYaw;
-        if (anglesChanged) camera.setEulerAngles(this._pitch, this._yaw, 0);
-        const pos = camera.getPosition();
-        let nx = pos.x;
-        let ny = pos.y;
-        let nz = pos.z;
-        if (this.enableFly) {
-            const fast = this._keys.ShiftLeft || this._keys.ShiftRight;
-            const slow = this._keys.ControlLeft || this._keys.ControlRight;
-            const speed = (fast ? this.moveFastSpeed : slow ? this.moveSlowSpeed : this.moveSpeed) * dt;
-            const fwd = (this._keys.KeyW || this._keys.ArrowUp ? 1 : 0) - (this._keys.KeyS || this._keys.ArrowDown ? 1 : 0);
-            const strafe = (this._keys.KeyD || this._keys.ArrowRight ? 1 : 0) - (this._keys.KeyA || this._keys.ArrowLeft ? 1 : 0);
-            const scrollFwd = -this._scrollDelta * this.scrollSpeed;
-            if (0 !== fwd || 0 !== strafe || 0 !== scrollFwd) {
-                _quat.setFromEulerAngles(0, this._yaw, 0);
-                _quat.transformVector(Vec3.FORWARD, _flatForward);
-                _quat.transformVector(Vec3.RIGHT, _flatRight);
-                nx += _flatForward.x * (fwd * speed + scrollFwd) + _flatRight.x * strafe * speed;
-                nz += _flatForward.z * (fwd * speed + scrollFwd) + _flatRight.z * strafe * speed;
-            }
-            if (this.freeFly) {
-                const up = (this._keys.KeyE ? 1 : 0) - (this._keys.KeyQ ? 1 : 0);
-                if (0 !== up) ny += up * speed;
-            }
-        }
-        this._scrollDelta = 0;
-        if (!this.freeFly) {
-            const cdx = nx - this.boundsCenter.x;
-            const cdz = nz - this.boundsCenter.z;
-            const dist = Math.sqrt(cdx * cdx + cdz * cdz);
-            if (dist > this.boundsRadius) {
-                const scale = this.boundsRadius / dist;
-                nx = this.boundsCenter.x + cdx * scale;
-                nz = this.boundsCenter.z + cdz * scale;
-            }
+    const pos = camera.getPosition();
+    let nx = pos.x;
+    let ny = pos.y;
+    let nz = pos.z;
+    if (this.enableFly) {
+      const fast = this._keys.ShiftLeft || this._keys.ShiftRight;
+      const slow = this._keys.ControlLeft || this._keys.ControlRight;
+      const speed = (fast ? this.moveFastSpeed : slow ? this.moveSlowSpeed : this.moveSpeed) * dt;
+      const fwd = (this._keys.KeyW || this._keys.ArrowUp ? 1 : 0) - (this._keys.KeyS || this._keys.ArrowDown ? 1 : 0);
+      const strafe = (this._keys.KeyD || this._keys.ArrowRight ? 1 : 0) - (this._keys.KeyA || this._keys.ArrowLeft ? 1 : 0);
+      const scrollFwd = -this._scrollDelta * this.scrollSpeed;
+      if (fwd !== 0 || strafe !== 0 || scrollFwd !== 0) {
+        // Use yaw-only rotation so movement is always horizontal.
+        _quat.setFromEulerAngles(0, this._yaw, 0);
+        _quat.transformVector(Vec3.FORWARD, _flatForward);
+        _quat.transformVector(Vec3.RIGHT, _flatRight);
+        nx += _flatForward.x * (fwd * speed + scrollFwd) + _flatRight.x * strafe * speed;
+        nz += _flatForward.z * (fwd * speed + scrollFwd) + _flatRight.z * strafe * speed;
+      }
+      if (this.freeFly) {
+        const up = (this._keys.KeyE ? 1 : 0) - (this._keys.KeyQ ? 1 : 0);
+        if (up !== 0) {
+          ny += up * speed;
         }
-        const groundY = this._hasGroundPlane ? yOnPlane(nx, nz, this._planeNormal, this._planePoint, this.boundsCenter.y) + this.averageCameraHeight : this.boundsCenter.y;
-        const targetY = this.freeFly ? ny : groundY;
-        if (Math.abs(nx - pos.x) > POSITION_EPSILON || Math.abs(targetY - pos.y) > POSITION_EPSILON || Math.abs(nz - pos.z) > POSITION_EPSILON) camera.setPosition(nx, targetY, nz);
+      }
+    }
+    this._scrollDelta = 0;
+    if (!this.freeFly) {
+      // Circular XZ clamp: project back onto the circle edge if outside.
+      const cdx = nx - this.boundsCenter.x;
+      const cdz = nz - this.boundsCenter.z;
+      const dist = Math.sqrt(cdx * cdx + cdz * cdz);
+      if (dist > this.boundsRadius) {
+        const scale = this.boundsRadius / dist;
+        nx = this.boundsCenter.x + cdx * scale;
+        nz = this.boundsCenter.z + cdz * scale;
+      }
     }
-    destroy() {
-        this._removeListeners.forEach((fn)=>fn());
-        this._removeListeners = [];
+    const groundY = this._hasGroundPlane ? yOnPlane(nx, nz, this._planeNormal, this._planePoint, this.boundsCenter.y) + this.averageCameraHeight : this.boundsCenter.y;
+    const targetY = this.freeFly ? ny : groundY;
+    // Only write the position when it actually moved. This keeps the scene node clean on
+    // idle frames; note it does not stop per-frame rasterization — while autoRender is on
+    // the app renders every frame regardless of whether the transform changed.
+    if (Math.abs(nx - pos.x) > POSITION_EPSILON || Math.abs(targetY - pos.y) > POSITION_EPSILON || Math.abs(nz - pos.z) > POSITION_EPSILON) {
+      camera.setPosition(nx, targetY, nz);
     }
+  }
+  destroy() {
+    this._removeListeners.forEach(fn => fn());
+    this._removeListeners = [];
+  }
 }
+
 export { WalkthroughCamera };