@terraware/web-components 4.2.12 → 4.2.14-rc.0

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)
+  };
+};

package/components/VirtualWalkthrough/groundPlane.test.js

@@ -0,0 +1,45 @@
+import { Vec3 } from 'playcanvas';
+import { computeGroundPlane, yOnPlane } from './groundPlane';
+describe('computeGroundPlane', () => {
+  it('returns an up normal for a flat horizontal plane', () => {
+    const plane = computeGroundPlane([new Vec3(0, 5, 0), new Vec3(1, 5, 0), new Vec3(0, 5, 1)]);
+    expect(plane).not.toBeNull();
+    expect(plane.normal.x).toBeCloseTo(0);
+    expect(plane.normal.y).toBeCloseTo(1);
+    expect(plane.normal.z).toBeCloseTo(0);
+    expect(plane.point.y).toBeCloseTo(5);
+  });
+  it('flips a downward-facing normal so normal.y >= 0', () => {
+    const plane = computeGroundPlane([new Vec3(0, 0, 0), new Vec3(0, 0, 1), new Vec3(1, 0, 0)]);
+    expect(plane).not.toBeNull();
+    expect(plane.normal.y).toBeCloseTo(1);
+  });
+  it('computes a unit normal for a plane tilted 45deg about X (y = z)', () => {
+    const plane = computeGroundPlane([new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(0, 1, 1)]);
+    expect(plane).not.toBeNull();
+    const n = plane.normal;
+    expect(Math.sqrt(n.x * n.x + n.y * n.y + n.z * n.z)).toBeCloseTo(1);
+    expect(n.x).toBeCloseTo(0);
+    expect(n.y).toBeCloseTo(Math.SQRT1_2);
+    expect(n.z).toBeCloseTo(-Math.SQRT1_2);
+  });
+  it('returns null for fewer than 3 points', () => {
+    expect(computeGroundPlane([new Vec3(0, 0, 0), new Vec3(1, 0, 0)])).toBeNull();
+  });
+  it('returns null for collinear points', () => {
+    expect(computeGroundPlane([new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(2, 0, 0)])).toBeNull();
+  });
+});
+describe('yOnPlane', () => {
+  it('returns the constant height on a flat plane', () => {
+    expect(yOnPlane(3, 7, new Vec3(0, 1, 0), new Vec3(0, 5, 0), -1)).toBeCloseTo(5);
+  });
+  it('interpolates height on a plane where y = z', () => {
+    const n = new Vec3(0, Math.SQRT1_2, -Math.SQRT1_2);
+    expect(yOnPlane(0, 2, n, new Vec3(0, 0, 0), 0)).toBeCloseTo(2);
+    expect(yOnPlane(10, -3, n, new Vec3(0, 0, 0), 0)).toBeCloseTo(-3);
+  });
+  it('returns the fallback when the normal is (near) horizontal', () => {
+    expect(yOnPlane(1, 1, new Vec3(1, 0, 0), new Vec3(0, 9, 0), 42)).toBe(42);
+  });
+});

package/components/VirtualWalkthrough/gsplat-fade-crop-effect.d.ts

@@ -0,0 +1,19 @@
+import { Vec3 } from 'playcanvas';
+import { GsplatShaderEffect } from 'playcanvas/scripts/esm/gsplat/gsplat-shader-effect.mjs';
+/**
+ * Fade crop shader effect for gaussian splats.
+ * Applies a smooth fade to splats outside the AABB based on distance.
+ * Splats at the AABB edge are fully visible, and fade to invisible at fadeDistance away.
+ */
+export declare class GsplatFadeCropShaderEffect extends GsplatShaderEffect {
+    static scriptName: string;
+    _aabbMinArray: number[];
+    _aabbMaxArray: number[];
+    aabbMin: Vec3;
+    aabbMax: Vec3;
+    fadeDistance: number;
+    getShaderGLSL(): string;
+    getShaderWGSL(): string;
+    updateEffect(): void;
+}
+//# sourceMappingURL=gsplat-fade-crop-effect.d.ts.map

