@terraware/web-components 5.0.0 → 5.0.1-rc.1

package/components/VirtualWalkthrough/BoundaryWall.d.ts

@@ -1,6 +1,5 @@
 import { Vec3 } from 'playcanvas';
 export type BoundaryWallProps = {
-    /** World-space, i.e. already multiplied by the scene scaleFactor. */
     center: Vec3;
     radius: number;
     groundPlane: Vec3[];

package/components/VirtualWalkthrough/BoundaryWall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BoundaryWall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/BoundaryWall.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIlC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qEAAqE;IACrE,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,QAAA,MAAM,YAAY,GAAI,wCAAwC,iBAAiB,4CAuB9E,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"BoundaryWall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/BoundaryWall.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIlC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,QAAA,MAAM,YAAY,GAAI,wCAAwC,iBAAiB,4CAuB9E,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/components/VirtualWalkthrough/SplatControls.js

@@ -47,7 +47,8 @@ const SplatControls = ({
   const theme = useTheme();
   const strings = useStrings();
   const {
-    isDesktop
+    isDesktop,
+    isMobile
   } = useDeviceInfo();
   const {
     setCamera,
@@ -140,10 +141,10 @@ const SplatControls = ({
         gap: 1,
         pointerEvents: 'auto'
       },
-      children: [isXrAvailable('AR') && !isEdit && /*#__PURE__*/jsx(Button, {
+      children: [isMobile && isXrAvailable('AR') && !isEdit && /*#__PURE__*/jsx(Button, {
         label: strings.AR,
         onClick: () => startXr('AR')
-      }), isXrAvailable('VR') && !isEdit && /*#__PURE__*/jsx(Button, {
+      }), !isMobile && isXrAvailable('VR') && !isEdit && /*#__PURE__*/jsx(Button, {
         label: strings.VR,
         onClick: () => startXr('VR')
       }), isDesktop && editable && !isEdit && onToggleEdit && /*#__PURE__*/jsx(Button, {

package/components/VirtualWalkthrough/SplatModel.d.ts

@@ -9,14 +9,29 @@ export interface SplatModelProps {
      */
     splatFormat?: SplatFormat;
     rotation?: [number, number, number];
+    /**
+     * Scale applied to the splat entity. Splat models come out of reconstruction in their own
+     * arbitrary units, so this is what converts them world units.
+     */
+    scaleFactor?: number;
     cropAabbMin?: [number, number, number];
     cropAabbMax?: [number, number, number];
     cropEdgeScaleFactor?: number;
     cropFade?: boolean;
     cropFadeDistance?: number;
     revealRain?: boolean;
+    /**
+     * Maximum allowable budget for splat rendering operations. Only applies to streamed sog models.
+     * A value of 0 means no limit. Left at the engine's default when omitted.
+     */
+    splatBudget?: number;
+    /**
+     * Caps the device pixel ratio the scene renders at, trading sharpness for fill rate on high-DPI
+     * displays. Left at the engine's default when omitted.
+     */
+    maxPixelRatio?: number;
     onError?: (error: Error) => void;
 }
-declare const _default: React.MemoExoticComponent<({ splatSrc, splatFormat, rotation, cropAabbMin, cropAabbMax, cropEdgeScaleFactor, cropFade, cropFadeDistance, revealRain, onError, }: SplatModelProps) => import("react/jsx-runtime").JSX.Element | null>;
+declare const _default: React.MemoExoticComponent<({ splatSrc, splatFormat, rotation, scaleFactor, cropAabbMin, cropAabbMax, cropEdgeScaleFactor, cropFade, cropFadeDistance, revealRain, splatBudget, maxPixelRatio, onError, }: SplatModelProps) => import("react/jsx-runtime").JSX.Element | null>;
 export default _default;
 //# sourceMappingURL=SplatModel.d.ts.map

package/components/VirtualWalkthrough/SplatModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SplatModel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/SplatModel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0B,MAAM,OAAO,CAAC;AAU/C,OAAO,EAAE,WAAW,EAA0C,MAAM,eAAe,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;yLAaE,eAAe;AAkClB,wBAAgC"}
+{"version":3,"file":"SplatModel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/SplatModel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0B,MAAM,OAAO,CAAC;AAU/C,OAAO,EAAE,WAAW,EAA0C,MAAM,eAAe,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;kOAgBE,eAAe;AAgDlB,wBAAgC"}

package/components/VirtualWalkthrough/SplatModel.js

@@ -1,7 +1,7 @@
 import { memo, useEffect } from 'react';
 import { Entity } from '@playcanvas/react';
 import { GSplat } from '@playcanvas/react/components';
-import { useSplat } from '@playcanvas/react/hooks';
+import { useApp, useSplat } from '@playcanvas/react/hooks';
 import BlockingSpinner from './BlockingSpinner.js';
 import SplatCrop from './SplatCrop.js';
 import SplatFadeCrop from './SplatFadeCrop.js';
@@ -13,14 +13,19 @@ const SplatModel = ({
   splatSrc,
   splatFormat,
   rotation,
+  scaleFactor = 1,
   cropAabbMin,
   cropAabbMax,
   cropEdgeScaleFactor,
   cropFade = false,
   cropFadeDistance = 0.5,
   revealRain = false,
+  splatBudget,
+  maxPixelRatio,
   onError
 }) => {
+  const app = useApp();
+
   // The loader selects its parser from this filename rather than from splatSrc, so it has to name the
   // format we are actually loading. See splatFormat.ts.
   const filename = splatLoaderFilename(splatFormat ?? detectSplatFormat(splatSrc));
@@ -33,6 +38,17 @@ const SplatModel = ({
       filename
     }
   });
+  useEffect(() => {
+    if (!app) {
+      return;
+    }
+    if (splatBudget !== undefined) {
+      app.scene.gsplat.splatBudget = splatBudget;
+    }
+    if (maxPixelRatio !== undefined) {
+      app.graphicsDevice.maxPixelRatio = maxPixelRatio;
+    }
+  }, [app, splatBudget, maxPixelRatio]);
   useEffect(() => {
     if (error) {
       onError?.(new Error(error));
@@ -47,6 +63,7 @@ const SplatModel = ({
   return /*#__PURE__*/jsxs(Entity, {
     name: "splat",
     rotation: rotation,
+    scale: [scaleFactor, scaleFactor, scaleFactor],
     children: [/*#__PURE__*/jsx(GSplat, {
       asset: asset,
       unified: true

package/components/VirtualWalkthrough/TfAnnotationManager.d.ts

@@ -8,7 +8,6 @@ import { AnnotationIconType } from './Annotation';
 export declare class TfAnnotationManager extends PcAnnotationManager {
     static scriptName: string;
     private _maxWorldSize;
-    private _scratchScale;
     private _customParentDom;
     private _clickHandlersAttached;
     private _hotspotBackgroundColor;
@@ -98,8 +97,8 @@ export declare class TfAnnotationManager extends PcAnnotationManager {
     _updateAnnotationPositions(annotation: any, resources: any, screenPos: any): void;
     /**
      * Override to also disable the hotspot mesh (not just the DOM) when the annotation is behind the
-     * camera. The base implementation leaves the mesh enabled, so a not-yet-scaled plane under a
-     * scaled content-root would stay huge in view until the camera moves the anchor in front.
+     * camera. The base implementation leaves the mesh enabled, so a not-yet-scaled plane would stay
+     * in view at its full unit size until the camera moves the anchor in front.
      * @private
      */
     _hideAnnotationElements(annotation: any, resources: any): void;
@@ -109,12 +108,6 @@ export declare class TfAnnotationManager extends PcAnnotationManager {
      * @private
      */
     _updateAnnotationRotationAndScale(annotation: any): void;
-    /**
-     * World-space uniform scale of the annotation entity's parent (e.g. a scaled
-     * content-root). Returns 1 when there is no parent or it has no scale.
-     * @private
-     */
-    _getParentWorldScale(entity: any): number;
     /**
      * Override to create hotspot texture with custom background color.
      * @private

package/components/VirtualWalkthrough/TfAnnotationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TfAnnotationManager.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/TfAnnotationManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoC,OAAO,EAAQ,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,iBAAiB,IAAI,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAIlG,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAelD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,mBAAmB;IAC1D,MAAM,CAAC,UAAU,SAAyB;IAE1C,OAAO,CAAC,aAAa,CAAO;IAC5B,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,sBAAsB,CAAkB;IAChD,OAAO,CAAC,uBAAuB,CAAa;IAC5C,OAAO,CAAC,WAAW,CAAmD;IAEtE;;;;;;;;OAQG;IACH,IAAI,YAAY,CAAC,KAAK,EAAE,MAAM,EAE7B;IAED,IAAI,YAAY,IAJQ,MAAM,CAM7B;IAED;;;;;;;;;;OAUG;IACH,IAAI,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAEvC;IAED,IAAI,sBAAsB,IAJQ,MAAM,CAMvC;IAED;;OAEG;IACH,UAAU;IAgBV;;;;OAIG;IACH,eAAe;IAiBf;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,kBAAkB;IAazC;;OAEG;IACH,MAAM;IAmCN;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,GAAG;IAcnC;;;OAGG;IACH,oBAAoB,CAAC,UAAU,EAAE,GAAG;IAiBpC;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,wBAAwB,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM;IAW/E;;;;OAIG;IACH,cAAc,CAAC,UAAU,EAAE,GAAG;IAI9B;;;;OAIG;IACH,sBAAsB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG;IASlD,mBAAmB,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO;IAKrD,0BAA0B;IAK1B,YAAY,CAAC,WAAW,EAAE,GAAG;IAK7B,aAAa,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM;IAI7C;;;OAGG;IACH,0BAA0B,CAAC,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG;IA6B1E;;;;;OAKG;IACH,uBAAuB,CAAC,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG;IAMvD;;;;OAIG;IACH,iCAAiC,CAAC,UAAU,EAAE,GAAG;IAiDjD;;;;OAIG;IACH,oBAAoB,CAAC,MAAM,EAAE,GAAG;IAUhC;;;OAGG;IACH,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAuB,EAAE,WAAW,SAAI,EAAE,IAAI,CAAC,EAAE,kBAAkB;CAyD7G"}
+{"version":3,"file":"TfAnnotationManager.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/TfAnnotationManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoC,OAAO,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,iBAAiB,IAAI,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAIlG,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAelD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,mBAAmB;IAC1D,MAAM,CAAC,UAAU,SAAyB;IAE1C,OAAO,CAAC,aAAa,CAAO;IAC5B,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,sBAAsB,CAAkB;IAChD,OAAO,CAAC,uBAAuB,CAAa;IAC5C,OAAO,CAAC,WAAW,CAAmD;IAEtE;;;;;;;;OAQG;IACH,IAAI,YAAY,CAAC,KAAK,EAAE,MAAM,EAE7B;IAED,IAAI,YAAY,IAJQ,MAAM,CAM7B;IAED;;;;;;;;;;OAUG;IACH,IAAI,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAEvC;IAED,IAAI,sBAAsB,IAJQ,MAAM,CAMvC;IAED;;OAEG;IACH,UAAU;IAgBV;;;;OAIG;IACH,eAAe;IAiBf;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,kBAAkB;IAazC;;OAEG;IACH,MAAM;IAmCN;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,GAAG;IAcnC;;;OAGG;IACH,oBAAoB,CAAC,UAAU,EAAE,GAAG;IAiBpC;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,wBAAwB,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM;IAW/E;;;;OAIG;IACH,cAAc,CAAC,UAAU,EAAE,GAAG;IAI9B;;;;OAIG;IACH,sBAAsB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG;IASlD,mBAAmB,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO;IAKrD,0BAA0B;IAK1B,YAAY,CAAC,WAAW,EAAE,GAAG;IAK7B,aAAa,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM;IAI7C;;;OAGG;IACH,0BAA0B,CAAC,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG;IA6B1E;;;;;OAKG;IACH,uBAAuB,CAAC,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG;IAMvD;;;;OAIG;IACH,iCAAiC,CAAC,UAAU,EAAE,GAAG;IA2CjD;;;OAGG;IACH,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAuB,EAAE,WAAW,SAAI,EAAE,IAAI,CAAC,EAAE,kBAAkB;CAyD7G"}

package/components/VirtualWalkthrough/TfAnnotationManager.js

@@ -1,6 +1,6 @@
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
-import { Vec3, Texture, FILTER_LINEAR, PIXELFORMAT_RGBA8 } from 'playcanvas';
+import { Texture, FILTER_LINEAR, PIXELFORMAT_RGBA8 } from 'playcanvas';
 import { AnnotationManager } from 'playcanvas/scripts/esm/annotations.mjs';
 import Icon from '../Icon/Icon.js';
 
@@ -24,7 +24,6 @@ const HOTSPOT_HOVER_SCALE = 1.3;
 class TfAnnotationManager extends AnnotationManager {
   static scriptName = 'tfAnnotationManager';
   _maxWorldSize = 1.0;
-  _scratchScale = new Vec3();
   _customParentDom = null;
   _clickHandlersAttached = new Set();
   _hotspotBackgroundColor = '#2C8658';
@@ -163,9 +162,9 @@ class TfAnnotationManager extends AnnotationManager {
     super._registerAnnotation(annotation);
     this._applyAnnotationIcon(annotation);
 
-    // Keep the hotspot mesh hidden until the first scale pass clamps it. The annotation entity
-    // starts at unit local scale, so under a scaled content-root the plane would render many world
-    // units across for the frames before _updateAnnotationRotationAndScale runs.
+    // Keep the hotspot mesh hidden until the first scale pass sizes it. The annotation entity
+    // starts at unit scale, so the plane would render a metre across for the frames before
+    // _updateAnnotationRotationAndScale runs.
     const resources = this._annotationResources.get(annotation);
     if (resources) {
       resources.baseEntity.enabled = false;
@@ -281,8 +280,8 @@ class TfAnnotationManager extends AnnotationManager {
 
   /**
    * Override to also disable the hotspot mesh (not just the DOM) when the annotation is behind the
-   * camera. The base implementation leaves the mesh enabled, so a not-yet-scaled plane under a
-   * scaled content-root would stay huge in view until the camera moves the anchor in front.
+   * camera. The base implementation leaves the mesh enabled, so a not-yet-scaled plane would stay
+   * in view at its full unit size until the camera moves the anchor in front.
    * @private
    */
   _hideAnnotationElements(annotation, resources) {
@@ -309,14 +308,9 @@ class TfAnnotationManager extends AnnotationManager {
     // The world size that projects to _hotspotSize screen pixels at this distance.
     const targetWorldSize = this._hotspotSize / screenHeight * (2 * distance / projMatrix.data[5]);
 
-    // setLocalScale is applied on top of the parent's world scale (e.g. a scaled
-    // content-root), so divide it out to keep the on-screen size independent of it.
-    const parentScale = this._getParentWorldScale(annotation.entity);
-    const unclampedScale = targetWorldSize / parentScale;
-
-    // Clamp in the annotation's own (parent-local) space so maxWorldSize keeps the
-    // same size relative to the model regardless of the content-root scale.
-    const clampedScale = Math.min(unclampedScale, this._maxWorldSize);
+    // Annotations hang off an unscaled parent, so local scale is world scale and maxWorldSize
+    // clamps the hotspot at a size in metres.
+    const clampedScale = Math.min(targetWorldSize, this._maxWorldSize);
     const hovered = this._hoverAnnotation === annotation;
     const hoverScale = hovered ? HOTSPOT_HOVER_SCALE : 1;
     const entityScale = clampedScale * hoverScale;
@@ -324,8 +318,7 @@ class TfAnnotationManager extends AnnotationManager {
 
     // Scale the hotspot DOM element proportionally when clamped, including the
     // hover growth so it tracks the visible circle. This is a pure screen-space
-    // size, so it uses the true _hotspotSize and the clamp ratio only (never the
-    // parent scale, which the DOM overlay does not inherit).
+    // size, so it uses the true _hotspotSize and the clamp ratio only.
     const resources = this._annotationResources.get(annotation);
     if (resources) {
       // This branch only runs for annotations in front of the camera, and the scale above is now
@@ -334,7 +327,7 @@ class TfAnnotationManager extends AnnotationManager {
       resources.overlayEntity.enabled = true;
     }
     if (resources && resources.hotspotDom) {
-      const clampRatio = clampedScale / unclampedScale;
+      const clampRatio = clampedScale / targetWorldSize;
       const baseSize = this._hotspotSize + 5; // Match the +5 from the stylesheet
       const scaledSize = baseSize * clampRatio * hoverScale;
       resources.hotspotDom.style.width = `${scaledSize}px`;
@@ -342,20 +335,6 @@ class TfAnnotationManager extends AnnotationManager {
     }
   }
 
-  /**
-   * World-space uniform scale of the annotation entity's parent (e.g. a scaled
-   * content-root). Returns 1 when there is no parent or it has no scale.
-   * @private
-   */
-  _getParentWorldScale(entity) {
-    const parent = entity.parent;
-    if (!parent) {
-      return 1;
-    }
-    parent.getWorldTransform().getScale(this._scratchScale);
-    return this._scratchScale.x || 1;
-  }
-
   /**
    * Override to create hotspot texture with custom background color.
    * @private

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.d.ts

@@ -1,21 +1,42 @@
 import { AnnotationProps } from './Annotation';
+import { SplatModelProps } from './SplatModel';
 import { SplatFormat } from './splatFormat';
+/**
+ * Every coordinate, distance and size in this component is world-space, in the metres an XR
+ * headset imposes on the scene: `scaleFactor` converts the splat's own arbitrary units to them,
+ * and is applied to nothing but the splat itself.
+ */
 export interface VirtualWalkthroughViewerProps {
     splatSrc: string;
     splatFormat?: SplatFormat;
+    /** World-space point the camera looks at. */
     origin?: [number, number, number];
+    /** World-space point the camera starts at. */
     cameraPosition?: [number, number, number];
+    /** World-space centre (x, y, z) and radius (m) of the circle the camera is held inside. */
     sceneBounds?: {
         x: number;
         y: number;
         z: number;
         m: number;
     };
+    /** Three world-space points defining the plane the camera walks on. */
     groundPlane?: [number, number, number][];
     skyColor?: string;
     groundColor?: string;
+    /** Eye height (m) above the ground plane. */
     averageCameraHeight?: number;
+    /**
+     * Scale that converts the splat model's units to the world's metres. Applied to the splat
+     * entity alone — every other coordinate this component takes is already world-space.
+     */
     scaleFactor?: number;
+    /**
+     * Overrides passed through to the splat model, for tuning things like `splatBudget` and
+     * `maxPixelRatio`. The props this component drives itself — `splatSrc`, `splatFormat`,
+     * `rotation`, `scaleFactor` and `revealRain` — take precedence over anything set here.
+     */
+    splatModelProps?: Partial<SplatModelProps>;
     annotations: AnnotationProps[];
     onSaveAnnotations: (annotations: AnnotationProps[]) => void | Promise<void>;
     editable?: boolean;
@@ -24,6 +45,6 @@ export interface VirtualWalkthroughViewerProps {
     onToggleFullScreen?: () => void;
     maxImagesPerAnnotation?: number;
 }
-declare const VirtualWalkthroughViewer: ({ splatSrc, splatFormat, origin, cameraPosition, sceneBounds, groundPlane: groundPlaneProp, skyColor, groundColor, averageCameraHeight, scaleFactor, annotations, onSaveAnnotations, editable, showFreeFly, isFullScreen, onToggleFullScreen, maxImagesPerAnnotation, }: VirtualWalkthroughViewerProps) => import("react/jsx-runtime").JSX.Element;
+declare const VirtualWalkthroughViewer: ({ splatSrc, splatFormat, origin, cameraPosition, sceneBounds, groundPlane: groundPlaneProp, skyColor, groundColor, averageCameraHeight, scaleFactor, splatModelProps, annotations, onSaveAnnotations, editable, showFreeFly, isFullScreen, onToggleFullScreen, maxImagesPerAnnotation, }: VirtualWalkthroughViewerProps) => import("react/jsx-runtime").JSX.Element;
 export default VirtualWalkthroughViewer;
 //# sourceMappingURL=VirtualWalkthroughViewer.d.ts.map

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualWalkthroughViewer.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VirtualWalkthroughViewer.tsx"],"names":[],"mappings":"AAYA,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAe3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAa5C,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,QAAA,MAAM,wBAAwB,GAAI,yQAkB/B,6BAA6B,4CAsX/B,CAAC;AAEF,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"VirtualWalkthroughViewer.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VirtualWalkthroughViewer.tsx"],"names":[],"mappings":"AAYA,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO3D,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAS3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAmB5C;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,6CAA6C;IAC7C,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,8CAA8C;IAC9C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,2FAA2F;IAC3F,WAAW,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,uEAAuE;IACvE,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3C,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,QAAA,MAAM,wBAAwB,GAAI,0RAmB/B,6BAA6B,4CA+X/B,CAAC;AAEF,eAAe,wBAAwB,CAAC"}

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.js

@@ -23,6 +23,8 @@ import XrAnnotationInteraction from './XrAnnotationInteraction.js';
 import XrExitButton from './XrExitButton.js';
 import XrGazeDwell from './XrGazeDwell.js';
 import XrPointerRay from './XrPointerRay.js';
+import { XrStartPose } from './XrStartPose.js';
+import useXrRenderTuning from './useXrRenderTuning.js';
 import { WalkthroughCamera } from './walkthrough-camera.js';
 import { rayHitsInteractiveUi } from './xr-interactive-ui.js';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -32,9 +34,21 @@ const DEFAULT_POSITION = [1, 0.1, 0];
 
 // How far outside the clamp radius the boundary wall stands. Without it the wall would be coplanar
 // with the surface the head is clamped to, so a pinned user would have it in their face and through
-// their near clip plane. Deliberately an absolute world-space distance rather than one scaled by
-// scaleFactor: it is about the size of the user's body, not about the size of the scene.
+// their near clip plane.
 const WALL_INSET = 0.25;
+
+/**
+ * Largest world size (metres) a hotspot is allowed to reach as the camera approaches it, so it
+ * stops growing rather than filling the view from close up.
+ */
+const MAX_HOTSPOT_WORLD_SIZE = 0.75;
+
+/**
+ * Every coordinate, distance and size in this component is world-space, in the metres an XR
+ * headset imposes on the scene: `scaleFactor` converts the splat's own arbitrary units to them,
+ * and is applied to nothing but the splat itself.
+ */
+
 const VirtualWalkthroughViewer = ({
   splatSrc,
   splatFormat,
@@ -46,6 +60,7 @@ const VirtualWalkthroughViewer = ({
   groundColor,
   averageCameraHeight = 0,
   scaleFactor = 1,
+  splatModelProps,
   annotations,
   onSaveAnnotations,
   editable = false,
@@ -77,6 +92,7 @@ const VirtualWalkthroughViewer = ({
     isCurrentlyInVr,
     isCurrentlyInAr
   } = useXr();
+  useXrRenderTuning();
   const sceneBoundsRadius = useMemo(() => {
     if (sceneBounds?.m !== undefined) {
       return sceneBounds.m;
@@ -84,36 +100,45 @@ const VirtualWalkthroughViewer = ({
     const dx = cameraPosition[0] - origin[0];
     const dy = cameraPosition[1] - origin[1];
     const dz = cameraPosition[2] - origin[2];
-    return Math.sqrt(dx * dx + dy * dy + dz * dz) * 0.5;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
   }, [cameraPosition, sceneBounds, origin]);
   const sceneBoundsCenter = useMemo(() => sceneBounds ? new Vec3(sceneBounds.x, sceneBounds.y, sceneBounds.z) : new Vec3(origin[0], cameraPosition[1], origin[2]), [sceneBounds, origin, cameraPosition]);
-  const cameraBoundsCenter = useMemo(() => sceneBoundsCenter.clone().mulScalar(scaleFactor), [sceneBoundsCenter, scaleFactor]);
   const groundPlane = useMemo(() => groundPlaneProp?.length === 3 ? groundPlaneProp.map(p => new Vec3(p[0], p[1], p[2])) : [], [groundPlaneProp]);
-  const cameraGroundPlane = useMemo(() => groundPlane.map(p => p.clone().mulScalar(scaleFactor)), [groundPlane, scaleFactor]);
+
+  // Also runs when a session ends. WalkthroughCamera is unmounted for the duration of a session, so
+  // the camera entity is left holding the last head pose — an eye height above wherever in the rig
+  // the user was standing — which is neither where nor how high the walkthrough left off.
   useEffect(() => {
+    if (isCurrentlyInXr) {
+      return;
+    }
     setCamera(origin, cameraPosition);
-  }, [origin, cameraPosition, setCamera]);
+  }, [origin, cameraPosition, setCamera, isCurrentlyInXr]);
+
+  // Re-applied when a session ends for the same reason: the script that comes back is a new
+  // instance, and without the ground plane it walks the camera at the bounds centre's height
+  // instead of an eye height above the ground.
   useEffect(() => {
-    if (!cameraGroundPlane.length) {
+    if (!groundPlane.length || isCurrentlyInXr) {
       return;
     }
     // @ts-expect-error - scripts are added dynamically to the camera entity
     const walkthroughCam = app.root.findByName('camera')?.script?.walkthroughCamera;
     if (walkthroughCam) {
       // Should be changed to a react prop if shallowEquals in playcanvas/react is fixed (see https://github.com/playcanvas/react/pull/298)
-      walkthroughCam.groundPlane = cameraGroundPlane;
+      walkthroughCam.groundPlane = groundPlane;
     }
-  }, [cameraGroundPlane, app]);
+  }, [groundPlane, app, isCurrentlyInXr]);
   useEffect(() => {
     // Set imperatively for the same reason as BoundaryRing: boundsCenter is a Vec3, and the
     // @playcanvas/react memo() comparator stops at the first prop with an .equals() method.
     // @ts-expect-error - scripts are added dynamically to the entity
     const navigation = app.root.findByName('camera-root')?.script?.tfXrNavigation;
     if (navigation) {
-      navigation.boundsCenter = cameraBoundsCenter;
-      navigation.boundsRadius = sceneBoundsRadius * scaleFactor;
+      navigation.boundsCenter = sceneBoundsCenter;
+      navigation.boundsRadius = sceneBoundsRadius;
     }
-  }, [app, cameraBoundsCenter, sceneBoundsRadius, scaleFactor]);
+  }, [app, sceneBoundsCenter, sceneBoundsRadius]);
   const handleToggleFreeFly = useCallback(() => {
     const newFreeFly = !isFreeFly;
     // @ts-expect-error - scripts are added dynamically to the camera entity
@@ -228,11 +253,13 @@ const VirtualWalkthroughViewer = ({
   }), [handleAnnotationUpdate]);
   const canSave = useMemo(() => localAnnotations.every(annotation => annotation.title && annotation.title.trim() !== ''), [localAnnotations]);
   const splatModel = useMemo(() => /*#__PURE__*/jsx(SplatModel, {
+    ...splatModelProps,
     splatSrc: splatSrc,
     splatFormat: splatFormat,
     rotation: [-180, 0, 0],
+    scaleFactor: scaleFactor,
     revealRain: isHighPerformance
-  }, 'splat'), [isHighPerformance, splatSrc, splatFormat]);
+  }, 'splat'), [isHighPerformance, splatSrc, splatFormat, scaleFactor, splatModelProps]);
   return /*#__PURE__*/jsxs(Fragment, {
     children: [/*#__PURE__*/jsx(GradientSky, {
       topColor: skyColor || '#FFFFFF',
@@ -247,13 +274,10 @@ const VirtualWalkthroughViewer = ({
           fov: 60
         }), !isCurrentlyInXr && /*#__PURE__*/jsx(Script, {
           script: WalkthroughCamera,
-          boundsCenter: cameraBoundsCenter,
-          boundsRadius: sceneBoundsRadius * scaleFactor,
+          boundsCenter: sceneBoundsCenter,
+          boundsRadius: sceneBoundsRadius,
           enableFly: !isTextFieldFocused,
-          averageCameraHeight: scaleFactor * averageCameraHeight,
-          moveSpeed: 0.3 * scaleFactor,
-          moveFastSpeed: 0.5 * scaleFactor,
-          moveSlowSpeed: 0.15 * scaleFactor
+          averageCameraHeight: averageCameraHeight
         })]
       }), /*#__PURE__*/jsx(XrExitButton, {}), /*#__PURE__*/jsx(Script, {
         script: XrControllers,
@@ -262,10 +286,15 @@ const VirtualWalkthroughViewer = ({
         onDismiss: handleCloseAnnotation
       }), /*#__PURE__*/jsx(XrPointerRay, {}), isCurrentlyInVr && viewingAnnotation && /*#__PURE__*/jsx(VrAnnotationPanel, {
         annotation: viewingAnnotation,
-        annotationIndex: viewingAnnotationIndex,
-        scaleFactor: scaleFactor
+        annotationIndex: viewingAnnotationIndex
       }, viewingAnnotationIndex), isCurrentlyInXr && /*#__PURE__*/jsx(XrGazeDwell, {
         activeIndex: viewingAnnotationIndex
+      }), /*#__PURE__*/jsx(Script, {
+        script: XrStartPose,
+        targetX: cameraPosition[0],
+        targetZ: cameraPosition[2],
+        focusX: origin[0],
+        focusZ: origin[2]
       }), /*#__PURE__*/jsx(Script, {
         script: TfXrNavigation,
         enabled: !isEdit,
@@ -280,7 +309,6 @@ const VirtualWalkthroughViewer = ({
       })]
     }), /*#__PURE__*/jsxs(Entity, {
       name: "content-root",
-      scale: [scaleFactor, scaleFactor, scaleFactor],
       children: [splatModel, sceneBounds?.m !== undefined && groundPlane.length === 3 && /*#__PURE__*/jsx(BoundaryRing, {
         center: sceneBoundsCenter,
         radius: sceneBoundsRadius,
@@ -291,7 +319,7 @@ const VirtualWalkthroughViewer = ({
           script: TfAnnotationManager,
           enabled: true,
           hotspotSize: 30,
-          maxWorldSize: 0.05,
+          maxWorldSize: MAX_HOTSPOT_WORLD_SIZE,
           opacity: 1,
           hotspotColor: new Color().fromString(theme.palette.TwClrIcnBrand),
           hoverColor: new Color().fromString('#ffffff'),
@@ -310,9 +338,9 @@ const VirtualWalkthroughViewer = ({
         }, `annotation-${index}`))]
       })]
     }), isCurrentlyInXr && sceneBoundsRadius > 0 && /*#__PURE__*/jsx(BoundaryWall, {
-      center: cameraBoundsCenter,
-      radius: sceneBoundsRadius * scaleFactor + WALL_INSET,
-      groundPlane: cameraGroundPlane,
+      center: sceneBoundsCenter,
+      radius: sceneBoundsRadius + WALL_INSET,
+      groundPlane: groundPlane,
       baseY: 0
     }), /*#__PURE__*/jsx(SplatControls, {
       defaultCameraFocus: origin,

package/components/VirtualWalkthrough/VrAnnotationPanel.d.ts

@@ -2,8 +2,7 @@ import type { AnnotationProps } from './Annotation';
 interface VrAnnotationPanelProps {
     annotation: AnnotationProps;
     annotationIndex: number;
-    scaleFactor: number;
 }
-declare const VrAnnotationPanel: ({ annotation, annotationIndex, scaleFactor }: VrAnnotationPanelProps) => import("react/jsx-runtime").JSX.Element;
+declare const VrAnnotationPanel: ({ annotation, annotationIndex }: VrAnnotationPanelProps) => import("react/jsx-runtime").JSX.Element;
 export default VrAnnotationPanel;
 //# sourceMappingURL=VrAnnotationPanel.d.ts.map

package/components/VirtualWalkthrough/VrAnnotationPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VrAnnotationPanel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VrAnnotationPanel.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,QAAA,MAAM,iBAAiB,GAAI,8CAA8C,sBAAsB,4CAY9F,CAAC;AAEF,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"VrAnnotationPanel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VrAnnotationPanel.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,QAAA,MAAM,iBAAiB,GAAI,iCAAiC,sBAAsB,4CAWjF,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/components/VirtualWalkthrough/VrAnnotationPanel.js

@@ -6,8 +6,7 @@ import { jsx } from 'react/jsx-runtime';
 
 const VrAnnotationPanel = ({
   annotation,
-  annotationIndex,
-  scaleFactor
+  annotationIndex
 }) => /*#__PURE__*/jsx(Entity, {
   name: "vr-annotation-panel",
   children: /*#__PURE__*/jsx(Script, {
@@ -16,8 +15,7 @@ const VrAnnotationPanel = ({
     label: annotation.label,
     bodyText: annotation.bodyText,
     imageUrls: annotation.imageUrls,
-    annotationIndex: annotationIndex,
-    scaleFactor: scaleFactor
+    annotationIndex: annotationIndex
   })
 });
 

package/components/VirtualWalkthrough/XrStartPose.d.ts

@@ -0,0 +1,52 @@
+import { Script } from 'playcanvas';
+/**
+ * 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.
+ */
+export declare class XrStartPose extends Script {
+    static scriptName: string;
+    /** World-space X the head should start at, i.e. the viewer's `cameraPosition`. */
+    targetX: number;
+    /** World-space Z the head should start at. */
+    targetZ: number;
+    /** World-space X the head should face from there, i.e. the viewer's `origin`. */
+    focusX: number;
+    /** World-space Z the head should face from there. */
+    focusZ: number;
+    /** Set when a session starts, cleared once the rig has been placed. */
+    private _pending;
+    /**
+     * Whether the engine has written a head pose for this session yet.
+     */
+    private _posed;
+    private _onXrStart;
+    /** Fired from XrManager.update only after the head pose has been written to the camera. */
+    private _onXrUpdate;
+    private _onXrEnd;
+    initialize(): void;
+    private _isXrActive;
+    /**
+     * 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.
+     */
+    private _bounds;
+    /**
+     * 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(): void;
+    private _teardown;
+}
+//# sourceMappingURL=XrStartPose.d.ts.map

package/components/VirtualWalkthrough/XrStartPose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XrStartPose.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/XrStartPose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAwB,MAAM,YAAY,CAAC;AAM1D;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,MAAM;IACrC,MAAM,CAAC,UAAU,SAAiB;IAElC,kFAAkF;IAClF,OAAO,SAAK;IAEZ,8CAA8C;IAC9C,OAAO,SAAK;IAEZ,iFAAiF;IACjF,MAAM,SAAK;IAEX,qDAAqD;IACrD,MAAM,SAAK;IAEX,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAS;IAEzB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,UAAU,CAEhB;IAEF,2FAA2F;IAC3F,OAAO,CAAC,WAAW,CAEjB;IAEF,OAAO,CAAC,QAAQ,CAEd;IAEF,UAAU;IAWV,OAAO,CAAC,WAAW,CACoF;IAEvG;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAQb;IAEF;;;;OAIG;IACH,MAAM;IA2BN,OAAO,CAAC,SAAS;CAKlB"}

package/components/VirtualWalkthrough/XrStartPose.js

@@ -0,0 +1,128 @@
+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';
+
+  /** 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;
+    }
+    return {
+      x: navigation.boundsCenter.x,
+      z: navigation.boundsCenter.z,
+      radius: navigation.boundsRadius
+    };
+  };
+
+  /**
+   * 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;
+    }
+    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-wall.d.ts

@@ -42,8 +42,6 @@ export declare const boundaryWallMesh: ({ center, radius, groundPlane, baseY, to
  *
  * center / radius / groundPlane / baseY are set imperatively by the BoundaryWall component (see
  * BoundaryWall.tsx for why they are not reactive Script props), which calls `rebuild()` afterwards.
- * All of them are world-space: this entity is deliberately mounted outside `content-root`, which
- * carries the scene's scaleFactor.
  */
 export declare class BoundaryWallScript extends Script {
     static scriptName: string;

package/components/VirtualWalkthrough/boundary-wall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boundary-wall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/boundary-wall.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,EAOL,MAAM,EAEN,IAAI,EACL,MAAM,YAAY,CAAC;AAKpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,gHAAgH;IAChH,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,sEAQ9B,0BAA0B,KAAG,oBAqD/B,CAAC;AA2EF;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;IAC5C,MAAM,CAAC,UAAU,SAAkB;IAEnC,MAAM,OAAc;IACpB,MAAM,SAAK;IACX,WAAW,EAAE,IAAI,EAAE,CAAM;IACzB,uEAAuE;IACvE,KAAK,SAAK;IACV;;;OAGG;IACH,IAAI,SAAO;IACX,QAAQ,SAAM;IACd,WAAW,SAAO;IAClB,2CAA2C;IAC3C,SAAS,SAAS;IAClB,0EAA0E;IAC1E,YAAY,SAAO;IACnB,0EAA0E;IAC1E,gBAAgB,SAAO;IACvB,SAAS,QAA2B;IACpC,SAAS,QAA2B;IAEpC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,UAAU,CAAuB;IAEzC,UAAU;IAwBV;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO;IA6CP,MAAM;IAgCN,OAAO,CAAC,UAAU;CASnB"}
+{"version":3,"file":"boundary-wall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/boundary-wall.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,EAOL,MAAM,EAEN,IAAI,EACL,MAAM,YAAY,CAAC;AAKpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,gHAAgH;IAChH,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,sEAQ9B,0BAA0B,KAAG,oBAqD/B,CAAC;AA2EF;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;IAC5C,MAAM,CAAC,UAAU,SAAkB;IAEnC,MAAM,OAAc;IACpB,MAAM,SAAK;IACX,WAAW,EAAE,IAAI,EAAE,CAAM;IACzB,uEAAuE;IACvE,KAAK,SAAK;IACV;;;OAGG;IACH,IAAI,SAAO;IACX,QAAQ,SAAM;IACd,WAAW,SAAO;IAClB,2CAA2C;IAC3C,SAAS,SAAS;IAClB,0EAA0E;IAC1E,YAAY,SAAO;IACnB,0EAA0E;IAC1E,gBAAgB,SAAO;IACvB,SAAS,QAA2B;IACpC,SAAS,QAA2B;IAEpC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,UAAU,CAAuB;IAEzC,UAAU;IAwBV;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO;IA6CP,MAAM;IAgCN,OAAO,CAAC,UAAU;CASnB"}

package/components/VirtualWalkthrough/boundary-wall.js

@@ -179,8 +179,6 @@ const wallFragmentGLSL = /* glsl */`
  *
  * center / radius / groundPlane / baseY are set imperatively by the BoundaryWall component (see
  * BoundaryWall.tsx for why they are not reactive Script props), which calls `rebuild()` afterwards.
- * All of them are world-space: this entity is deliberately mounted outside `content-root`, which
- * carries the scene's scaleFactor.
  */
 class BoundaryWallScript extends Script {
   static scriptName = 'boundaryWall';

package/components/VirtualWalkthrough/useXrRenderTuning.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Holds the XR render settings in place for the duration of a session.
+ *
+ * Call this once per application. The gsplat settings it writes are scene-global, so a second
+ * caller would capture the first caller's tuned values as the state to restore, and the scene would
+ * come out of the session still tuned.
+ */
+export declare const useXrRenderTuning: () => void;
+export default useXrRenderTuning;
+//# sourceMappingURL=useXrRenderTuning.d.ts.map

package/components/VirtualWalkthrough/useXrRenderTuning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useXrRenderTuning.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/useXrRenderTuning.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,YAsC7B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/components/VirtualWalkthrough/useXrRenderTuning.js

@@ -0,0 +1,46 @@
+import { useEffect } from 'react';
+import { useApp } from '@playcanvas/react/hooks';
+import { applyGsplatTuning, XR_FIXED_FOVEATION, restoreGsplatTuning } from './xr-render-tuning.js';
+
+/**
+ * Holds the XR render settings in place for the duration of a session.
+ *
+ * Call this once per application. The gsplat settings it writes are scene-global, so a second
+ * caller would capture the first caller's tuned values as the state to restore, and the scene would
+ * come out of the session still tuned.
+ */
+const useXrRenderTuning = () => {
+  const app = useApp();
+  useEffect(() => {
+    const xr = app.xr;
+    if (!xr) {
+      return;
+    }
+    let previous = null;
+    const restore = () => {
+      if (previous) {
+        restoreGsplatTuning(app.scene.gsplat, previous);
+        previous = null;
+      }
+    };
+    const handleStart = () => {
+      // Guards against capturing already-tuned values as the restore target if `start` ever
+      // fires again before a matching `end`.
+      if (!previous) {
+        previous = applyGsplatTuning(app.scene.gsplat);
+      }
+      // Only settable on an active session, so it cannot go in the start options alongside
+      // framebufferScaleFactor. A no-op when the presentation layer doesn't support it.
+      xr.fixedFoveation = XR_FIXED_FOVEATION;
+    };
+    xr.on('start', handleStart);
+    xr.on('end', restore);
+    return () => {
+      xr.off('start', handleStart);
+      xr.off('end', restore);
+      restore();
+    };
+  }, [app]);
+};
+
+export { useXrRenderTuning as default, useXrRenderTuning };

package/components/VirtualWalkthrough/vr-annotation-panel.d.ts

@@ -6,7 +6,6 @@ export declare class VrAnnotationPanel extends Script {
     bodyText?: string;
     imageUrls?: string[];
     annotationIndex: number;
-    scaleFactor: number;
     private _material?;
     private _texture?;
     private _mesh?;

package/components/VirtualWalkthrough/vr-annotation-panel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vr-annotation-panel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/vr-annotation-panel.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,MAAM,EAGN,IAAI,EAEL,MAAM,YAAY,CAAC;AAiCpB,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAGxC,KAAK,SAAM;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,SAAM;IACrB,WAAW,SAAK;IAEhB,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAC,CAAoB;IACpC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,aAAa,CAAc;IAEnC,OAAO,CAAC,SAAS,CAsBf;IAEF,UAAU;IAwCV,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;IAkBlB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,YAAY;IAqFpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,WAAW;IAmBnB,8FAA8F;IAC9F,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO;IAIpD,MAAM;IAsCN,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAYlB"}
+{"version":3,"file":"vr-annotation-panel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/vr-annotation-panel.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,MAAM,EAGN,IAAI,EAEL,MAAM,YAAY,CAAC;AAmCpB,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAGxC,KAAK,SAAM;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,SAAM;IAErB,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAC,CAAoB;IACpC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,aAAa,CAAc;IAEnC,OAAO,CAAC,SAAS,CAsBf;IAEF,UAAU;IAwCV,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;IAkBlB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,YAAY;IAqFpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,WAAW;IAmBnB,8FAA8F;IAC9F,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO;IAIpD,MAAM;IAmCN,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAYlB"}

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

@@ -4,14 +4,15 @@ import { rayQuadHit } from './xr-ray-quad.js';
 
 const CANVAS_WIDTH = 1024;
 const CANVAS_HEIGHT = 768;
-
-/** Panel width in world meters; height derived from the canvas aspect ratio. */
-const PANEL_WIDTH = 0.5;
+const PANEL_WIDTH = 7.5;
 const PANEL_HEIGHT = PANEL_WIDTH * CANVAS_HEIGHT / CANVAS_WIDTH;
 
+/** Gap (m) between the top of the hotspot and the bottom edge of the panel. */
+const PANEL_GAP = 0.75;
+
 /** World-space offset from the anchored hotspot: raise the panel above it so the
  * (tall) panel clears the hotspot rather than covering it. */
-const PANEL_OFFSET = new Vec3(0, PANEL_HEIGHT / 2 + 0.05, 0);
+const PANEL_OFFSET = new Vec3(0, PANEL_HEIGHT / 2 + PANEL_GAP, 0);
 const PAD_X = 48;
 
 /** Local +z (the quad's front face) — used to derive the panel's yaw toward the viewer. */
@@ -33,7 +34,6 @@ class VrAnnotationPanel extends Script {
   // Props assigned by the React wrapper.
   title = '';
   annotationIndex = -1;
-  scaleFactor = 1;
   _drawnSignature = null;
   _currentImage = 0;
   _loadToken = 0;
@@ -278,10 +278,7 @@ class VrAnnotationPanel extends Script {
       return;
     }
     this._anchor.copy(anchor.getPosition());
-    // Panel size and its offset from the hotspot scale with the scene so the panel keeps its
-    // proportions relative to the (content-root-scaled) annotations across scenes.
-    this.entity.setLocalScale(this.scaleFactor, this.scaleFactor, this.scaleFactor);
-    this.entity.setPosition(this._anchor.x + PANEL_OFFSET.x * this.scaleFactor, this._anchor.y + PANEL_OFFSET.y * this.scaleFactor, this._anchor.z + PANEL_OFFSET.z * this.scaleFactor);
+    this.entity.setPosition(this._anchor.x + PANEL_OFFSET.x, this._anchor.y + PANEL_OFFSET.y, this._anchor.z + PANEL_OFFSET.z);
 
     // Billboard on yaw only: face the viewer horizontally but stay upright and level, so
     // tilting/rolling the headset does not tilt the panel. Derived from the head's forward

package/components/VirtualWalkthrough/walkthrough-camera.d.ts

@@ -1,7 +1,6 @@
 import { Script, Vec3 } from 'playcanvas';
 export declare class WalkthroughCamera extends Script {
     static scriptName: string;
-    /** @attribute */
     moveSpeed: number;
     /** @attribute */
     moveFastSpeed: number;

package/components/VirtualWalkthrough/walkthrough-camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walkthrough-camera.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/walkthrough-camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAAE,IAAI,EAAQ,MAAM,YAAY,CAAC;AA8BtD,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAExC,iBAAiB;IACjB,SAAS,SAAO;IAEhB,iBAAiB;IACjB,aAAa,SAAO;IAEpB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,eAAe,SAAO;IAEtB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,QAAQ,SAAO;IAEf,iBAAiB;IACjB,QAAQ,SAAM;IAEd,iBAAiB;IACjB,WAAW,SAAS;IAEpB,iBAAiB;IACjB,YAAY,OAAqB;IAEjC,iBAAiB;IACjB,YAAY,SAAM;IAElB,iBAAiB;IACjB,OAAO,UAAS;IAEhB,iBAAiB;IACjB,SAAS,UAAQ;IAEjB,iBAAiB;IACjB,mBAAmB,SAAK;IAExB;;;;;;;;;;OAUG;IACH,WAAW,EAAE,IAAI,EAAE,CAAM;IAGzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,IAAI,CAAK;IAGjB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,gBAAgB,CAAsB;IAG9C,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,gBAAgB;IAaxB,UAAU;IAkFV;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI;IAsBjC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM;IAsB1B;;;OAGG;IACH,IAAI,UAAU,IAAI,IAAI,CAMrB;IAED,MAAM,CAAC,EAAE,EAAE,MAAM;IA4FjB,OAAO;CAIR"}
+{"version":3,"file":"walkthrough-camera.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/walkthrough-camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAAE,IAAI,EAAQ,MAAM,YAAY,CAAC;AA8BtD,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAExC,SAAS,SAAO;IAEhB,iBAAiB;IACjB,aAAa,SAAO;IAEpB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,eAAe,SAAO;IAEtB,iBAAiB;IACjB,aAAa,SAAQ;IAErB,iBAAiB;IACjB,QAAQ,SAAO;IAEf,iBAAiB;IACjB,QAAQ,SAAM;IAEd,iBAAiB;IACjB,WAAW,SAAS;IAEpB,iBAAiB;IACjB,YAAY,OAAqB;IAEjC,iBAAiB;IACjB,YAAY,SAAM;IAElB,iBAAiB;IACjB,OAAO,UAAS;IAEhB,iBAAiB;IACjB,SAAS,UAAQ;IAEjB,iBAAiB;IACjB,mBAAmB,SAAK;IAExB;;;;;;;;;;OAUG;IACH,WAAW,EAAE,IAAI,EAAE,CAAM;IAGzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,IAAI,CAAK;IAGjB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,gBAAgB,CAAsB;IAG9C,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,gBAAgB;IAaxB,UAAU;IAkFV;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI;IAsBjC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM;IAsB1B;;;OAGG;IACH,IAAI,UAAU,IAAI,IAAI,CAMrB;IAED,MAAM,CAAC,EAAE,EAAE,MAAM;IA4FjB,OAAO;CAIR"}

package/components/VirtualWalkthrough/walkthrough-camera.js

@@ -28,15 +28,13 @@ const ANGLE_EPSILON = 1e-3;
 const POSITION_EPSILON = 1e-5;
 class WalkthroughCamera extends Script {
   static scriptName = 'walkthroughCamera';
+  moveSpeed = 4.5;
 
   /** @attribute */
-  moveSpeed = 0.3;
+  moveFastSpeed = 7.5;
 
   /** @attribute */
-  moveFastSpeed = 0.5;
-
-  /** @attribute */
-  moveSlowSpeed = 0.15;
+  moveSlowSpeed = 2.25;
 
   /** @attribute */
   lookSensitivity = 0.1;

package/components/VirtualWalkthrough/xr-render-tuning.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Render settings applied for the duration of an XR session. Splats rasterize as alpha-blended
+ * quads with no early-z rejection, which makes a headset's stereo pixel throughput the binding
+ * constraint on framerate long before splat count is.
+ */
+/**
+ * Peripheral back-buffer resolution reduction, 0 (off) to 1 (strongest). Ineffective while MSAA is
+ * on, which is one reason the application requests `antialias: false`.
+ */
+export declare const XR_FIXED_FOVEATION = 1;
+/**
+ * The subset of `GSplatParams` this module writes. Structural rather than the PlayCanvas type so
+ * the logic can be exercised against a plain object.
+ */
+export interface GsplatTuningParams {
+    radialSorting: boolean;
+    alphaClipForward: number;
+    minPixelSize: number;
+}
+/**
+ * `radialSorting` orders splats by distance from the camera rather than by depth along its forward
+ * axis, which is the more accurate ordering when the camera rotates rather than translates. Sorting
+ * runs on a worker and so lags the view by at least a frame; head rotation dominates in a headset,
+ * where that lag is what reads as swimming.
+ *
+ * The other two trade fidelity for fill rate: `alphaClipForward` drops near-transparent splats from
+ * the forward pass, and `minPixelSize` drops splats that project to less than a few pixels.
+ */
+export declare const XR_GSPLAT_TUNING: GsplatTuningParams;
+/**
+ * Applies the XR settings, returning the values that were replaced so they can be restored when the
+ * session ends. These live on the scene, so leaving them tuned would degrade desktop rendering.
+ */
+export declare const applyGsplatTuning: (params: GsplatTuningParams) => GsplatTuningParams;
+export declare const restoreGsplatTuning: (params: GsplatTuningParams, previous: GsplatTuningParams) => void;
+//# sourceMappingURL=xr-render-tuning.d.ts.map

package/components/VirtualWalkthrough/xr-render-tuning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-render-tuning.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-render-tuning.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,kBAI9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,kBAAkB,KAAG,kBAY9D,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,QAAQ,kBAAkB,EAAE,UAAU,kBAAkB,KAAG,IAI9F,CAAC"}

package/components/VirtualWalkthrough/xr-render-tuning.js

@@ -0,0 +1,54 @@
+/**
+ * Render settings applied for the duration of an XR session. Splats rasterize as alpha-blended
+ * quads with no early-z rejection, which makes a headset's stereo pixel throughput the binding
+ * constraint on framerate long before splat count is.
+ */
+
+/**
+ * Peripheral back-buffer resolution reduction, 0 (off) to 1 (strongest). Ineffective while MSAA is
+ * on, which is one reason the application requests `antialias: false`.
+ */
+const XR_FIXED_FOVEATION = 1;
+
+/**
+ * The subset of `GSplatParams` this module writes. Structural rather than the PlayCanvas type so
+ * the logic can be exercised against a plain object.
+ */
+
+/**
+ * `radialSorting` orders splats by distance from the camera rather than by depth along its forward
+ * axis, which is the more accurate ordering when the camera rotates rather than translates. Sorting
+ * runs on a worker and so lags the view by at least a frame; head rotation dominates in a headset,
+ * where that lag is what reads as swimming.
+ *
+ * The other two trade fidelity for fill rate: `alphaClipForward` drops near-transparent splats from
+ * the forward pass, and `minPixelSize` drops splats that project to less than a few pixels.
+ */
+const XR_GSPLAT_TUNING = {
+  radialSorting: true,
+  alphaClipForward: 0.1,
+  minPixelSize: 1
+};
+
+/**
+ * Applies the XR settings, returning the values that were replaced so they can be restored when the
+ * session ends. These live on the scene, so leaving them tuned would degrade desktop rendering.
+ */
+const applyGsplatTuning = params => {
+  const previous = {
+    radialSorting: params.radialSorting,
+    alphaClipForward: params.alphaClipForward,
+    minPixelSize: params.minPixelSize
+  };
+  params.radialSorting = XR_GSPLAT_TUNING.radialSorting;
+  params.alphaClipForward = XR_GSPLAT_TUNING.alphaClipForward;
+  params.minPixelSize = XR_GSPLAT_TUNING.minPixelSize;
+  return previous;
+};
+const restoreGsplatTuning = (params, previous) => {
+  params.radialSorting = previous.radialSorting;
+  params.alphaClipForward = previous.alphaClipForward;
+  params.minPixelSize = previous.minPixelSize;
+};
+
+export { XR_FIXED_FOVEATION, XR_GSPLAT_TUNING, applyGsplatTuning, restoreGsplatTuning };

package/components/VirtualWalkthrough/xr-start-pose.d.ts

@@ -0,0 +1,57 @@
+export type Point2 = {
+    x: number;
+    z: number;
+};
+export type XrStartBounds = Point2 & {
+    radius: number;
+};
+export type XrStartPoseInput = {
+    /** Where the head is now. */
+    head: Point2;
+    /** Yaw of the head's forward direction now. */
+    headYaw: number;
+    /** Where the rig is now. */
+    rig: Point2;
+    /** Where the head should end up. */
+    target: Point2;
+    /** What the head should face from there. */
+    focus: Point2;
+    /**
+     * Circle to keep the target inside. Omit (or pass a non-positive radius) to place the head on the
+     * target as given.
+     */
+    bounds?: XrStartBounds;
+};
+export type XrStartPose = {
+    /** Yaw to turn the rig by, about its own origin. */
+    yawDelta: number;
+    /** Where the rig ends up once turned. */
+    x: number;
+    z: number;
+};
+/**
+ * Yaw of a heading on the XZ plane, matching PlayCanvas' right-handed CCW Y rotation:
+ * forward = (-sin(yaw), 0, -cos(yaw)).
+ */
+export declare const yawFromDirection: (dx: number, dz: number) => number | null;
+/**
+ * Yaw an entity is facing, from its world basis vectors. Falls back to the right vector when the
+ * forward vector is vertical — a head tipped fully up or down still has a heading, but its forward
+ * vector has no horizontal component to read it from.
+ */
+export declare const yawFromBasis: (forward: {
+    x: number;
+    z: number;
+}, right: {
+    x: number;
+    z: number;
+}) => number;
+/**
+ * Solves for the rig pose that lands the head on `target` facing `focus`.
+ *
+ * Turning the rig swings the head around the rig's origin, so the turn is applied to the head's
+ * offset within the rig first and the rig is then placed so that swung offset lands on the target.
+ * A focus point on top of the target gives no heading, so the rig is only moved, not turned.
+ */
+export declare const xrStartRigPose: ({ head, headYaw, rig, target, focus, bounds }: XrStartPoseInput) => XrStartPose;
+//# sourceMappingURL=xr-start-pose.d.ts.map

package/components/VirtualWalkthrough/xr-start-pose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-start-pose.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-start-pose.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAeF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,EAAE,IAAI,MAAM,KAAG,MAAM,GAAG,IAC8C,CAAC;AAElH;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,MACZ,CAAC;AAWvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,+CAA+C,gBAAgB,KAAG,WAOhG,CAAC"}

package/components/VirtualWalkthrough/xr-start-pose.js

@@ -0,0 +1,80 @@
+import { clampToCircle } from './xr-scene-bounds.js';
+
+/**
+ * Where to put the XR rig so the head starts at a chosen spot facing a chosen point.
+ *
+ * PlayCanvas writes the head pose into the camera entity's *local* transform every frame, so the
+ * only thing a scene can move is the rig the camera hangs off. The head sits at an arbitrary offset
+ * within the rig — the reference space is pinned to wherever the user physically stood when the
+ * session began — so the rig pose has to be solved backwards from the head pose rather than set to
+ * the target outright.
+ *
+ * All angles are degrees and all coordinates world-space XZ; Y is left to the caller, since the
+ * user stands on the rig floor rather than on the scene's ground plane.
+ */
+const RAD_TO_DEG = 180 / Math.PI;
+const DEG_TO_RAD = Math.PI / 180;
+
+/** Below this length a direction vector carries no usable heading. */
+const DIRECTION_EPSILON = 1e-6;
+
+/** Wraps to (-180, 180] so the rig always turns the short way round. */
+const normalizeAngle = degrees => {
+  const wrapped = ((degrees + 180) % 360 + 360) % 360 - 180;
+  return wrapped === -180 ? 180 : wrapped;
+};
+
+/**
+ * Yaw of a heading on the XZ plane, matching PlayCanvas' right-handed CCW Y rotation:
+ * forward = (-sin(yaw), 0, -cos(yaw)).
+ */
+const yawFromDirection = (dx, dz) => Math.abs(dx) < DIRECTION_EPSILON && Math.abs(dz) < DIRECTION_EPSILON ? null : Math.atan2(-dx, -dz) * RAD_TO_DEG;
+
+/**
+ * Yaw an entity is facing, from its world basis vectors. Falls back to the right vector when the
+ * forward vector is vertical — a head tipped fully up or down still has a heading, but its forward
+ * vector has no horizontal component to read it from.
+ */
+const yawFromBasis = (forward, right) => yawFromDirection(forward.x, forward.z) ?? Math.atan2(-right.z, right.x) * RAD_TO_DEG;
+
+/** Rotates a point about the origin by `degrees` of PlayCanvas yaw. */
+const rotateXz = (point, degrees) => {
+  const radians = degrees * DEG_TO_RAD;
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+  return {
+    x: point.x * cos + point.z * sin,
+    z: -point.x * sin + point.z * cos
+  };
+};
+
+/**
+ * Solves for the rig pose that lands the head on `target` facing `focus`.
+ *
+ * Turning the rig swings the head around the rig's origin, so the turn is applied to the head's
+ * offset within the rig first and the rig is then placed so that swung offset lands on the target.
+ * A focus point on top of the target gives no heading, so the rig is only moved, not turned.
+ */
+const xrStartRigPose = ({
+  head,
+  headYaw,
+  rig,
+  target,
+  focus,
+  bounds
+}) => {
+  const landing = bounds ? clampToCircle(target.x, target.z, bounds.x, bounds.z, bounds.radius) : target;
+  const facingYaw = yawFromDirection(focus.x - landing.x, focus.z - landing.z);
+  const yawDelta = facingYaw === null ? 0 : normalizeAngle(facingYaw - headYaw);
+  const offset = rotateXz({
+    x: head.x - rig.x,
+    z: head.z - rig.z
+  }, yawDelta);
+  return {
+    yawDelta,
+    x: landing.x - offset.x,
+    z: landing.z - offset.z
+  };
+};
+
+export { xrStartRigPose, yawFromBasis, yawFromDirection };

package/hooks/useXr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useXr.d.ts","sourceRoot":"","sources":["../../src/hooks/useXr.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjC,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAOD,eAAO,MAAM,KAAK,GAAI,cAAa,YAAiB;0BA4CT,MAAM;oBAGtC,MAAM;;;;;CA6BhB,CAAC;AAEF,eAAe,KAAK,CAAC"}
+{"version":3,"file":"useXr.d.ts","sourceRoot":"","sources":["../../src/hooks/useXr.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjC,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAgBD,eAAO,MAAM,KAAK,GAAI,cAAa,YAAiB;0BA4CT,MAAM;oBAGtC,MAAM;;;;;CA8BhB,CAAC;AAEF,eAAe,KAAK,CAAC"}

package/hooks/useXr.js

@@ -6,6 +6,15 @@ const XR_TYPES = {
   VR: XRTYPE_VR,
   AR: XRTYPE_AR
 };
+
+/**
+ * Factor PlayCanvas applies on top of the device pixel ratio to compute the headset's
+ * framebuffer resolution: `app.graphicsDevice.maxPixelRatio / window.devicePixelRatio *
+ * XR_FRAMEBUFFER_SCALE_FACTOR`. Splat rendering in stereo is fill-rate bound, so this (and
+ * `maxPixelRatio`, which also multiplies XR resolution) is the largest lever on XR framerate.
+ * Read once when the session starts and fixed for its lifetime.
+ */
+const XR_FRAMEBUFFER_SCALE_FACTOR = 1;
 const useXr = ({
   onError
 } = {}) => {
@@ -56,6 +65,7 @@ const useXr = ({
   const startXr = useCallback(type => {
     const camera = app.root.findComponent('camera');
     app.xr?.start(camera, XR_TYPES[type], XRSPACE_LOCALFLOOR, {
+      framebufferScaleFactor: XR_FRAMEBUFFER_SCALE_FACTOR,
       callback: err => {
         if (err) {
           onError?.(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terraware/web-components",
-  "version": "5.0.0",
+  "version": "5.0.1-rc.1",
   "author": "Terraformation Inc.",
   "license": "Apache-2.0",
   "repository": {