@terraware/web-components 4.2.13 → 4.2.14-rc.1

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.js

@@ -0,0 +1,282 @@
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTheme } from '@mui/material';
+import { Entity } from '@playcanvas/react';
+import { Camera, Script } from '@playcanvas/react/components';
+import { useApp } from '@playcanvas/react/hooks';
+import { Color, Vec3 } from 'playcanvas';
+import { XrControllers } from 'playcanvas/scripts/esm/xr-controllers.mjs';
+import { useCameraPosition } from '../../hooks/useCameraPosition';
+import { useDevicePerformance } from '../../hooks/useDevicePerformance';
+import Annotation from './Annotation';
+import AnnotationPanel from './AnnotationPanel';
+import { AutoRotator } from './AutoRotator';
+import BoundaryRing from './BoundaryRing';
+import GradientSky from './GradientSky';
+import SplatControls from './SplatControls';
+import SplatModel from './SplatModel';
+import { TfAnnotationManager } from './TfAnnotationManager';
+import { TfXrNavigation } from './TfXrNavigation';
+import { WalkthroughCamera } from './walkthrough-camera';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const DEFAULT_FOCUS_POINT = [0, 0.1, 0];
+const DEFAULT_POSITION = [1, 0.1, 0];
+const VirtualWalkthroughViewer = ({
+  splatSrc,
+  origin = DEFAULT_FOCUS_POINT,
+  cameraPosition = DEFAULT_POSITION,
+  sceneBounds,
+  groundPlane: groundPlaneProp,
+  skyColor,
+  groundColor,
+  averageCameraHeight = 0,
+  annotations,
+  onSaveAnnotations,
+  strings,
+  editable = false,
+  showFreeFly = false,
+  isFullScreen = false,
+  onToggleFullScreen
+}) => {
+  const theme = useTheme();
+  const {
+    setCamera
+  } = useCameraPosition();
+  const {
+    isHighPerformance
+  } = useDevicePerformance();
+  const app = useApp();
+  const [showAnnotations, setShowAnnotations] = useState(true);
+  const [autoRotate, setAutoRotate] = useState(true);
+  const [isEdit, setIsEdit] = useState(false);
+  const [isFreeFly, setIsFreeFly] = useState(false);
+  const [selectedAnnotationIndex, setSelectedAnnotationIndex] = useState(-1);
+  const [localAnnotations, setLocalAnnotations] = useState(annotations);
+  const [isTextFieldFocused, setIsTextFieldFocused] = useState(false);
+  const [viewingAnnotation, setViewingAnnotation] = useState(null);
+  const [viewingAnnotationIndex, setViewingAnnotationIndex] = useState(-1);
+  const [viewedScreenPos, setViewedScreenPos] = useState(null);
+  const sceneBoundsRadius = useMemo(() => {
+    if (sceneBounds?.m !== undefined) {
+      return sceneBounds.m;
+    }
+    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;
+  }, [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 groundPlane = useMemo(() => groundPlaneProp?.length === 3 ? groundPlaneProp.map(p => new Vec3(p[0], p[1], p[2])) : [], [groundPlaneProp]);
+  useEffect(() => {
+    setCamera(origin, cameraPosition);
+  }, [origin, cameraPosition, setCamera]);
+  useEffect(() => {
+    if (!groundPlane.length) {
+      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 = groundPlane;
+    }
+  }, [groundPlane, app]);
+  const handleToggleFreeFly = useCallback(() => {
+    const newFreeFly = !isFreeFly;
+    // @ts-expect-error - scripts are added dynamically to the camera entity
+    const walkthroughCam = app.root.findByName('camera')?.script?.walkthroughCamera;
+    if (walkthroughCam) {
+      walkthroughCam.freeFly = newFreeFly;
+    }
+    if (!newFreeFly) {
+      setCamera(origin, cameraPosition);
+    }
+    setIsFreeFly(newFreeFly);
+  }, [isFreeFly, app, setCamera, origin, cameraPosition]);
+  useEffect(() => {
+    setLocalAnnotations(annotations);
+  }, [annotations]);
+  useEffect(() => {
+    if (!isEdit) {
+      setSelectedAnnotationIndex(-1);
+    }
+  }, [isEdit]);
+  const handleAnnotationPositionChange = useCallback(position => {
+    setLocalAnnotations(prev => {
+      if (selectedAnnotationIndex === -1) {
+        return prev;
+      }
+      const updated = [...prev];
+      updated[selectedAnnotationIndex] = {
+        ...updated[selectedAnnotationIndex],
+        position
+      };
+      return updated;
+    });
+  }, [selectedAnnotationIndex]);
+  const handleSave = useCallback(() => {
+    const saveAndClose = async () => {
+      await onSaveAnnotations(localAnnotations);
+      setIsEdit(false);
+      setSelectedAnnotationIndex(-1);
+    };
+    void saveAndClose();
+  }, [onSaveAnnotations, localAnnotations]);
+  const handleCancel = useCallback(() => {
+    setLocalAnnotations(annotations);
+    setIsEdit(false);
+    setSelectedAnnotationIndex(-1);
+  }, [annotations]);
+  const handleAddAnnotation = useCallback(() => {
+    const newAnnotation = {
+      position: origin,
+      title: ''
+    };
+    setLocalAnnotations(prev => [...prev, newAnnotation]);
+    setSelectedAnnotationIndex(localAnnotations.length);
+  }, [origin, localAnnotations]);
+  const handleDeleteAnnotation = useCallback(() => {
+    if (selectedAnnotationIndex === -1) {
+      return;
+    }
+    setLocalAnnotations(prev => prev.filter((_, index) => index !== selectedAnnotationIndex));
+    setSelectedAnnotationIndex(-1);
+  }, [selectedAnnotationIndex]);
+  const handleDeselectAnnotation = useCallback(() => {
+    setSelectedAnnotationIndex(-1);
+  }, []);
+  const handleAnnotationView = useCallback(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  (annotation, annotationIndex, screenX, screenY) => {
+    setViewingAnnotation(annotation);
+    setViewingAnnotationIndex(annotationIndex);
+    // Cleared so the connector line waits for the hotspot's post-aim position
+    // rather than briefly pointing at its old spot.
+    setViewedScreenPos(null);
+  }, []);
+  const handleAnnotationScreenPositionUpdate = useCallback((_index, screenX, screenY, size) => {
+    // The scene is frozen while the panel is open, so guard against redundant
+    // updates from the per-frame callback to avoid needless re-renders.
+    setViewedScreenPos(prev => prev && prev.x === screenX && prev.y === screenY && prev.size === size ? prev : {
+      x: screenX,
+      y: screenY,
+      size
+    });
+  }, []);
+  const handleCloseAnnotation = useCallback(() => {
+    setViewingAnnotation(null);
+    setViewingAnnotationIndex(-1);
+    setViewedScreenPos(null);
+  }, []);
+  const handleAnnotationUpdate = useCallback(updates => {
+    if (selectedAnnotationIndex === -1) {
+      return;
+    }
+    setLocalAnnotations(prev => {
+      const updated = [...prev];
+      updated[selectedAnnotationIndex] = {
+        ...updated[selectedAnnotationIndex],
+        ...updates
+      };
+      return updated;
+    });
+  }, [selectedAnnotationIndex]);
+  const canSave = useMemo(() => localAnnotations.every(annotation => annotation.title && annotation.title.trim() !== ''), [localAnnotations]);
+  const splatModel = useMemo(() => /*#__PURE__*/_jsx(SplatModel, {
+    splatSrc: splatSrc,
+    rotation: [-180, 0, 0],
+    revealRain: isHighPerformance
+  }, 'splat'), [isHighPerformance, splatSrc]);
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(GradientSky, {
+      topColor: skyColor || '#FFFFFF',
+      horizonColor: skyColor || '#EAF8FF',
+      groundColor: groundColor || '#C3BDB7'
+    }), /*#__PURE__*/_jsxs(Entity, {
+      name: "camera-root",
+      children: [/*#__PURE__*/_jsxs(Entity, {
+        name: "camera",
+        children: [/*#__PURE__*/_jsx(Camera, {
+          clearColor: "#EAF8FF",
+          fov: 60
+        }), /*#__PURE__*/_jsx(Script, {
+          script: WalkthroughCamera,
+          boundsCenter: sceneBoundsCenter,
+          boundsRadius: sceneBoundsRadius,
+          enableFly: !isTextFieldFocused,
+          averageCameraHeight: averageCameraHeight
+        })]
+      }), /*#__PURE__*/_jsx(Script, {
+        script: XrControllers,
+        enabled: !isEdit
+      }), /*#__PURE__*/_jsx(Script, {
+        script: TfXrNavigation,
+        enabled: !isEdit,
+        enableTeleport: false
+      }), /*#__PURE__*/_jsx(Script, {
+        script: AutoRotator,
+        enabled: !isEdit && autoRotate && !viewingAnnotation,
+        startDelay: 0.5,
+        restartDelay: 3,
+        startFadeInTime: 0.5
+      })]
+    }), splatModel, sceneBounds?.m !== undefined && groundPlane.length === 3 && /*#__PURE__*/_jsx(BoundaryRing, {
+      center: sceneBoundsCenter,
+      radius: sceneBoundsRadius,
+      groundPlane: groundPlane
+    }), localAnnotations.length > 0 && /*#__PURE__*/_jsxs(Entity, {
+      name: "annotations-root",
+      children: [/*#__PURE__*/_jsx(Script, {
+        script: TfAnnotationManager,
+        enabled: true,
+        hotspotSize: 30,
+        maxWorldSize: 0.05,
+        opacity: 1,
+        hotspotColor: new Color().fromString(theme.palette.TwClrIcnBrand),
+        hoverColor: new Color().fromString('#ffffff'),
+        hotspotBackgroundColor: theme.palette.TwClrBaseWhite
+      }), localAnnotations.map((annotation, index) => /*#__PURE__*/_jsx(Annotation, {
+        ...annotation,
+        index: index,
+        visible: showAnnotations,
+        isEdit: isEdit,
+        isSelected: selectedAnnotationIndex === index,
+        isViewed: viewingAnnotationIndex === index,
+        onSelect: () => setSelectedAnnotationIndex(index),
+        onPositionChange: handleAnnotationPositionChange,
+        onView: (anno, screenX, screenY) => handleAnnotationView(anno, index, screenX, screenY),
+        onScreenPositionUpdate: handleAnnotationScreenPositionUpdate
+      }, `annotation-${index}`))]
+    }), /*#__PURE__*/_jsx(SplatControls, {
+      defaultCameraFocus: origin,
+      defaultCameraPosition: cameraPosition,
+      showAnnotations: showAnnotations,
+      onToggleAnnotations: setShowAnnotations,
+      autoRotate: autoRotate,
+      onToggleAutoRotate: setAutoRotate,
+      isEdit: isEdit,
+      onToggleEdit: setIsEdit,
+      onSave: handleSave,
+      onCancel: handleCancel,
+      onAddAnnotation: handleAddAnnotation,
+      onDeleteAnnotation: handleDeleteAnnotation,
+      onDeselectAnnotation: handleDeselectAnnotation,
+      hasSelectedAnnotation: selectedAnnotationIndex >= 0,
+      selectedAnnotation: selectedAnnotationIndex >= 0 ? localAnnotations[selectedAnnotationIndex] : null,
+      onAnnotationUpdate: handleAnnotationUpdate,
+      onTextFieldFocus: setIsTextFieldFocused,
+      canSave: canSave,
+      editable: editable,
+      isFullScreen: isFullScreen,
+      onToggleFullScreen: onToggleFullScreen,
+      isFreeFly: isFreeFly,
+      onToggleFreeFly: handleToggleFreeFly,
+      showFreeFly: showFreeFly,
+      strings: strings
+    }), /*#__PURE__*/_jsx(AnnotationPanel, {
+      annotation: viewingAnnotation,
+      hotspotPosition: viewedScreenPos,
+      onClose: handleCloseAnnotation
+    })]
+  });
+};
+export default VirtualWalkthroughViewer;

