@terraware/web-components 5.0.27 → 5.1.0

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

@@ -1,33 +1,15 @@
-/** 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;
-/**
- * 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 readScrollAxis = (inputSource)=>{
+    const axes = inputSource.gamepad?.axes;
+    if ('right' !== inputSource.handedness || !axes || axes.length < 4) return 0;
+    return axes[3];
 };
-
-/**
- * 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);
+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,348 +1,223 @@
-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.
- */
-
+import { Quat, Script, Vec3, math } from "playcanvas";
+import { computeGroundPlane, yOnPlane } from "./groundPlane.js";
 const _quat = new Quat();
 const _flatForward = new Vec3();
 const _flatRight = new Vec3();
-
-/** 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 dampRate = (damping, dt)=>1 - Math.pow(damping, 1000 * dt);
 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;
-
-  /** @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;
+    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;
     }
-    const plane = computeGroundPlane(this.groundPlane);
-    if (!plane) {
-      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;
     }
-    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);
+    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)
+        ];
     }
-
-    // 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;
-    }
-    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;
+    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);
     }
-
-    // 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;
+    get currentYaw() {
+        return this._targetYaw;
     }
-    if (Math.abs(this._targetYaw - nextYaw) < ANGLE_EPSILON) {
-      nextYaw = this._targetYaw;
+    get currentPitch() {
+        return this._targetPitch;
     }
-    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);
+    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);
     }
-    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);
+    get focusPoint() {
+        const pos = (this._posedCamera() ?? this.entity).getPosition();
+        _quat.setFromEulerAngles(this._pitch, 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;
-        }
-      }
+        return new Vec3(pos.x + _flatForward.x, pos.y + _flatForward.y, pos.z + _flatForward.z);
     }
-    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;
-      }
+    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 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);
     }
-    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 = [];
     }
-  }
-  destroy() {
-    this._removeListeners.forEach(fn => fn());
-    this._removeListeners = [];
-  }
 }
-
 export { WalkthroughCamera };