package/components/VirtualWalkthrough/gsplat-fade-crop-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gsplat-fade-crop-effect.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/gsplat-fade-crop-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AA0F5F;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,kBAAkB;IAChE,MAAM,CAAC,UAAU,SAAgC;IAEjD,aAAa,WAAa;IAC1B,aAAa,WAAa;IAE1B,OAAO,OAA8B;IACrC,OAAO,OAA2B;IAClC,YAAY,SAAO;IAEnB,aAAa;IAIb,aAAa;IAIb,YAAY;CAab"}

package/components/VirtualWalkthrough/gsplat-fade-crop-effect.js

@@ -0,0 +1,119 @@
+import { Vec3 } from 'playcanvas';
+import { GsplatShaderEffect } from 'playcanvas/scripts/esm/gsplat/gsplat-shader-effect.mjs';
+const shaderGLSL = /* glsl */`
+uniform vec3 uAabbMin;
+uniform vec3 uAabbMax;
+uniform float uFadeDistance;
+
+void modifySplatCenter(inout vec3 center) {
+    // No modifications needed
+}
+
+void modifySplatRotationScale(vec3 originalCenter, vec3 modifiedCenter, inout vec4 rotation, inout vec3 scale) {
+    // Check if splat is inside AABB
+    bool insideAABB = all(greaterThanEqual(modifiedCenter, uAabbMin)) && all(lessThanEqual(modifiedCenter, uAabbMax));
+
+    if (insideAABB) {
+        // Inside the box, no fade needed
+        return;
+    }
+
+    // Calculate distance to AABB for splats outside
+    vec3 distToMin = uAabbMin - modifiedCenter;
+    vec3 distToMax = modifiedCenter - uAabbMax;
+
+    // Get the maximum positive distance on each axis (how far outside we are)
+    vec3 outsideDistance = max(distToMin, distToMax);
+    outsideDistance = max(outsideDistance, vec3(0.0));
+
+    // Use the maximum distance across all axes
+    float maxOutsideDistance = max(max(outsideDistance.x, outsideDistance.y), outsideDistance.z);
+
+    // Calculate fade factor: 1.0 at edge, 0.0 at fadeDistance away
+    float fadeFactor = 1.0 - clamp(maxOutsideDistance / uFadeDistance, 0.0, 1.0);
+
+    // Apply smooth fade using smoothstep for nicer transition
+    fadeFactor = smoothstep(0.0, 1.0, fadeFactor);
+
+    // Scale the splat based on fade factor
+    scale *= fadeFactor;
+}
+
+void modifySplatColor(vec3 center, inout vec4 color) {
+    // No color modification needed
+}
+`;
+const shaderWGSL = /* wgsl */`
+uniform uAabbMin: vec3f;
+uniform uAabbMax: vec3f;
+uniform uFadeDistance: f32;
+
+fn modifySplatCenter(center: ptr<function, vec3f>) {
+    // No modifications needed
+}
+
+fn modifySplatRotationScale(originalCenter: vec3f, modifiedCenter: vec3f, rotation: ptr<function, vec4f>, scale: ptr<function, vec3f>) {
+    // Check if splat is inside AABB
+    let insideAABB = all(modifiedCenter >= uniform.uAabbMin) && all(modifiedCenter <= uniform.uAabbMax);
+
+    if (insideAABB) {
+        // Inside the box, no fade needed
+        return;
+    }
+
+    // Calculate distance to AABB for splats outside
+    let distToMin = uniform.uAabbMin - modifiedCenter;
+    let distToMax = modifiedCenter - uniform.uAabbMax;
+
+    // Get the maximum positive distance on each axis (how far outside we are)
+    var outsideDistance = max(distToMin, distToMax);
+    outsideDistance = max(outsideDistance, vec3f(0.0));
+
+    // Use the maximum distance across all axes
+    let maxOutsideDistance = max(max(outsideDistance.x, outsideDistance.y), outsideDistance.z);
+
+    // Calculate fade factor: 1.0 at edge, 0.0 at fadeDistance away
+    var fadeFactor = 1.0 - clamp(maxOutsideDistance / uniform.uFadeDistance, 0.0, 1.0);
+
+    // Apply smooth fade using smoothstep for nicer transition
+    fadeFactor = smoothstep(0.0, 1.0, fadeFactor);
+
+    // Scale the splat based on fade factor
+    *scale = (*scale) * fadeFactor;
+}
+
+fn modifySplatColor(center: vec3f, color: ptr<function, vec4f>) {
+    // No color modification needed
+}
+`;
+
+/**
+ * Fade crop shader effect for gaussian splats.
+ * Applies a smooth fade to splats outside the AABB based on distance.
+ * Splats at the AABB edge are fully visible, and fade to invisible at fadeDistance away.
+ */
+export class GsplatFadeCropShaderEffect extends GsplatShaderEffect {
+  static scriptName = 'gsplatFadeCropShaderEffect';
+  _aabbMinArray = [0, 0, 0];
+  _aabbMaxArray = [0, 0, 0];
+  aabbMin = new Vec3(-0.5, -0.5, -0.5);
+  aabbMax = new Vec3(0.5, 0.5, 0.5);
+  fadeDistance = 0.5;
+  getShaderGLSL() {
+    return shaderGLSL;
+  }
+  getShaderWGSL() {
+    return shaderWGSL;
+  }
+  updateEffect() {
+    this._aabbMinArray[0] = this.aabbMin.x;
+    this._aabbMinArray[1] = this.aabbMin.y;
+    this._aabbMinArray[2] = this.aabbMin.z;
+    this.setUniform('uAabbMin', this._aabbMinArray);
+    this._aabbMaxArray[0] = this.aabbMax.x;
+    this._aabbMaxArray[1] = this.aabbMax.y;
+    this._aabbMaxArray[2] = this.aabbMax.z;
+    this.setUniform('uAabbMax', this._aabbMaxArray);
+    this.setUniform('uFadeDistance', this.fadeDistance);
+  }
+}

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