package/components/VirtualWalkthrough/annotation-styles.css

@@ -0,0 +1,5 @@
+/* This is necessary to ensure annotations are in front of other elements in the page, such as overlay backdrops. */
+.pc-annotation,
+.pc-annotation-hotspot {
+  z-index: 5000;
+}

package/components/VirtualWalkthrough/application-styles.css

@@ -0,0 +1,4 @@
+/* Allow pointer events on annotation hotspots while container blocks events */
+.annotation-container > * {
+  pointer-events: auto;
+}

package/components/VirtualWalkthrough/boundary-ring.d.ts

@@ -0,0 +1,47 @@
+import { Color, Script, Vec3 } from 'playcanvas';
+export type BoundaryRingGeometryParams = {
+    center: Vec3;
+    radius: number;
+    groundPlane: Vec3[];
+    /** Band width in world units (the ring spans radius ± width / 2). */
+    width: number;
+    dashCount?: number;
+    dashRatio?: number;
+};
+/** Flat-array triangle geometry ready for `Mesh.setPositions` / `Mesh.setIndices`. */
+export type BoundaryRingGeometry = {
+    positions: number[];
+    indices: number[];
+};
+/**
+ * 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.
+ */
+export declare const boundaryRingMesh: ({ center, radius, groundPlane, width, dashCount, dashRatio, }: BoundaryRingGeometryParams) => BoundaryRingGeometry;
+/**
+ * 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.
+ */
+export declare class BoundaryRingScript extends Script {
+    static scriptName: string;
+    center: Vec3;
+    radius: number;
+    groundPlane: Vec3[];
+    color: Color;
+    dashCount: number;
+    dashRatio: number;
+    /** Band width as a fraction of the radius. */
+    widthRatio: number;
+    private _material?;
+    private _mesh?;
+    initialize(): void;
+    rebuild(): void;
+    private _clearMesh;
+    destroy(): void;
+}
+//# sourceMappingURL=boundary-ring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-ring.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/boundary-ring.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,EAIL,MAAM,EAEN,IAAI,EACL,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,+DAO9B,0BAA0B,KAAG,oBAgC/B,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;IAC5C,MAAM,CAAC,UAAU,SAAkB;IAEnC,MAAM,OAAc;IACpB,MAAM,SAAK;IACX,WAAW,EAAE,IAAI,EAAE,CAAM;IACzB,KAAK,QAAsB;IAC3B,SAAS,SAAM;IACf,SAAS,SAAO;IAChB,8CAA8C;IAC9C,UAAU,SAAQ;IAElB,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,KAAK,CAAC,CAAO;IAErB,UAAU;IAUV,OAAO;IA+BP,OAAO,CAAC,UAAU;IAUlB,OAAO;CAKR"}

