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

package/components/VirtualWalkthrough/xr-exit-button.js

@@ -1,163 +1,222 @@
-import { ADDRESS_CLAMP_TO_EDGE, FILTER_LINEAR, LAYERID_IMMEDIATE, MeshInstance, Quat, Script, Texture, Vec3, XRTYPE_VR } from "playcanvas";
-import { ButtonArmingLatch } from "./xr-button-arming.js";
-import { INITIAL_HOLD_STATE, advanceHold } from "./xr-button-hold.js";
-import { drawExitButtonMask } from "./xr-exit-button-mask.js";
-import { FaceButtonPressTracker, secondaryFaceButtonPressed } from "./xr-face-buttons.js";
-import { pieShaderProgress } from "./xr-progress-pie.js";
-import { createProgressPieMaterial, progressPieQuadMesh } from "./xr-progress-pie-material.js";
-const raySphereIntersect = (origin, direction, center, radius)=>{
-    const dir = direction.clone().normalize();
-    const m = new Vec3().sub2(origin, center);
-    const b = m.dot(dir);
-    const c = m.dot(m) - radius * radius;
-    if (c > 0 && b > 0) return false;
-    return b * b - c >= 0;
+import { Script, Vec3, Quat, XRTYPE_VR, Texture, FILTER_LINEAR, ADDRESS_CLAMP_TO_EDGE, MeshInstance, LAYERID_IMMEDIATE } from 'playcanvas';
+import { ButtonArmingLatch } from './xr-button-arming.js';
+import { INITIAL_HOLD_STATE, advanceHold } from './xr-button-hold.js';
+import { drawExitButtonMask } from './xr-exit-button-mask.js';
+import { FaceButtonPressTracker, secondaryFaceButtonPressed } from './xr-face-buttons.js';
+import { pieShaderProgress } from './xr-progress-pie.js';
+import { createProgressPieMaterial, progressPieQuadMesh } from './xr-progress-pie-material.js';
+
+/**
+ * Boolean ray-sphere hit test. Treats the ray as a half-line (t >= 0) and returns true when it
+ * intersects the sphere or starts inside it. `direction` is normalized internally.
+ */
+const raySphereIntersect = (origin, direction, center, radius) => {
+  const dir = direction.clone().normalize();
+  const m = new Vec3().sub2(origin, center);
+  const b = m.dot(dir);
+  const c = m.dot(m) - radius * radius;
+  if (c > 0 && b > 0) {
+    return false;
+  }
+  return b * b - c >= 0;
 };
 const TEXTURE_SIZE = 256;
+
+/** Opacity of the button while it is not being aimed at. */
 const IDLE_OPACITY = 0.9;
+
+/** Seconds of continuous B/Y hold required to leave the session. Matches the gaze-dwell threshold. */
 const EXIT_HOLD_SECONDS = 1.25;
 class XrExitButton extends Script {
-    static scriptName = 'xrExitButton';
-    offset = new Vec3(0.45, 0.35, -1.2);
-    halfSize = 0.12;
-    hitRadius = 0.15;
-    onClose;
-    _material;
-    _texture;
-    _mesh;
-    _hovered = false;
-    _headPosition = new Vec3();
-    _headRotation = new Quat();
-    _worldOffset = new Vec3();
-    _faceButtons = new FaceButtonPressTracker();
-    _hold = INITIAL_HOLD_STATE;
-    _arming = new ButtonArmingLatch();
-    _isVrActive = ()=>this.app.xr?.active === true && this.app.xr?.type === XRTYPE_VR;
-    _onXrStart = ()=>{
-        this.entity.enabled = this._isVrActive();
-        this._resetProgress();
-    };
-    _onXrEnd = ()=>{
-        this.entity.enabled = false;
-        this._hovered = false;
-        this._resetProgress();
-        this.entity.setLocalScale(1, 1, 1);
-        this._material?.setParameter('uOpacity', IDLE_OPACITY);
-    };
-    _onSelect = (inputSource)=>{
-        if (!this.entity.enabled) return;
-        if (this.rayHitsButton(inputSource.getOrigin(), inputSource.getDirection())) this.close();
-    };
-    rayHitsButton(origin, direction) {
-        if (!this.entity.enabled) return false;
-        return raySphereIntersect(origin, direction, this.entity.getPosition(), this.hitRadius);
+  static scriptName = 'xrExitButton';
+
+  /** Offset from the head, in head space: right, up, and forward (-z) into the upper-right of the view. */
+  offset = new Vec3(0.45, 0.35, -1.2);
+
+  /** Half-extent of the square button quad, in world units at the offset distance. */
+  halfSize = 0.12;
+
+  /** World-space radius of the hover/hit sphere. Slightly larger than halfSize for easier targeting. */
+  hitRadius = 0.15;
+
+  /**
+   * Called in place of ending the XR session when the user activates the button, leaving the
+   * session running so the handler decides what happens next.
+   */
+
+  _hovered = false;
+  _headPosition = new Vec3();
+  _headRotation = new Quat();
+  _worldOffset = new Vec3();
+  _faceButtons = new FaceButtonPressTracker();
+  _hold = INITIAL_HOLD_STATE;
+  _arming = new ButtonArmingLatch();
+  _isVrActive = () => this.app.xr?.active === true && this.app.xr?.type === XRTYPE_VR;
+  _onXrStart = () => {
+    this.entity.enabled = this._isVrActive();
+    this._resetProgress();
+  };
+  _onXrEnd = () => {
+    this.entity.enabled = false;
+    this._hovered = false;
+    this._resetProgress();
+    this.entity.setLocalScale(1, 1, 1);
+    this._material?.setParameter('uOpacity', IDLE_OPACITY);
+  };
+  _onSelect = inputSource => {
+    if (!this.entity.enabled) {
+      return;
     }
-    close() {
-        if (this.onClose) return void this.onClose();
-        this.app.xr?.end();
+    if (this.rayHitsButton(inputSource.getOrigin(), inputSource.getDirection())) {
+      this.close();
     }
-    _createMaskTexture() {
-        const canvas = document.createElement('canvas');
-        canvas.width = TEXTURE_SIZE;
-        canvas.height = TEXTURE_SIZE;
-        const ctx = canvas.getContext('2d');
-        if (ctx) drawExitButtonMask(ctx, TEXTURE_SIZE);
-        const texture = new Texture(this.app.graphicsDevice, {
-            name: 'xr-exit-button-mask',
-            width: TEXTURE_SIZE,
-            height: TEXTURE_SIZE,
-            addressU: ADDRESS_CLAMP_TO_EDGE,
-            addressV: ADDRESS_CLAMP_TO_EDGE,
-            minFilter: FILTER_LINEAR,
-            magFilter: FILTER_LINEAR,
-            mipmaps: true
-        });
-        texture.setSource(canvas);
-        return texture;
+  };
+
+  /** True when the ray points at the button's hit sphere. False while the button entity is disabled. */
+  rayHitsButton(origin, direction) {
+    if (!this.entity.enabled) {
+      return false;
     }
-    _resetProgress() {
-        this._hold = INITIAL_HOLD_STATE;
-        this._material?.setParameter('uProgress', 0);
+    return raySphereIntersect(origin, direction, this.entity.getPosition(), this.hitRadius);
+  }
+
+  /** The button's exit action: the `onClose` handler when one is set, otherwise ending the session. */
+  close() {
+    if (this.onClose) {
+      this.onClose();
+      return;
     }
-    initialize() {
-        this._texture = this._createMaskTexture();
-        this._material = createProgressPieMaterial({
-            uniqueName: 'xr-exit-button',
-            maskMap: this._texture,
-            discColor: [
-                20 / 255,
-                20 / 255,
-                20 / 255
-            ],
-            discAlpha: 0.75
-        });
-        this._material.setParameter('uOpacity', IDLE_OPACITY);
-        this._resetProgress();
-        this._mesh = progressPieQuadMesh(this.app.graphicsDevice, this.halfSize);
-        const meshInstance = new MeshInstance(this._mesh, this._material);
-        this.entity.addComponent('render', {
-            meshInstances: [
-                meshInstance
-            ],
-            layers: [
-                LAYERID_IMMEDIATE
-            ]
-        });
-        this.entity.enabled = this._isVrActive();
-        this.app.xr?.on('start', this._onXrStart);
-        this.app.xr?.on('end', this._onXrEnd);
-        this.app.xr?.input?.on('select', this._onSelect);
+    this.app.xr?.end();
+  }
+
+  /** The button's static artwork, painted once. Only the sweep changes per frame, and that lives in
+   * the shader. */
+  _createMaskTexture() {
+    const canvas = document.createElement('canvas');
+    canvas.width = TEXTURE_SIZE;
+    canvas.height = TEXTURE_SIZE;
+    const ctx = canvas.getContext('2d');
+    if (ctx) {
+      drawExitButtonMask(ctx, TEXTURE_SIZE);
     }
-    update(dt) {
-        if (!this.entity.enabled) return;
-        this._trackHead();
-        const sources = this.app.xr?.input?.inputSources ?? [];
-        let hovered = false;
-        let holdActive = false;
-        for (const source of sources){
-            const sourceHovers = this.rayHitsButton(source.getOrigin(), source.getDirection());
-            hovered = hovered || sourceHovers;
-            const facePressed = this._faceButtons.justPressed(source);
-            if (sourceHovers && facePressed) return void this.close();
-            const armedPress = this._arming.trackPress(source, secondaryFaceButtonPressed(source));
-            holdActive = holdActive || armedPress;
-        }
-        const hold = advanceHold(this._hold, holdActive, dt, EXIT_HOLD_SECONDS);
-        this._hold = hold.state;
-        this._material?.setParameter('uProgress', pieShaderProgress(hold.progress));
-        if (hold.justFired) return void this.close();
-        if (hovered !== this._hovered) {
-            this._hovered = hovered;
-            const scale = hovered ? 1.15 : 1;
-            this.entity.setLocalScale(scale, scale, scale);
-            this._material?.setParameter('uOpacity', hovered ? 1 : IDLE_OPACITY);
-        }
+    const texture = new Texture(this.app.graphicsDevice, {
+      name: 'xr-exit-button-mask',
+      width: TEXTURE_SIZE,
+      height: TEXTURE_SIZE,
+      addressU: ADDRESS_CLAMP_TO_EDGE,
+      addressV: ADDRESS_CLAMP_TO_EDGE,
+      minFilter: FILTER_LINEAR,
+      magFilter: FILTER_LINEAR,
+      mipmaps: true
+    });
+    texture.setSource(canvas);
+    return texture;
+  }
+  _resetProgress() {
+    this._hold = INITIAL_HOLD_STATE;
+    this._material?.setParameter('uProgress', 0);
+  }
+  initialize() {
+    this._texture = this._createMaskTexture();
+    this._material = createProgressPieMaterial({
+      uniqueName: 'xr-exit-button',
+      maskMap: this._texture,
+      discColor: [20 / 255, 20 / 255, 20 / 255],
+      discAlpha: 0.75
+    });
+    this._material.setParameter('uOpacity', IDLE_OPACITY);
+    this._resetProgress();
+    this._mesh = progressPieQuadMesh(this.app.graphicsDevice, this.halfSize);
+    const meshInstance = new MeshInstance(this._mesh, this._material);
+
+    // Immediate layer draws after the World layer (where the splats render) so the button is never
+    // composited behind them; depthTest:false keeps it on top within the layer.
+    this.entity.addComponent('render', {
+      meshInstances: [meshInstance],
+      layers: [LAYERID_IMMEDIATE]
+    });
+    this.entity.enabled = this._isVrActive();
+    this.app.xr?.on('start', this._onXrStart);
+    this.app.xr?.on('end', this._onXrEnd);
+    this.app.xr?.input?.on('select', this._onSelect);
+  }
+  update(dt) {
+    if (!this.entity.enabled) {
+      return;
     }
-    _trackHead() {
-        const views = this.app.xr?.views?.list;
-        if (!views || 0 === views.length) return;
-        this._headPosition.set(0, 0, 0);
-        for (const view of views){
-            view.viewInvOffMat.getTranslation(this._worldOffset);
-            this._headPosition.add(this._worldOffset);
-        }
-        this._headPosition.mulScalar(1 / views.length);
-        this._headRotation.setFromMat4(views[0].viewInvOffMat);
-        this._headRotation.transformVector(this.offset, this._worldOffset);
-        this.entity.setPosition(this._headPosition.x + this._worldOffset.x, this._headPosition.y + this._worldOffset.y, this._headPosition.z + this._worldOffset.z);
-        this.entity.setRotation(this._headRotation);
+    this._trackHead();
+    const sources = this.app.xr?.input?.inputSources ?? [];
+    let hovered = false;
+    let holdActive = false;
+    for (const source of sources) {
+      const sourceHovers = this.rayHitsButton(source.getOrigin(), source.getDirection());
+      hovered = hovered || sourceHovers;
+
+      // A face-button press exits only while that controller is aimed at the button, matching the
+      // trigger. Edge-detected so holding a button and then aiming onto it doesn't fire.
+      const facePressed = this._faceButtons.justPressed(source);
+      if (sourceHovers && facePressed) {
+        this.close();
+        return;
+      }
+
+      // Two statements, not `holdActive = holdActive || this._arming.trackPress(...)`: trackPress
+      // arms the source as a side effect and must run for every source every frame, but `||`
+      // short-circuits once holdActive is true and would skip arming later sources.
+      const armedPress = this._arming.trackPress(source, secondaryFaceButtonPressed(source));
+      holdActive = holdActive || armedPress;
     }
-    destroy() {
-        this.app.xr?.off('start', this._onXrStart);
-        this.app.xr?.off('end', this._onXrEnd);
-        this.app.xr?.input?.off('select', this._onSelect);
-        if (this.entity.render) this.entity.render.meshInstances = [];
-        this._mesh?.destroy();
-        this._material?.destroy();
-        this._texture?.destroy();
-        this._mesh = void 0;
-        this._material = void 0;
-        this._texture = void 0;
+    const hold = advanceHold(this._hold, holdActive, dt, EXIT_HOLD_SECONDS);
+    this._hold = hold.state;
+    this._material?.setParameter('uProgress', pieShaderProgress(hold.progress));
+    if (hold.justFired) {
+      this.close();
+      return;
     }
+    if (hovered !== this._hovered) {
+      this._hovered = hovered;
+      const scale = hovered ? 1.15 : 1;
+      this.entity.setLocalScale(scale, scale, scale);
+      this._material?.setParameter('uOpacity', hovered ? 1 : IDLE_OPACITY);
+    }
+  }
+
+  /**
+   * Pin the button to the upper-right of the headset view. The camera entity's transform is
+   * overwritten every frame by WalkthroughCamera and is not the rendered head pose, so the head
+   * pose is read from the XR views (each view's inverse-view matrix is that eye's world transform)
+   * and the button places itself in world space, offset in head space.
+   */
+  _trackHead() {
+    const views = this.app.xr?.views?.list;
+    if (!views || views.length === 0) {
+      return;
+    }
+    this._headPosition.set(0, 0, 0);
+    for (const view of views) {
+      view.viewInvOffMat.getTranslation(this._worldOffset);
+      this._headPosition.add(this._worldOffset);
+    }
+    this._headPosition.mulScalar(1 / views.length);
+    this._headRotation.setFromMat4(views[0].viewInvOffMat);
+    this._headRotation.transformVector(this.offset, this._worldOffset);
+    this.entity.setPosition(this._headPosition.x + this._worldOffset.x, this._headPosition.y + this._worldOffset.y, this._headPosition.z + this._worldOffset.z);
+    this.entity.setRotation(this._headRotation);
+  }
+  destroy() {
+    this.app.xr?.off('start', this._onXrStart);
+    this.app.xr?.off('end', this._onXrEnd);
+    this.app.xr?.input?.off('select', this._onSelect);
+    if (this.entity.render) {
+      this.entity.render.meshInstances = [];
+    }
+    this._mesh?.destroy();
+    this._material?.destroy();
+    this._texture?.destroy();
+    this._mesh = undefined;
+    this._material = undefined;
+    this._texture = undefined;
+  }
 }
+
 export { XrExitButton, raySphereIntersect };

package/components/VirtualWalkthrough/xr-face-buttons.js

@@ -1,23 +1,33 @@
-const FACE_BUTTON_INDICES = [
-    4,
-    5
-];
-const SECONDARY_FACE_BUTTON_INDICES = [
-    5
-];
-const anyButtonPressed = (inputSource, indices)=>{
-    const buttons = inputSource.gamepad?.buttons;
-    return buttons ? indices.some((index)=>buttons[index]?.pressed === true) : false;
+/** xr-standard gamepad button indices for the face buttons: A/X (4) and B/Y (5). */
+const FACE_BUTTON_INDICES = [4, 5];
+
+/** xr-standard gamepad button indices for the secondary face button: B on the right hand, Y on the left. */
+const SECONDARY_FACE_BUTTON_INDICES = [5];
+const anyButtonPressed = (inputSource, indices) => {
+  const buttons = inputSource.gamepad?.buttons;
+  return buttons ? indices.some(index => buttons[index]?.pressed === true) : false;
 };
-const faceButtonPressed = (inputSource)=>anyButtonPressed(inputSource, FACE_BUTTON_INDICES);
-const secondaryFaceButtonPressed = (inputSource)=>anyButtonPressed(inputSource, SECONDARY_FACE_BUTTON_INDICES);
+
+/** True while either face button is held. False for hand-tracked sources, which have no gamepad. */
+const faceButtonPressed = inputSource => anyButtonPressed(inputSource, FACE_BUTTON_INDICES);
+
+/** True while B or Y is held, regardless of which hand holds the controller. */
+const secondaryFaceButtonPressed = inputSource => anyButtonPressed(inputSource, SECONDARY_FACE_BUTTON_INDICES);
+
+/**
+ * Edge-detects face-button presses per input source so one press fires once. Callers must poll every
+ * frame for every source they care about; a press and release between polls is missed.
+ */
 class FaceButtonPressTracker {
-    _down = new WeakMap();
-    justPressed(inputSource) {
-        const pressed = faceButtonPressed(inputSource);
-        const wasPressed = this._down.get(inputSource) ?? false;
-        this._down.set(inputSource, pressed);
-        return pressed && !wasPressed;
-    }
+  _down = new WeakMap();
+
+  /** True only on the poll where a face button goes from released to pressed. */
+  justPressed(inputSource) {
+    const pressed = faceButtonPressed(inputSource);
+    const wasPressed = this._down.get(inputSource) ?? false;
+    this._down.set(inputSource, pressed);
+    return pressed && !wasPressed;
+  }
 }
+
 export { FaceButtonPressTracker, faceButtonPressed, secondaryFaceButtonPressed };

package/components/VirtualWalkthrough/xr-gaze-dwell-state.js

@@ -1,30 +1,41 @@
 const INITIAL_DWELL_STATE = {
-    targetIndex: null,
-    elapsed: 0
+  targetIndex: null,
+  elapsed: 0
 };
-const advanceDwell = (prev, target, dt, threshold)=>{
-    if (null === target) return {
-        state: INITIAL_DWELL_STATE,
-        progress: 0,
-        justOpened: false
-    };
-    if (target !== prev.targetIndex) return {
-        state: {
-            targetIndex: target,
-            elapsed: 0
-        },
-        progress: 0,
-        justOpened: false
+
+/**
+ * Advances gaze-dwell timing for one frame. `target` is the annotation index currently under the
+ * gaze ray, or null. Dwell time accumulates while the same target is held and resets when it
+ * changes or is lost. `justOpened` is true only on the frame the dwell first reaches `threshold`.
+ */
+const advanceDwell = (prev, target, dt, threshold) => {
+  if (target === null) {
+    return {
+      state: INITIAL_DWELL_STATE,
+      progress: 0,
+      justOpened: false
     };
-    const elapsed = Math.min(prev.elapsed + dt, threshold);
-    const justOpened = prev.elapsed < threshold && elapsed >= threshold;
+  }
+  if (target !== prev.targetIndex) {
     return {
-        state: {
-            targetIndex: target,
-            elapsed
-        },
-        progress: elapsed / threshold,
-        justOpened
+      state: {
+        targetIndex: target,
+        elapsed: 0
+      },
+      progress: 0,
+      justOpened: false
     };
+  }
+  const elapsed = Math.min(prev.elapsed + dt, threshold);
+  const justOpened = prev.elapsed < threshold && elapsed >= threshold;
+  return {
+    state: {
+      targetIndex: target,
+      elapsed
+    },
+    progress: elapsed / threshold,
+    justOpened
+  };
 };
+
 export { INITIAL_DWELL_STATE, advanceDwell };