@call-me-sensei/toonlab 0.1.1

package/src/environment/environmentAmbientProbe.js

@@ -0,0 +1,160 @@
+import * as THREE from 'three';
+
+import { setEnvironmentAmbientProbeColors } from './environmentShaderMaterials.js';
+
+// Six-direction ambient probe: renders the scene along ±X/±Y/±Z from one
+// point (typically the room center at head height), averages each view to a
+// single color, and publishes the result to every environment material via
+// the shared ambientProbe uniform. One capture, no per-frame cost — refresh
+// explicitly when lighting changes (time of day, lamps toggled).
+
+const PROBE_DIRECTIONS = [
+  { look: new THREE.Vector3(1, 0, 0), up: new THREE.Vector3(0, 1, 0) },
+  { look: new THREE.Vector3(-1, 0, 0), up: new THREE.Vector3(0, 1, 0) },
+  { look: new THREE.Vector3(0, 1, 0), up: new THREE.Vector3(0, 0, -1) },
+  { look: new THREE.Vector3(0, -1, 0), up: new THREE.Vector3(0, 0, 1) },
+  { look: new THREE.Vector3(0, 0, 1), up: new THREE.Vector3(0, 1, 0) },
+  { look: new THREE.Vector3(0, 0, -1), up: new THREE.Vector3(0, 1, 0) },
+];
+
+function averageProbePixels(pixels, resolution, intensity) {
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  const pixelCount = resolution * resolution;
+  for (let i = 0; i < pixelCount; i += 1) {
+    r += pixels[i * 4];
+    g += pixels[i * 4 + 1];
+    b += pixels[i * 4 + 2];
+  }
+  const scale = intensity / (pixelCount * 255);
+  return new THREE.Color(r * scale, g * scale, b * scale);
+}
+
+/**
+ * On the classic renderer this is fully synchronous and returns the colors.
+ * On the node backends (WebGPU / forced WebGL2) pixel readback is async, so
+ * it returns a Promise<colors>; `apply` publishes to the environment
+ * materials either way, so fire-and-forget callers work on both.
+ */
+// Node backends keep one cached probe target per renderer: disposing the
+// target immediately after the async readback races WebGPU's deferred
+// command submission (validation: "buffer used in submit while destroyed").
+const nodeBackendProbeTargets = new WeakMap();
+
+export function captureEnvironmentAmbientProbe({
+  renderer,
+  scene,
+  position = new THREE.Vector3(),
+  near = 0.05,
+  far = 200,
+  resolution = 16,
+  // Scales the averaged colors before publishing; 1 keeps the scene's own
+  // brightness.
+  intensity = 1,
+  apply = true,
+} = {}) {
+  if (!renderer || !scene) return null;
+
+  const isNodeBackend = Boolean(renderer.isWebGPURenderer);
+  let renderTarget = null;
+  if (isNodeBackend) {
+    const atlasWidth = resolution * PROBE_DIRECTIONS.length;
+    const cached = nodeBackendProbeTargets.get(renderer);
+    if (cached?.width === atlasWidth) {
+      renderTarget = cached;
+    } else {
+      cached?.dispose();
+      renderTarget = new THREE.WebGLRenderTarget(atlasWidth, resolution, {
+        minFilter: THREE.LinearFilter,
+        magFilter: THREE.LinearFilter,
+      });
+      nodeBackendProbeTargets.set(renderer, renderTarget);
+    }
+  } else {
+    renderTarget = new THREE.WebGLRenderTarget(resolution, resolution, {
+      minFilter: THREE.LinearFilter,
+      magFilter: THREE.LinearFilter,
+    });
+  }
+  const probeCamera = new THREE.PerspectiveCamera(90, 1, near, far);
+  probeCamera.position.copy(position);
+
+  const colors = [];
+
+  const currentRenderTarget = renderer.getRenderTarget();
+  const currentXrEnabled = renderer.xr.enabled;
+  renderer.xr.enabled = false;
+
+  const finish = () => {
+    renderer.setRenderTarget(currentRenderTarget);
+    renderer.xr.enabled = currentXrEnabled;
+    if (!isNodeBackend) renderTarget.dispose();
+    // The camera looking along +X sees the -X half of the room; a surface
+    // normal pointing +X is lit by what lies in that view. So the probe slot
+    // for +X normals is the +X-looking capture directly.
+    if (apply) setEnvironmentAmbientProbeColors(colors);
+    return colors;
+  };
+
+  const aimCamera = (direction) => {
+    probeCamera.up.copy(direction.up);
+    probeCamera.lookAt(position.clone().add(direction.look));
+    probeCamera.updateMatrixWorld();
+  };
+
+  if (renderer.isWebGPURenderer) {
+    // All six faces render back-to-back into one 6-tile atlas within a single
+    // JS tick, then ONE async readback: awaiting between renders lets main
+    // frames interleave, and the render-object revalidation that follows
+    // destroys probe-context buffers while earlier probe submits are still
+    // queued (WebGPU validation: "used in submit while destroyed").
+    return (async () => {
+      const previousAutoClear = renderer.autoClear;
+      renderer.setRenderTarget(renderTarget);
+      renderer.setScissorTest?.(false);
+      renderer.clear();
+      // One manual clear for the whole atlas; per-render autoClear would wipe
+      // the previously rendered tiles.
+      renderer.autoClear = false;
+      PROBE_DIRECTIONS.forEach((direction, index) => {
+        aimCamera(direction);
+        renderer.setViewport(index * resolution, 0, resolution, resolution);
+        renderer.render(scene, probeCamera);
+      });
+      renderer.autoClear = previousAutoClear;
+      const pixels = await renderer.readRenderTargetPixelsAsync(
+        renderTarget, 0, 0, resolution * PROBE_DIRECTIONS.length, resolution,
+      );
+      const atlasWidth = resolution * PROBE_DIRECTIONS.length;
+      for (let index = 0; index < PROBE_DIRECTIONS.length; index += 1) {
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        for (let y = 0; y < resolution; y += 1) {
+          for (let x = 0; x < resolution; x += 1) {
+            const p = (y * atlasWidth + index * resolution + x) * 4;
+            r += pixels[p];
+            g += pixels[p + 1];
+            b += pixels[p + 2];
+          }
+        }
+        const scale = intensity / (resolution * resolution * 255);
+        colors.push(new THREE.Color(r * scale, g * scale, b * scale));
+      }
+      renderer.setViewport(0, 0, renderer.domElement.width, renderer.domElement.height);
+      return finish();
+    })();
+  }
+
+  const pixels = new Uint8Array(resolution * resolution * 4);
+  for (const direction of PROBE_DIRECTIONS) {
+    aimCamera(direction);
+    renderer.setRenderTarget(renderTarget);
+    renderer.clear();
+    renderer.render(scene, probeCamera);
+    renderer.readRenderTargetPixels(renderTarget, 0, 0, resolution, resolution, pixels);
+    colors.push(averageProbePixels(pixels, resolution, intensity));
+  }
+  return finish();
+}