package/components/VirtualWalkthrough/boundary-ring.js

@@ -0,0 +1,125 @@
+import { CULLFACE_NONE, Color, LAYERID_IMMEDIATE, Mesh, MeshInstance, Script, StandardMaterial, Vec3 } from 'playcanvas';
+import { computeGroundPlane, yOnPlane } from './groundPlane';
+
+/** 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.
+ */
+export 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 = 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.
+ */
+export class BoundaryRingScript extends Script {
+  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;
+    }
+    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 = undefined;
+    }
+  }
+  destroy() {
+    this._clearMesh();
+    this._material?.destroy();
+    this._material = undefined;
+  }
+}

package/components/VirtualWalkthrough/boundary-ring.test.js

@@ -0,0 +1,109 @@
+import { Vec3 } from 'playcanvas';
+import { boundaryRingMesh } from './boundary-ring';
+const FLAT = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(0, 0, 1)];
+const toVertices = positions => {
+  const out = [];
+  for (let i = 0; i < positions.length; i += 3) {
+    out.push([positions[i], positions[i + 1], positions[i + 2]]);
+  }
+  return out;
+};
+describe('boundaryRingMesh', () => {
+  it('produces four vertices and six indices per dash', () => {
+    const geom = boundaryRingMesh({
+      center: new Vec3(0, 0, 0),
+      radius: 5,
+      width: 0.1,
+      groundPlane: FLAT,
+      dashCount: 16
+    });
+    expect(geom.positions).toHaveLength(16 * 4 * 3);
+    expect(geom.indices).toHaveLength(16 * 6);
+  });
+  it('places every vertex at the inner or outer radius from center in XZ', () => {
+    const center = new Vec3(2, 0, -3);
+    const radius = 4;
+    const width = 0.2;
+    const inner = radius - width / 2;
+    const outer = radius + width / 2;
+    const geom = boundaryRingMesh({
+      center,
+      radius,
+      width,
+      groundPlane: FLAT,
+      dashCount: 32
+    });
+    for (const [x,, z] of toVertices(geom.positions)) {
+      const d = Math.sqrt((x - center.x) ** 2 + (z - center.z) ** 2);
+      const atInner = Math.abs(d - inner) < 1e-6;
+      const atOuter = Math.abs(d - outer) < 1e-6;
+      expect(atInner || atOuter).toBe(true);
+    }
+  });
+  it('lifts every vertex onto a tilted ground plane (y = z)', () => {
+    const tilted = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(0, 1, 1)];
+    const geom = boundaryRingMesh({
+      center: new Vec3(0, 0, 0),
+      radius: 3,
+      width: 0.1,
+      groundPlane: tilted,
+      dashCount: 8
+    });
+    for (const [, y, z] of toVertices(geom.positions)) {
+      expect(y).toBeCloseTo(z);
+    }
+  });
+  it('references only in-range vertices from the index buffer', () => {
+    const geom = boundaryRingMesh({
+      center: new Vec3(0, 0, 0),
+      radius: 5,
+      width: 0.1,
+      groundPlane: FLAT,
+      dashCount: 8
+    });
+    const vertexCount = geom.positions.length / 3;
+    for (const idx of geom.indices) {
+      expect(idx).toBeGreaterThanOrEqual(0);
+      expect(idx).toBeLessThan(vertexCount);
+    }
+  });
+  it('returns empty geometry for a non-positive radius', () => {
+    const geom = boundaryRingMesh({
+      center: new Vec3(0, 0, 0),
+      radius: 0,
+      width: 0.1,
+      groundPlane: FLAT
+    });
+    expect(geom.positions).toHaveLength(0);
+    expect(geom.indices).toHaveLength(0);
+  });
+  it('returns empty geometry for a non-positive width', () => {
+    const geom = boundaryRingMesh({
+      center: new Vec3(0, 0, 0),
+      radius: 5,
+      width: 0,
+      groundPlane: FLAT
+    });
+    expect(geom.positions).toHaveLength(0);
+  });
+  it('returns empty geometry for a non-positive dashCount', () => {
+    const geom = boundaryRingMesh({
+      center: new Vec3(0, 0, 0),
+      radius: 5,
+      width: 0.1,
+      groundPlane: FLAT,
+      dashCount: 0
+    });
+    expect(geom.positions).toHaveLength(0);
+  });
+  it('returns empty geometry for an invalid ground plane', () => {
+    const collinear = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(2, 0, 0)];
+    const geom = boundaryRingMesh({
+      center: new Vec3(0, 0, 0),
+      radius: 5,
+      width: 0.1,
+      groundPlane: collinear
+    });
+    expect(geom.positions).toHaveLength(0);
+  });
+});

