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

package/components/VirtualWalkthrough/AutoRotator.js

@@ -1,97 +1,235 @@
-import { Quat, Script, Vec3 } from "playcanvas";
+import { Script, Vec3, Quat } from 'playcanvas';
+
+/**
+ * Auto-rotator script for PlayCanvas CameraControls.
+ * Automatically orbits the camera around its focus point after a period of inactivity.
+ */
 class AutoRotator extends Script {
-    static scriptName = 'autoRotator';
-    speed = 4;
-    startDelay = 5;
-    restartDelay = 2;
-    startFadeInTime = 5;
-    timer = 0;
-    hasStartedRotating = false;
-    isCurrentlyRotating = false;
-    pitch = null;
-    yaw = null;
-    cameraEntity = null;
-    cameraControls = null;
-    walkthroughCamera = null;
-    onPointerDown;
-    onKeyDown;
-    handleUserInput() {
+  static scriptName = 'autoRotator';
+
+  /**
+   * Rotation speed in degrees per second when auto-rotating.
+   *
+   * @attribute
+   * @title Speed
+   */
+  speed = 4;
+
+  /**
+   * Delay in seconds before auto-rotation starts after initialization.
+   *
+   * @attribute
+   * @title Start Delay
+   */
+  startDelay = 5;
+
+  /**
+   * Delay in seconds before auto-rotation restarts after the camera stops moving.
+   *
+   * @attribute
+   * @title Restart Delay
+   */
+  restartDelay = 2;
+
+  /**
+   * Duration in seconds to fade in the rotation speed.
+   *
+   * @attribute
+   * @title Start Fade In Time
+   */
+  startFadeInTime = 5;
+
+  /**
+   * Internal timer tracking how long the camera has been idle.
+   * @private
+   */
+  timer = 0;
+
+  /**
+   * Flag to track if rotation has started at least once.
+   * @private
+   */
+  hasStartedRotating = false;
+
+  /**
+   * Flag to track if we're currently rotating.
+   * @private
+   */
+  isCurrentlyRotating = false;
+
+  /**
+   * Last known pitch angle for movement detection.
+   * @private
+   */
+  pitch = null;
+
+  /**
+   * Last known yaw angle for movement detection.
+   * @private
+   */
+  yaw = null;
+
+  /**
+   * Reference to the camera entity.
+   * @private
+   */
+  cameraEntity = null;
+
+  /**
+   * Reference to the CameraControls script.
+   * @private
+   */
+  cameraControls = null;
+
+  /**
+   * Reference to the WalkthroughCamera script (used when CameraControls is absent).
+   * @private
+   */
+  walkthroughCamera = null;
+
+  /**
+   * Bound event handlers for cleanup.
+   * @private
+   */
+
+  /**
+   * Handle user input events.
+   * @private
+   */
+  handleUserInput() {
+    this.timer = 0;
+    this.isCurrentlyRotating = false;
+    this.hasStartedRotating = true;
+  }
+
+  /**
+   * Initialize the script.
+   */
+  initialize() {
+    this.onPointerDown = this.handleUserInput.bind(this);
+    this.onKeyDown = this.handleUserInput.bind(this);
+    if (this.app.graphicsDevice.canvas) {
+      this.app.graphicsDevice.canvas.addEventListener('pointerdown', this.onPointerDown);
+    }
+    window.addEventListener('keydown', this.onKeyDown);
+    this.resolveCamera();
+  }
+
+  /**
+   * Finds the camera and the script posing it. WalkthroughCamera is mounted on this entity, the rig,
+   * so that it poses a camera the walkthrough adopted from a host scene as readily as one of its own;
+   * CameraControls sits on the camera entity itself.
+   *
+   * Called again while nothing has been found, because an adopted camera is reparented into the rig
+   * by an effect that runs after the scripts are mounted.
+   * @private
+   */
+  resolveCamera() {
+    this.cameraEntity = this.entity.findComponent('camera')?.entity ?? null;
+    this.cameraControls = this.cameraEntity?.script?.cameraControls ?? null;
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const rigWalkthroughCamera = this.entity.script?.walkthroughCamera;
+    this.walkthroughCamera = rigWalkthroughCamera ?? this.cameraEntity?.script?.walkthroughCamera ?? null;
+  }
+
+  /**
+   * Update loop that handles auto-rotation logic.
+   * Runs after CameraControls updates.
+   */
+  postUpdate(dt) {
+    if (!this.cameraControls && !this.walkthroughCamera) {
+      this.resolveCamera();
+    }
+    const hasControls = this.cameraControls && this.cameraControls._pose;
+    const hasWalkthrough = !!this.walkthroughCamera;
+    if (!hasControls && !hasWalkthrough) {
+      return;
+    }
+    const currentPitch = hasControls ? this.cameraControls._pose.angles.x : this.walkthroughCamera.currentPitch;
+    const currentYaw = hasControls ? this.cameraControls._pose.angles.y : this.walkthroughCamera.currentYaw;
+
+    // Initialize angles on first frame
+    if (this.pitch === null || this.yaw === null) {
+      this.pitch = currentPitch;
+      this.yaw = currentYaw;
+    }
+
+    // Check for camera movement only after initial rotation has started and while not actively rotating
+    if (this.hasStartedRotating && !this.isCurrentlyRotating && this.pitch !== null && this.yaw !== null) {
+      const pitchDiff = Math.abs(this.pitch - currentPitch);
+      const yawDiff = Math.abs(this.yaw - currentYaw);
+      if (pitchDiff > 0.1 || yawDiff > 0.1) {
+        this.pitch = currentPitch;
+        this.yaw = currentYaw;
         this.timer = 0;
         this.isCurrentlyRotating = false;
         this.hasStartedRotating = true;
+        return;
+      }
     }
-    initialize() {
-        this.onPointerDown = this.handleUserInput.bind(this);
-        this.onKeyDown = this.handleUserInput.bind(this);
-        if (this.app.graphicsDevice.canvas) this.app.graphicsDevice.canvas.addEventListener('pointerdown', this.onPointerDown);
-        window.addEventListener('keydown', this.onKeyDown);
-        this.resolveCamera();
+    this.timer += dt;
+
+    // Determine which delay to use
+    const currentDelay = this.hasStartedRotating ? this.restartDelay : this.startDelay;
+
+    // Start auto-rotation after delay
+    if (this.timer >= currentDelay) {
+      this.isCurrentlyRotating = true;
+      const time = this.timer - currentDelay;
+      const fadeIn = this.smoothStep(time / this.startFadeInTime);
+      const yawDelta = dt * fadeIn * this.speed;
+      if (hasControls) {
+        const pose = this.cameraControls._pose;
+        const focusPoint = pose.getFocus(new Vec3());
+        const offset = new Vec3().sub2(pose.position.clone(), focusPoint);
+        const rotationQuat = new Quat().setFromAxisAngle(Vec3.UP, yawDelta);
+        const rotatedOffset = new Vec3();
+        rotationQuat.transformVector(offset, rotatedOffset);
+        const newPos = new Vec3().add2(focusPoint, rotatedOffset);
+        pose.look(newPos, focusPoint);
+        if (this.cameraControls._controller?.attach) {
+          this.cameraControls._controller.attach(pose, false);
+        }
+        this.cameraEntity.setPosition(pose.position);
+        this.cameraEntity.setEulerAngles(pose.angles);
+        this.pitch = pose.angles.x;
+        this.yaw = pose.angles.y;
+      } else {
+        this.walkthroughCamera.orbitStep(yawDelta);
+        this.pitch = this.walkthroughCamera.currentPitch;
+        this.yaw = this.walkthroughCamera.currentYaw;
+      }
     }
-    resolveCamera() {
-        this.cameraEntity = this.entity.findComponent('camera')?.entity ?? null;
-        this.cameraControls = this.cameraEntity?.script?.cameraControls ?? null;
-        const rigWalkthroughCamera = this.entity.script?.walkthroughCamera;
-        this.walkthroughCamera = rigWalkthroughCamera ?? this.cameraEntity?.script?.walkthroughCamera ?? null;
+  }
+
+  /**
+   * Smooth step interpolation function.
+   *
+   * @param {number} x - Input value.
+   * @returns {number} - Smoothly interpolated value.
+   * @private
+   */
+  smoothStep(x) {
+    if (x <= 0) {
+      return 0;
     }
-    postUpdate(dt) {
-        if (!this.cameraControls && !this.walkthroughCamera) this.resolveCamera();
-        const hasControls = this.cameraControls && this.cameraControls._pose;
-        const hasWalkthrough = !!this.walkthroughCamera;
-        if (!hasControls && !hasWalkthrough) return;
-        const currentPitch = hasControls ? this.cameraControls._pose.angles.x : this.walkthroughCamera.currentPitch;
-        const currentYaw = hasControls ? this.cameraControls._pose.angles.y : this.walkthroughCamera.currentYaw;
-        if (null === this.pitch || null === this.yaw) {
-            this.pitch = currentPitch;
-            this.yaw = currentYaw;
-        }
-        if (this.hasStartedRotating && !this.isCurrentlyRotating && null !== this.pitch && null !== this.yaw) {
-            const pitchDiff = Math.abs(this.pitch - currentPitch);
-            const yawDiff = Math.abs(this.yaw - currentYaw);
-            if (pitchDiff > 0.1 || yawDiff > 0.1) {
-                this.pitch = currentPitch;
-                this.yaw = currentYaw;
-                this.timer = 0;
-                this.isCurrentlyRotating = false;
-                this.hasStartedRotating = true;
-                return;
-            }
-        }
-        this.timer += dt;
-        const currentDelay = this.hasStartedRotating ? this.restartDelay : this.startDelay;
-        if (this.timer >= currentDelay) {
-            this.isCurrentlyRotating = true;
-            const time = this.timer - currentDelay;
-            const fadeIn = this.smoothStep(time / this.startFadeInTime);
-            const yawDelta = dt * fadeIn * this.speed;
-            if (hasControls) {
-                const pose = this.cameraControls._pose;
-                const focusPoint = pose.getFocus(new Vec3());
-                const offset = new Vec3().sub2(pose.position.clone(), focusPoint);
-                const rotationQuat = new Quat().setFromAxisAngle(Vec3.UP, yawDelta);
-                const rotatedOffset = new Vec3();
-                rotationQuat.transformVector(offset, rotatedOffset);
-                const newPos = new Vec3().add2(focusPoint, rotatedOffset);
-                pose.look(newPos, focusPoint);
-                if (this.cameraControls._controller?.attach) this.cameraControls._controller.attach(pose, false);
-                this.cameraEntity.setPosition(pose.position);
-                this.cameraEntity.setEulerAngles(pose.angles);
-                this.pitch = pose.angles.x;
-                this.yaw = pose.angles.y;
-            } else {
-                this.walkthroughCamera.orbitStep(yawDelta);
-                this.pitch = this.walkthroughCamera.currentPitch;
-                this.yaw = this.walkthroughCamera.currentYaw;
-            }
-        }
+    if (x >= 1) {
+      return 1;
     }
-    smoothStep(x) {
-        if (x <= 0) return 0;
-        if (x >= 1) return 1;
-        return 0.5 * Math.sin((x - 0.5) * Math.PI) + 0.5;
+    return Math.sin((x - 0.5) * Math.PI) * 0.5 + 0.5;
+  }
+
+  /**
+   * Clean up event listeners when the script is destroyed.
+   */
+  destroy() {
+    if (this.app.graphicsDevice.canvas && this.onPointerDown) {
+      this.app.graphicsDevice.canvas.removeEventListener('pointerdown', this.onPointerDown);
     }
-    destroy() {
-        if (this.app.graphicsDevice.canvas && this.onPointerDown) this.app.graphicsDevice.canvas.removeEventListener('pointerdown', this.onPointerDown);
-        if (this.onKeyDown) window.removeEventListener('keydown', this.onKeyDown);
+    if (this.onKeyDown) {
+      window.removeEventListener('keydown', this.onKeyDown);
     }
+  }
 }
+
 export { AutoRotator };

package/components/VirtualWalkthrough/BlockingSpinner.js

@@ -1,28 +1,30 @@
-import { jsx } from "react/jsx-runtime";
-import "react";
-import { CircularProgress, StyledEngineProvider, useTheme } from "@mui/material";
+import 'react';
+import { useTheme, StyledEngineProvider, CircularProgress } from '@mui/material';
+import { jsx } from 'react/jsx-runtime';
+
 function BlockingSpinner() {
-    const theme = useTheme();
-    return /*#__PURE__*/ jsx(StyledEngineProvider, {
-        injectFirst: true,
-        children: /*#__PURE__*/ jsx(CircularProgress, {
-            size: "193",
-            sx: {
-                height: '200px',
-                width: '200px',
-                position: 'absolute',
-                top: 0,
-                bottom: 0,
-                left: 0,
-                right: 0,
-                margin: 'auto',
-                '& .MuiCircularProgress-svg': {
-                    color: theme.palette.TwClrIcnBrand,
-                    height: '200px',
-                    width: '200px'
-                }
-            }
-        })
-    });
+  const theme = useTheme();
+  return /*#__PURE__*/jsx(StyledEngineProvider, {
+    injectFirst: true,
+    children: /*#__PURE__*/jsx(CircularProgress, {
+      size: "193",
+      sx: {
+        height: '200px',
+        width: '200px',
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        left: 0,
+        right: 0,
+        margin: 'auto',
+        '& .MuiCircularProgress-svg': {
+          color: theme.palette.TwClrIcnBrand,
+          height: '200px',
+          width: '200px'
+        }
+      }
+    })
+  });
 }
-export default BlockingSpinner;
+
+export { BlockingSpinner as default };

package/components/VirtualWalkthrough/BoundaryRing.js

@@ -1,31 +1,35 @@
-import { jsx } from "react/jsx-runtime";
-import { useEffect } from "react";
-import { Entity } from "@playcanvas/react";
-import { Script } from "@playcanvas/react/components";
-import { useApp } from "@playcanvas/react/hooks";
-import { BoundaryRingScript } from "./boundary-ring.js";
-const BoundaryRing = ({ center, radius, groundPlane })=>{
-    const app = useApp();
-    useEffect(()=>{
-        const script = app.root.findByName('boundary-ring')?.script?.boundaryRing;
-        if (script) {
-            script.center = center;
-            script.radius = radius;
-            script.groundPlane = groundPlane;
-            script.rebuild();
-        }
-    }, [
-        app,
-        center,
-        radius,
-        groundPlane
-    ]);
-    return /*#__PURE__*/ jsx(Entity, {
-        name: "boundary-ring",
-        children: /*#__PURE__*/ jsx(Script, {
-            script: BoundaryRingScript
-        })
-    });
+import { useEffect } from 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { useApp } from '@playcanvas/react/hooks';
+import { BoundaryRingScript } from './boundary-ring.js';
+import { jsx } from 'react/jsx-runtime';
+
+const BoundaryRing = ({
+  center,
+  radius,
+  groundPlane
+}) => {
+  const app = useApp();
+  useEffect(() => {
+    // Set imperatively rather than via reactive Script props. @playcanvas/react wraps Script
+    // in memo() whose shallowEquals returns early on the first prop with a .equals() method
+    // (Vec3), so any prop after a Vec3 is never compared and would not propagate.
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const script = app.root.findByName('boundary-ring')?.script?.boundaryRing;
+    if (script) {
+      script.center = center;
+      script.radius = radius;
+      script.groundPlane = groundPlane;
+      script.rebuild();
+    }
+  }, [app, center, radius, groundPlane]);
+  return /*#__PURE__*/jsx(Entity, {
+    name: "boundary-ring",
+    children: /*#__PURE__*/jsx(Script, {
+      script: BoundaryRingScript
+    })
+  });
 };
-const VirtualWalkthrough_BoundaryRing = BoundaryRing;
-export default VirtualWalkthrough_BoundaryRing;
+
+export { BoundaryRing as default };

package/components/VirtualWalkthrough/BoundaryWall.js

@@ -1,33 +1,37 @@
-import { jsx } from "react/jsx-runtime";
-import { useEffect } from "react";
-import { Entity } from "@playcanvas/react";
-import { Script } from "@playcanvas/react/components";
-import { useApp } from "@playcanvas/react/hooks";
-import { BoundaryWallScript } from "./boundary-wall.js";
-const BoundaryWall = ({ center, radius, groundPlane, baseY })=>{
-    const app = useApp();
-    useEffect(()=>{
-        const script = app.root.findByName('boundary-wall')?.script?.boundaryWall;
-        if (script) {
-            script.center = center;
-            script.radius = radius;
-            script.groundPlane = groundPlane;
-            script.baseY = baseY;
-            script.rebuild();
-        }
-    }, [
-        app,
-        center,
-        radius,
-        groundPlane,
-        baseY
-    ]);
-    return /*#__PURE__*/ jsx(Entity, {
-        name: "boundary-wall",
-        children: /*#__PURE__*/ jsx(Script, {
-            script: BoundaryWallScript
-        })
-    });
+import { useEffect } from 'react';
+import { Entity } from '@playcanvas/react';
+import { Script } from '@playcanvas/react/components';
+import { useApp } from '@playcanvas/react/hooks';
+import { BoundaryWallScript } from './boundary-wall.js';
+import { jsx } from 'react/jsx-runtime';
+
+const BoundaryWall = ({
+  center,
+  radius,
+  groundPlane,
+  baseY
+}) => {
+  const app = useApp();
+  useEffect(() => {
+    // Set imperatively rather than via reactive Script props. @playcanvas/react wraps Script
+    // in memo() whose shallowEquals returns early on the first prop with a .equals() method
+    // (Vec3), so any prop after a Vec3 is never compared and would not propagate.
+    // @ts-expect-error - scripts are added dynamically to the entity
+    const script = app.root.findByName('boundary-wall')?.script?.boundaryWall;
+    if (script) {
+      script.center = center;
+      script.radius = radius;
+      script.groundPlane = groundPlane;
+      script.baseY = baseY;
+      script.rebuild();
+    }
+  }, [app, center, radius, groundPlane, baseY]);
+  return /*#__PURE__*/jsx(Entity, {
+    name: "boundary-wall",
+    children: /*#__PURE__*/jsx(Script, {
+      script: BoundaryWallScript
+    })
+  });
 };
-const VirtualWalkthrough_BoundaryWall = BoundaryWall;
-export default VirtualWalkthrough_BoundaryWall;
+
+export { BoundaryWall as default };