@needle-tools/usd 0.0.2-next.d90870e → 1.0.0-next.4d692f6

package/src/hydra/ThreeJsRenderDelegate.js

@@ -1,7 +1,35 @@
-import { TextureLoader, BufferGeometry, MeshPhysicalMaterial, DoubleSide, Color, Mesh, Float32BufferAttribute, SRGBColorSpace, RGBAFormat, RepeatWrapping, LinearSRGBColorSpace, Vector2 } from 'three';
+import * as THREE from 'three';
 import { TGALoader } from 'three/addons/loaders/TGALoader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 
+const {
+  TextureLoader,
+  BufferGeometry,
+  MeshPhysicalMaterial,
+  FrontSide,
+  BackSide,
+  DoubleSide,
+  Color,
+  Mesh,
+  InstancedMesh,
+  Matrix4,
+  Float32BufferAttribute,
+  SRGBColorSpace,
+  RGBAFormat,
+  RepeatWrapping,
+  LinearSRGBColorSpace,
+  Vector2,
+  CameraHelper,
+  DirectionalLight,
+  DirectionalLightHelper,
+  HemisphereLight,
+  OrthographicCamera,
+  PerspectiveCamera,
+  PointLight,
+  PointLightHelper,
+  MathUtils,
+} = THREE;
+
 const debugTextures = false;
 const debugMaterials = false;
 const debugMeshes = false;
@@ -9,6 +37,113 @@ const debugPrims = false;
 const disableTextures = false;
 const disableMaterials = false;
 
