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

package/components/VirtualWalkthrough/VrAnnotationPanel.js

@@ -1,18 +1,22 @@
-import { jsx } from "react/jsx-runtime";
-import "react";
-import { Entity } from "@playcanvas/react";
-import { Script } from "@playcanvas/react/components";
-import { VrAnnotationPanel } from "./vr-annotation-panel.js";
-const VrAnnotationPanel_VrAnnotationPanel = ({ annotation, annotationIndex })=>/*#__PURE__*/ jsx(Entity, {
-        name: "vr-annotation-panel",
-        children: /*#__PURE__*/ jsx(Script, {
-            script: VrAnnotationPanel,
-            title: annotation.title,
-            label: annotation.label,
-            bodyText: annotation.bodyText,
-            imageUrls: annotation.imageUrls,
-            annotationIndex: annotationIndex
-        })
-    });
-const VirtualWalkthrough_VrAnnotationPanel = VrAnnotationPanel_VrAnnotationPanel;
-export default VirtualWalkthrough_VrAnnotationPanel;
+import 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { VrAnnotationPanel as VrAnnotationPanel$1 } from './vr-annotation-panel.js';
+import { jsx } from 'react/jsx-runtime';
+
+const VrAnnotationPanel = ({
+  annotation,
+  annotationIndex
+}) => /*#__PURE__*/jsx(Entity, {
+  name: "vr-annotation-panel",
+  children: /*#__PURE__*/jsx(Script, {
+    script: VrAnnotationPanel$1,
+    title: annotation.title,
+    label: annotation.label,
+    bodyText: annotation.bodyText,
+    imageUrls: annotation.imageUrls,
+    annotationIndex: annotationIndex
+  })
+});
+
+export { VrAnnotationPanel as default };

package/components/VirtualWalkthrough/XrAnnotationInteraction.js

@@ -1,14 +1,17 @@
-import { jsx } from "react/jsx-runtime";
-import "react";
-import { Entity } from "@playcanvas/react";
-import { Script } from "@playcanvas/react/components";
-import { XrAnnotationInteraction } from "./xr-annotation-interaction.js";
-const XrAnnotationInteraction_XrAnnotationInteraction = ({ onDismiss })=>/*#__PURE__*/ jsx(Entity, {
-        name: "xr-annotation-interaction",
-        children: /*#__PURE__*/ jsx(Script, {
-            script: XrAnnotationInteraction,
-            onDismissCallback: onDismiss
-        })
-    });
-const VirtualWalkthrough_XrAnnotationInteraction = XrAnnotationInteraction_XrAnnotationInteraction;
-export default VirtualWalkthrough_XrAnnotationInteraction;
+import 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { XrAnnotationInteraction as XrAnnotationInteraction$1 } from './xr-annotation-interaction.js';
+import { jsx } from 'react/jsx-runtime';
+
+const XrAnnotationInteraction = ({
+  onDismiss
+}) => /*#__PURE__*/jsx(Entity, {
+  name: "xr-annotation-interaction",
+  children: /*#__PURE__*/jsx(Script, {
+    script: XrAnnotationInteraction$1,
+    onDismissCallback: onDismiss
+  })
+});
+
+export { XrAnnotationInteraction as default };

package/components/VirtualWalkthrough/XrExitButton.js

@@ -1,14 +1,17 @@
-import { jsx } from "react/jsx-runtime";
-import "react";
-import { Entity } from "@playcanvas/react";
-import { Script } from "@playcanvas/react/components";
-import { XrExitButton } from "./xr-exit-button.js";
-const XrExitButton_XrExitButton = ({ onClose })=>/*#__PURE__*/ jsx(Entity, {
-        name: "xr-exit-button",
-        children: /*#__PURE__*/ jsx(Script, {
-            script: XrExitButton,
-            onClose: onClose
-        })
-    });
-const VirtualWalkthrough_XrExitButton = XrExitButton_XrExitButton;
-export default VirtualWalkthrough_XrExitButton;
+import 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { XrExitButton as XrExitButton$1 } from './xr-exit-button.js';
+import { jsx } from 'react/jsx-runtime';
+
+const XrExitButton = ({
+  onClose
+}) => /*#__PURE__*/jsx(Entity, {
+  name: "xr-exit-button",
+  children: /*#__PURE__*/jsx(Script, {
+    script: XrExitButton$1,
+    onClose: onClose
+  })
+});
+
+export { XrExitButton as default };

package/components/VirtualWalkthrough/XrGazeDwell.js

