@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/src/rock-shader/rockRegionRuntime.js

@@ -0,0 +1,185 @@
+export const ROCK_REGION_BINDING_SCHEMA = 'toonlab.rock-region-binding';
+export const ROCK_REGION_BINDING_VERSION = 1;
+export const ROCK_REGION_PROFILE = 'hoodoo-caprock-normalized-height-v1';
+export const ROCK_REGION_GLTF_ATTRIBUTE = '_TL_ROCK_REGION';
+export const ROCK_REGION_THREE_ATTRIBUTE = '_tl_rock_region';
+export const ROCK_REGION_CHANNELS = Object.freeze(['base', 'shaft', 'neck', 'cap']);
+export const ROCK_REGION_BINDING_KEY = 'toonlabRockRegionBinding';
+export const ROCK_REGION_BANDS = Object.freeze({
+  base: Object.freeze([0.12, 0.30]),
+  cap: Object.freeze([0.72, 0.86]),
+  neckEnter: Object.freeze([0.60, 0.70]),
+  neckExit: Object.freeze([0.80, 0.89]),
+});
+
+function fail(reason, details = null) {
+  const error = new Error(`Invalid ToonLab rock-region binding: ${reason}`);
+  error.code = 'TOONLAB_ROCK_REGION_BINDING_INVALID';
+  error.details = details;
+  throw error;
+}
+
+function sameChannels(value) {
+  return Array.isArray(value)
+    && value.length === ROCK_REGION_CHANNELS.length
+    && value.every((channel, index) => channel === ROCK_REGION_CHANNELS[index]);
+}
+
+function sameBands(value) {
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(ROCK_REGION_BANDS).every(([key, expected]) => (
+    Array.isArray(value[key])
+    && value[key].length === expected.length
+    && value[key].every((entry, index) => entry === expected[index])
+  ));
+}
+
+function smoothstep(edge0, edge1, value) {
+  const t = Math.min(1, Math.max(0, (value - edge0) / (edge1 - edge0)));
+  return t * t * (3 - (2 * t));
+}
+
+function expectedRegionBytes(normalizedHeight) {
+  const base = 1 - smoothstep(...ROCK_REGION_BANDS.base, normalizedHeight);
+  const cap = smoothstep(...ROCK_REGION_BANDS.cap, normalizedHeight);
+  const neck = smoothstep(...ROCK_REGION_BANDS.neckEnter, normalizedHeight)
+    * (1 - smoothstep(...ROCK_REGION_BANDS.neckExit, normalizedHeight));
+  const baseByte = Math.round(base * 255);
+  const capByte = Math.round(cap * 255);
+  return [baseByte, 255 - baseByte - capByte, Math.round(neck * 255), capByte];
+}
+
+/**
+ * Validates one loaded GLB mesh without adding aliases or mutating geometry.
+ * GLTFLoader lower-cases the custom `_TL_ROCK_REGION` semantic and exposes it
+ * as `_tl_rock_region`, which TSL can consume directly.
+ */
+export function inspectRockRegionBinding(mesh, { sampleValues = true } = {}) {
+  if (!mesh?.isMesh || !mesh.geometry?.isBufferGeometry) {
+    fail('target must be a THREE.Mesh with BufferGeometry');
+  }
+  const binding = mesh.userData?.[ROCK_REGION_BINDING_KEY];
+  if (!binding || typeof binding !== 'object') fail(`missing ${ROCK_REGION_BINDING_KEY}`);
+  if (binding.schema !== ROCK_REGION_BINDING_SCHEMA) fail(`schema must be ${ROCK_REGION_BINDING_SCHEMA}`);
+  if (binding.version !== ROCK_REGION_BINDING_VERSION) fail(`version must be ${ROCK_REGION_BINDING_VERSION}`);
+  if (binding.profile !== ROCK_REGION_PROFILE) fail(`profile must be ${ROCK_REGION_PROFILE}`);
+  if (binding.attribute !== ROCK_REGION_GLTF_ATTRIBUTE) fail(`attribute must be ${ROCK_REGION_GLTF_ATTRIBUTE}`);
+  if (binding.encoding !== 'unorm8') fail('encoding must be unorm8');
+  if (binding.space !== 'mesh-local-normalized-height') fail('unsupported coordinate space');
+  if (binding.failClosed !== true) fail('failClosed must be true');
+  if (!sameChannels(binding.channels)) fail('channel order must be base, shaft, neck, cap');
+  if (!sameBands(binding.bands)) fail('height bands do not match the immutable hoodoo-caprock-normalized-height-v1 profile');
+
+  const position = mesh.geometry.getAttribute('position');
+  const region = mesh.geometry.getAttribute(ROCK_REGION_THREE_ATTRIBUTE);
+  if (!position) fail('mesh has no position attribute');
+  if (!region) fail(`mesh has no ${ROCK_REGION_THREE_ATTRIBUTE} attribute`);
+  if (region.itemSize !== 4) fail('region attribute must be VEC4');
+  if (region.count !== position.count) fail('region and position accessor counts differ');
+  if (region.normalized !== true) fail('region attribute must be normalized');
+  if (!(region.array instanceof Uint8Array)) fail('region attribute must use UNSIGNED_BYTE storage');
+
+  let primaryPartitionFailures = 0;
+  let compilerProfileMismatches = 0;
+  let neckSamples = 0;
+  const nonzeroSamples = [0, 0, 0, 0];
+  const channelMinUnorm8 = [255, 255, 255, 255];
+  const channelMaxUnorm8 = [0, 0, 0, 0];
+  if (sampleValues) {
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (let index = 0; index < position.count; index += 1) {
+      const y = position.getY(index);
+      if (!Number.isFinite(y)) fail('position attribute contains a non-finite height value');
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+    }
+    const height = maxY - minY;
+    if (!(height > 1e-8)) fail('mesh height range is too small for hoodoo-caprock-normalized-height-v1 regions');
+    for (let index = 0; index < region.count; index += 1) {
+      const offset = index * 4;
+      const base = region.array[offset];
+      const shaft = region.array[offset + 1];
+      const neck = region.array[offset + 2];
+      const cap = region.array[offset + 3];
+      if (base + shaft + cap !== 255) primaryPartitionFailures += 1;
+      if (neck > 0) neckSamples += 1;
+      const channels = [base, shaft, neck, cap];
+      const expected = expectedRegionBytes((position.getY(index) - minY) / height);
+      for (let channel = 0; channel < channels.length; channel += 1) {
+        const value = channels[channel];
+        if (value > 0) nonzeroSamples[channel] += 1;
+        channelMinUnorm8[channel] = Math.min(channelMinUnorm8[channel], value);
+        channelMaxUnorm8[channel] = Math.max(channelMaxUnorm8[channel], value);
+        if (value !== expected[channel]) compilerProfileMismatches += 1;
+      }
+    }
+    if (primaryPartitionFailures > 0) {
+      fail('base + shaft + cap must equal one at every quantized vertex', { primaryPartitionFailures });
+    }
+    if (neckSamples === 0) fail('neck overlay has no nonzero samples');
+    if (nonzeroSamples[0] === 0 || nonzeroSamples[1] === 0 || nonzeroSamples[3] === 0) {
+      fail('base, shaft, and cap must each have nonzero coverage', { nonzeroSamples });
+    }
+    if (channelMaxUnorm8.some((value) => value !== 255)) {
+      fail('base, shaft, neck, and cap must each reach full authored coverage', { channelMaxUnorm8 });
+    }
+    if (compilerProfileMismatches > 0) {
+      fail('region bytes do not match the immutable hoodoo-caprock-normalized-height-v1 compiler profile', {
+        compilerProfileMismatches,
+      });
+    }
+  }
+
+  return Object.freeze({
+    binding,
+    attribute: region,
+    attributeName: ROCK_REGION_THREE_ATTRIBUTE,
+    count: region.count,
+    bytes: region.array.byteLength,
+    primaryPartitionFailures,
+    compilerProfileMismatches,
+    neckSamples,
+    nonzeroSamples: Object.freeze([...nonzeroSamples]),
+    channelMinUnorm8: Object.freeze([...channelMinUnorm8]),
+    channelMaxUnorm8: Object.freeze([...channelMaxUnorm8]),
+    passed: true,
+  });
+}
+
+/**
+ * Audits all visual meshes. Missing bindings are failures by default because
+ * silently applying a partial palette to a multi-primitive rock changes its
+ * geological reading.
+ */
+export function inspectRockRegionBindings(root, {
+  requireEveryMesh = true,
+  sampleValues = true,
+} = {}) {
+  const records = [];
+  const failures = [];
+  root?.traverse?.((object) => {
+    if (!object?.isMesh || object.userData?.rockShaderExclude === true) return;
+    const hasBinding = Boolean(object.userData?.[ROCK_REGION_BINDING_KEY]);
+    if (!hasBinding && !requireEveryMesh) return;
+    try {
+      records.push({ mesh: object, ...inspectRockRegionBinding(object, { sampleValues }) });
+    } catch (error) {
+      failures.push({ mesh: object, error });
+    }
+  });
+  if (!records.length && !failures.length) fail('root has no visual meshes');
+  if (failures.length) {
+    fail(`${failures.length} mesh binding(s) failed validation`, failures.map(({ mesh, error }) => ({
+      mesh: mesh.name,
+      reason: error.message,
+    })));
+  }
+  return Object.freeze({
+    passed: true,
+    meshCount: records.length,
+    totalVertices: records.reduce((sum, record) => sum + record.count, 0),
+    totalBytes: records.reduce((sum, record) => sum + record.bytes, 0),
+    records: Object.freeze(records),
+  });
+}