package/components/VirtualWalkthrough/groundPlane.d.ts

@@ -0,0 +1,14 @@
+import { Vec3 } from 'playcanvas';
+export type GroundPlane = {
+    normal: Vec3;
+    point: Vec3;
+};
+/** Compute Y on the plane defined by `normal` passing through `point` at world XZ coords (x, z). */
+export declare const yOnPlane: (x: number, z: number, normal: Vec3, point: Vec3, fallback: number) => number;
+/**
+ * Derive a ground plane from 3 world-space points.
+ * Returns a normalized normal (flipped so normal.y >= 0) and a point on the plane,
+ * or null when fewer than 3 points are supplied or they are degenerate/collinear.
+ */
+export declare const computeGroundPlane: (points: Vec3[]) => GroundPlane | null;
+//# sourceMappingURL=groundPlane.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"groundPlane.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/groundPlane.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,MAAM,WAAW,GAAG;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,CAAC;AAExD,oGAAoG;AACpG,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,QAAQ,IAAI,EAAE,OAAO,IAAI,EAAE,UAAU,MAAM,KAAG,MAM5F,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,IAAI,EAAE,KAAG,WAAW,GAAG,IA8BjE,CAAC"}

package/components/VirtualWalkthrough/groundPlane.js

@@ -0,0 +1,47 @@
+import { Vec3 } from 'playcanvas';
+/** Compute Y on the plane defined by `normal` passing through `point` at world XZ coords (x, z). */
+export const yOnPlane = (x, z, normal, point, fallback) => {
+  if (Math.abs(normal.y) < 1e-6) {
+    return fallback;
+  }
+  return point.y - (normal.x * (x - point.x) + normal.z * (z - point.z)) / normal.y;
+};
+
+/**
+ * Derive a ground plane from 3 world-space points.
+ * Returns a normalized normal (flipped so normal.y >= 0) and a point on the plane,
+ * or null when fewer than 3 points are supplied or they are degenerate/collinear.
+ */
+export const computeGroundPlane = points => {
+  if (points.length < 3) {
+    return null;
+  }
+  const p0 = points[0];
+  const p1 = points[1];
+  const p2 = points[2];
+  const v1x = p1.x - p0.x;
+  const v1y = p1.y - p0.y;
+  const v1z = p1.z - p0.z;
+  const v2x = p2.x - p0.x;
+  const v2y = p2.y - p0.y;
+  const v2z = p2.z - p0.z;
+  let nx = v1y * v2z - v1z * v2y;
+  let ny = v1z * v2x - v1x * v2z;
+  let nz = v1x * v2y - v1y * v2x;
+  const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  if (len < 1e-10) {
+    return null;
+  }
+  nx /= len;
+  ny /= len;
+  nz /= len;
+  if (ny < 0) {
+    nx = -nx;
+    ny = -ny;
+    nz = -nz;
+  }
+  return {
+    normal: new Vec3(nx, ny, nz),
+    point: new Vec3(p0.x, p0.y, p0.z)
+  };
+};