@@ -1,14 +1,17 @@
-import { jsx } from "react/jsx-runtime";
-import "react";
-import { Entity } from "@playcanvas/react";
-import { Script } from "@playcanvas/react/components";
-import { XrGazeDwell } from "./xr-gaze-dwell.js";
-const XrGazeDwell_XrGazeDwell = ({ activeIndex })=>/*#__PURE__*/ jsx(Entity, {
-        name: "xr-gaze-dwell",
-        children: /*#__PURE__*/ jsx(Script, {
-            script: XrGazeDwell,
-            activeIndex: activeIndex
-        })
-    });
-const VirtualWalkthrough_XrGazeDwell = XrGazeDwell_XrGazeDwell;
-export default VirtualWalkthrough_XrGazeDwell;
+import 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { XrGazeDwell as XrGazeDwell$1 } from './xr-gaze-dwell.js';
+import { jsx } from 'react/jsx-runtime';
+
+const XrGazeDwell = ({
+  activeIndex
+}) => /*#__PURE__*/jsx(Entity, {
+  name: "xr-gaze-dwell",
+  children: /*#__PURE__*/jsx(Script, {
+    script: XrGazeDwell$1,
+    activeIndex: activeIndex
+  })
+});
+
+export { XrGazeDwell as default };

package/components/VirtualWalkthrough/XrPointerRay.js

@@ -1,14 +1,17 @@
-import { jsx } from "react/jsx-runtime";
-import "react";
-import { Entity } from "@playcanvas/react";
-import { Script } from "@playcanvas/react/components";
-import { DEFAULT_RAY_COLOR, XrPointerRay } from "./xr-pointer-ray.js";
-const XrPointerRay_XrPointerRay = ({ color = DEFAULT_RAY_COLOR })=>/*#__PURE__*/ jsx(Entity, {
-        name: "xr-pointer-ray",
-        children: /*#__PURE__*/ jsx(Script, {
-            script: XrPointerRay,
-            color: color
-        })
-    });
-const VirtualWalkthrough_XrPointerRay = XrPointerRay_XrPointerRay;
-export default VirtualWalkthrough_XrPointerRay;
+import 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { DEFAULT_RAY_COLOR, XrPointerRay as XrPointerRay$1 } from './xr-pointer-ray.js';
+import { jsx } from 'react/jsx-runtime';
+
+const XrPointerRay = ({
+  color = DEFAULT_RAY_COLOR
+}) => /*#__PURE__*/jsx(Entity, {
+  name: "xr-pointer-ray",
+  children: /*#__PURE__*/jsx(Script, {
+    script: XrPointerRay$1,
+    color: color
+  })
+});
+
+export { XrPointerRay as default };

package/components/VirtualWalkthrough/XrStartPose.js