+let materialXModulePromise = null;
+
+async function getMaterialXModule() {
+  materialXModulePromise ??= import('@needle-tools/materialx').then(module => ({
+    MaterialX: module.Experimental_API,
+    MaterialXMaterial: module.MaterialXMaterial,
+  }));
+  return materialXModulePromise;
+}
+
+function disposeTexture(texture, disposed = new Set()) {
+  if (!texture || disposed.has(texture) || typeof texture.dispose !== 'function') return;
+  disposed.add(texture);
+  texture.dispose();
+}
+
+function disposeMaterialResources(material, disposedMaterials = new Set(), disposedTextures = new Set()) {
+  if (!material) return;
+  if (Array.isArray(material)) {
+    for (const entry of material) disposeMaterialResources(entry, disposedMaterials, disposedTextures);
+    return;
+  }
+  if (disposedMaterials.has(material)) return;
+  disposedMaterials.add(material);
+
+  for (const value of Object.values(material)) {
+    if (value && typeof value === 'object' && value.isTexture) {
+      disposeTexture(value, disposedTextures);
+    }
+  }
+
+  if (material !== defaultMaterial && typeof material.dispose === 'function') {
+    material.dispose();
+  }
+}
+
+function disposeObjectResources(object) {
+  if (!object) return;
+  object.traverse?.((entry) => {
+    entry.geometry?.dispose?.();
+    disposeMaterialResources(entry.material);
+  });
+  object.parent?.remove(object);
+}
+
+function isFiniteArray(values, dimension = 3) {
+  if (!values || values.length === 0 || values.length % dimension !== 0) return false;
+  for (let i = 0; i < values.length; i++) {
+    if (!Number.isFinite(values[i])) return false;
+  }
+  return true;
+}
+
+function cullStyleToThreeSide(doubleSided, cullStyle) {
+  switch (cullStyle) {
+    case "nothing":
+      return DoubleSide;
+    case "back":
+      return FrontSide;
+    case "front":
+      return BackSide;
+    case "frontUnlessDoubleSided":
+      return doubleSided ? DoubleSide : BackSide;
+    case "backUnlessDoubleSided":
+    case "dontCare":
+    default:
+      return doubleSided ? DoubleSide : FrontSide;
+  }
+}
+
+function primNameFromPath(id, fallback) {
+  const path = String(id || "");
+  const slash = path.lastIndexOf("/");
+  return slash >= 0 ? path.substring(slash + 1) || fallback : path || fallback;
+}
+
+function applyHydraTransform(object, matrix) {
+  if (!object || !matrix || matrix.length < 16) return;
+  object.matrix.set(...Array.from(matrix).slice(0, 16));
+  object.matrix.transpose();
+  object.matrix.decompose(object.position, object.quaternion, object.scale);
+  object.matrixAutoUpdate = true;
+}
+
+const defaultScenePrimitiveLightIntensityScale = 0.01;
+const lightSprimTypeIds = new Set([
+  "domeLight",
+  "cylinderLight",
+  "diskLight",
+  "distantLight",
+  "light",
+  "rectLight",
+  "simpleLight",
+  "sphereLight",
+]);
+
+const usdLightTypeNames = {
+  domeLight: "DomeLight",
+  cylinderLight: "CylinderLight",
+  diskLight: "DiskLight",
+  distantLight: "DistantLight",
+  light: "LightAPI",
+  rectLight: "RectLight",
+  simpleLight: "SimpleLight",
+  sphereLight: "SphereLight",
+};
+
 class TextureRegistry {
   /** 
    * @param {import('..').threeJsRenderDelegateConfig} config
@@ -17,6 +152,9 @@ class TextureRegistry {
     this.config = config;
     this.allPaths = config.paths;
     this.textures = [];
+    this.loadedTextures = new Set();
+    this.objectUrls = new Set();
+    this.disposed = false;
     this.loader = new TextureLoader();
     this.tgaLoader = new TGALoader();
     this.exrLoader = new EXRLoader();
@@ -32,7 +170,97 @@ class TextureRegistry {
     }
   }
 
+  normalizeResourcePath(resourcePath) {
+    const rawPath = String(resourcePath ?? "").replace(/\\/g, "/");
+    const isUrl = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(rawPath);
+    if (isUrl) {
+      return rawPath;
+    }
+
+    const preserveLeadingSlash = rawPath.startsWith("/");
+    const path = rawPath
+      .replace(/^\/+/, preserveLeadingSlash ? "/" : "")
+      .replace(/^(?:\.\/)+/, "")
+      .replace(/\/\.\//g, "/");
+    const parts = [];
+    for (const part of path.split("/")) {
+      if (!part || part === ".") continue;
+      if (part === "..") {
+        parts.pop();
+        continue;
+      }
+      parts.push(part);
+    }
+    return (preserveLeadingSlash ? "/" : "") + parts.join("/");
+  }
+
+  materialResourcePathCandidates(resourcePath) {
+    const rawPath = String(resourcePath ?? "").replace(/\\/g, "/");
+    const normalized = this.normalizeResourcePath(rawPath);
+    const withoutLeadingSlash = normalized.replace(/^\/+/, "");
+    const candidates = new Set([
+      rawPath,
+      normalized,
+      withoutLeadingSlash,
+      withoutLeadingSlash.replace(/^(?:\.\/)+/, ""),
+      withoutLeadingSlash.replace(/^(?:\.\.\/)+/, ""),
+    ]);
+
+    const pathParts = withoutLeadingSlash.split("/").filter(Boolean);
+    const texturesIndex = pathParts.lastIndexOf("textures");
+    if (texturesIndex >= 0) {
+      candidates.add(pathParts.slice(texturesIndex).join("/"));
+    }
+
+    return [...candidates].filter(Boolean);
+  }
+
+  getResourceExtension(resourcePath) {
+    const path = String(resourcePath ?? "").toLowerCase();
+    const extensionMatches = [...path.matchAll(/\.([a-z0-9]+)(?=\]|$|[?#])/g)];
+    return extensionMatches.length ? extensionMatches[extensionMatches.length - 1][1] : "";
+  }
+
+  readResolvedResource(resourcePath) {
+    if (!resourcePath?.startsWith("/") || typeof this.config.USD?.ReadFile !== "function") {
+      return null;
+    }
+
+    try {
+      const file = this.config.USD.ReadFile(resourcePath);
+      return file?.byteLength ? file : null;
+    }
+    catch {
+      return null;
+    }
+  }
+
+  resolveResourcePath(resourcePath) {
+    const candidates = this.materialResourcePathCandidates(resourcePath);
+    if (!candidates.length) return "";
+
+    const knownPaths = Array.isArray(this.allPaths) ? this.allPaths : [];
+    for (const candidate of candidates) {
+      const candidateWithoutRoot = candidate.replace(/^needle\//, "");
+      for (const knownPath of knownPaths) {
+        const known = this.normalizeResourcePath(knownPath);
+        const knownWithoutRoot = known.replace(/^needle\//, "");
+        if (
+          known === candidate ||
+          knownWithoutRoot === candidate ||
+          knownWithoutRoot === candidateWithoutRoot ||
+          knownWithoutRoot.endsWith("/" + candidateWithoutRoot)
+        ) {
+          return known;
+        }
+      }
+    }
+
+    return candidates[0];
+  }
+
   getTexture(resourcePath) {
+    resourcePath = this.resolveResourcePath(resourcePath);
     if (debugTextures) console.log("get texture", resourcePath);
     if (this.textures[resourcePath]) {
       return this.textures[resourcePath];
@@ -49,18 +277,16 @@ class TextureRegistry {
     }
 
     let filetype = undefined;
-    let lowercaseFilename = resourcePath.toLowerCase();
-    if (lowercaseFilename.indexOf('.png') >= lowercaseFilename.length - 5) {
+    const extension = this.getResourceExtension(resourcePath);
+    if (extension === 'png') {
       filetype = 'image/png';
-    } else if (lowercaseFilename.indexOf('.jpg') >= lowercaseFilename.length - 5) {
+    } else if (extension === 'jpg') {
       filetype = 'image/jpeg';
-    } else if (lowercaseFilename.indexOf('.jpeg') >= lowercaseFilename.length - 5) {
+    } else if (extension === 'jpeg') {
       filetype = 'image/jpeg';
-    } else if (lowercaseFilename.indexOf('.exr') >= lowercaseFilename.length - 4) {
-      console.warn("EXR textures are not fully supported yet", resourcePath);
-      // using EXRLoader explicitly
+    } else if (extension === 'exr') {
       filetype = 'image/x-exr';
-    } else if (lowercaseFilename.indexOf('.tga') >= lowercaseFilename.length - 4) {
+    } else if (extension === 'tga') {
       console.warn("TGA textures are not fully supported yet", resourcePath);
       // using TGALoader explicitly
       filetype = 'image/tga';
@@ -69,48 +295,69 @@ class TextureRegistry {
       // throw new Error('Unknown filetype');
     }
 
-    this.config.driver().getFile(resourcePath, async (loadedFile) => {
-      let loader = this.loader;
-      if (filetype === 'image/tga')
-        loader = this.tgaLoader;
-      else if (filetype === 'image/x-exr')
-        loader = this.exrLoader;
-
-      const baseUrl = this.baseUrl;
-      function loadFromFile(_loadedFile) {
-        let url = undefined;
-        if (debugTextures) console.log("window.driver.getFile", resourcePath, " => ", _loadedFile);
-        if (_loadedFile) {
-          let blob = new Blob([_loadedFile.slice(0)], { type: filetype });
-          url = URL.createObjectURL(blob);
-        } else {
-          if (baseUrl)
-            url = baseUrl + '/' + resourcePath;
-          else
-            url = resourcePath;
-        }
-        if (debugTextures) console.log("Loading texture from", url, "with loader", loader, "_loadedFile", _loadedFile, "baseUrl", baseUrl, "resourcePath", resourcePath);
-        // Load the texture
-        loader.load(
-          // resource URL
-          url,
-
-          // onLoad callback
-          (texture) => {
-            texture.name = resourcePath;
-            textureResolve(texture);
-          },
-
-          // onProgress callback currently not used
-          undefined,
-
-          // onError callback
-          (err) => {
-            textureReject(err);
-          }
-        );
+    let loader = this.loader;
+    if (filetype === 'image/tga')
+      loader = this.tgaLoader;
+    else if (filetype === 'image/x-exr')
+      loader = this.exrLoader;
+
+    const baseUrl = this.baseUrl;
+    const loadFromFile = (_loadedFile) => {
+      let url = undefined;
+      if (debugTextures) console.log("window.driver.getFile", resourcePath, " => ", _loadedFile);
+      if (_loadedFile) {
+        let blob = new Blob([_loadedFile.slice(0)], { type: filetype });
+        url = URL.createObjectURL(blob);
+        this.objectUrls.add(url);
+      } else {
+        if (baseUrl)
+          url = baseUrl + '/' + resourcePath;
+        else
+          url = resourcePath;
       }
+      if (debugTextures) console.log("Loading texture from", url, "with loader", loader, "_loadedFile", _loadedFile, "baseUrl", baseUrl, "resourcePath", resourcePath);
+      // Load the texture
+      loader.load(
+        // resource URL
+        url,
+
+        // onLoad callback
+        (texture) => {
+          if (url?.startsWith('blob:')) {
+            URL.revokeObjectURL(url);
+            this.objectUrls.delete(url);
+          }
+          texture.name = resourcePath;
+          if (this.disposed) {
+            texture.dispose();
+          }
+          else {
+            this.loadedTextures.add(texture);
+          }
+          textureResolve(texture);
+        },
+
+        // onProgress callback currently not used
+        undefined,
 
+        // onError callback
+        (err) => {
+          if (url?.startsWith('blob:')) {
+            URL.revokeObjectURL(url);
+            this.objectUrls.delete(url);
+          }
+          textureReject(err);
+        }
+      );
+    };
+
+    const resolvedFile = this.readResolvedResource(resourcePath);
+    if (resolvedFile) {
+      loadFromFile(resolvedFile);
+      return this.textures[resourcePath];
+    }
+
+    this.config.driver().getFile(resourcePath, async (loadedFile) => {
       if (!loadedFile) {
         // if the file is not part of the filesystem, we can still try to fetch it from the network
         if (baseUrl) {
@@ -127,6 +374,166 @@ class TextureRegistry {
 
     return this.textures[resourcePath];
   }
+
+  dispose() {
+    this.disposed = true;
+    for (const url of this.objectUrls) {
+      URL.revokeObjectURL(url);
+    }
+    this.objectUrls.clear();
+
+    for (const texture of this.loadedTextures) {
+      texture.dispose();
+    }
+    this.loadedTextures.clear();
+
+    for (const texturePromise of Object.values(this.textures)) {
+      Promise.resolve(texturePromise).then(texture => {
+        if (texture?.dispose) texture.dispose();
+      }).catch(() => {});
+    }
+    this.textures = [];
+  }
+}
+
+class HydraScenePrimitive {
+  /**
+   * @param {string} typeId
+   * @param {string} id
+   * @param {ThreeRenderDelegateInterface} hydraInterface
+   */
+  constructor(typeId, id, hydraInterface) {
+    this._typeId = typeId;
+    this._id = id;
+    this._interface = hydraInterface;
+    this._object = null;
+    this._helper = null;
+  }
+
+  updateCameraState(state) {
+    if (!this._id) return;
+    const projection = state?.projection || "perspective";
+    const isOrthographic = projection === "orthographic";
+    if (!this._object || (isOrthographic && !this._object.isOrthographicCamera) || (!isOrthographic && !this._object.isPerspectiveCamera)) {
+      this._replaceObject(isOrthographic
+        ? new OrthographicCamera(-1, 1, 1, -1, Number(state?.near) || 0.01, Number(state?.far) || 100000)
+        : new PerspectiveCamera(45, 1, Number(state?.near) || 0.01, Number(state?.far) || 100000));
+      this._object.userData.usdKind = "sprim";
+    }
+
+    const focalLength = Number(state?.focalLength) || 50;
+    const verticalAperture = Number(state?.verticalAperture) || 20.955;
+    const horizontalAperture = Number(state?.horizontalAperture) || verticalAperture;
+    const near = Number(state?.near);
+    const far = Number(state?.far);
+    if (this._object.isPerspectiveCamera) {
+      this._object.fov = MathUtils.radToDeg(2 * Math.atan((verticalAperture * 0.5) / focalLength));
+      this._object.aspect = horizontalAperture > 0 && verticalAperture > 0 ? horizontalAperture / verticalAperture : 1;
+    }
+    if (Number.isFinite(near) && near > 0) this._object.near = near;
+    if (Number.isFinite(far) && far > 0) this._object.far = far;
+    this._object.name = primNameFromPath(this._id, "UsdCamera");
+    this._object.userData.usdPath = this._id;
+    this._object.userData.usdTypeName = "Camera";
+    applyHydraTransform(this._object, state?.transform);
+    this._object.updateProjectionMatrix?.();
+    this._syncHelper();
+  }
+
+  updateLightState(state) {
+    if (!this._id) return;
+    const typeId = String(state?.typeId || this._typeId);
+    const LightCtor = typeId === "distantLight"
+      ? DirectionalLight
+      : typeId === "domeLight"
+        ? HemisphereLight
+        : PointLight;
+
+    if (!this._object || !(this._object instanceof LightCtor)) {
+      const color = new Color(1, 1, 1);
+      this._replaceObject(typeId === "domeLight"
+        ? new HemisphereLight(color, new Color(0.2, 0.2, 0.2), 1)
+        : new LightCtor(color, 1));
+      this._object.userData.usdKind = "sprim";
+    }
+
+    const colorValue = Array.isArray(state?.color) ? state.color : [1, 1, 1];
+    this._object.color?.setRGB?.(
+      Number(colorValue[0]) || 0,
+      Number(colorValue[1]) || 0,
+      Number(colorValue[2]) || 0);
+    const scale = this._interface.config.scenePrimitiveLightIntensityScale ?? defaultScenePrimitiveLightIntensityScale;
+    this._object.intensity = (Number(state?.intensity) || 0) * scale;
+    this._object.visible = state?.visible !== false;
+    this._object.name = primNameFromPath(this._id, usdLightTypeNames[typeId] || "UsdLight");
+    this._object.userData.usdPath = this._id;
+    this._object.userData.usdTypeName = usdLightTypeNames[typeId] || typeId;
+    applyHydraTransform(this._object, state?.transform);
+    this._syncHelper(state);
+  }
+
+  dispose() {
+    disposeObjectResources(this._helper);
+    disposeObjectResources(this._object);
+    this._helper = null;
+    this._object = null;
+  }
+
+  _replaceObject(object) {
+    disposeObjectResources(this._helper);
+    disposeObjectResources(this._object);
+    this._helper = null;
+    this._object = object;
+    this._interface.config.scenePrimitiveRoot?.add(object);
+  }
+
+  _syncHelper(state = {}) {
+    const object = this._object;
+    if (!object) return;
+    const wantHelper = object.isCamera
+      ? (this._interface.config.showCameraHelpers || this._interface.config.showScenePrimitiveHelpers)
+      : object.isLight
+        ? (this._interface.config.showLightHelpers || this._interface.config.showScenePrimitiveHelpers)
+        : false;
+    if (!wantHelper) {
+      disposeObjectResources(this._helper);
+      this._helper = null;
+      return;
+    }
+
+    const helperCtor = object.isCamera
+      ? CameraHelper
+      : object.isDirectionalLight
+        ? DirectionalLightHelper
+        : object.isPointLight
+          ? PointLightHelper
+          : null;
+    if (!helperCtor) {
+      disposeObjectResources(this._helper);
+      this._helper = null;
+      return;
+    }
+
+    const needsNewHelper = !this._helper ||
+      (object.isCamera && !this._helper.isCameraHelper) ||
+      (object.isDirectionalLight && this._helper.type !== "DirectionalLightHelper") ||
+      (object.isPointLight && this._helper.type !== "PointLightHelper");
+    if (needsNewHelper) {
+      disposeObjectResources(this._helper);
+      const color = object.color || new Color(1, 1, 1);
+      this._helper = object.isCamera
+        ? new CameraHelper(object)
+        : object.isDirectionalLight
+          ? new DirectionalLightHelper(object, 0.5, color)
+          : new PointLightHelper(object, Number(state?.radius) || 0.25, color);
+      this._helper.name = `${object.name}Helper`;
+      this._helper.userData.usdHelperFor = this._id;
+      this._interface.config.scenePrimitiveRoot?.add(this._helper);
+    }
+    this._helper.name = `${object.name}Helper`;
+    this._helper.visible = object.visible;
+    this._helper.update?.();
+  }
 }
 
 class HydraMesh {
@@ -140,18 +547,28 @@ class HydraMesh {
     this._interface = hydraInterface;
     this._points = undefined;
     this._normals = undefined;
+    this._tangents = undefined;
     this._colors = undefined;
     this._uvs = undefined;
     this._indices = undefined;
     this._materials = [];
+    this._materialSideClones = new Map();
+    this._side = DoubleSide;
+    this._visible = false;
+    this._renderTag = 'geometry';
+    this._instancedMesh = null;
+    this._instanceMatrix = new Matrix4();
 
     let material = new MeshPhysicalMaterial({
       side: DoubleSide,
       color: new Color(0xB4B4B4),
       // envMap: hydraInterface.config.envMap,
     });
+    this._ownedMaterial = material;
     this._materials.push(material);
     this._mesh = new Mesh(this._geometry, material);
+    this._installMeshHooks(this._mesh);
+    this._mesh.visible = false;
     this._mesh.castShadow = true;
     this._mesh.receiveShadow = true;
 
@@ -168,17 +585,47 @@ class HydraMesh {
     hydraInterface.config.usdRoot.add(this._mesh); // FIXME
   }
 
+  dispose() {
+    if (!this._mesh) return;
+    this._interface.unassignMeshFromMaterials(this._mesh);
+    this._disposeInstancedMesh();
+    this._disposeMaterialSideClones();
+    if (this._mesh.parent) {
+      this._mesh.parent.remove(this._mesh);
+    }
+    this._geometry.dispose();
+    disposeMaterialResources(this._ownedMaterial);
+    this._ownedMaterial = null;
+    this._mesh = null;
+  }
+
   updateOrder(attribute, attributeName, dimension = 3) {
     if (debugMeshes) console.log("updateOrder", attribute, attributeName, dimension);
     if (attribute && this._indices) {
+      if (!isFiniteArray(attribute, dimension)) {
+        this._geometry.deleteAttribute(attributeName);
+        return;
+      }
       let values = [];
       for (let i = 0; i < this._indices.length; i++) {
         let index = this._indices[i]
+        if (!Number.isInteger(index) || index < 0 || (dimension * index + dimension) > attribute.length) {
+          this._geometry.deleteAttribute(attributeName);
+          return;
+        }
         for (let j = 0; j < dimension; ++j) {
           values.push(attribute[dimension * index + j]);
         }
       }
+      if (!isFiniteArray(values, dimension)) {
+        this._geometry.deleteAttribute(attributeName);
+        return;
+      }
       this._geometry.setAttribute(attributeName, new Float32BufferAttribute(values, dimension));
+      if (attributeName === 'position') {
+        this._geometry.computeBoundingBox();
+        this._geometry.computeBoundingSphere();
+      }
     }
   }
 
@@ -210,6 +657,138 @@ class HydraMesh {
     this._mesh.matrixAutoUpdate = false;
   }
 
+  setInstanceTransforms(matrices, count = 0) {
+    if (!this._mesh) return;
+    const instanceCount = Number(count) || 0;
+    if (instanceCount <= 0) {
+      this._disposeInstancedMesh();
+      this._mesh.visible = this._visible && this._renderTag !== 'hidden';
+      return;
+    }
+
+    if (!this._instancedMesh || this._instancedMesh.count !== instanceCount) {
+      this._disposeInstancedMesh();
+      this._instancedMesh = new InstancedMesh(this._geometry, this._mesh.material, instanceCount);
+      this._installMeshHooks(this._instancedMesh);
+      this._instancedMesh.name = `${this._mesh.name}_instances`;
+      this._instancedMesh.castShadow = this._mesh.castShadow;
+      this._instancedMesh.receiveShadow = this._mesh.receiveShadow;
+      this._instancedMesh.matrixAutoUpdate = false;
+      this._instancedMesh.userData.usdPath = this._id;
+      this._instancedMesh.userData.usdInstanced = true;
+      this._interface.config.usdRoot.add(this._instancedMesh);
+    }
+
+    this._instancedMesh.material = this._mesh.material;
+    this._instancedMesh.visible = this._visible && this._renderTag !== 'hidden';
+    this._instancedMesh.userData.usdRenderTag = this._renderTag;
+    this._mesh.visible = false;
+
+    for (let i = 0; i < instanceCount; i++) {
+      const offset = i * 16;
+      this._instanceMatrix.set(...Array.from(matrices.slice(offset, offset + 16)));
+      this._instanceMatrix.transpose();
+      this._instancedMesh.setMatrixAt(i, this._instanceMatrix);
+    }
+    this._instancedMesh.instanceMatrix.needsUpdate = true;
+    this._instancedMesh.computeBoundingBox?.();
+    this._instancedMesh.computeBoundingSphere?.();
+  }
+
+  _disposeInstancedMesh() {
+    if (!this._instancedMesh) return;
+    if (this._instancedMesh.parent) {
+      this._instancedMesh.parent.remove(this._instancedMesh);
+    }
+    this._instancedMesh.dispose?.();
+    this._instancedMesh = null;
+  }
+
+  _installMeshHooks(mesh) {
+    mesh.userData.usdPath = this._id;
+    mesh.userData.usdHydraMaterialSide = this._side;
+    mesh.userData.usdHydraApplyMaterialSide = (material, hydraMaterial) => this._applyMaterialSide(material, hydraMaterial);
+  }
+
+  _disposeMaterialSideClones() {
+    for (const material of this._materialSideClones.values()) {
+      material.dispose?.();
+    }
+    this._materialSideClones.clear();
+  }
+
+  _updateMeshSideState() {
+    if (this._mesh) {
+      this._mesh.userData.usdHydraMaterialSide = this._side;
+    }
+    if (this._instancedMesh) {
+      this._instancedMesh.userData.usdHydraMaterialSide = this._side;
+    }
+  }
+
+  _applyMaterialSide(material, hydraMaterial = null) {
+    if (!material) return material;
+    if (Array.isArray(material)) {
+      return material.map(entry => this._applyMaterialSide(entry, hydraMaterial));
+    }
+    if (material === this._ownedMaterial || material.userData?.usdHydraMeshOwner === this._id) {
+      material.side = this._side;
+      material.needsUpdate = true;
+      return material;
+    }
+
+    if (!hydraMaterial?.requiresMaterialSideVariants?.()) {
+      material.side = this._side;
+      material.needsUpdate = true;
+      return material;
+    }
+
+    let clone = this._materialSideClones.get(material);
+    if (!clone) {
+      clone = material.clone();
+      clone.userData.usdHydraSideCloneOf = material.uuid;
+      this._materialSideClones.set(material, clone);
+    } else {
+      clone.copy(material);
+      clone.userData.usdHydraSideCloneOf = material.uuid;
+    }
+    clone.side = this._side;
+    clone.needsUpdate = true;
+    return clone;
+  }
+
+  _applyCullSideToMeshes() {
+    this._updateMeshSideState();
+    let refreshedMaterialAssignments = false;
+    if (this._mesh) {
+      refreshedMaterialAssignments = this._interface.refreshMeshMaterialAssignments(this._mesh);
+      if (!refreshedMaterialAssignments) {
+        this._mesh.material = this._applyMaterialSide(this._mesh.material);
+      }
+    }
+    if (this._instancedMesh) {
+      this._instancedMesh.material = this._mesh?.material;
+    }
+  }
+
+  setCullStyle(doubleSided, cullStyle) {
+    this._side = cullStyleToThreeSide(Boolean(doubleSided), String(cullStyle || "dontCare"));
+    this._applyCullSideToMeshes();
+  }
+
+  setVisibilityState(visible, renderTag = 'geometry') {
+    this._visible = Boolean(visible);
+    this._renderTag = String(renderTag || 'geometry');
+    if (this._mesh) {
+      this._mesh.visible = !this._instancedMesh && this._visible && this._renderTag !== 'hidden';
+      this._mesh.userData.usdRenderTag = this._renderTag;
+    }
+    if (this._instancedMesh) {
+      this._instancedMesh.visible = this._visible && this._renderTag !== 'hidden';
+      this._instancedMesh.userData.usdRenderTag = this._renderTag;
+    }
+  }
+
   /**
    * Sets automatically generated normals on the mesh. Should only be used if there are no authored normals.
    * @param {} normals 
@@ -222,6 +801,14 @@ class HydraMesh {
     this.updateOrder(this._normals, 'normal');
   }
 
+  updateOrderedNormals(normals) {
+    // don't apply automatically generated normals if there are already authored normals.
+    if (this._geometry.hasAttribute('normal')) return;
+
+    this._normals = normals.slice(0);
+    this._geometry.setAttribute('normal', new Float32BufferAttribute(this._normals, 3));
+  }
+
   setNormals(data, interpolation) {
     if (interpolation === 'facevarying') {
       // The UV buffer has already been prepared on the C++ side, so we just set it
@@ -233,11 +820,21 @@ class HydraMesh {
     }
   }
 
+  setTangents(data, dimension, interpolation) {
+    if (interpolation === 'facevarying') {
+      this._geometry.setAttribute('tangent', new Float32BufferAttribute(data, dimension));
+    } else if (interpolation === 'vertex') {
+      this._tangents = data.slice(0);
+      this.updateOrder(this._tangents, 'tangent', dimension);
+    }
+  }
+
   // This is always called before prims are updated
   setMaterial(materialId) {
     if (debugMaterials) console.log('Setting material on hydra prim: ' + materialId, this._mesh, materialId, this._interface.materials[materialId]);
-    if (this._interface.materials[materialId]) {
-      this._mesh.material = this._interface.materials[materialId]._material;
+    const hydraMaterial = this._interface.materials[materialId];
+    if (hydraMaterial) {
+      hydraMaterial.assignToMesh(this._mesh);
     }
     else {
       console.error("Material not found", materialId, this._interface.materials);
@@ -249,14 +846,26 @@ class HydraMesh {
 
     for (let i = 0; i < sections.length; i++) {
       const section = sections[i];
-      if (this._interface.materials[section.materialId]) {
-        this._materials.push(this._interface.materials[section.materialId]._material);
+      const hydraMaterial = this._interface.materials[section.materialId];
+      if (hydraMaterial) {
+        this._materials.push(hydraMaterial._material);
         this._geometry.addGroup(section.start, section.length, i + 1);
       }
     }
 
+    if (this._mesh.parent) {
+      this._mesh.parent.remove(this._mesh);
+    }
     this._mesh = new Mesh(this._geometry, this._materials);
+    this._installMeshHooks(this._mesh);
+    this.setVisibilityState(this._visible, this._renderTag);
+    this._applyCullSideToMeshes();
     this._interface.config.usdRoot.add(this._mesh);
+
+    for (let i = 0; i < sections.length; i++) {
+      const hydraMaterial = this._interface.materials[sections[i].materialId];
+      hydraMaterial?.assignToMesh(this._mesh, i + 1);
+    }
   }
 
   setDisplayColor(data, interpolation) {
@@ -265,8 +874,10 @@ class HydraMesh {
     let wasDefaultMaterial = false;
     if (this._mesh.material === defaultMaterial) {
       this._mesh.material = this._mesh.material.clone();
+      this._mesh.material.userData.usdHydraMeshOwner = this._id;
       wasDefaultMaterial = true;
     }
+    this._mesh.material = this._applyMaterialSide(this._mesh.material);
 
     this._colors = null;
 
@@ -340,6 +951,12 @@ class HydraMesh {
       case "normals":
         this.setNormals(data, interpolation);
         break;
+      case "tangent":
+      case "tangents":
+        this.setTangents(data, dimension, interpolation);
+        break;
+      case "rest":
+        break;
       default:
         if (warningMessagesToCount.has(name)) {
           warningMessagesToCount.set(name, warningMessagesToCount.get(name) + 1);
@@ -357,7 +974,9 @@ class HydraMesh {
   }
 
   commit() {
-    // Nothing to do here. All Three.js resources are already updated during the sync phase.
+    if (this._instancedMesh && this._mesh) {
+      this._instancedMesh.material = this._mesh.material;
+    }
   }
 
 }
@@ -415,6 +1034,8 @@ class HydraMaterial {
   constructor(id, hydraInterface) {
     this._id = id;
     this._nodes = {};
+    this._resolvedAssetPaths = new Map();
+    this._materialXDocuments = [];
     this._interface = hydraInterface;
     if (!defaultMaterial) {
       defaultMaterial = new MeshPhysicalMaterial({
@@ -430,13 +1051,157 @@ class HydraMaterial {
 
     /** @type {MeshPhysicalMaterial} */
     this._material = defaultMaterial;
+    this._assignments = [];
+    this._interface.diagnostics.materialSPrims++;
 
     if (debugMaterials) console.log("Hydra Material", this)
   }
 
+  assignToMesh(mesh, materialIndex = null) {
+    this._interface.diagnostics.materialAssignments++;
+    const existing = this._assignments.find(assignment => assignment.mesh === mesh && assignment.materialIndex === materialIndex);
+    if (!existing) {
+      this._assignments.push({ mesh, materialIndex });
+    }
+    this._applyMaterialToAssignedMeshes();
+  }
+
+  unassignMesh(mesh) {
+    const previousLength = this._assignments.length;
+    this._assignments = this._assignments.filter(assignment => assignment.mesh !== mesh);
+    if (this._assignments.length !== previousLength) {
+      this._applyMaterialToAssignedMeshes();
+    }
+  }
+
+  dispose() {
+    this._assignments = [];
+    disposeMaterialResources(this._material);
+    this._material = null;
+  }
+
+  _applyMaterialToMesh(mesh, materialIndex) {
+    const applyMaterialSide = mesh.userData?.usdHydraApplyMaterialSide;
+    const material = typeof applyMaterialSide === 'function'
+      ? applyMaterialSide(this._material, this)
+      : this._material;
+
+    if (materialIndex === null || materialIndex === undefined) {
+      mesh.material = material;
+      return;
+    }
+
+    if (Array.isArray(mesh.material)) {
+      mesh.material[materialIndex] = material;
+      return;
+    }
+
+    mesh.material = material;
+  }
+
+  _applyMaterialToAssignedMeshes() {
+    for (const assignment of this._assignments) {
+      this._applyMaterialToMesh(assignment.mesh, assignment.materialIndex);
+    }
+  }
+
+  hasMeshAssignment(mesh) {
+    return this._assignments.some(assignment => assignment.mesh === mesh);
+  }
+
+  requiresMaterialSideVariants() {
+    const sides = new Set();
+    for (const assignment of this._assignments) {
+      const side = assignment.mesh?.userData?.usdHydraMaterialSide;
+      if (typeof side === 'number') {
+        sides.add(side);
+      }
+      if (sides.size > 1) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  refreshAssignments() {
+    this._applyMaterialToAssignedMeshes();
+  }
+
+  beginMaterialSync() {
+    this._nodes = {};
+    this._resolvedAssetPaths.clear();
+    this._materialXDocuments = [];
+  }
+
+  static canonicalAssetPath(path) {
+    return String(path ?? "")
+      .replace(/\\/g, "/")
+      .replace(/^\/+(?=\.?\/)/, "")
+      .replace(/^(?:\.\/)+/, "")
+      .replace(/\/\.\//g, "/");
+  }
+
+  _rememberResolvedAssetPath(authoredPath, resolvedPath) {
+    if (!authoredPath || !resolvedPath) {
+      return;
+    }
+
+    const authored = String(authoredPath);
+    const canonical = HydraMaterial.canonicalAssetPath(authored);
+    for (const key of [
+      authored,
+      canonical,
+      canonical.replace(/^\/+/, ""),
+      canonical.replace(/^\/?(?:\.\.\/)+/, ""),
+      `./${canonical}`,
+      `/./${canonical}`,
+    ]) {
+      this._resolvedAssetPaths.set(key, String(resolvedPath));
+    }
+  }
+
+  _resolveMaterialTexturePath(authoredPath) {
+    if (!authoredPath) {
+      return "";
+    }
+
+    const authored = String(authoredPath);
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(authored)) {
+      return authored;
+    }
+
+    const candidates = this._interface.registry.materialResourcePathCandidates(authored);
+    for (const candidate of candidates) {
+      const resolved = this._resolvedAssetPaths.get(candidate)
+        || this._resolvedAssetPaths.get(HydraMaterial.canonicalAssetPath(candidate));
+      if (resolved) return resolved;
+    }
+
+    for (const candidate of candidates) {
+      const resolved = this._interface.registry.resolveResourcePath(candidate);
+      if (resolved) return resolved;
+    }
+
+    return "";
+  }
+
   updateNode(networkId, path, parameters) {
     if (debugTextures) console.log('Updating Material Node: ' + networkId + ' ' + path, parameters);
+    this._interface.diagnostics.materialNodes++;
     this._nodes[path] = parameters;
+    this._rememberResolvedAssetPath(parameters?.file, parameters?.resolvedPath);
+  }
+
+  updateMaterialXDocument(document) {
+    if (debugMaterials) console.log('Updating MaterialX document: ' + this._id, document);
+    this._interface.diagnostics.materialXDocuments++;
+    const existingIndex = this._materialXDocuments.findIndex(existing => existing.terminal === document?.terminal);
+    if (existingIndex >= 0) {
+      this._materialXDocuments[existingIndex] = document;
+    }
+    else {
+      this._materialXDocuments.push(document);
+    }
   }
 
   convertWrap(usdWrapMode) {
@@ -468,12 +1233,15 @@ class HydraMaterial {
       }
       if (mainMaterial[parameterName] && mainMaterial[parameterName].nodeIn) {
         const nodeIn = mainMaterial[parameterName].nodeIn;
-        if (!nodeIn.resolvedPath) {
-          console.warn("Texture node has no file!", nodeIn);
+        const textureFileName = this._resolveMaterialTexturePath(nodeIn.resolvedPath || nodeIn.file);
+        if (!textureFileName) {
+          if (debugTextures) console.debug("Texture node has no file; skipping optional texture input.", nodeIn);
+          this._material[materialParameterMapName] = undefined;
+          resolve();
+          return;
         }
         if (debugTextures)
-          console.log("Assigning texture with resolved path", parameterName, nodeIn.resolvedPath);
-        const textureFileName = nodeIn.resolvedPath?.replace("./", "");
+          console.log("Assigning texture with resolved path", parameterName, { file: nodeIn.file, resolvedPath: nodeIn.resolvedPath });
         const channel = mainMaterial[parameterName].inputName;
 
         // For debugging
@@ -529,7 +1297,7 @@ class HydraMaterial {
           if (materialParameterMapName == 'metalnessMap' && channel != 'b') {
             targetSwizzle = '01' + channel + '1';
           }
-          if (materialParameterMapName == 'occlusionMap' && channel != 'r') {
+          if (materialParameterMapName == 'aoMap' && channel != 'r') {
             targetSwizzle = channel + '111';
           }
           if (materialParameterMapName == 'opacityMap' && channel != 'a') {
@@ -703,6 +1471,127 @@ class HydraMaterial {
     }
   }
 
+  static _imageChannelData(image, width, height, channel) {
+    if (!image) return null;
+
+    if ((typeof HTMLImageElement !== 'undefined' && image instanceof HTMLImageElement) ||
+      (typeof HTMLCanvasElement !== 'undefined' && image instanceof HTMLCanvasElement) ||
+      (typeof ImageBitmap !== 'undefined' && image instanceof ImageBitmap)) {
+
+      const canvas = document.createElementNS('http://www.w3.org/1999/xhtml', 'canvas');
+      canvas.width = width;
+      canvas.height = height;
+
+      const context = canvas.getContext('2d');
+      context.drawImage(image, 0, 0, width, height);
+
+      const imageData = context.getImageData(0, 0, width, height);
+      const data = imageData.data;
+      const channelData = new Uint8ClampedArray(width * height);
+      for (let i = 0, j = channel; i < channelData.length; i++, j += 4) {
+        channelData[i] = data[j];
+      }
+      return channelData;
+    }
+
+    return null;
+  }
+
+  static _packMetallicRoughnessMap({ aoMap, roughnessMap, metalnessMap }) {
+    const sourceTexture = roughnessMap || metalnessMap || aoMap;
+    const sourceImage = sourceTexture?.image;
+    const width = sourceImage?.width;
+    const height = sourceImage?.height;
+    if (!sourceTexture || !sourceImage || !width || !height) {
+      return null;
+    }
+
+    const canvas = document.createElementNS('http://www.w3.org/1999/xhtml', 'canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d');
+    const imageData = context.createImageData(width, height);
+    const data = imageData.data;
+
+    for (let i = 0; i < data.length; i += 4) {
+      data[i] = 255;
+      data[i + 1] = 255;
+      data[i + 2] = 255;
+      data[i + 3] = 255;
+    }
+
+    const ao = HydraMaterial._imageChannelData(aoMap?.image, width, height, 0);
+    const roughness = HydraMaterial._imageChannelData(roughnessMap?.image, width, height, 1);
+    const metalness = HydraMaterial._imageChannelData(metalnessMap?.image, width, height, 2);
+
+    for (let i = 0, j = 0; i < width * height; i++, j += 4) {
+      if (ao) data[j] = ao[i];
+      if (roughness) data[j + 1] = roughness[i];
+      if (metalness) data[j + 2] = metalness[i];
+    }
+
+    context.putImageData(imageData, 0, 0);
+
+    const packedTexture = sourceTexture.clone();
+    packedTexture.image = canvas;
+    packedTexture.format = RGBAFormat;
+    packedTexture.colorSpace = LinearSRGBColorSpace;
+    packedTexture.name = [
+      "packed-orm",
+      aoMap?.name || "ao:1",
+      roughnessMap?.name || "roughness:1",
+      metalnessMap?.name || "metalness:1",
+    ].join("|");
+    packedTexture.needsUpdate = true;
+    return packedTexture;
+  }
+
+  _packMaterialTextureChannels({ haveOcclusionMap, haveRoughnessMap, haveMetalnessMap }) {
+    if (!haveOcclusionMap && !haveRoughnessMap && !haveMetalnessMap) return;
+
+    const aoMap = this._material.aoMap;
+    const roughnessMap = this._material.roughnessMap;
+    const metalnessMap = this._material.metalnessMap;
+    const existingPackedMap = [aoMap, roughnessMap, metalnessMap]
+      .find(texture => texture?.name?.startsWith?.("packed-orm"));
+    if (existingPackedMap) {
+      if (haveOcclusionMap) this._material.aoMap = existingPackedMap;
+      this._material.roughnessMap = existingPackedMap;
+      this._material.metalnessMap = existingPackedMap;
+      return;
+    }
+
+    if ((haveOcclusionMap && !aoMap) || (haveRoughnessMap && !roughnessMap) || (haveMetalnessMap && !metalnessMap)) {
+      console.error("Something went wrong with the texture promise; a material texture was authored but not loaded.", {
+        haveOcclusionMap,
+        haveRoughnessMap,
+        haveMetalnessMap,
+        aoMap,
+        roughnessMap,
+        metalnessMap,
+      });
+      return;
+    }
+
+    const packedMap = HydraMaterial._packMetallicRoughnessMap({ aoMap, roughnessMap, metalnessMap });
+    if (!packedMap) {
+      console.error("Something went wrong while packing occlusion/metallic/roughness textures.", {
+        aoMap,
+        roughnessMap,
+        metalnessMap,
+      });
+      return;
+    }
+
+    if (haveOcclusionMap) this._material.aoMap = packedMap;
+    this._material.roughnessMap = packedMap;
+    this._material.metalnessMap = packedMap;
+
+    for (const texture of new Set([aoMap, roughnessMap, metalnessMap])) {
+      if (texture && texture !== packedMap) texture.dispose();
+    }
+  }
+
   assignProperty(mainMaterial, parameterName) {
     const materialParameterName = HydraMaterial.usdPreviewToMeshPhysicalMap[parameterName];
     if (materialParameterName === undefined) {
@@ -726,16 +1615,39 @@ class HydraMaterial {
     }
   }
 
-  async updateFinished(type, relationships) {
+  updateFinished(type, relationships) {
+    this._interface.diagnostics.materialUpdateFinished++;
+    const promise = this._updateFinished(type, relationships);
+    this._interface.trackMaterialUpdate(promise);
+  }
+
+  async _updateFinished(type, relationships) {
     for (let relationship of relationships) {
       relationship.nodeIn = this._nodes[relationship.inputId];
       relationship.nodeOut = this._nodes[relationship.outputId];
+      if (!relationship.nodeIn || !relationship.nodeOut) {
+        console.warn('Material relationship references an unknown node.', relationship);
+        continue;
+      }
       relationship.nodeIn[relationship.inputName] = relationship;
       relationship.nodeOut[relationship.outputName] = relationship;
     }
     if (debugMaterials) console.log('Finalizing Material: ' + this._id);
     if (debugMaterials) console.log("updateFinished", type, relationships)
 
+    const materialXDocument = this._materialXDocuments.find(document => document.terminal === type);
+    if (materialXDocument) {
+      const materialXMaterial = await this.createMaterialXMaterial(materialXDocument);
+      if (!materialXMaterial) {
+        this._material = defaultMaterial;
+        this._applyMaterialToAssignedMeshes();
+        return;
+      }
+      this._material = materialXMaterial;
+      this._applyMaterialToAssignedMeshes();
+      return;
+    }
+
     // find the main material node
     let mainMaterialNode = undefined;
     for (let node of Object.values(this._nodes)) {
@@ -747,6 +1659,7 @@ class HydraMaterial {
 
     if (!mainMaterialNode || disableMaterials) {
       this._material = defaultMaterial;
+      this._applyMaterialToAssignedMeshes();
       return;
     }
 
@@ -783,21 +1696,7 @@ class HydraMaterial {
       }
       await Promise.all(texturePromises);
 
-      // Need to sanitize metallic/roughness/occlusion maps - if we want to export glTF they need to be identical right now
-      if (haveRoughnessMap && !haveMetalnessMap) {
-        if (debugMaterials) console.log(this._material.roughnessMap, this._material);
-        this._material.metalnessMap = this._material.roughnessMap;
-        if (this._material.metalnessMap) this._material.metalnessMap.needsUpdate = true;
-        else console.error("Something went wrong with the texture promise; haveRoughnessMap is true but no roughnessMap was loaded.");
-      }
-      else if (haveMetalnessMap && !haveRoughnessMap) {
-        this._material.roughnessMap = this._material.metalnessMap;
-        if (this._material.roughnessMap) this._material.roughnessMap.needsUpdate = true;
-        else console.error("Something went wrong with the texture promise; haveMetalnessMap is true but no metalnessMap was loaded.");
-      }
-      else if (haveMetalnessMap && haveRoughnessMap) {
-        console.warn("TODO: [Three USD] separate metalness and roughness textures need to be merged");
-      }
+      this._packMaterialTextureChannels({ haveOcclusionMap, haveRoughnessMap, haveMetalnessMap });
     }
 
     // Assign material properties
@@ -806,6 +1705,60 @@ class HydraMaterial {
     }
 
     if (debugMaterials) console.log("Material Node \"" + this._material.name + "\"", mainMaterialNode, "Resulting Material", this._material);
+    this._applyMaterialToAssignedMeshes();
+  }
+
+  async createMaterialXMaterial(materialXDocument) {
+    if (!materialXDocument || disableMaterials) {
+      if (!materialXDocument) {
+        this._interface.diagnostics.materialXSkippedNoDocuments++;
+      }
+      return null;
+    }
+    this._interface.diagnostics.materialXCreateAttempts++;
+
+    const xml = materialXDocument?.xml;
+    if (!xml) {
+      return null;
+    }
+
+    try {
+      const { MaterialX, MaterialXMaterial } = await getMaterialXModule();
+      const materialName = this._id.split('/').pop() || this._id;
+      const materialNodeNameOrIndex = materialXDocument.materialName || materialName || 0;
+      const material = await MaterialX.createMaterialXMaterial(xml, materialNodeNameOrIndex, {
+        cacheKey: `${this._id}:${materialXDocument.terminal}`,
+        getTexture: async (url) => {
+          const texturePath = this._resolveMaterialTexturePath(url);
+          return texturePath ? this._interface.registry.getTexture(texturePath) : null;
+        },
+      }, {
+        parameters: {
+          side: DoubleSide,
+        },
+      }, {});
+
+      if (typeof MaterialXMaterial === 'function' && !(material instanceof MaterialXMaterial)) {
+        this._interface.diagnostics.materialXCreateFailures++;
+        if (debugMaterials) console.debug('MaterialX shader generation returned a non-MaterialX material.', {
+          materialId: this._id,
+          materialName: material?.name,
+          materialType: material?.constructor?.name,
+        });
+        return null;
+      }
+
+      material.name = materialName;
+      material.side = DoubleSide;
+      material.needsUpdate = true;
+      this._interface.diagnostics.materialXCreateSuccess++;
+      return material;
+    }
+    catch (error) {
+      this._interface.diagnostics.materialXCreateFailures++;
+      console.warn('Failed to create MaterialX material.', error);
+      return null;
+    }
   }
 }
 
@@ -828,6 +1781,37 @@ export class ThreeRenderDelegateInterface {
     this.registry = new TextureRegistry(config);
     this.materials = {};
     this.meshes = {};
+    this.scenePrimitives = {};
+    this.pendingMaterialUpdates = new Set();
+    this.diagnostics = {
+      materialSPrims: 0,
+      sceneSPrims: 0,
+      materialAssignments: 0,
+      materialNodes: 0,
+      materialUpdateFinished: 0,
+      materialXDocuments: 0,
+      materialXSkippedNoDocuments: 0,
+      materialXCreateAttempts: 0,
+      materialXCreateSuccess: 0,
+      materialXCreateFailures: 0,
+      materialIds: [],
+      scenePrimitiveIds: [],
+    };
+  }
+
+  trackMaterialUpdate(promise) {
+    this.pendingMaterialUpdates.add(promise);
+    promise.finally(() => this.pendingMaterialUpdates.delete(promise));
+  }
+
+  async waitForMaterialsReady() {
+    while (this.pendingMaterialUpdates.size > 0) {
+      await Promise.allSettled([...this.pendingMaterialUpdates]);
+    }
+  }
+
+  getDiagnostics() {
+    return { ...this.diagnostics };
   }
 
   /**
@@ -839,11 +1823,20 @@ export class ThreeRenderDelegateInterface {
    */
   createRPrim(typeId, id, instancerId) {
     if (debugPrims) console.log('Creating RPrim: ', typeId, id, typeof id);
+    this.destroyRPrim(id);
     let mesh = new HydraMesh(id, this);
     this.meshes[id] = mesh;
     return mesh;
   }
 
+  destroyRPrim(id) {
+    if (debugPrims) console.log('Destroying RPrim: ', id);
+    const mesh = this.meshes[id];
+    if (!mesh) return;
+    mesh.dispose();
+    delete this.meshes[id];
+  }
+
   createBPrim(typeId, id) {
     if (debugPrims) console.log('Creating BPrim: ', typeId, id);
     /*let mesh = new HydraMesh(id, this);
@@ -855,14 +1848,74 @@ export class ThreeRenderDelegateInterface {
     if (debugPrims) console.log('Creating SPrim: ', typeId, id);
 
     if (typeId === 'material') {
+      this.destroySPrim(id);
       let material = new HydraMaterial(id, this);
       this.materials[id] = material;
+      if (this.diagnostics.materialIds.length < 20) {
+        this.diagnostics.materialIds.push(id);
+      }
       return material;
+    } else if (typeId === 'camera' || lightSprimTypeIds.has(typeId)) {
+      const scenePrimitive = new HydraScenePrimitive(typeId, id, this);
+      if (!id) {
+        return scenePrimitive;
+      }
+      this.destroySPrim(id);
+      this.scenePrimitives[id] = scenePrimitive;
+      this.diagnostics.sceneSPrims++;
+      if (this.diagnostics.scenePrimitiveIds.length < 20) {
+        this.diagnostics.scenePrimitiveIds.push(id);
+      }
+      return scenePrimitive;
     } else {
       return undefined;
     }
   }
 
+  destroySPrim(id) {
+    if (debugPrims) console.log('Destroying SPrim: ', id);
+    const material = this.materials[id];
+    if (material) {
+      material.dispose();
+      delete this.materials[id];
+    }
+    const scenePrimitive = this.scenePrimitives[id];
+    if (scenePrimitive) {
+      scenePrimitive.dispose();
+      delete this.scenePrimitives[id];
+    }
+  }
+
+  dispose() {
+    for (const id of Object.keys(this.meshes)) {
+      this.destroyRPrim(id);
+    }
+    for (const id of Object.keys(this.materials)) {
+      this.destroySPrim(id);
+    }
+    for (const id of Object.keys(this.scenePrimitives)) {
+      this.destroySPrim(id);
+    }
+    this.registry.dispose();
+    this.pendingMaterialUpdates.clear();
+  }
+
+  unassignMeshFromMaterials(mesh) {
+    for (const material of Object.values(this.materials)) {
+      material.unassignMesh(mesh);
+    }
+  }
+
+  refreshMeshMaterialAssignments(mesh) {
+    let refreshed = false;
+    for (const material of Object.values(this.materials)) {
+      if (!material.hasMeshAssignment(mesh)) continue;
+      material.refreshAssignments();
+      refreshed = true;
+    }
+    return refreshed;
+  }
+
   CommitResources() {
     for (const id in this.meshes) {
       const hydraMesh = this.meshes[id]