@@ -0,0 +1,77 @@
+import { Script, Vec3 } from 'playcanvas';
+export declare class WalkthroughCamera extends Script {
+    static scriptName: string;
+    /** @attribute */
+    moveSpeed: number;
+    /** @attribute */
+    moveFastSpeed: number;
+    /** @attribute */
+    moveSlowSpeed: number;
+    /** @attribute */
+    lookSensitivity: number;
+    /** @attribute */
+    rotateDamping: number;
+    /** @attribute */
+    pitchMin: number;
+    /** @attribute */
+    pitchMax: number;
+    /** @attribute */
+    scrollSpeed: number;
+    /** @attribute */
+    boundsCenter: Vec3;
+    /** @attribute */
+    boundsRadius: number;
+    /** @attribute */
+    freeFly: boolean;
+    /** @attribute */
+    enableFly: boolean;
+    /** @attribute */
+    averageCameraHeight: number;
+    /**
+     * Three world-space points defining the ground plane.
+     * When provided, the camera Y position is derived from this plane during non-freeFly movement.
+     *
+     * Not a React prop — must be set directly on the script instance via useEffect. The @playcanvas/react
+     * Script component is wrapped in memo() whose shallowEquals comparator returns early on the first prop
+     * with a .equals() method (Vec3), so any prop listed after boundsCenter is never compared and the
+     * component won't re-render when it changes. Set via:
+     *   app.root.findByName('camera')?.script?.walkthroughCamera.groundPlane = points
+     * Should be updated if shallowEquals is fixed (see https://github.com/playcanvas/react/pull/298)
+     */
+    groundPlane: Vec3[];
+    private _pitch;
+    private _yaw;
+    private _targetPitch;
+    private _targetYaw;
+    private _isDragging;
+    private _lastX;
+    private _lastY;
+    private _scrollDelta;
+    private _keys;
+    private _removeListeners;
+    private _planeNormal;
+    private _planePoint;
+    private _hasGroundPlane;
+    private _syncGroundPlane;
+    initialize(): void;
+    /**
+     * Position the camera at `position` looking toward `focus`.
+     * Compatible with the useCameraPosition hook's reset() call.
+     */
+    reset(focus: Vec3, position: Vec3): void;
+    get currentYaw(): number;
+    get currentPitch(): number;
+    /**
+     * Orbit the camera by `yawDelta` degrees around `boundsCenter`.
+     * Called by AutoRotator
+     */
+    orbitStep(yawDelta: number): void;
+    /**
+     * Returns the point directly in front of the camera.
+     * Compatible with the useCameraPosition hook's focusPoint read.
+     */
+    get focusPoint(): Vec3;
+    update(dt: number): void;
+    destroy(): void;
+}
+//# sourceMappingURL=walkthrough-camera.d.ts.map

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

@@ -0,0 +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"}