package/src/rock-shader/rockSemanticMaterialRuntime.js

@@ -0,0 +1,337 @@
+import {
+  LinearFilter,
+  LinearMipmapLinearFilter,
+  NoColorSpace,
+  RepeatWrapping,
+  SRGBColorSpace,
+  TextureLoader,
+} from 'three';
+
+export const ROCK_MATERIAL_BINDING_SCHEMA = 'toonlab.rock-material-binding';
+export const ROCK_SEMANTIC_MATERIAL_SET_SCHEMA = 'toonlab.rock-semantic-material-set';
+
+const jsonPromises = new Map();
+const texturePromises = new Map();
+
+function absoluteUrl(value, base) {
+  const fallback = globalThis.location?.href ?? 'http://toonlab.invalid/';
+  return new URL(String(value), new URL(String(base), fallback)).href;
+}
+
+async function loadJson(url, fetchImpl) {
+  if (!jsonPromises.has(url)) {
+    const promise = fetchImpl(url).then(async (response) => {
+      if (!response.ok) throw new Error(`Rock material dependency is unavailable (${response.status}): ${url}`);
+      return response.json();
+    }).catch((error) => {
+      jsonPromises.delete(url);
+      throw error;
+    });
+    jsonPromises.set(url, promise);
+  }
+  return jsonPromises.get(url);
+}
+
+function configureTexture(map, descriptor) {
+  map.name = `ToonLab shared rock texture ${descriptor.hash}`;
+  map.colorSpace = descriptor.colorSpace === 'srgb' ? SRGBColorSpace : NoColorSpace;
+  map.flipY = false;
+  map.wrapS = RepeatWrapping;
+  map.wrapT = RepeatWrapping;
+  map.magFilter = LinearFilter;
+  map.minFilter = LinearMipmapLinearFilter;
+  map.generateMipmaps = true;
+  map.userData.toonlabContentHash = descriptor.hash;
+  map.userData.toonLabImportSettings = {
+    colorSpace: descriptor.colorSpace,
+    flipGreenChannel: Boolean(descriptor.flipGreenChannel),
+    textureFlipY: false,
+  };
+  map.needsUpdate = true;
+  return map;
+}
+
+async function loadTexture(url, descriptor, textureLoader) {
+  const key = `${descriptor.hash}|${url}`;
+  if (!texturePromises.has(key)) {
+    const promise = textureLoader.loadAsync(url)
+      .then((map) => configureTexture(map, descriptor))
+      .catch((error) => {
+        texturePromises.delete(key);
+        throw error;
+      });
+    texturePromises.set(key, promise);
+  }
+  return texturePromises.get(key);
+}
+
+const RUNTIME_TEXTURE_ROLES = Object.freeze({
+  grassAlbedo: 'grass',
+  grassBaseColor: 'grassBaseColor',
+  grassRoughness: 'grassRoughness',
+  mossPattern: 'moss',
+  noise: 'noise',
+  primaryAlbedo: 'rock',
+  primaryNormal: 'rockNormal',
+  primarySmoothness: 'smoothness',
+  sandAlbedo: 'sand',
+  sandNormal: 'sandNormal',
+  snowAlbedo: 'snow',
+  stripe: 'stripe',
+  stylizedNormal: 'stylizedNormal',
+  topMask: 'topMask',
+});
+
+function finite(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function clamp(value, minimum, maximum) {
+  return Math.min(maximum, Math.max(minimum, finite(value, minimum)));
+}
+
+function multiplyColor(value, gain, maximum = 2) {
+  const source = Array.isArray(value) ? value : [1, 1, 1];
+  const multiplier = Array.isArray(gain) ? gain : [1, 1, 1];
+  return source.slice(0, 3).map((channel, index) => clamp(
+    finite(channel, 1) * finite(multiplier[index], 1),
+    0,
+    maximum,
+  ));
+}
+
+function sourceProfileForRuntime(set, binding) {
+  const source = structuredClone(set.profile);
+  const variation = binding.materialVariation ?? {};
+  source.id = set.id;
+  source.sourceName = `semantic-set:${set.id}`;
+  source.sourcePath = null;
+  source.sourceGuid = set.id;
+  source.base ??= {};
+  source.base.tint = multiplyColor(source.base.tint, variation.colorGain);
+  source.base.brightness = clamp(
+    finite(source.base.brightness, 0) + finite(variation.brightnessOffset, 0),
+    -1,
+    1,
+  );
+  source.base.saturation = clamp(
+    finite(source.base.saturation, 1) * finite(variation.saturationGain, 1),
+    0,
+    2,
+  );
+  source.base.contrast = clamp(
+    finite(source.base.contrast, 1) * finite(variation.contrastGain, 1),
+    0,
+    3,
+  );
+  source.base.scale = clamp(
+    finite(source.base.scale, 1.6) * finite(variation.projectionScaleGain, 1),
+    0.05,
+    256,
+  );
+  source.base.projectionContrast = clamp(
+    finite(source.base.projectionContrast, 0.62) * finite(variation.projectionBlendGain, 1),
+    0.05,
+    4,
+  );
+  const sourceRoughness = 1 - Number(source.base.smoothness ?? 0);
+  source.base.smoothness = 1 - Math.min(1, Math.max(
+    0,
+    sourceRoughness * finite(variation.roughnessGain, 1),
+  ));
+  source.base.metallic = Math.min(1, Math.max(
+    0,
+    Number(source.base.metallic ?? 0) * finite(variation.metallicGain, 1),
+  ));
+  source.layers ??= {};
+  source.layers.maskEnabled = Number(source.layerMask?.semanticMaskStrength ?? 0) > 0;
+  source.layers.sharpness = clamp(
+    finite(source.layerMask?.sharpness, 0.8) * finite(variation.layerSharpnessGain, 1),
+    0,
+    8,
+  );
+  source.layers.offset = clamp(
+    finite(source.layerMask?.offset, 0.3) + finite(variation.layerSlopeOffset, 0),
+    -1,
+    1,
+  );
+  const sourceHeightStart = finite(source.layerMask?.heightStart, 0.48);
+  const sourceHeightEnd = finite(source.layerMask?.heightEnd, 0.88);
+  const heightShift = clamp(
+    finite(variation.layerHeightOffset, 0),
+    -sourceHeightStart,
+    1 - sourceHeightEnd,
+  );
+  source.layers.heightStart = sourceHeightStart + heightShift;
+  source.layers.heightEnd = sourceHeightEnd + heightShift;
+  source.layers.cavityStrength = Number(source.layerMask?.cavityStrength ?? 0);
+  source.layers.exposureStrength = Number(source.layerMask?.exposureStrength ?? 0);
+  source.layers.semanticMaskStrength = Number(source.layerMask?.semanticMaskStrength ?? 0);
+  for (const role of ['grass', 'snow', 'sand']) {
+    source.layers[role] = { ...(source.layers[role] ?? {}) };
+    source.layers[role].scale = clamp(
+      finite(source.layers[role].scale, 1) * finite(variation.layerScaleGain, 1),
+      0.05,
+      50,
+    );
+    source.layers[role].tint = multiplyColor(
+      source.layers[role].tint,
+      variation.layerTintGain,
+    );
+  }
+  source.layers.sand.normalScale = clamp(
+    finite(source.layers.sand.normalScale, source.layers.sand.scale)
+      * finite(variation.layerScaleGain, 1),
+    0.05,
+    50,
+  );
+  source.moss ??= {};
+  source.moss.size = Math.max(
+    0.000001,
+    finite(source.moss.size, 25) * finite(variation.mossScaleGain, 1),
+  );
+  source.moss.offset = finite(source.moss.offset, -0.15)
+    + finite(variation.mossCoverageOffset, 0);
+  source.base.striping = { ...(source.striping ?? {}), ...(source.base.striping ?? {}) };
+  return source;
+}
+
+function bindingMaterials(root) {
+  const materials = new Set();
+  root?.traverse?.((object) => {
+    if (!object?.isMesh) return;
+    for (const material of Array.isArray(object.material) ? object.material : [object.material]) {
+      if (material?.userData?.toonlabRockMaterialBinding) materials.add(material);
+    }
+  });
+  return [...materials];
+}
+
+function restoreSemanticMaskAttributeNames(root) {
+  root?.traverse?.((object) => {
+    if (!object?.isMesh) return;
+    const bound = (Array.isArray(object.material) ? object.material : [object.material])
+      .some((material) => material?.userData?.toonlabRockMaterialBinding);
+    if (!bound) return;
+    for (const name of ['rockCavity', 'rockExposure', 'rockHeight']) {
+      const exportedName = `_${name.toLowerCase()}`;
+      const attribute = object.geometry?.getAttribute(name)
+        ?? object.geometry?.getAttribute(exportedName);
+      if (!attribute) {
+        throw new Error(`${object.name || 'Semantic rock mesh'} is missing required ${name} data.`);
+      }
+      if (!object.geometry.getAttribute(name)) object.geometry.setAttribute(name, attribute);
+    }
+  });
+}
+
+/**
+ * Resolves every fail-closed GLB material binding before the asset is exposed.
+ * Throws on any missing manifest, set, or source texture; there is no fallback.
+ *
+ * @param {import('three').Object3D} root
+ * @param {{
+ *   fetchImpl?: typeof globalThis.fetch,
+ *   modelUrl?: string | URL,
+ *   textureLoader?: TextureLoader,
+ * }} [options]
+ * @returns {Promise<{ materialSets: number, textures: number }>}
+ */
+export async function prepareRockSemanticMaterialBindings(root, {
+  fetchImpl = globalThis.fetch?.bind(globalThis),
+  modelUrl,
+  textureLoader = new TextureLoader(),
+} = {}) {
+  const materials = bindingMaterials(root);
+  if (materials.length === 0) return { materialSets: 0, textures: 0 };
+  // glTF reserves custom vertex semantics with an underscore and GLTFLoader
+  // exposes them lower-cased. Publish the shader-facing aliases only after a
+  // semantic binding is identified, and fail rather than inventing masks.
+  restoreSemanticMaskAttributeNames(root);
+  if (typeof fetchImpl !== 'function') throw new Error('Semantic rock materials require fetch().');
+  if (!modelUrl) throw new Error('Semantic rock materials require the geometry model URL.');
+
+  const loadedHashes = new Set();
+  const loadedSets = new Set();
+  for (const material of materials) {
+    const binding = material.userData.toonlabRockMaterialBinding;
+    if (binding.schema !== ROCK_MATERIAL_BINDING_SCHEMA || binding.failClosed !== true) {
+      throw new Error('Rock geometry contains an invalid or non-fail-closed material binding.');
+    }
+    const manifestUrl = absoluteUrl(binding.manifest, modelUrl);
+    const manifest = await loadJson(manifestUrl, fetchImpl);
+    if (manifest.schema !== 'toonlab.rock-semantic-material-library') {
+      throw new Error(`Invalid semantic rock material library: ${manifestUrl}`);
+    }
+    const descriptor = manifest.sets?.find((entry) => entry.id === binding.materialSetId);
+    if (!descriptor) throw new Error(`Rock material set ${binding.materialSetId} is absent.`);
+    const setUrl = absoluteUrl(descriptor.file, manifestUrl);
+    const set = await loadJson(setUrl, fetchImpl);
+    if (set.schema !== ROCK_SEMANTIC_MATERIAL_SET_SCHEMA || set.id !== binding.materialSetId) {
+      throw new Error(`Rock material set ${binding.materialSetId} failed identity validation.`);
+    }
+    const textures = {};
+    const semanticTextures = {
+      ...(set.semanticTextures ?? {}),
+      ...(binding.semanticTextureOverrides ?? {}),
+    };
+    for (const [semanticRole, textureDescriptor] of Object.entries(semanticTextures)) {
+      const runtimeRole = RUNTIME_TEXTURE_ROLES[semanticRole];
+      if (!runtimeRole) continue;
+      if (!textureDescriptor?.hash || !textureDescriptor?.file) {
+        throw new Error(`${set.id}/${semanticRole} has no content-addressed source texture.`);
+      }
+      const libraryTexture = manifest.textures?.find((entry) => entry.hash === textureDescriptor.hash);
+      if (
+        !libraryTexture
+        || libraryTexture.file !== textureDescriptor.file
+        || libraryTexture.colorSpace !== textureDescriptor.colorSpace
+        || Boolean(libraryTexture.normalMap) !== Boolean(textureDescriptor.normalMap)
+      ) {
+        throw new Error(`${set.id}/${semanticRole} is not registered by the material library.`);
+      }
+      const textureUrl = absoluteUrl(textureDescriptor.file, manifestUrl);
+      textures[runtimeRole] = await loadTexture(textureUrl, textureDescriptor, textureLoader);
+      loadedHashes.add(textureDescriptor.hash);
+    }
+    if (!textures.rock?.isTexture) throw new Error(`${set.id} has no primary rock albedo.`);
+    material.userData.toonlabRockSemanticMaterial = Object.freeze({
+      binding: structuredClone(binding),
+      materialSetId: set.id,
+      profile: sourceProfileForRuntime(set, binding),
+      sourceChannels: structuredClone(set.sourceChannels ?? {}),
+      textures: Object.freeze(textures),
+    });
+    // The serialized descriptor is invisible so an unresolved asset cannot
+    // masquerade as a usable material. Once every dependency has loaded and
+    // validated, make the transient live descriptor opaque so strict scene
+    // material auditing can hand it to the rock adapter. It is replaced before
+    // the acquired asset enters a rendered scene.
+    material.opacity = 1;
+    material.transparent = false;
+    material.depthWrite = true;
+    material.needsUpdate = true;
+    loadedSets.add(set.id);
+  }
+  return { materialSets: loadedSets.size, textures: loadedHashes.size };
+}
+
+/** Preserves cache-owned Texture instances when official assets clone materials. */
+export function copyRockSemanticMaterialBinding(source, target) {
+  const semantic = source?.userData?.toonlabRockSemanticMaterial;
+  if (semantic) target.userData.toonlabRockSemanticMaterial = semantic;
+  return target;
+}
+
+export function rockSemanticMaterialTextures(material) {
+  return material?.userData?.toonlabRockSemanticMaterial?.textures ?? null;
+}
+
+export function clearRockSemanticMaterialCaches({ disposeTextures = false } = {}) {
+  if (disposeTextures) {
+    for (const promise of texturePromises.values()) promise.then((texture) => texture.dispose()).catch(() => {});
+  }
+  texturePromises.clear();
+  jsonPromises.clear();
+}