package/src/environment/environmentMaterialAdapter.js

@@ -0,0 +1,336 @@
+import { syncToonSceneLights } from '../shaders-tsl/chunks/character-scene-lights.js';
+import {
+  classifyEnvironmentMaterialRole,
+  toMaterialArray,
+} from './environmentMaterialClassifier.js';
+
+// Environment node materials read scene lights from the shared toon light
+// uniforms (shaders-tsl/chunks/character-scene-lights.js) instead of three's
+// classic light blocks; converted meshes mirror the light state right before
+// they render, exactly like the toon adapter's toonNodeLightSync. Both
+// renderers invoke Object3D.onBeforeRender.
+function environmentNodeLightSync(renderer, scene, camera) {
+  syncToonSceneLights(scene, camera);
+}
+import {
+  applyEnvironmentSettingsToMaterial,
+  createEnvironmentSettings,
+  normalizeEnvironmentDebugMode,
+} from './environmentSettings.js';
+import {
+  createDebugEnvironmentMaterial,
+  createEnvironmentAoMaterial,
+  createEnvironmentMaterial,
+  createEnvironmentShadowMaterial,
+  setEnvironmentDebugOutput,
+} from './environmentShaderMaterials.js';
+import {
+  resolveEnvironmentTextureSet,
+} from './environmentTextureResolver.js';
+import {
+  bakeEnvironmentVertexAo,
+} from './environmentVertexAo.js';
+import {
+  DEFAULT_SCAN_STYLIZE_PARAMS,
+  applyScanStylizeToMaterial,
+  isScanAssetMaterial,
+  stylizeScanBaseMap,
+} from './scanAssetStylize.js';
+
+export {
+  DEFAULT_SCAN_STYLIZE_PARAMS,
+  applyScanStylizeToMaterial,
+  isScanAssetMaterial,
+  stylizeScanBaseMap,
+} from './scanAssetStylize.js';
+
+export {
+  ENVIRONMENT_MATERIAL_ROLES,
+  alphaCutoffForMaterial,
+  classifyEnvironmentMaterialRole,
+  isAoOverlayMaterial,
+  isEmissiveEnvironmentMaterial,
+  isEnvironmentAoOverlay,
+  isEnvironmentShadowMesh,
+  isFoliageMaterial,
+  isUtilityTextureLabel,
+  isWindowCutoutMaterial,
+  materialBaseColor,
+  materialText,
+  objectMaterialText,
+  sourceOpacity,
+  textureLabel,
+  textureSourceUrl,
+  toMaterialArray,
+  usesAlphaCutout,
+} from './environmentMaterialClassifier.js';
+
+export {
+  DEFAULT_ENVIRONMENT_FEATURES,
+  DEFAULT_ENVIRONMENT_PARAMETERS,
+  ENVIRONMENT_DEBUG_MODES,
+  ENVIRONMENT_SETTING_FIELD_SCHEMA,
+  ENVIRONMENT_SETTING_GROUPS,
+  applyEnvironmentSettingsToMaterial,
+  createEnvironmentSettings,
+  normalizeEnvironmentDebugMode,
+  updateEnvironmentBoundsUniforms,
+} from './environmentSettings.js';
+
+export {
+  advanceEnvironmentShaderTime,
+  createDebugEnvironmentMaterial,
+  createEnvironmentAoMaterial,
+  createEnvironmentMaterial,
+  createEnvironmentShadowMaterial,
+  createEnvironmentWindowOpeningMaterial,
+  resetEnvironmentShaderTime,
+  setEnvironmentAmbientProbeColors,
+  setEnvironmentCloudShadow,
+  setEnvironmentDebugOutput,
+  setEnvironmentOpenings,
+  setEnvironmentPlanarReflection,
+} from './environmentShaderMaterials.js';
+
+export {
+  copyTextureTransform,
+  fallbackEnvironmentBlackTexture,
+  fallbackEnvironmentNormalTexture,
+  fallbackEnvironmentWhiteTexture,
+  loadEnvironmentTexture,
+  resolveEnvironmentTextureSet,
+  textureKindCandidateUrl,
+  textureUrlExists,
+} from './environmentTextureResolver.js';
+
+export { bakeEnvironmentVertexAo } from './environmentVertexAo.js';
+
+function resolveEnvironmentSettings({ features = {}, parameters = {}, settings = {} } = {}) {
+  const mergedSettings = createEnvironmentSettings(settings);
+  return createEnvironmentSettings({
+    features: {
+      ...mergedSettings.features,
+      ...features,
+    },
+    parameters: {
+      ...mergedSettings.parameters,
+      ...parameters,
+    },
+  });
+}
+
+// The FBX/legacy loaders name the second uv set uv2; the shader reads uv1
+// (the modern three.js convention). Alias so both work.
+function ensureUv2Attribute(geometry) {
+  if (geometry.attributes.uv1) return true;
+  if (geometry.attributes.uv2) {
+    geometry.setAttribute('uv1', geometry.attributes.uv2);
+    return true;
+  }
+  return false;
+}
+
+function createConvertedEnvironmentMaterial(mat, options) {
+  return options.normalizedShaderMode === 'anime'
+    ? createEnvironmentMaterial(mat, options.textureSet, options)
+    : createDebugEnvironmentMaterial(mat, options.normalizedShaderMode, options.textureSet, {
+      hasVertexColors: options.hasVertexColors,
+    });
+}
+
+// Converts every mesh under root to the environment shader.
+//
+// Options beyond the original set:
+// - roleOverrides: [{ match: string|RegExp, role }] — corrects heuristic
+//   classification without renaming assets (userData.envRole wins over both).
+// - bakeVertexAo: 'auto' | true | false — bake per-vertex ambient occlusion
+//   at conversion for grounding. 'auto' bakes untextured meshes only (the
+//   input class with no baked AO of its own) within the vertex budget.
+// - vertexAoOptions: forwarded to bakeEnvironmentVertexAo.
+// - debugOutputMode: compile debug views in from the start ('off' keeps
+//   normal rendering; setEnvironmentDebugOutput can enable them later).
+// - scanStylize: 'auto' | true | false — photoscan stylization pass
+//   (albedo simplify + detail-map compression, see scanAssetStylize.js).
+//   'auto' applies it only to materials that detect as Megascans/Fab scans;
+//   material.userData.envScanStylize overrides detection per material.
+// - scanStylizeParams: overrides merged over DEFAULT_SCAN_STYLIZE_PARAMS.
+//
+// Returns conversion counts plus a classification report:
+// [{ object, material, role, source }] for every converted material.
+export async function applyEnvironmentShader(root, {
+  bakeVertexAo = 'auto',
+  debugOutputMode = 'off',
+  environmentBox = null,
+  features = {},
+  hasSun = false,
+  parameters = {},
+  roleOverrides = null,
+  scanStylize = 'auto',
+  scanStylizeParams = {},
+  settings = {},
+  shaderMode = 'anime',
+  openWindows = false,
+  vertexAoOptions = {},
+} = {}) {
+  const environmentSettings = resolveEnvironmentSettings({ features, parameters, settings });
+  const normalizedShaderMode = ['anime', 'basic', 'standard'].includes(shaderMode)
+    ? shaderMode
+    : 'anime';
+  const resolvedDebugMode = normalizeEnvironmentDebugMode(debugOutputMode);
+  let convertedMeshCount = 0;
+  let aoOverlayMeshCount = 0;
+  let windowCutoutMaterialCount = 0;
+  let shadowMeshCount = 0;
+  let vertexAoMeshCount = 0;
+  let scanStylizedMaterialCount = 0;
+  const classification = [];
+  const materialTextureSets = new WeakMap();
+  const materialPromises = [];
+  const scanMaterials = new Set();
+  const scanParams = { ...DEFAULT_SCAN_STYLIZE_PARAMS, ...scanStylizeParams };
+
+  root.traverse((obj) => {
+    if (!obj.isMesh || !obj.geometry || !obj.material) return;
+    if (obj.userData?.environmentShaderExclude) return;
+
+    const originalMaterials = toMaterialArray(obj.material);
+    if (!obj.geometry.attributes.normal) obj.geometry.computeVertexNormals();
+
+    for (const mat of originalMaterials) {
+      if (!mat) continue;
+      if (scanStylize === true || (scanStylize === 'auto' && isScanAssetMaterial(obj, mat))) {
+        scanMaterials.add(mat);
+      }
+      if (materialTextureSets.has(mat)) continue;
+      const promise = resolveEnvironmentTextureSet(mat)
+        .then((textureSet) => {
+          materialTextureSets.set(mat, textureSet);
+        });
+      materialPromises.push(promise);
+    }
+  });
+
+  await Promise.all(materialPromises);
+
+  // Photoscan albedo simplify runs on the resolved texture sets so both the
+  // converted material and the vertex-AO bake below see the stylized map.
+  for (const mat of scanMaterials) {
+    const textureSet = materialTextureSets.get(mat);
+    if (!textureSet || textureSet.untextured) continue;
+    textureSet.baseMap = stylizeScanBaseMap(textureSet.baseMap, scanParams);
+  }
+
+  // Vertex AO bakes before material creation so baked meshes compile with
+  // USE_ENV_VERTEX_AO. 'auto' targets untextured meshes with no ao/lightmap
+  // of their own — the flat-color input class that needs grounding most.
+  const vertexAoTargets = [];
+  if (environmentSettings.features.vertexAo && bakeVertexAo !== false && normalizedShaderMode === 'anime') {
+    root.traverse((obj) => {
+      if (!obj.isMesh || !obj.geometry || !obj.material) return;
+      if (obj.userData?.environmentShaderExclude) return;
+      if (obj.geometry.attributes.envVertexAo) return;
+      const materials = toMaterialArray(obj.material);
+      const textureSet = materialTextureSets.get(materials[0]);
+      if (!textureSet) return;
+      if (bakeVertexAo === 'auto'
+        && (!textureSet.untextured || textureSet.aoMap || textureSet.lightMap)) return;
+      vertexAoTargets.push(obj);
+    });
+  }
+  if (vertexAoTargets.length > 0) {
+    const baked = await bakeEnvironmentVertexAo(vertexAoTargets, {
+      occluderRoot: root,
+      environmentBox,
+      ...vertexAoOptions,
+    });
+    vertexAoMeshCount = baked.bakedMeshCount;
+  }
+
+  root.traverse((obj) => {
+    if (!obj.isMesh || !obj.geometry || !obj.material) return;
+    // Meshes with bespoke shaders (e.g. leaf-card tree canopies) opt out of
+    // conversion; the adapter would otherwise replace their material.
+    if (obj.userData?.environmentShaderExclude) return;
+
+    const originalMaterials = toMaterialArray(obj.material);
+    const roleInfos = originalMaterials.map((mat) => {
+      const info = classifyEnvironmentMaterialRole(obj, mat, { roleOverrides });
+      classification.push({
+        material: mat?.name ?? '',
+        object: obj.name ?? '',
+        role: info.role,
+        source: info.source,
+      });
+      return info;
+    });
+    const shadowMesh = environmentSettings.features.shadowMesh
+      && roleInfos.some((info) => info.role === 'shadowMesh');
+    const aoOverlay = !shadowMesh && environmentSettings.features.aoOverlay
+      && roleInfos.some((info) => info.role === 'aoOverlay');
+    const hasVertexColors = Boolean(obj.geometry.attributes.color);
+    const hasVertexAo = Boolean(obj.geometry.attributes.envVertexAo);
+    const hasUv2 = ensureUv2Attribute(obj.geometry);
+
+    const convertMaterial = (mat, index) => {
+      const converted = createConvertedEnvironmentMaterial(mat, {
+        debugOutputMode: resolvedDebugMode,
+        environmentBox,
+        environmentSettings,
+        hasSun,
+        hasUv2,
+        hasVertexAo,
+        hasVertexColors,
+        normalizedShaderMode,
+        openWindows,
+        role: roleInfos[index]?.role ?? null,
+        textureSet: materialTextureSets.get(mat),
+      });
+      if (scanMaterials.has(mat)) {
+        applyScanStylizeToMaterial(converted, scanParams);
+        scanStylizedMaterialCount += 1;
+      }
+      return converted;
+    };
+
+    obj.material = shadowMesh
+      ? (Array.isArray(obj.material)
+        ? originalMaterials.map((mat) => createEnvironmentShadowMaterial(mat, { hasVertexColors }))
+        : createEnvironmentShadowMaterial(originalMaterials[0], { hasVertexColors }))
+      : aoOverlay
+        ? (Array.isArray(obj.material)
+          ? originalMaterials.map((mat) => createEnvironmentAoMaterial(mat, materialTextureSets.get(mat)))
+          : createEnvironmentAoMaterial(originalMaterials[0], materialTextureSets.get(originalMaterials[0])))
+        : Array.isArray(obj.material)
+          ? originalMaterials.map((mat, index) => convertMaterial(mat, index))
+          : convertMaterial(originalMaterials[0], 0);
+
+    for (const mat of toMaterialArray(obj.material)) {
+      if (mat?.userData?.windowCutout) windowCutoutMaterialCount += 1;
+    }
+    if (toMaterialArray(obj.material).some((mat) => mat?.userData?.environmentMaterial)) {
+      obj.onBeforeRender = environmentNodeLightSync;
+    }
+    if (shadowMesh) shadowMeshCount += 1;
+    if (aoOverlay) aoOverlayMeshCount += 1;
+
+    obj.frustumCulled = false;
+    obj.castShadow = hasSun && environmentSettings.features.shadowMask;
+    obj.receiveShadow = hasSun && environmentSettings.features.shadowMask;
+    convertedMeshCount += 1;
+  });
+
+  // Materials compiled with the debug define still need the shared debug-mode
+  // uniform pointed at the requested view.
+  if (resolvedDebugMode > 0) setEnvironmentDebugOutput(root, resolvedDebugMode);
+
+  return {
+    aoOverlayMeshCount,
+    classification,
+    convertedMeshCount,
+    scanStylizedMaterialCount,
+    shaderMode: normalizedShaderMode,
+    shadowMeshCount,
+    vertexAoMeshCount,
+    windowCutoutMaterialCount,
+  };
+}

