@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/src/character/characterRuntime.js

@@ -45,7 +45,7 @@ export const DEFAULT_CHARACTER_ANIMATION_ROLES = Object.freeze([
 ]);
 
 function stage(callback, name, detail = {}) {
-  callback?.({ detail, stage: name });
+  return callback?.({ detail, stage: name });
 }
 
 function throwIfAborted(signal) {
@@ -137,6 +137,116 @@ function prepareNeutralCharacterSource(root, renderer) {
   return replacements.size;
 }
 
+export const CHARACTER_MATERIAL_MODES = Object.freeze({
+  neutral: 'neutral',
+  toon: 'toon',
+});
+
+function normalizeCharacterMaterialMode(mode) {
+  return mode === CHARACTER_MATERIAL_MODES.neutral
+    ? CHARACTER_MATERIAL_MODES.neutral
+    : CHARACTER_MATERIAL_MODES.toon;
+}
+
+function isToonHelperMesh(object) {
+  return object?.userData?.isToonOutline === true || object?.userData?.isToonFurShell === true;
+}
+
+function collectCharacterBodyMeshes(root) {
+  const meshes = [];
+  root.traverse((object) => {
+    if (!object?.isMesh || !object.material || isToonHelperMesh(object)) return;
+    meshes.push(object);
+  });
+  return meshes;
+}
+
+/**
+ * Builds a second, neutral material set over an already-converted character so
+ * a single load can present both looks.
+ *
+ * `prepareNeutralCharacterSource` mounts its neutral materials destructively and
+ * disposes the imported ones, which is right for a one-look runtime and wrong for
+ * a comparison: §11-style shader wipes must share one skeleton, one mixer and one
+ * set of geometry buffers, so the two looks can only differ by which `mesh.material`
+ * reference is bound at draw time. This builds the neutral set from the retained
+ * imported materials without mounting or disposing anything, so both sets stay live
+ * and swapping is a reference assignment rather than a rebuild.
+ */
+function createCharacterMaterialModeState({
+  integration,
+  originalsByMesh,
+  renderer,
+  root,
+}) {
+  const usesNodeMaterials = renderer?.isWebGPURenderer === true;
+  const neutralReplacements = new Map();
+  const neutralByMesh = new Map();
+  const toonByMesh = new Map();
+  const neutralBeforeRender = new Map();
+  const toonBeforeRender = new Map();
+  const helpers = [];
+
+  root.traverse((object) => {
+    if (isToonHelperMesh(object)) helpers.push(object);
+  });
+
+  for (const [mesh, originalMaterial] of originalsByMesh) {
+    const replace = (source) => {
+      if (!source) return source;
+      if (!usesNodeMaterials) return source;
+      if (!neutralReplacements.has(source)) {
+        neutralReplacements.set(source, createNeutralCharacterMaterial(source));
+      }
+      return neutralReplacements.get(source);
+    };
+    neutralByMesh.set(mesh, Array.isArray(originalMaterial)
+      ? originalMaterial.map(replace)
+      : replace(originalMaterial));
+    toonByMesh.set(mesh, mesh.material);
+    toonBeforeRender.set(mesh, mesh.onBeforeRender);
+    neutralBeforeRender.set(
+      mesh,
+      usesNodeMaterials && mesh.isSkinnedMesh
+        ? () => updateToonStorageSkinning(mesh)
+        : THREE.Object3D.prototype.onBeforeRender,
+    );
+  }
+
+  let mode = CHARACTER_MATERIAL_MODES.toon;
+
+  return {
+    disposeNeutral() {
+      for (const material of neutralReplacements.values()) material.dispose?.();
+      neutralReplacements.clear();
+    },
+    get mode() {
+      return mode;
+    },
+    neutralMaterialCount: usesNodeMaterials ? neutralReplacements.size : originalsByMesh.size,
+    set(nextMode) {
+      const resolved = normalizeCharacterMaterialMode(nextMode);
+      if (resolved === mode) return mode;
+      const neutral = resolved === CHARACTER_MATERIAL_MODES.neutral;
+      const source = neutral ? neutralByMesh : toonByMesh;
+      const beforeRender = neutral ? neutralBeforeRender : toonBeforeRender;
+      for (const [mesh, material] of source) {
+        mesh.material = material;
+        mesh.onBeforeRender = beforeRender.get(mesh);
+      }
+      // Outline and fur shells are separate child meshes, never removed — the
+      // toon look owns them and the neutral look must not draw them.
+      for (const helper of helpers) helper.visible = !neutral;
+      mode = resolved;
+      // The depth prepass and self-shadow target bind concrete materials; they
+      // must follow the swap or the neutral half shades against toon buffers.
+      integration?.refresh?.();
+      return mode;
+    },
+    usesNodeMaterials,
+  };
+}
+
 function attachCharacterStyleMetadata(carrier, {
   managed,
   styleTarget,
@@ -181,6 +291,7 @@ function attachCharacterStyleMetadata(carrier, {
 export async function createCharacterRuntime({
   animation = true,
   carrier = null,
+  materialModes = false,
   materialUrl = null,
   name = 'ToonLab Character',
   onStage = null,
@@ -203,12 +314,12 @@ export async function createCharacterRuntime({
   characterCarrier.name ||= name;
   let attached = false;
 
-  stage(onStage, CHARACTER_RUNTIME_STAGE.MODEL, { url });
+  await stage(onStage, CHARACTER_RUNTIME_STAGE.MODEL, { url });
   const asset = await loadModelAsset(url, { materialUrl, renderer });
   throwIfAborted(signal);
 
   try {
-    stage(onStage, CHARACTER_RUNTIME_STAGE.TEXTURES, { asset, url });
+    await stage(onStage, CHARACTER_RUNTIME_STAGE.TEXTURES, { asset, url });
     await waitForObjectTextures(asset.root);
     throwIfAborted(signal);
     setObjectTextureColorSpaces(asset.root);
@@ -218,7 +329,14 @@ export async function createCharacterRuntime({
       : null;
     bakeSolidBaseColorTextures(asset.root);
 
-    stage(onStage, CHARACTER_RUNTIME_STAGE.STYLE, { asset, bounds, url });
+    await stage(onStage, CHARACTER_RUNTIME_STAGE.STYLE, { asset, bounds, url });
+    // A dual-mode runtime keeps the imported materials alive so the neutral set
+    // can be rebuilt from them after conversion; the single-mode path stays
+    // exactly as before, including the destructive neutral swap.
+    const wantsMaterialModes = materialModes === true && toon !== false;
+    const originalsByMesh = wantsMaterialModes
+      ? new Map(collectCharacterBodyMeshes(asset.root).map((mesh) => [mesh, mesh.material]))
+      : null;
     const neutralSourceMaterialCount = toon === false
       ? prepareNeutralCharacterSource(asset.root, renderer)
       : 0;
@@ -231,7 +349,7 @@ export async function createCharacterRuntime({
     let animationSource = 'none';
 
     if (animationOptions.enabled) {
-      stage(onStage, CHARACTER_RUNTIME_STAGE.ANIMATION, { asset, rig, targetMesh, url });
+      await stage(onStage, CHARACTER_RUNTIME_STAGE.ANIMATION, { asset, rig, targetMesh, url });
       const nativeRoles = resolveNativeLocomotionClips(asset.clips) ?? {};
       clipRoles = keepRequestedRoles(nativeRoles, animationOptions.roles);
       animationSource = Object.keys(clipRoles).length ? 'native' : 'none';
@@ -243,6 +361,11 @@ export async function createCharacterRuntime({
           retargetMode: animationOptions.retargetMode,
           rootMotion: animationOptions.rootMotion,
           sourceUrl: animationOptions.fallbackSourceUrl,
+          // This runtime owns one mixer rooted at the imported model scene,
+          // so packaged clips must bind named bone nodes just like native
+          // glTF clips. The lower-level loader keeps its skeleton-rooted
+          // default for callers that mix directly on a SkinnedMesh.
+          trackNameStyle: 'node',
         });
         throwIfAborted(signal);
         for (const role of missingRoles) {
@@ -295,6 +418,15 @@ export async function createCharacterRuntime({
     };
     characterCarrier.userData.toonlabCharacterStyleIntegration = characterStyleIntegration;
 
+    const materialModeState = originalsByMesh
+      ? createCharacterMaterialModeState({
+        integration: characterStyleIntegration,
+        originalsByMesh,
+        renderer,
+        root: asset.root,
+      })
+      : null;
+
     const mixer = Object.keys(clipRoles).length
       ? new THREE.AnimationMixer(asset.root)
       : null;
@@ -317,9 +449,32 @@ export async function createCharacterRuntime({
       rig,
       targetMesh,
       toonState,
-      neutralSourceMaterialCount,
+      neutralSourceMaterialCount: materialModeState
+        ? materialModeState.neutralMaterialCount
+        : neutralSourceMaterialCount,
       url,
 
+      /**
+       * `'neutral' | 'toon'` when the runtime was created with
+       * `materialModes: true`, otherwise `null`. Reading it is cheap; it is the
+       * authoritative record of which material set is currently bound.
+       */
+      get materialMode() {
+        return materialModeState?.mode ?? null;
+      },
+
+      /**
+       * Binds one of the two material sets over the same meshes, skeleton and
+       * mixer. Returns the resolved mode, or `null` on a single-mode runtime.
+       *
+       * Cheap enough to call between two `renderer.render` calls in one frame,
+       * which is what a §11-style scissor wipe needs.
+       */
+      setMaterialMode(mode) {
+        if (disposed || !materialModeState) return null;
+        return materialModeState.set(mode);
+      },
+
       applyToonSettings(settings) {
         if (disposed || !toonState) return null;
         return applyToonSettingsToMaterial(asset.root, settings);
@@ -327,6 +482,19 @@ export async function createCharacterRuntime({
 
       dispose({ disposeResources = true } = {}) {
         if (disposed) return;
+        // Rebind the toon set so the unmounted half is the one this method
+        // disposes explicitly and `disposeLoadedRoot` still sees a complete
+        // mounted material set.
+        materialModeState?.set(CHARACTER_MATERIAL_MODES.toon);
+        if (disposeResources && materialModeState) {
+          // The neutral bridge materials, then the imported ones they were built
+          // from. When the renderer needs no bridge the two are the same objects
+          // and the second pass is a no-op re-dispose.
+          materialModeState.disposeNeutral();
+          for (const material of originalsByMesh.values()) {
+            for (const entry of Array.isArray(material) ? material : [material]) entry?.dispose?.();
+          }
+        }
         disposed = true;
         mixer?.stopAllAction();
         mixer?.uncacheRoot(asset.root);
@@ -363,7 +531,7 @@ export async function createCharacterRuntime({
       },
     };
 
-    stage(onStage, CHARACTER_RUNTIME_STAGE.READY, { runtime, url });
+    await stage(onStage, CHARACTER_RUNTIME_STAGE.READY, { runtime, url });
     return runtime;
   } catch (error) {
     if (attached) {

package/src/environment/environmentMaterialAdapter.js

@@ -33,6 +33,7 @@ import {
   setEnvironmentDebugOutput,
 } from './environmentShaderMaterials.js';
 import { resolveEnvironmentPreset } from './environmentPresets.js';
+import { installToonLabSurfaceLighting } from './toonLabSurfaceLighting.js';
 import {
   resolveEnvironmentTextureSet,
 } from './environmentTextureResolver.js';
@@ -213,6 +214,23 @@ export async function applyEnvironmentShader(root, {
   scenario = undefined,
   settings = {},
   shaderMode = 'anime',
+  // Surface-lighting model options (D19-150). A material this adapter converts
+  // now JOINS the ToonLab surface-lighting model instead of being left outside
+  // it. Before this, `applyEnvironmentShader` reported a material as converted
+  // while never setting `userData.toonLabSurfaceLighting` — the exact flag every
+  // scene guards on when adopting its own shadow fill:
+  //
+  //   if (!material?.userData?.toonLabSurfaceLighting) continue;   // missed it
+  //
+  // so a scene's shadow fill silently reached every first-party surface and
+  // skipped every dropped-in asset. Nothing warned; the adoption loop simply
+  // reported a lower count. The divergence grows with how much fill the scene
+  // adopts, which is what made it severe rather than cosmetic.
+  //
+  // Defaults are the installer's own defaults (shadowFill 0), so installing
+  // here changes no existing capture — it only makes the material present in
+  // the model, which is what lets a scene's adoption loop find it afterwards.
+  surfaceLighting = {},
   openWindows = false,
   vertexAoOptions = {},
 } = {}) {
@@ -258,6 +276,8 @@ export async function applyEnvironmentShader(root, {
     : 'anime';
   const resolvedDebugMode = normalizeEnvironmentDebugMode(debugOutputMode);
   let convertedMeshCount = 0;
+  // D19-150: how many converted materials actually joined the lighting model.
+  let surfaceLightingMaterialCount = 0;
   let aoOverlayMeshCount = 0;
   let windowCutoutMaterialCount = 0;
   let shadowMeshCount = 0;
@@ -409,6 +429,15 @@ export async function applyEnvironmentShader(root, {
 
     for (const mat of toMaterialArray(obj.material)) {
       if (mat?.userData?.windowCutout) windowCutoutMaterialCount += 1;
+      // D19-150: enrol every converted environment material in the surface
+      // lighting model. `installToonLabSurfaceLighting` is a no-op on anything
+      // that is not a NodeMaterial and preserves prior options when re-run, so
+      // this is safe both for materials that already carry it and for the
+      // scene-side adoption pass that re-installs with an authored shadowFill.
+      if (mat?.isNodeMaterial && mat.userData?.environmentMaterial) {
+        installToonLabSurfaceLighting(mat, surfaceLighting);
+        if (mat.userData?.toonLabSurfaceLighting) surfaceLightingMaterialCount += 1;
+      }
     }
     if (toMaterialArray(obj.material).some((mat) => mat?.userData?.environmentMaterial)) {
       obj.onBeforeRender = environmentNodeLightSync;
@@ -430,6 +459,7 @@ export async function applyEnvironmentShader(root, {
     aoOverlayMeshCount,
     classification,
     convertedMeshCount,
+    surfaceLightingMaterialCount,
     manifestWarnings: manifestResult?.warnings ?? [],
     manufacturedAssetId: resolvedAssetId,
     manufacturedObjectClass: resolvedObjectClass,

package/src/environment/environmentPresets.js

@@ -660,6 +660,96 @@ registerEnvironmentPreset('call_me_sensei', {
         },
       },
     },
+    // The finish axis is the one an audience actually reads at a glance:
+    // brushed stainless next to charcoal powder coat is the same base material
+    // and must not look like the same surface. Without these profiles the
+    // finish was validated by the contract, stored on the material, and then
+    // had no effect on the frame, so `metal`/`brushed` converted to the same
+    // response as `mineral`/`raw`. Resolution order puts finishes AFTER
+    // baseMaterials, so a finish refines its base rather than fighting it.
+    finishes: {
+      anodized: {
+        parameters: {
+          specularShininess: 70,
+          specularSoftness: 0.3,
+          specularStrength: 0.34,
+        },
+      },
+      brushed: {
+        // Anisotropic metal: a broad, smeared highlight (low shininess, wide
+        // softness) rather than a point hit, plus a real sky pickup — that
+        // cool skylight in the mid-tones is what says "metal" in an anime
+        // frame, not the metalness channel the toon shader does not have.
+        parameters: {
+          skyTintStrength: 0.34,
+          specularColor: [0.86, 0.9, 1],
+          specularShininess: 26,
+          specularSoftness: 0.42,
+          specularStrength: 0.55,
+        },
+      },
+      clearCoated: {
+        parameters: {
+          specularShininess: 140,
+          specularSoftness: 0.14,
+          specularStrength: 0.42,
+        },
+      },
+      glazed: {
+        parameters: {
+          specularShininess: 120,
+          specularSoftness: 0.16,
+          specularStrength: 0.46,
+        },
+      },
+      matte: {
+        parameters: {
+          specularShininess: 10,
+          specularSoftness: 0.55,
+          specularStrength: 0.03,
+        },
+      },
+      mirror: {
+        parameters: {
+          skyTintStrength: 0.6,
+          specularShininess: 240,
+          specularSoftness: 0.08,
+          specularStrength: 0.9,
+        },
+      },
+      // Powder coat and enamel are dielectric films: a soft, broad sheen that
+      // must stay clearly below `brushed` so painted metal and bare metal
+      // separate at a glance.
+      painted: {
+        parameters: {
+          specularShininess: 34,
+          specularSoftness: 0.34,
+          specularStrength: 0.14,
+        },
+      },
+      polished: {
+        parameters: {
+          skyTintStrength: 0.45,
+          specularShininess: 180,
+          specularSoftness: 0.1,
+          specularStrength: 0.7,
+        },
+      },
+      raw: {
+        parameters: {
+          specularShininess: 12,
+          specularSoftness: 0.5,
+          specularStrength: 0.04,
+        },
+      },
+      varnished: {
+        parameters: {
+          specularShininess: 90,
+          specularSoftness: 0.2,
+          specularStrength: 0.3,
+        },
+      },
+    },
     objectClasses: {
       buildingExterior: {
         parameters: { normalMapStrength: 0.66 },

package/src/environment/environmentSunShadowPass.js

@@ -61,6 +61,13 @@ export function createEnvironmentSunShadowPass({ renderer, scene } = {}) {
   const warmedCasterSources = new WeakMap();
   let cachedSunLight = null;
   let renderCount = 0;
+  // Real health, not "the object exists". D19-041 shipped a Gate 3 check
+  // written as `Boolean(runtime.shadowPass)`, which is true from construction
+  // and therefore cannot fail. These are the three things that actually have
+  // to be true for a receiver to see a cast shadow.
+  let lastCasterCount = 0;
+  let lastSkippedNonCasterCount = 0;
+  let lastFailure = 'pass has not run';
   let casterDepthSamplePoints = Object.freeze([]);
   let casterCoverage = Object.freeze({
     byDomain: Object.freeze({}),
@@ -345,6 +352,8 @@ export function createEnvironmentSunShadowPass({ renderer, scene } = {}) {
     if (!sun) {
       environmentSunShadow.ready.value = false;
       environmentSunShadow.farReady.value = false;
+      lastCasterCount = 0;
+      lastFailure = 'no visible DirectionalLight with castShadow in the scene';
       return;
     }
 
@@ -359,6 +368,7 @@ export function createEnvironmentSunShadowPass({ renderer, scene } = {}) {
     if (needsPrimaryRenderWarmup) {
       // The host's normal scene render follows this scheduled pass. Retain any
       // existing map for one frame and include the new caster on the next one.
+      lastFailure = 'warming up a newly added caster';
       return;
     }
 
@@ -557,6 +567,9 @@ export function createEnvironmentSunShadowPass({ renderer, scene } = {}) {
     renderer.shadowMap.enabled = previousShadowAutoUpdate;
     scene.background = previousBackground;
 
+    lastCasterCount = materialRestores.length;
+    lastSkippedNonCasterCount = visibilityRestores.length;
+    lastFailure = lastCasterCount > 0 ? null : 'no visible castShadow mesh was drawn into the map';
     for (const { material, mesh } of materialRestores) mesh.material = material;
     for (const obj of visibilityRestores) obj.visible = true;
     materialRestores.length = 0;
@@ -607,12 +620,41 @@ export function createEnvironmentSunShadowPass({ renderer, scene } = {}) {
     get ready() {
       return environmentSunShadow.ready.value === true;
     },
+    /**
+     * Whether the pass is actually producing a usable shadow map, and why not
+     * when it is not. Hosts gating a review on shadows must read `ok` here
+     * rather than testing that the pass object exists (D19-041).
+     */
+    get health() {
+      const ready = environmentSunShadow.ready.value === true;
+      const ok = ready && renderCount > 0 && lastCasterCount > 0;
+      return Object.freeze({
+        backend: isNodeBackend ? 'node' : 'classic-webgl-unused',
+        casterCount: lastCasterCount,
+        farReady: environmentSunShadow.farReady.value === true,
+        hiddenNonCasterCount: lastSkippedNonCasterCount,
+        ok,
+        ready,
+        reason: ok ? null : (lastFailure ?? (ready ? null : 'pass has not published a map')),
+        renderCount,
+        sunName: cachedSunLight?.name ?? null,
+      });
+    },
     get renderCount() {
       return renderCount;
     },
     get shadowTexture() {
       return shadowTarget?.texture ?? null;
     },
+    // Render targets, for diagnostics that need to read the depth the pass
+    // actually wrote (D19-041/D19-062). `inspectDepthContent` only samples
+    // labelled style targets; these let a caller probe any world point.
+    get nearShadowTarget() {
+      return shadowTarget;
+    },
+    get farShadowTarget() {
+      return farShadowTarget;
+    },
     get shadowMatrix() {
       return shadowMatrix;
     },