@@ -1,74 +1,128 @@
-import { Script, XRTYPE_AR, XRTYPE_VR } from "playcanvas";
-import { xrStartRigPose, yawFromBasis } from "./xr-start-pose.js";
+import { Script, XRTYPE_VR, XRTYPE_AR } from 'playcanvas';
+import { xrStartRigPose, yawFromBasis } from './xr-start-pose.js';
+
+/**
+ * Starts an immersive session at the scene's camera position rather than at the world origin.
+ *
+ * PlayCanvas overwrites the camera entity's local transform with the head pose every frame, so the
+ * head lands wherever the headset's reference space puts it — near (0, 0) for a rig that has never
+ * been moved. This script moves the rig on the first frame of a session so the head instead starts
+ * at `targetX`/`targetZ` facing `focusX`/`focusZ`.
+ *
+ * Only XZ is touched: the user stands on the rig floor, which the boundary wall is also built
+ * against, so lifting the rig onto the splat's ground plane would put them through it.
+ *
+ * Attach to the rig entity — the camera's parent, alongside TfXrNavigation, whose bounds clamp
+ * pulls the start point back inside the scene bounds when the camera position sits outside them.
+ */
 class XrStartPose extends Script {
-    static scriptName = 'xrStartPose';
-    targetX = 0;
-    targetZ = 0;
-    focusX = 0;
-    focusZ = 0;
-    _pending = false;
-    _posed = false;
-    _onXrStart = ()=>{
-        this._pending = true;
-    };
-    _onXrUpdate = ()=>{
-        this._posed = true;
-    };
-    _onXrEnd = ()=>{
-        this._posed = false;
-    };
-    initialize() {
-        this._pending = this._isXrActive();
-        this.app.xr?.on('start', this._onXrStart);
-        this.app.xr?.on('update', this._onXrUpdate);
-        this.app.xr?.on('end', this._onXrEnd);
-        this.once('destroy', ()=>this._teardown());
+  static scriptName = 'xrStartPose';
+
+  /** World-space X the head should start at, i.e. the viewer's `cameraPosition`. */
+  targetX = 0;
+
+  /** World-space Z the head should start at. */
+  targetZ = 0;
+
+  /** World-space X the head should face from there, i.e. the viewer's `origin`. */
+  focusX = 0;
+
+  /** World-space Z the head should face from there. */
+  focusZ = 0;
+
+  /** Set when a session starts, cleared once the rig has been placed. */
+  _pending = false;
+
+  /**
+   * Whether the engine has written a head pose for this session yet.
+   */
+  _posed = false;
+  _onXrStart = () => {
+    this._pending = true;
+  };
+
+  /** Fired from XrManager.update only after the head pose has been written to the camera. */
+  _onXrUpdate = () => {
+    this._posed = true;
+  };
+  _onXrEnd = () => {
+    this._posed = false;
+  };
+  initialize() {
+    // Covers mounting into a session that is already running as well as the usual mount before one.
+    this._pending = this._isXrActive();
+    this.app.xr?.on('start', this._onXrStart);
+    this.app.xr?.on('update', this._onXrUpdate);
+    this.app.xr?.on('end', this._onXrEnd);
+    // Script removal fires a 'destroy' event rather than calling a destroy() method, so the
+    // teardown has to be registered as a listener or these handlers outlive the script.
+    this.once('destroy', () => this._teardown());
+  }
+  _isXrActive = () => this.app.xr?.active === true && (this.app.xr?.type === XRTYPE_VR || this.app.xr?.type === XRTYPE_AR);
+
+  /**
+   * The bounds circle to place the start point in, or undefined when nothing is clamping the head.
+   * Resolved per call rather than cached: the React wrapper assigns the bounds to the navigation
+   * script imperatively, so they can land after this script initializes.
+   */
+  _bounds = () => {
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const navigation = this.entity.script?.tfXrNavigation;
+    if (!navigation || navigation.boundsRadius <= 0) {
+      return undefined;
     }
-    _isXrActive = ()=>this.app.xr?.active === true && (this.app.xr?.type === XRTYPE_VR || this.app.xr?.type === XRTYPE_AR);
-    _bounds = ()=>{
-        const navigation = this.entity.script?.tfXrNavigation;
-        if (!navigation || navigation.boundsRadius <= 0) return;
-        return {
-            x: navigation.boundsCenter.x,
-            z: navigation.boundsCenter.z,
-            radius: navigation.boundsRadius
-        };
+    return {
+      x: navigation.boundsCenter.x,
+      z: navigation.boundsCenter.z,
+      radius: navigation.boundsRadius
     };
-    update() {
-        if (!this._pending || !this._posed || !this._isXrActive()) return;
-        const camera = this.entity.findComponent('camera')?.entity;
-        if (!camera) return;
-        const head = camera.getPosition();
-        const rig = this.entity.getPosition();
-        const rigY = rig.y;
-        const pose = xrStartRigPose({
-            head: {
-                x: head.x,
-                z: head.z
-            },
-            headYaw: yawFromBasis(camera.forward, camera.right),
-            rig: {
-                x: rig.x,
-                z: rig.z
-            },
-            target: {
-                x: this.targetX,
-                z: this.targetZ
-            },
-            focus: {
-                x: this.focusX,
-                z: this.focusZ
-            },
-            bounds: this._bounds()
-        });
-        this.entity.rotate(0, pose.yawDelta, 0);
-        this.entity.setPosition(pose.x, rigY, pose.z);
-        this._pending = false;
+  };
+
+  /**
+   * Runs in update rather than on the 'start' event: the engine writes the head pose during
+   * xr.update, which precedes the script update in the same tick, so a frame that has posed is the
+   * first point at which there is a real head to solve the rig pose from.
+   */
+  update() {
+    if (!this._pending || !this._posed || !this._isXrActive()) {
+      return;
     }
-    _teardown() {
-        this.app.xr?.off('start', this._onXrStart);
-        this.app.xr?.off('update', this._onXrUpdate);
-        this.app.xr?.off('end', this._onXrEnd);
+    const camera = this.entity.findComponent('camera')?.entity;
+    if (!camera) {
+      return;
     }
+    const head = camera.getPosition();
+    const rig = this.entity.getPosition();
+    const rigY = rig.y;
+    const pose = xrStartRigPose({
+      head: {
+        x: head.x,
+        z: head.z
+      },
+      headYaw: yawFromBasis(camera.forward, camera.right),
+      rig: {
+        x: rig.x,
+        z: rig.z
+      },
+      target: {
+        x: this.targetX,
+        z: this.targetZ
+      },
+      focus: {
+        x: this.focusX,
+        z: this.focusZ
+      },
+      bounds: this._bounds()
+    });
+    this.entity.rotate(0, pose.yawDelta, 0);
+    this.entity.setPosition(pose.x, rigY, pose.z);
+    this._pending = false;
+  }
+  _teardown() {
+    this.app.xr?.off('start', this._onXrStart);
+    this.app.xr?.off('update', this._onXrUpdate);
+    this.app.xr?.off('end', this._onXrEnd);
+  }
 }
+
 export { XrStartPose };

package/components/VirtualWalkthrough/boundary-ring.js

@@ -1,97 +1,127 @@
-import { CULLFACE_NONE, Color, LAYERID_IMMEDIATE, Mesh, MeshInstance, Script, StandardMaterial, Vec3 } from "playcanvas";
-import { computeGroundPlane, yOnPlane } from "./groundPlane.js";
-const boundaryRingMesh = ({ center, radius, groundPlane, width, dashCount = 64, dashRatio = 0.5 })=>{
-    const plane = computeGroundPlane(groundPlane);
-    if (radius <= 0 || width <= 0 || dashCount <= 0 || !plane) return {
-        positions: [],
-        indices: []
-    };
-    const innerR = radius - width / 2;
-    const outerR = radius + width / 2;
-    const step = 2 * Math.PI / dashCount;
-    const on = step * dashRatio;
-    const positions = [];
-    const indices = [];
-    const pushVertex = (r, angle)=>{
-        const x = center.x + r * Math.cos(angle);
-        const z = center.z + r * Math.sin(angle);
-        positions.push(x, yOnPlane(x, z, plane.normal, plane.point, center.y), z);
-    };
-    for(let i = 0; i < dashCount; i++){
-        const a0 = i * step;
-        const a1 = a0 + on;
-        const base = 4 * i;
-        pushVertex(innerR, a0);
-        pushVertex(outerR, a0);
-        pushVertex(innerR, a1);
-        pushVertex(outerR, a1);
-        indices.push(base, base + 1, base + 3, base, base + 3, base + 2);
-    }
+import { Script, Vec3, Color, StandardMaterial, CULLFACE_NONE, Mesh, MeshInstance, LAYERID_IMMEDIATE } from 'playcanvas';
+import { computeGroundPlane, yOnPlane } from './groundPlane.js';
+
+/** Flat-array triangle geometry ready for `Mesh.setPositions` / `Mesh.setIndices`. */
+
+/**
+ * Triangle geometry for a dashed boundary ring laid flat on the ground plane. Each dash is a
+ * short band (a quad = two triangles) sweeping from `radius - width / 2` to `radius + width / 2`;
+ * every vertex is sampled on the circle in XZ and lifted onto the plane via `yOnPlane`.
+ * Returns empty arrays when radius, width, or dashCount is non-positive, or the plane is invalid.
+ */
+const boundaryRingMesh = ({
+  center,
+  radius,
+  groundPlane,
+  width,
+  dashCount = 64,
+  dashRatio = 0.5
+}) => {
+  const plane = computeGroundPlane(groundPlane);
+  if (radius <= 0 || width <= 0 || dashCount <= 0 || !plane) {
     return {
-        positions,
-        indices
+      positions: [],
+      indices: []
     };
+  }
+  const innerR = radius - width / 2;
+  const outerR = radius + width / 2;
+  const step = Math.PI * 2 / dashCount;
+  const on = step * dashRatio;
+  const positions = [];
+  const indices = [];
+  const pushVertex = (r, angle) => {
+    const x = center.x + r * Math.cos(angle);
+    const z = center.z + r * Math.sin(angle);
+    positions.push(x, yOnPlane(x, z, plane.normal, plane.point, center.y), z);
+  };
+  for (let i = 0; i < dashCount; i++) {
+    const a0 = i * step;
+    const a1 = a0 + on;
+    const base = i * 4;
+    // Per dash: v0 inner@a0, v1 outer@a0, v2 inner@a1, v3 outer@a1.
+    pushVertex(innerR, a0);
+    pushVertex(outerR, a0);
+    pushVertex(innerR, a1);
+    pushVertex(outerR, a1);
+    indices.push(base, base + 1, base + 3, base, base + 3, base + 2);
+  }
+  return {
+    positions,
+    indices
+  };
 };
+
+/**
+ * Draws a dashed boundary ring as a flat band mesh on the ground plane.
+ *
+ * Rendered as a thin triangle band whose width is a fraction of the radius (`widthRatio`).
+ * center / radius / groundPlane are set imperatively by the BoundaryRing component (see BoundaryRing.tsx for why
+ * they are not reactive Script props), which calls `rebuild()` after updating them.
+ */
 class BoundaryRingScript extends Script {
-    static scriptName = 'boundaryRing';
-    center = new Vec3();
-    radius = 0;
-    groundPlane = [];
-    color = new Color(1, 1, 1);
-    dashCount = 64;
-    dashRatio = 0.5;
-    widthRatio = 0.05;
-    _material;
-    _mesh;
-    initialize() {
-        const material = new StandardMaterial();
-        material.useLighting = false;
-        material.emissive = this.color;
-        material.cull = CULLFACE_NONE;
-        material.update();
-        this._material = material;
-        this.rebuild();
+  static scriptName = 'boundaryRing';
+  center = new Vec3();
+  radius = 0;
+  groundPlane = [];
+  color = new Color(1, 1, 1);
+  dashCount = 64;
+  dashRatio = 0.5;
+  /** Band width as a fraction of the radius. */
+  widthRatio = 0.05;
+  initialize() {
+    const material = new StandardMaterial();
+    material.useLighting = false;
+    material.emissive = this.color;
+    material.cull = CULLFACE_NONE;
+    material.update();
+    this._material = material;
+    this.rebuild();
+  }
+  rebuild() {
+    this._clearMesh();
+    const geometry = boundaryRingMesh({
+      center: this.center,
+      radius: this.radius,
+      groundPlane: this.groundPlane,
+      width: this.radius * this.widthRatio,
+      dashCount: this.dashCount,
+      dashRatio: this.dashRatio
+    });
+    if (geometry.positions.length === 0 || !this._material) {
+      return;
     }
-    rebuild() {
-        this._clearMesh();
-        const geometry = boundaryRingMesh({
-            center: this.center,
-            radius: this.radius,
-            groundPlane: this.groundPlane,
-            width: this.radius * this.widthRatio,
-            dashCount: this.dashCount,
-            dashRatio: this.dashRatio
-        });
-        if (0 === geometry.positions.length || !this._material) return;
-        const mesh = new Mesh(this.app.graphicsDevice);
-        mesh.setPositions(geometry.positions);
-        mesh.setIndices(geometry.indices);
-        mesh.update();
-        this._mesh = mesh;
-        const meshInstance = new MeshInstance(mesh, this._material);
-        if (this.entity.render) this.entity.render.meshInstances = [
-            meshInstance
-        ];
-        else this.entity.addComponent('render', {
-            meshInstances: [
-                meshInstance
-            ],
-            layers: [
-                LAYERID_IMMEDIATE
-            ]
-        });
+    const mesh = new Mesh(this.app.graphicsDevice);
+    mesh.setPositions(geometry.positions);
+    mesh.setIndices(geometry.indices);
+    mesh.update();
+    this._mesh = mesh;
+    const meshInstance = new MeshInstance(mesh, this._material);
+    if (this.entity.render) {
+      this.entity.render.meshInstances = [meshInstance];
+    } else {
+      // Render on the Immediate layer (drawn after the World layer where the splats render) so
+      // the ring is not composited behind them.
+      this.entity.addComponent('render', {
+        meshInstances: [meshInstance],
+        layers: [LAYERID_IMMEDIATE]
+      });
     }
-    _clearMesh() {
-        if (this.entity.render) this.entity.render.meshInstances = [];
-        if (this._mesh) {
-            this._mesh.destroy();
-            this._mesh = void 0;
-        }
+  }
+  _clearMesh() {
+    if (this.entity.render) {
+      this.entity.render.meshInstances = [];
     }
-    destroy() {
-        this._clearMesh();
-        this._material?.destroy();
-        this._material = void 0;
+    if (this._mesh) {
+      this._mesh.destroy();
+      this._mesh = undefined;
     }
+  }
+  destroy() {
+    this._clearMesh();
+    this._material?.destroy();
+    this._material = undefined;
+  }
 }
+
 export { BoundaryRingScript, boundaryRingMesh };