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

package/components/VirtualWalkthrough/TfXrNavigation.js

@@ -1,83 +1,172 @@
-import { Vec3 } from "playcanvas";
-import { XrNavigation } from "playcanvas/scripts/esm/xr/xr-navigation.mjs";
-import { clampToCircle } from "./xr-scene-bounds.js";
-import { TeleportGestureLatch } from "./xr-teleport-gesture.js";
+import { Vec3 } from 'playcanvas';
+import { XrNavigation } from 'playcanvas/scripts/esm/xr/xr-navigation.mjs';
+import { clampToCircle } from './xr-scene-bounds.js';
+import { TeleportGestureLatch } from './xr-teleport-gesture.js';
+
+/** The base script's per-source aim state, which it exposes only as underscore-private fields. */
+
+/**
+ * XrNavigation that never teleports on a select meant for something else: it honours the
+ * enableTeleport flag (which the base ignores in tryTeleport) and skips sources whose ray is over
+ * interactive UI.
+ */
 class TfXrNavigation extends XrNavigation {
-    static scriptName = 'tfXrNavigation';
-    isTeleportBlocked;
-    boundsCenter = new Vec3();
-    boundsRadius = 0;
-    clampDistance = 0;
-    _gestures = new TeleportGestureLatch();
-    _isBlocked(inputSource) {
-        return !this.enableTeleport || this.isTeleportBlocked?.(inputSource) === true;
-    }
-    _syncInputSources() {
-        const internals = this;
-        for (const inputSource of this.app.xr?.input?.inputSources ?? []){
-            if (internals._inputSources.has(inputSource)) continue;
-            const handleSelectStart = ()=>{
-                internals._activePointers.set(inputSource, true);
-                internals._arcHits.delete(inputSource);
-            };
-            const handleSelectEnd = ()=>{
-                internals._activePointers.set(inputSource, false);
-                if (this.enableTeleport) this.tryTeleport(inputSource);
-            };
-            inputSource.on('selectstart', handleSelectStart);
-            inputSource.on('selectend', handleSelectEnd);
-            internals._inputHandlers.set(inputSource, {
-                handleSelectStart,
-                handleSelectEnd
-            });
-            internals._inputSources.add(inputSource);
+  static scriptName = 'tfXrNavigation';
+
+  /** Assigned by the React wrapper. True when this source's ray is over interactive UI. */
+
+  /**
+   * World-space bounds circle. Assigned by the React wrapper rather than passed as a Script prop:
+   * boundsCenter is a Vec3, and @playcanvas/react's memo() comparator stops at the first prop with
+   * an .equals() method, so any prop after it would never propagate.
+   * A boundsRadius of 0 disables clamping entirely.
+   */
+  boundsCenter = new Vec3();
+  boundsRadius = 0;
+
+  /** How far the rig was pulled back in the last postUpdate to keep the head inside the bounds. */
+  clampDistance = 0;
+  _gestures = new TeleportGestureLatch();
+  _isBlocked(inputSource) {
+    return !this.enableTeleport || this.isTeleportBlocked?.(inputSource) === true;
+  }
+
+  /**
+   * Tracks controllers the base script never heard about.
+   *
+   * Movement, turning and teleport all iterate `_inputSources`, which the base fills from the XR
+   * input `add` event it subscribes to in initialize. A walkthrough that adopts the host's camera is
+   * mounted into a session that is already running, so the controllers present at session start
+   * fired `add` before this script existed and every control is inert for the whole session.
+   *
+   * The sources are picked up by hand rather than by re-firing `add` on the input manager, which
+   * would also reach the host's own listeners and have them handle controllers they already know
+   * about. The handlers mirror the base's and are stored in its map, so its teardown detaches them.
+   */
+  _syncInputSources() {
+    const internals = this;
+    for (const inputSource of this.app.xr?.input?.inputSources ?? []) {
+      if (internals._inputSources.has(inputSource)) {
+        continue;
+      }
+      const handleSelectStart = () => {
+        internals._activePointers.set(inputSource, true);
+        internals._arcHits.delete(inputSource);
+      };
+      const handleSelectEnd = () => {
+        internals._activePointers.set(inputSource, false);
+        if (this.enableTeleport) {
+          this.tryTeleport(inputSource);
         }
+      };
+      inputSource.on('selectstart', handleSelectStart);
+      inputSource.on('selectend', handleSelectEnd);
+      internals._inputHandlers.set(inputSource, {
+        handleSelectStart,
+        handleSelectEnd
+      });
+      internals._inputSources.add(inputSource);
     }
-    _resolveCamera() {
-        const internals = this;
-        if (!internals._cameraEntity) internals._cameraEntity = this.entity.findComponent('camera')?.entity ?? null;
+  }
+  _resolveCamera() {
+    const internals = this;
+    if (!internals._cameraEntity) {
+      internals._cameraEntity = this.entity.findComponent('camera')?.entity ?? null;
     }
-    tryTeleport(inputSource) {
-        if (this._gestures.consumeBlocked(inputSource) || this._isBlocked(inputSource)) return;
-        super.tryTeleport(inputSource);
+  }
+  tryTeleport(inputSource) {
+    // The latch decides on the frames the press actually aimed through, because super.tryTeleport
+    // commits the arc hit cached back then rather than re-tracing the release-time ray. The live
+    // check stays too: the same release also fires 'select', so a ray that lands on UI at release
+    // is operating that UI and must not move the rig as well.
+    if (this._gestures.consumeBlocked(inputSource) || this._isBlocked(inputSource)) {
+      return;
     }
-    update(dt) {
-        this._resolveCamera();
-        this._syncInputSources();
-        super.update(dt);
-        const internals = this;
-        for (const inputSource of internals._inputSources){
-            const uiBlocked = this.isTeleportBlocked?.(inputSource) === true;
-            this._gestures.track(inputSource, {
-                pressed: true === internals._activePointers.get(inputSource),
-                teleportDisabled: !this.enableTeleport,
-                uiBlocked
-            });
-            const visual = internals._arcVisuals.get(inputSource);
-            if (visual && (visual.entity.enabled || visual.ringEntity.enabled)) {
-                if (!this.enableTeleport || uiBlocked) {
-                    visual.entity.enabled = false;
-                    visual.ringEntity.enabled = false;
-                }
-            }
-        }
+    super.tryTeleport(inputSource);
+  }
+  update(dt) {
+    this._resolveCamera();
+    this._syncInputSources();
+    super.update(dt);
+    const internals = this;
+    for (const inputSource of internals._inputSources) {
+      // Sampled once per source per frame: isTeleportBlocked ray-tests every hotspot.
+      const uiBlocked = this.isTeleportBlocked?.(inputSource) === true;
+
+      // Tracked unconditionally, and before the arc-hiding work below. super.update has just cached
+      // this frame's arc hit, which is what a release would commit, so the latch has to see the same
+      // frame. A source that isn't pressed carries no gesture, so any stale entry from a press that
+      // ended while teleport was disabled (skipping tryTeleport entirely) is dropped here rather
+      // than leaking into the source's next press.
+      this._gestures.track(inputSource, {
+        pressed: internals._activePointers.get(inputSource) === true,
+        teleportDisabled: !this.enableTeleport,
+        uiBlocked
+      });
+
+      // The base hides the arc only from inside its own teleport handling, which it skips entirely
+      // once teleport is off - so an arc raised before the block (gaze dwell can open a panel while
+      // the trigger is held) would otherwise stay frozen in the world. These writes are idempotent,
+      // and the base re-enables the visuals itself on the first frame a source is unblocked.
+      const visual = internals._arcVisuals.get(inputSource);
+      if (!visual || !visual.entity.enabled && !visual.ringEntity.enabled) {
+        continue;
+      }
+      if (!this.enableTeleport || uiBlocked) {
+        visual.entity.enabled = false;
+        visual.ringEntity.enabled = false;
+      }
+    }
+  }
+
+  /**
+   * Holds the head inside the bounds circle. Runs in postUpdate, after PlayCanvas has written this
+   * frame's head pose into the camera's local transform (xr.update runs before app.update) and after
+   * the base script's locomotion, so one clamp covers every way the head can move: thumbstick
+   * translation of the rig, room-scale walking within the rig, and snap turns pivoting the rig.
+   *
+   * This script must stay a no-op outside XR regardless of how it's mounted.
+   */
+  postUpdate() {
+    this.clampDistance = 0;
+    const camera = this._cameraEntity;
+    if (!this.app.xr?.active || !camera || this.boundsRadius <= 0) {
+      return;
     }
-    postUpdate() {
-        this.clampDistance = 0;
-        const camera = this._cameraEntity;
-        if (!this.app.xr?.active || !camera || this.boundsRadius <= 0) return;
-        const head = camera.getPosition();
-        const clamped = clampToCircle(head.x, head.z, this.boundsCenter.x, this.boundsCenter.z, this.boundsRadius);
-        if (0 === clamped.distance) return;
-        this.entity.translate(clamped.x - head.x, 0, clamped.z - head.z);
-        this.clampDistance = clamped.distance;
+    const head = camera.getPosition();
+    const clamped = clampToCircle(head.x, head.z, this.boundsCenter.x, this.boundsCenter.z, this.boundsRadius);
+    if (clamped.distance === 0) {
+      return;
     }
-    _computeArcHit(origin, direction, rec) {
-        super._computeArcHit(origin, direction, rec);
-        if (!rec.valid || this.boundsRadius <= 0) return;
-        const clamped = clampToCircle(rec.point.x, rec.point.z, this.boundsCenter.x, this.boundsCenter.z, this.boundsRadius);
-        rec.point.x = clamped.x;
-        rec.point.z = clamped.z;
+
+    // World-space translate, not translateLocal: a snap turn has yawed the rig, so a local-space
+    // correction would be rotated away from the direction the head actually overshot.
+    this.entity.translate(clamped.x - head.x, 0, clamped.z - head.z);
+    this.clampDistance = clamped.distance;
+  }
+
+  /**
+   * Clamps the teleport landing point to the bounds circle. Overriding here rather than in
+   * tryTeleport covers both paths that produce a landing point — the per-frame aim in
+   * _handleTeleportation and tryTeleport's own recompute when no hit is cached — and because
+   * _handleTeleportation positions the landing ring from this same record immediately afterwards,
+   * the ring previews the clamped destination without any extra work.
+   *
+   * Only valid hits are clamped: when the base finds no hit it leaves rec.point holding a stale
+   * value from an earlier frame, which must not be projected onto the circle and shown as a target.
+   * Clamping only ever shortens the throw, so a hit that passed the base's distance check still does.
+   */
+  _computeArcHit(origin, direction, rec) {
+    super._computeArcHit(origin, direction, rec);
+    if (!rec.valid || this.boundsRadius <= 0) {
+      return;
     }
+
+    // Y is left alone: it is the navigation plane height, and bounds are XZ-only.
+    const clamped = clampToCircle(rec.point.x, rec.point.z, this.boundsCenter.x, this.boundsCenter.z, this.boundsRadius);
+    rec.point.x = clamped.x;
+    rec.point.z = clamped.z;
+  }
 }
+
 export { TfXrNavigation };