package/src/environment/environmentMaterialClassifier.js

@@ -0,0 +1,178 @@
+import * as THREE from 'three';
+
+export function toMaterialArray(material) {
+  return (Array.isArray(material) ? material : [material]).filter(Boolean);
+}
+
+export function textureLabel(texture) {
+  const image = texture?.image;
+  return [
+    texture?.name,
+    image?.currentSrc,
+    image?.src,
+    image?.name,
+  ].filter(Boolean).join(' ');
+}
+
+export function textureSourceUrl(texture) {
+  const image = texture?.image;
+  return image?.currentSrc || image?.src || '';
+}
+
+export function materialText(mat) {
+  return [
+    mat?.name,
+    textureLabel(mat?.map),
+    textureLabel(mat?.emissiveMap),
+    textureLabel(mat?.alphaMap),
+  ].filter(Boolean).join(' ').toLowerCase();
+}
+
+export function isUtilityTextureLabel(text) {
+  return /(?:^|[_\-/])(lsab|smbe|normal|nrm|height|ao|mask|esa)(?:[_.?#\-/]|$)/i.test(text);
+}
+
+export function isFoliageMaterial(mat) {
+  const text = materialText(mat);
+  return (
+    text.includes('leaf') ||
+    text.includes('grass') ||
+    text.includes('plant') ||
+    text.includes('potted') ||
+    text.includes('tree') ||
+    text.includes('banana')
+  );
+}
+
+export function sourceOpacity(mat) {
+  return Number.isFinite(mat?.opacity) ? mat.opacity : 1;
+}
+
+export function usesAlphaCutout(mat) {
+  const text = materialText(mat);
+  return (
+    (Number.isFinite(mat?.alphaTest) && mat.alphaTest > 0) ||
+    Boolean(mat?.alphaMap) ||
+    mat?.map?.transparent === true ||
+    text.includes('leaf') ||
+    text.includes('grass') ||
+    text.includes('plant') ||
+    text.includes('potted') ||
+    text.includes('mask')
+  );
+}
+
+export function alphaCutoffForMaterial(mat) {
+  if (!usesAlphaCutout(mat)) return -1.0;
+  if (isFoliageMaterial(mat)) return Math.max(mat?.alphaTest ?? 0.12, 0.08);
+  return Math.max(mat?.alphaTest ?? 0.35, 0.35);
+}
+
+export function isEmissiveEnvironmentMaterial(mat) {
+  const text = materialText(mat);
+  return (
+    Boolean(mat?.emissiveMap) ||
+    text.includes('light') ||
+    text.includes('lamp') ||
+    text.includes('fire') ||
+    text.includes('glow')
+  );
+}
+
+export function materialBaseColor(mat, { baseMapWasUtility = false, resolvedDiffuseMap = false } = {}) {
+  const color = mat?.color?.isColor ? mat.color.clone() : new THREE.Color(1, 1, 1);
+  const strongestChannel = Math.max(color.r, color.g, color.b);
+  if (isFoliageMaterial(mat) && strongestChannel < 0.14) {
+    return resolvedDiffuseMap || !baseMapWasUtility
+      ? new THREE.Color(1, 1, 1)
+      : new THREE.Color(0.26, 0.36, 0.17);
+  }
+
+  return color;
+}
+
+export function isWindowCutoutMaterial(mat) {
+  const text = materialText(mat);
+  if (/(screen|curtain|blind|painting|banner|poster|floor|ceiling|pillar|chair|table|cup|plate|book|vase|plant|leaf|grass|tree)/i.test(text)) {
+    return false;
+  }
+
+  return /(window|glass|pane|shutter)/i.test(text);
+}
+
+export function objectMaterialText(obj, materials) {
+  return [
+    obj?.name,
+    obj?.parent?.name,
+    ...materials.map((mat) => materialText(mat)),
+  ].filter(Boolean).join(' ').toLowerCase();
+}
+
+export function isEnvironmentShadowMesh(obj, materials) {
+  return /(?:^|[_\-\s])shadow\s*mesh(?:$|[_\-\s])|(?:^|[_\-\s])shadow(?:$|[_\-\s])/i
+    .test(objectMaterialText(obj, materials));
+}
+
+export function isAoOverlayMaterial(mat) {
+  return /(?:^|[_\-/])ao(?:[_.?#\-/]|$)|ambient.?occlusion/i.test(materialText(mat));
+}
+
+export function isEnvironmentAoOverlay(obj, materials) {
+  const text = objectMaterialText(obj, materials);
+  return /(?:^|[_\-\s])ao\d*(?:$|[_\-\s(])|mdbuild_ao/i.test(text) ||
+    materials.some((mat) => isAoOverlayMaterial(mat));
+}
+
+// Explicit material roles. Heuristics above are the fallback for unlabeled
+// packs; authors and integrators override them without renaming assets via:
+//   1. userData.envRole on the material or mesh ('standard' opts out of all
+//      heuristic special-casing),
+//   2. conversion-time roleOverrides: [{ match: string|RegExp, role }] tested
+//      against the material/object naming text.
+export const ENVIRONMENT_MATERIAL_ROLES = Object.freeze([
+  'standard',
+  'foliage',
+  'window',
+  'emissive',
+  'shadowMesh',
+  'aoOverlay',
+  'glossFloor',
+]);
+
+function normalizeEnvironmentRole(role) {
+  return ENVIRONMENT_MATERIAL_ROLES.includes(role) ? role : null;
+}
+
+function roleFromOverrides(text, roleOverrides) {
+  if (!Array.isArray(roleOverrides)) return null;
+  for (const override of roleOverrides) {
+    const match = override?.match;
+    const role = normalizeEnvironmentRole(override?.role);
+    if (!role || !match) continue;
+    if (match instanceof RegExp ? match.test(text) : text.includes(String(match).toLowerCase())) {
+      return role;
+    }
+  }
+  return null;
+}
+
+// Resolves the effective role for one material on one object, and reports
+// where the decision came from so misclassification is diagnosable:
+// { role, source: 'userData' | 'override' | 'heuristic' | 'default' }.
+export function classifyEnvironmentMaterialRole(obj, mat, { roleOverrides = null } = {}) {
+  const explicit = normalizeEnvironmentRole(mat?.userData?.envRole)
+    ?? normalizeEnvironmentRole(obj?.userData?.envRole);
+  if (explicit) return { role: explicit, source: 'userData' };
+
+  const text = objectMaterialText(obj, [mat]);
+  const overridden = roleFromOverrides(text, roleOverrides);
+  if (overridden) return { role: overridden, source: 'override' };
+
+  const materials = [mat];
+  if (isEnvironmentShadowMesh(obj, materials)) return { role: 'shadowMesh', source: 'heuristic' };
+  if (isEnvironmentAoOverlay(obj, materials)) return { role: 'aoOverlay', source: 'heuristic' };
+  if (isWindowCutoutMaterial(mat)) return { role: 'window', source: 'heuristic' };
+  if (isFoliageMaterial(mat)) return { role: 'foliage', source: 'heuristic' };
+  if (isEmissiveEnvironmentMaterial(mat)) return { role: 'emissive', source: 'heuristic' };
+  return { role: 'standard', source: 'default' };
+}