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

package/components/VirtualWalkthrough/TfAnnotationManager.js

@@ -0,0 +1,368 @@
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { FILTER_LINEAR, PIXELFORMAT_RGBA8, Texture } from 'playcanvas';
+import { AnnotationManager as PcAnnotationManager } from 'playcanvas/scripts/esm/annotations.mjs';
+import Icon from '../Icon/Icon';
+// Maps each annotation icon type to a @terraware/web-components icon.
+const ANNOTATION_ICONS = {
+  text: 'iconComment',
+  image: 'iconPhoto',
+  video: 'iconVideo'
+};
+
+// Pixel dimensions of the (square) hotspot texture canvas at rest.
+const HOTSPOT_TEXTURE_SIZE = 64;
+
+// How much larger the hotspot appears while hovered.
+const HOTSPOT_HOVER_SCALE = 1.3;
+
+/**
+ * Extended AnnotationManager that adds max size clamping for annotations
+ * and fixes positioning when canvas is not at document origin.
+ */
+export class TfAnnotationManager extends PcAnnotationManager {
+  static scriptName = 'tfAnnotationManager';
+  _maxWorldSize = 1.0;
+  _customParentDom = null;
+  _clickHandlersAttached = new Set();
+  _hotspotBackgroundColor = '#2C8658';
+  _iconImages = new Map();
+
+  /**
+   * Maximum world-space size for annotations.
+   * This prevents annotations from growing beyond this size regardless of camera distance.
+   *
+   * @attribute
+   * @title Max World Size
+   * @type {number}
+   * @default 1.0
+   */
+  set maxWorldSize(value) {
+    this._maxWorldSize = value;
+  }
+  get maxWorldSize() {
+    return this._maxWorldSize;
+  }
+
+  /**
+   * Background color for the hotspot texture canvas (the circle fill color).
+   * This is a hex color string (e.g., '#2C8658') that's drawn on the texture canvas.
+   * Note: This is different from hotspotColor and hoverColor, which are PlayCanvas Color objects
+   * used for the material's emissive property.
+   *
+   * @attribute
+   * @title Hotspot Background Color
+   * @type {string}
+   * @default '#2C8658'
+   */
+  set hotspotBackgroundColor(value) {
+    this._hotspotBackgroundColor = value;
+  }
+  get hotspotBackgroundColor() {
+    return this._hotspotBackgroundColor;
+  }
+
+  /**
+   * Initialize with custom parent DOM if needed.
+   */
+  initialize() {
+    // Find a container div with data-annotation-container attribute
+    const canvas = this.app.graphicsDevice.canvas;
+    const container = canvas.parentElement?.querySelector('[data-annotation-container]');
+    if (container) {
+      this._customParentDom = container;
+      this._parentDom = container;
+    }
+
+    // Call parent initialize
+    super.initialize();
+    this._loadIconImages();
+  }
+
+  /**
+   * Renders each web-components icon to an SVG image once. When an image finishes
+   * loading, any annotations already using that icon are redrawn.
+   * @private
+   */
+  _loadIconImages() {
+    const fillColor = this._hotspotColor?.toString() ?? '#ffffff';
+    Object.keys(ANNOTATION_ICONS).forEach(iconType => {
+      const name = ANNOTATION_ICONS[iconType];
+      const markup = renderToStaticMarkup(/*#__PURE__*/createElement(Icon, {
+        name,
+        fillColor
+      })).replace(/^<svg/, '<svg width="128" height="128"');
+      const image = new Image();
+      image.onload = () => this._refreshIcon(iconType);
+      image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
+      this._iconImages.set(iconType, image);
+    });
+  }
+
+  /**
+   * Redraws the texture for all annotations using the given icon, once its image
+   * has loaded.
+   * @private
+   */
+  _refreshIcon(iconType) {
+    const annotationResources = this._annotationResources;
+    if (!annotationResources) {
+      return;
+    }
+    annotationResources.forEach((_resources, annotation) => {
+      if ((annotation.icon ?? 'text') === iconType) {
+        this._applyAnnotationIcon(annotation);
+      }
+    });
+  }
+
+  /**
+   * Update loop to attach click handlers to annotations and manage visibility.
+   */
+  update() {
+    const annotationResources = this._annotationResources;
+    if (!annotationResources) {
+      return;
+    }
+
+    // Attach click handlers and manage visibility for all annotations
+    annotationResources.forEach((resources, annotation) => {
+      if (resources && resources.hotspotDom) {
+        // Attach click handler if not already attached
+        if (!this._clickHandlersAttached.has(annotation)) {
+          const callback = annotation.onClickCallback;
+          if (callback) {
+            this._clickHandlersAttached.add(annotation);
+            resources.hotspotDom.addEventListener('pointerdown', e => {
+              callback(e.clientX, e.clientY);
+            });
+          }
+        }
+
+        // Disable/enable the entity itself based on visibility
+        const isVisible = annotation.enabled !== undefined ? annotation.enabled : true;
+
+        // Hide tooltip if the active annotation is hidden
+        if (this._activeAnnotation === annotation && !isVisible) {
+          this._tooltipDom.style.visibility = 'hidden';
+          this._tooltipDom.style.opacity = '0';
+          this._activeAnnotation = null;
+        }
+      }
+    });
+  }
+
+  /**
+   * Override annotation registration to draw the media icon onto the hotspot
+   * texture once the annotation (and its icon) is available.
+   * @private
+   */
+  _registerAnnotation(annotation) {
+    super._registerAnnotation(annotation);
+    this._applyAnnotationIcon(annotation);
+  }
+
+  /**
+   * Recreates the hotspot texture with the appropriate media icon drawn on it.
+   * @private
+   */
+  _applyAnnotationIcon(annotation) {
+    const resources = this._annotationResources.get(annotation);
+    if (!resources) {
+      return;
+    }
+    const icon = annotation.icon ?? 'text';
+    resources.texture.destroy();
+    resources.texture = this._createHotspotTexture(annotation.label, HOTSPOT_TEXTURE_SIZE, 6, icon);
+    resources.materials.forEach(material => {
+      material.emissiveMap = resources.texture;
+      material.opacityMap = resources.texture;
+      material.update();
+    });
+  }
+
+  /**
+   * Draws the icon image onto the hotspot texture canvas, scaled to fit the
+   * circle. Does nothing if the image has not finished loading yet; the
+   * annotation is redrawn once it has (see `_refreshIcon`).
+   * @private
+   */
+  _drawIcon(ctx, icon, size) {
+    const image = this._iconImages.get(icon);
+    if (!image || !image.complete || image.naturalWidth === 0) {
+      return;
+    }
+    const iconSize = size * 0.5;
+    const offset = (size - iconSize) / 2;
+    ctx.drawImage(image, offset, offset, iconSize, iconSize);
+  }
+
+  /**
+   * Keep the media icon drawn on the hotspot texture. The label text itself
+   * is not rendered on the hotspot, so we simply redraw with the icon.
+   * @private
+   */
+  _onLabelChange(annotation) {
+    this._applyAnnotationIcon(annotation);
+  }
+
+  /**
+   * The hotspot colors are baked into the texture in `_createHotspotTexture`,
+   * so the material emissive is kept white to let those colors render as drawn.
+   * @private
+   */
+  _createHotspotMaterial(texture, options) {
+    const material = super._createHotspotMaterial(texture, options);
+    material.emissive.set(1, 1, 1);
+    material.update();
+    return material;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _setAnnotationHover(_annotation, _hover) {
+    // No-op: the hover growth is handled in _updateAnnotationRotationAndScale
+    // (via _hoverAnnotation); the texture is identical in both states.
+  }
+  _updateAllAnnotationColors() {
+    // No-op: hotspot colors are baked into the texture (see _createHotspotMaterial).
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _showTooltip(_annotation) {
+    // No-op: AnnotationPanel handles all annotation UI, this removes default behavior
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _onTextChange(_annotation, _text) {
+    // No-op: AnnotationPanel handles all annotation UI, this removes default behavior
+  }
+
+  /**
+   * Override position update to adjust for canvas offset and respect visibility.
+   * @private
+   */
+  _updateAnnotationPositions(annotation, resources, screenPos) {
+    const canvas = this.app.graphicsDevice.canvas;
+    const rect = canvas.getBoundingClientRect();
+
+    // If using a custom parent (positioned container), use raw screen coordinates
+    // Otherwise, adjust for canvas position in document
+    const offsetX = this._customParentDom ? 0 : rect.left + window.scrollX;
+    const offsetY = this._customParentDom ? 0 : rect.top + window.scrollY;
+
+    // Check if annotation is visible (defaults to true if not specified)
+    const isVisible = annotation.enabled !== undefined ? annotation.enabled : true;
+    resources.hotspotDom.style.display = isVisible ? 'block' : 'none';
+    resources.hotspotDom.style.left = `${screenPos.x + offsetX}px`;
+    resources.hotspotDom.style.top = `${screenPos.y + offsetY}px`;
+    if (this._activeAnnotation === annotation) {
+      this._tooltipDom.style.display = isVisible ? 'block' : 'none';
+      this._tooltipDom.style.left = `${screenPos.x + offsetX}px`;
+      this._tooltipDom.style.top = `${screenPos.y + offsetY}px`;
+    }
+    if (annotation.onScreenPositionUpdateCallback) {
+      // Rendered hotspot diameter (px), set by _updateAnnotationRotationAndScale.
+      // Parsed from the style rather than measured to avoid forcing a reflow.
+      const hotspotSize = parseFloat(resources.hotspotDom.style.width) || undefined;
+      annotation.onScreenPositionUpdateCallback(screenPos.x + offsetX, screenPos.y + offsetY, hotspotSize);
+    }
+  }
+
+  /**
+   * Override the scale update to clamp the world size to a maximum value.
+   * Also scales the hotspot DOM element to match.
+   * @private
+   */
+  _updateAnnotationRotationAndScale(annotation) {
+    const cameraRotation = this._camera.getRotation();
+    annotation.entity.setRotation(cameraRotation);
+    annotation.entity.rotateLocal(90, 0, 0);
+    const cameraPos = this._camera.getPosition();
+    const distance = annotation.entity.getPosition().distance(cameraPos);
+    const canvas = this.app.graphicsDevice.canvas;
+    const screenHeight = canvas.clientHeight;
+    const projMatrix = this._camera.camera.projectionMatrix;
+
+    // Calculate world size based on screen size and distance
+    const unclamped = this._hotspotSize / screenHeight * (2 * distance / projMatrix.data[5]);
+
+    // Clamp to maximum world size
+    const worldSize = Math.min(unclamped, this._maxWorldSize);
+    const hovered = this._hoverAnnotation === annotation;
+    const hoverScale = hovered ? HOTSPOT_HOVER_SCALE : 1;
+    const entityScale = worldSize * hoverScale;
+    annotation.entity.setLocalScale(entityScale, entityScale, entityScale);
+
+    // Scale the hotspot DOM element proportionally when clamped, including the
+    // hover growth so it tracks the visible circle.
+    const resources = this._annotationResources.get(annotation);
+    if (resources && resources.hotspotDom) {
+      const scaleFactor = worldSize / unclamped;
+      const baseSize = this._hotspotSize + 5; // Match the +5 from the stylesheet
+      const scaledSize = baseSize * scaleFactor * hoverScale;
+      resources.hotspotDom.style.width = `${scaledSize}px`;
+      resources.hotspotDom.style.height = `${scaledSize}px`;
+    }
+  }
+
+  /**
+   * Override to create hotspot texture with custom background color.
+   * @private
+   */
+  _createHotspotTexture(label, size = HOTSPOT_TEXTURE_SIZE, borderWidth = 6, icon) {
+    const canvas = document.createElement('canvas');
+    canvas.width = size;
+    canvas.height = size;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+      throw new Error('Failed to get canvas 2d context');
+    }
+
+    // First clear with stroke color at zero alpha
+    ctx.fillStyle = 'white';
+    ctx.globalAlpha = 0;
+    ctx.fillRect(0, 0, size, size);
+    ctx.globalAlpha = 1.0;
+
+    // Draw circle with custom background color
+    const centerX = size / 2;
+    const centerY = size / 2;
+    const radius = size / 2 - 4;
+
+    // The icon fill and border share the hotspot color
+    const foregroundColor = this._hotspotColor?.toString() ?? '#ffffff';
+
+    // Draw main circle
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+    ctx.fillStyle = this._hotspotBackgroundColor;
+    ctx.fill();
+
+    // Draw border
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+    ctx.lineWidth = borderWidth;
+    ctx.strokeStyle = foregroundColor;
+    ctx.stroke();
+
+    // Draw the media icon inside the circle
+    if (icon) {
+      this._drawIcon(ctx, icon, size);
+    }
+
+    // Get pixel data
+    const imageData = ctx.getImageData(0, 0, size, size);
+    const data = imageData.data;
+
+    // Create and return the texture
+    return new Texture(this.app.graphicsDevice, {
+      width: size,
+      height: size,
+      format: PIXELFORMAT_RGBA8,
+      magFilter: FILTER_LINEAR,
+      minFilter: FILTER_LINEAR,
+      mipmaps: false,
+      levels: [new Uint8Array(data.buffer)]
+    });
+  }
+}

package/components/VirtualWalkthrough/TfXrNavigation.d.ts

@@ -0,0 +1,15 @@
+import { XrNavigation as PcXrNavigation } from 'playcanvas/scripts/esm/xr-navigation.mjs';
+/**
+ * Extended XrNavigation that fixes the bug where tryTeleport doesn't respect
+ * the enableTeleport flag setting.
+ */
+export declare class TfXrNavigation extends PcXrNavigation {
+    static scriptName: string;
+    /**
+     * Override tryTeleport to respect the enableTeleport flag.
+     * The base implementation is always called from handleSelectEnd,
+     * but we only want to teleport when enableTeleport is true.
+     */
+    tryTeleport(inputSource: any): void;
+}
+//# sourceMappingURL=TfXrNavigation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TfXrNavigation.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/TfXrNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE1F;;;GAGG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,MAAM,CAAC,UAAU,SAAoB;IAErC;;;;OAIG;IACH,WAAW,CAAC,WAAW,EAAE,GAAG;CAS7B"}

package/components/VirtualWalkthrough/TfXrNavigation.js

@@ -0,0 +1,24 @@
+import { XrNavigation as PcXrNavigation } from 'playcanvas/scripts/esm/xr-navigation.mjs';
+
+/**
+ * Extended XrNavigation that fixes the bug where tryTeleport doesn't respect
+ * the enableTeleport flag setting.
+ */
+export class TfXrNavigation extends PcXrNavigation {
+  static scriptName = 'tfXrNavigation';
+
+  /**
+   * Override tryTeleport to respect the enableTeleport flag.
+   * The base implementation is always called from handleSelectEnd,
+   * but we only want to teleport when enableTeleport is true.
+   */
+  tryTeleport(inputSource) {
+    // Only proceed with teleportation if enableTeleport is true
+    if (!this.enableTeleport) {
+      return;
+    }
+
+    // Call the parent implementation
+    super.tryTeleport(inputSource);
+  }
+}

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