@call-me-sensei/toonlab 0.4.24 → 0.5.0

package/NPM-LIBRARY.md

@@ -1,7 +1,7 @@
 # ToonLab npm library guide
 
 This guide is included in `@call-me-sensei/toonlab`. It is the package-first
-reference for version 0.4.24 and does not require access to the source
+reference for version 0.5.0 and does not require access to the source
 repository.
 
 ## Install
@@ -89,9 +89,10 @@ import {
 } from '@call-me-sensei/toonlab/toon';
 
 const settings = createToonSettings({
-  rimLight: { intensity: 0.35, mode: 'depth' },
-  outline: { thickness: 1.6 },
-  skinTone: { skinShadowBrightness: 0.94 },
+  preset: 'call_me_sensei',
+  rim: { intensity: { hair: 0.35 }, mode: 'depth' },
+  outline: { width: { cloth: 0.006 } },
+  ramp: { tone: { skin: [0.93, 0.74, 0.68] } },
 });
 
 applyToonShader(characterRoot, { settings });
@@ -142,7 +143,7 @@ surface detail, not displacement that replaces a geometric high-to-low bake.
 
 ## Load Nature Reference Rocks
 
-Version 0.4.24 understands both the original `rock-0001`–`rock-0480`
+Version 0.5.0 understands both the original `rock-0001`–`rock-0480`
 identities and the Nature Reference Rocks catalog. Acquiring an asset
 directly returns its realistic PBR GLB. The one-call placement path additionally
 loads that asset's reviewed geology maps and `call_me_sensei` material settings
@@ -228,7 +229,7 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
       "command": "npx",
       "args": [
         "-y",
-        "--package=@call-me-sensei/toonlab@0.4.24",
+        "--package=@call-me-sensei/toonlab@0.5.0",
         "toonlab-mcp",
         "--workspace",
         "/absolute/path/to/your-game/.toonlab"

package/README.md

@@ -19,7 +19,7 @@ Use ToonLab as a focused runtime library (`@call-me-sensei/toonlab` on npm), as
 an asset/preset authoring workspace, or as an asset-discovery service—not as a
 one-shot world generator.
 
-## Versioned expectation: 0.4.24
+## Versioned expectation: 0.5.0
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual
@@ -376,7 +376,7 @@ camera behavior, and game feel remain host-owned or pre-beta.
 | Cluster | Import | What you get |
 |---|---|---|
 | Styles and bundles | `@call-me-sensei/toonlab/styles` | Local, versioned style-bundle documents that coordinate domain profiles without storing asset identity or current scene state. Create, validate, serialize, parse, and resolve JSON with no account or database; hosts currently route explicitly labeled assets through each owning runtime. [Contract](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/styles-and-bundles.md) |
-| Toon character shading | `@call-me-sensei/toonlab/toon` | Modern anime character shader: cel bands with art-directed face lighting, skin-tone shadow management, shadow-color HSV control, scene/self/contact shadows, average-shadow smoothing, rim light (fresnel or screen-space depth), stylized + anisotropic hair highlights, eye catchlights, role-aware specular, source map routing (normal/AO/emissive/MatCap/ramp/detail), inverted-hull outlines, glitter, stickers, perspective removal, shell fur, dither fades — 23 settings groups, all preset-serializable. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/toon-shading.md) |
+| Toon character shading | `@call-me-sensei/toonlab/toon` | Anime-game character shader: flat lit colour, per-surface shadow tones with a warm band at the terminator, face maps baked automatically from the face, a nose shadow, eye-white shade and stocking sheen derived from the model, environment-aware light (sun, sky, cast shade), scenery, character and hair-on-face shadows, depth rim, hair ring and masked specular, ink outlines coloured from the surface, source map routing (normal/AO/emissive/MatCap/detail), stickers, shell fur, dither fades — 14 settings groups, all preset-serializable. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/toon-shading.md) |
 | Environment shading | `@call-me-sensei/toonlab/environment` | Modern anime-style scene shader for texture packs, standard glTF, and untextured scenes: material-role classification, wrapped lighting, packed-map hints, window cutouts, sun/lamp rigs, time-of-day, six-direction ambient probe, planar floor reflections, BVH vertex-AO baking, height fog, cloud shadows. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/environment.md) |
 | Water | `@call-me-sensei/toonlab/water` | Focused water treatment for a host-authored water footprint, continuous shore, and closed seabed: Gerstner waves, absorption color, refraction/caustics/foam, ripples, splashes, wakes, kelp, underwater treatment, and CPU buoyancy sampling. It does not design the coast or underwater habitat. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/water.md) |
 | Vegetation | `@call-me-sensei/toonlab/vegetation` | Tree/grass/flower construction and shader runtimes, including the focused procedural broadleaf `BranchTree` with deterministic branching, eight leaf silhouettes, caller-supplied leaf/bark textures, and a portable recipe. No authored tree asset collection is bundled or exported: reviewed tree recipes remain searchable Gallery assets delivered through MCP with their CC0 metadata. Package-generated trees preserve authored bark first and otherwise select a registered deterministic bark surface instead of a bare trunk. The experimental species roster remains repository-only. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/vegetation-sky.md) |
@@ -583,8 +583,8 @@ import { applyToonShader, createToonSettings } from '@call-me-sensei/toonlab/too
 
 const settings = createToonSettings({
   preset: 'default',
-  skinTone: {
-    skinShadowBrightness: 0.94,
+  ramp: {
+    tone: { skin: [0.94, 0.82, 0.76] },
   },
 });
 

package/agents/PROMPTS.md

@@ -1,7 +1,7 @@
 # ToonLab agent prompts
 
 These prompts are included with the npm package. They use only the supported
-0.4.24 runtime, agent skills, and MCP workflows.
+0.5.0 runtime, agent skills, and MCP workflows.
 
 ## New playable game
 

package/agents/skills/claude/toon-shading/SKILL.md

@@ -11,7 +11,7 @@ References beginning `agents/` resolve from the installed ToonLab package root
 
 Use this skill when a developer wants ToonLab character toon materials, toon
 settings, preset documents, material-role handling, outlines, hair highlights,
-rim light, shadows, stickers, glitter, fur, or debug views in their app.
+rim light, shadows, shadow tones, face maps, stickers, fur, or debug views in their app.
 
 Public imports:
 - `@call-me-sensei/toonlab/toon`

package/agents/skills/codex/toon-shading/SKILL.md

@@ -11,7 +11,7 @@ References beginning `agents/` resolve from the installed ToonLab package root
 
 Use this skill when a developer wants ToonLab character toon materials, toon
 settings, preset documents, material-role handling, outlines, hair highlights,
-rim light, shadows, stickers, glitter, fur, or debug views in their app.
+rim light, shadows, shadow tones, face maps, stickers, fur, or debug views in their app.
 
 Public imports:
 - `@call-me-sensei/toonlab/toon`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@call-me-sensei/toonlab",
-  "version": "0.4.24",
+  "version": "0.5.0",
   "description": "Anime-style game toolkit for Three.js with cel shading, vegetation, rocks, water, sky, clouds, procedural textures, and portable Lab artifacts",
   "license": "MIT",
   "author": "Hyperbond Studio PTE. LTD. (Call Me Sensei)",
@@ -340,6 +340,8 @@
     "verify:grass": "node scripts/verify-grass-palettes.mjs",
     "verify:grass-package": "node scripts/verify-packaged-grass.mjs",
     "verify:character-package": "node scripts/verify-packaged-character.mjs",
+    "verify:toon-shading": "node scripts/verify-toon-character-shading.mjs",
+    "verify:provenance": "node scripts/verify-provenance.mjs",
     "verify:ground-stabilizer": "node scripts/verify-ground-stabilizer.mjs",
     "verify:locomotion-state": "node scripts/verify-locomotion-state-machine.mjs",
     "verify:water-interaction": "node scripts/verify-water-interaction-controller.mjs",
@@ -371,7 +373,7 @@
     "verify:collision-package": "node scripts/verify-packaged-world-collision.mjs",
     "verify:official-catalog": "node scripts/verify-official-catalog-provider.mjs && node scripts/verify-official-catalog-rock-package.mjs && node scripts/verify-official-catalog-runtime.mjs && node scripts/verify-official-catalog-lod.mjs && node scripts/verify-official-catalog-placement.mjs && node scripts/verify-playground-official-catalog.mjs && node scripts/verify-packaged-official-catalog.mjs",
     "verify:system-style": "node scripts/verify-system-style-policy.mjs",
-    "verify:release": "npm run verify:repository && npm run verify:system-style && npm run verify:style-contract && npm run verify:style-labels-package && npm run verify:collision-package && npm run verify:scene-collision && npm run verify:official-catalog && npm run verify:public-labs && npm run verify:live-labs && npm run verify:natural-rock-surfaces && npm run verify:rock-shader && npm run verify:rock-generation-lab && npm run verify:rock-lab-lifecycle && npm run verify:ground-shader && npm run verify:manufactured-materials && npm run verify:material-labeling:agent && npm run verify:material-labeling:mcp && npm run verify:water-lab && npm run verify:water && npm run verify:vegetation-labs && npm run verify:texgen && npm run verify:cloud-shader && npm run verify:sky-cloud-lab && npm run verify:world-quality && npm run verify:scatter && npm run verify:branch-tree && npm run verify:grass-package && npm run verify:character-package && npm run verify:locomotion-state && npm run verify:ground-stabilizer && npm run verify:water-interaction && npm run verify:walkable-character && npm run verify:playground-walkable && npm run verify:renderer-configuration && npm run verify:scene-scheduler && npm run verify:scene-surface && npm run verify:shared-shadow-receivers && npm run verify:scene-quality && npm run verify:quality-integration && npm run verify:lab-asset-provenance && npm run verify:api && npm run verify:types && npm run verify:mcp && npm run verify:skills && npm run verify:docs && npm run verify:local-database && npm run verify:package",
+    "verify:release": "npm run verify:repository && npm run verify:system-style && npm run verify:style-contract && npm run verify:style-labels-package && npm run verify:collision-package && npm run verify:scene-collision && npm run verify:official-catalog && npm run verify:public-labs && npm run verify:live-labs && npm run verify:natural-rock-surfaces && npm run verify:rock-shader && npm run verify:rock-generation-lab && npm run verify:rock-lab-lifecycle && npm run verify:ground-shader && npm run verify:manufactured-materials && npm run verify:material-labeling:agent && npm run verify:material-labeling:mcp && npm run verify:water-lab && npm run verify:water && npm run verify:vegetation-labs && npm run verify:texgen && npm run verify:cloud-shader && npm run verify:sky-cloud-lab && npm run verify:world-quality && npm run verify:scatter && npm run verify:branch-tree && npm run verify:grass-package && npm run verify:character-package && npm run verify:toon-shading && npm run verify:locomotion-state && npm run verify:ground-stabilizer && npm run verify:water-interaction && npm run verify:walkable-character && npm run verify:playground-walkable && npm run verify:renderer-configuration && npm run verify:scene-scheduler && npm run verify:scene-surface && npm run verify:shared-shadow-receivers && npm run verify:scene-quality && npm run verify:quality-integration && npm run verify:lab-asset-provenance && npm run verify:api && npm run verify:types && npm run verify:mcp && npm run verify:skills && npm run verify:docs && npm run verify:local-database && npm run verify:package",
     "verify:generation": "node scripts/verify-generation.mjs",
     "verify:post": "node scripts/verify-post.mjs",
     "verify:camera": "node scripts/verify-camera.mjs",

package/src/character/modelLoader.js

@@ -5,6 +5,7 @@ import { MTLLoader } from 'three/examples/jsm/loaders/MTLLoader.js';
 import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
 import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+import { TGALoader } from 'three/examples/jsm/loaders/TGALoader.js';
 import { USDZLoader } from 'three/examples/jsm/loaders/USDZLoader.js';
 import { unzipSync } from 'three/examples/jsm/libs/fflate.module.js';
 import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
@@ -248,6 +249,9 @@ function createModelLoadingManager() {
   manager.setURLModifier((url) => {
     return resolveKnownModelAssetUrl(url) ?? url;
   });
+  // FBX and OBJ exports from Max/Maya commonly reference TGA textures, which
+  // the browser's image decoder cannot read.
+  manager.addHandler(/\.tga$/i, new TGALoader(manager));
 
   return manager;
 }
@@ -331,7 +335,20 @@ function configureGltfLoader(loader, {
   }
 }
 
+// Records the source format on every material so conversion can apply the
+// format's colour semantics (glTF records more detail itself).
+function tagMaterialSourceFormat(root, format) {
+  root?.traverse?.((obj) => {
+    if (!obj.isMesh || !obj.material) return;
+    for (const material of toMaterialArray(obj.material)) {
+      if (!material || material.userData?.toonSource?.format) continue;
+      material.userData.toonSource = { ...(material.userData.toonSource || {}), format };
+    }
+  });
+}
+
 function createModelAsset({ clips = [], format, materialUrl = null, resourcePath, root, url, vrm = null }) {
+  tagMaterialSourceFormat(root, format);
   return {
     clips,
     format,
@@ -378,6 +395,7 @@ function annotateGltfSourceMetadata(gltf, url) {
 
     material.userData.toonSource = {
       ...(material.userData.toonSource || {}),
+      alphaMode: materialDef.alphaMode || 'OPAQUE',
       baseColorTextureIndex: Number.isInteger(baseColorTextureIndex) ? baseColorTextureIndex : null,
       format: 'gltf',
       imageCount: json.images?.length ?? 0,
@@ -399,6 +417,24 @@ function annotateGltfSourceMetadata(gltf, url) {
   }
 }
 
+// Records on each MMD toon ramp (material.gradientMap) its file and whether it
+// is one of MMD's shared toon01–10 presets or a ramp the model's author
+// shipped: only authored ramps are imported as the material's shadow tone.
+// Wraps three-stdlib's material builder; without it ramps simply stay
+// unimported.
+function tagMmdToonTextures(loader) {
+  const materialBuilder = loader.meshBuilder?.materialBuilder;
+  const loadTexture = materialBuilder?._loadTexture;
+  if (typeof loadTexture !== 'function') return;
+  materialBuilder._loadTexture = function loadTaggedTexture(filePath, textures, params, ...rest) {
+    const texture = loadTexture.call(this, filePath, textures, params, ...rest);
+    if (params?.isToonTexture && texture?.isTexture) {
+      texture.userData.mmdToon = { file: String(filePath ?? ''), shared: params.isDefaultToonTexture === true };
+    }
+    return texture;
+  };
+}
+
 export async function loadModelAsset(url, {
   decoderBasePath = null,
   materialUrl = null,
@@ -413,6 +449,7 @@ export async function loadModelAsset(url, {
     const { MMDLoader } = await loadMmdSupport();
     const loader = new MMDLoader(manager);
     loader.setResourcePath(resourcePath);
+    tagMmdToonTextures(loader);
     const root = await loadAsync(loader, url);
 
     return createModelAsset({
@@ -453,8 +490,12 @@ export async function loadModelAsset(url, {
 
     const vrm = gltf.userData?.vrm ?? null;
     if (vrm) {
-      // VRM0 models face +Z after this, matching VRM1/three convention.
+      // VRM0 models face +Z after this, matching VRM1/three convention. The
+      // turn is a 180° rotation on the root itself, so in the root's own frame
+      // a VRM0 character faces −Z; record that for head-frame consumers
+      // (automatic roles, the face shadow bake, head tracking).
       vrmUtils.rotateVRM0(vrm);
+      if (vrm.meta?.metaVersion === '0') gltf.scene.userData.toonForward = [0, 0, -1];
       // Clips animate the raw scene bones directly; without this vrm.update()
       // would overwrite them from the untouched normalized rig every frame.
       vrm.humanoid.autoUpdateHumanBones = false;

package/src/core/materialRoles.js

@@ -87,8 +87,10 @@ const FACE_TOKENS = [
   'mouth',
   'tooth',
   'teeth',
+  'tongue',
   'brow',
   'lash',
+  'eyelid',
   '颜',
   '顏',
   '面',
@@ -171,6 +173,36 @@ export function hasAnyToken(text, tokens) {
   return tokens.some((token) => text.includes(token));
 }
 
+// Words that contain a role token without meaning that role. They are blanked
+// out before that role's tokens are tested, so "armor" never reads as an arm,
+// "headphones" never as a head, and a hair clip is an accessory, not hair.
+const SEPARATOR = '[\\s_-]*';
+const EYE_EXCLUSIONS = [
+  new RegExp(`eye${SEPARATOR}(brow|lash|line|liner|lid|shadow)`, 'g'),
+];
+const FACE_EXCLUSIONS = [
+  /surface|interface|facet/g,
+  new RegExp(`head${SEPARATOR}(phone|set|band|gear|wear|piece|dress|acc|scarf|lamp|light)`, 'g'),
+  /splash|flash/g,
+];
+const SKIN_EXCLUSIONS = [
+  new RegExp(`(arm|leg)${SEPARATOR}warmer`, 'g'),
+  /armou?r|charm|alarm|warm|farm|harm/g,
+  new RegExp(`arm${SEPARATOR}(band|let|guard|ring)`, 'g'),
+  /legging|legend|elegan/g,
+  /handle|handkerchief|handbag/g,
+  new RegExp(`body${SEPARATOR}suit|bodice`, 'g'),
+];
+const HAIR_EXCLUSIONS = [
+  /chair/g,
+  new RegExp(`hair${SEPARATOR}(pin|clip|band|tie|ornament|acc|ribbon|bow|flower|stick|comb|ring|clasp|jewel|net)`, 'g'),
+];
+
+function hasRoleToken(text, tokens, exclusions = []) {
+  const cleaned = exclusions.reduce((value, pattern) => value.replace(pattern, ' '), text);
+  return hasAnyToken(cleaned, tokens);
+}
+
 export function normalizeMaterialRole(value, fallback = 'default') {
   if (Number.isFinite(value)) {
     return MATERIAL_ROLE_NAMES_BY_VALUE[Math.round(value)] ?? fallback;
@@ -315,7 +347,10 @@ function flagsForPrimaryRole(primaryRole) {
 function classifyMaterialHeuristics(mat) {
   const text = materialText(mat);
   const isCatchlight = hasAnyToken(text, CATCHLIGHT_TOKENS);
-  const isEyeHighlight = hasAnyToken(text, EYE_HIGHLIGHT_TOKENS);
+  // "highlight" alone is ambiguous: a hair highlight overlay is not an eye.
+  const namesHairOnly = hasRoleToken(text, HAIR_TOKENS, HAIR_EXCLUSIONS) &&
+    !hasRoleToken(text, EYE_TOKENS, EYE_EXCLUSIONS);
+  const isEyeHighlight = hasAnyToken(text, EYE_HIGHLIGHT_TOKENS) && !namesHairOnly;
   const isBlush = hasAnyToken(text, BLUSH_TOKENS);
   const isTransparentOverlay = isEyeHighlight ||
     isCatchlight ||
@@ -324,10 +359,10 @@ function classifyMaterialHeuristics(mat) {
   const isIris = hasAnyToken(text, IRIS_TOKENS);
   const isPupil = hasAnyToken(text, PUPIL_TOKENS);
   const isSclera = hasAnyToken(text, SCLERA_TOKENS);
-  const isEye = hasAnyToken(text, EYE_TOKENS);
-  const isFace = hasAnyToken(text, FACE_TOKENS);
-  const isSkin = hasAnyToken(text, SKIN_TOKENS);
-  const isHair = hasAnyToken(text, HAIR_TOKENS);
+  const isEye = hasRoleToken(text, EYE_TOKENS, EYE_EXCLUSIONS);
+  const isFace = hasRoleToken(text, FACE_TOKENS, FACE_EXCLUSIONS);
+  const isSkin = hasRoleToken(text, SKIN_TOKENS, SKIN_EXCLUSIONS);
+  const isHair = hasRoleToken(text, HAIR_TOKENS, HAIR_EXCLUSIONS);
   const isMetal = hasAnyToken(text, METAL_TOKENS);
   const isCostume = hasAnyToken(text, COSTUME_TOKENS);
 

package/src/environment/environmentMaterialAdapter.js

@@ -1,4 +1,4 @@
-import { syncToonSceneLights } from '../shaders-tsl/chunks/character-scene-lights.js';
+import { syncToonSceneLights } from '../shaders-tsl/character/sceneLights.js';
 import {
   classifyEnvironmentMaterialRole,
   toMaterialArray,
@@ -13,12 +13,12 @@ import {
 } from './manufacturedMaterialContract.js';
 
 // Environment node materials read scene lights from the shared toon light
-// uniforms (shaders-tsl/chunks/character-scene-lights.js) instead of three's
+// uniforms (shaders-tsl/character/sceneLights.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);
+  syncToonSceneLights(scene, camera, renderer);
 }
 import {
   applyEnvironmentSettingsToMaterial,

package/src/post/postProcessing.js

@@ -37,6 +37,10 @@ export const DEFAULT_POST_PROCESSING_PARAMETERS = Object.freeze({
   // Defaults of 1/1 reproduce plain bloom.
   bloomBackgroundSuppress: 1.0,
   bloomCharacterBoost: 1.0,
+  // Saturation of bloom gathered from character pixels. Bloom is additive and
+  // pushes skin toward white; above 1 it keeps the glow the character's own
+  // hue (warm skin glows warm). 1 = unchanged.
+  bloomCharacterSaturation: 1.0,
   // 'single' = the original one-pass 9-tap bloom. 'pyramid' = multi-pass
   // dual-filter mip chain: wider, softer glow for roughly the same cost at
   // high radii, at the price of extra render targets.
@@ -160,6 +164,7 @@ export const POST_PROCESSING_PRESETS = Object.freeze({
     },
     parameters: {
       bloomCharacterBoost: 1.6,
+      bloomCharacterSaturation: 1.4,
       bloomLevels: 5,
       bloomMode: 'pyramid',
       bloomRadius: 0.5,
@@ -275,6 +280,11 @@ const POST_PROCESSING_FIELD_DEFINITIONS = Object.freeze({
       label: 'Bloom Character Boost',
       range: { max: 4, min: 0, step: 0.05 },
     },
+    bloomCharacterSaturation: {
+      description: 'Scales the saturation of bloom gathered from character pixels when a character mask is connected.',
+      label: 'Bloom Character Saturation',
+      range: { max: 3, min: 0, step: 0.05 },
+    },
     bloomLevels: {
       description: 'Number of mip levels in the pyramid bloom chain (pyramid mode only).',
       label: 'Bloom Levels',
@@ -879,6 +889,7 @@ function applyCompositeSettings(material, settings, camera, depthTexture, width,
   const uniforms = material.uniforms;
   uniforms.bloomBackgroundSuppress.value = parameters.bloomBackgroundSuppress;
   uniforms.bloomCharacterBoost.value = parameters.bloomCharacterBoost;
+  uniforms.bloomCharacterSaturation.value = parameters.bloomCharacterSaturation;
   uniforms.bloomRadius.value = parameters.bloomRadius;
   uniforms.bloomStrength.value = features.bloom ? parameters.bloomStrength : 0.0;
   uniforms.bloomThreshold.value = parameters.bloomThreshold;
@@ -1028,6 +1039,7 @@ export function createPostProcessingPipeline({
     bloomPrefilterMaterial.uniforms.tInput.value = target.texture;
     bloomPrefilterMaterial.uniforms.bloomThreshold.value = settings.parameters.bloomThreshold;
     bloomPrefilterMaterial.uniforms.bloomCharacterBoost.value = settings.parameters.bloomCharacterBoost;
+    bloomPrefilterMaterial.uniforms.bloomCharacterSaturation.value = settings.parameters.bloomCharacterSaturation;
     bloomPrefilterMaterial.uniforms.bloomBackgroundSuppress.value = settings.parameters.bloomBackgroundSuppress;
     bloomPrefilterMaterial.uniforms.tCharacterMask.value = compositeMaterial.uniforms.tCharacterMask.value;
     bloomPrefilterMaterial.uniforms.useCharacterMask.value = compositeMaterial.uniforms.useCharacterMask.value;

package/src/shaders-tsl/character/castShadows.js

@@ -0,0 +1,147 @@
+// Cast shadows on the character (spec §5.5). Each returns a visibility
+// (1 lit, 0 shadowed) that multiplies the lit amount — a cast shadow moves a
+// pixel into the shadow tone, it never darkens the tone.
+
+import {
+  abs,
+  mix,
+  cameraFar,
+  cameraNear,
+  cameraProjectionMatrix,
+  cameraViewMatrix,
+  clamp,
+  dot,
+  float,
+  If,
+  max,
+  min,
+  orthographicDepthToViewZ,
+  perspectiveDepthToViewZ,
+  screenUV,
+  select,
+  smoothstep,
+  step,
+  vec2,
+  vec4,
+} from 'three/tsl';
+
+// Screen UV (top-left origin, like screenUV) of a view-space point.
+export function viewToScreenUV(viewPosition) {
+  const clip = cameraProjectionMatrix.mul(vec4(viewPosition, 1));
+  const ndc = clip.xy.div(max(clip.w, 1e-6));
+  return vec2(ndc.x.mul(0.5).add(0.5), ndc.y.mul(-0.5).add(0.5));
+}
+
+/** Screen UV of this pixel shifted by a view-space offset at `viewPosition`. */
+export function offsetScreenUV(viewPosition, viewOffset, baseUV = viewToScreenUV(viewPosition)) {
+  return screenUV.add(viewToScreenUV(viewPosition.add(viewOffset)).sub(baseUV));
+}
+
+/**
+ * Screen-UV change per metre of a lateral (view-plane) offset at this
+ * pixel's depth: exact for perspective and orthographic cameras.
+ */
+export function uvPerMetre(viewPosition) {
+  const orthographic = cameraProjectionMatrix.element(3).w.equal(1);
+  const w = select(orthographic, float(1), viewPosition.z.negate().max(1e-4));
+  return vec2(cameraProjectionMatrix.element(0).x, cameraProjectionMatrix.element(1).y.negate()).mul(0.5).div(w);
+}
+
+// The character passes store window depth in [0, 1], plus 2 on face (and
+// eye) surfaces so face receivers can ignore them; node materials clamp
+// their output at 0, so the flag must stay positive.
+export const FACE_DEPTH_OFFSET = 2;
+
+/** `{ depth, face }` from a value stored by the character passes. */
+export function decodeStoredDepth(stored) {
+  const face = stored.greaterThan(1.5);
+  return { depth: select(face, stored.sub(FACE_DEPTH_OFFSET), stored), face };
+}
+
+/** Window depth written by the depth prepass → distance in front of the camera. */
+export function prepassDistance(windowDepth) {
+  const orthographic = cameraProjectionMatrix.element(3).w.equal(1);
+  const viewZ = select(
+    orthographic,
+    orthographicDepthToViewZ(windowDepth, cameraNear, cameraFar),
+    perspectiveDepthToViewZ(windowDepth, cameraNear, cameraFar),
+  );
+  return viewZ.negate();
+}
+
+/**
+ * The character's own orthographic shadow map (characterRenderPasses.js):
+ * normal-offset and slope-scaled bias, bilinear filtering, and a fade toward the
+ * edge of the map's coverage.
+ */
+export function characterShadowVisibility(u, state, worldPosition, geometryNormal, faceLike, gate) {
+  const visibility = float(1).toVar('toonCharacterShadow');
+  If(state.shadowReady.greaterThan(0.5).and(gate), () => {
+    // Offset along the normal side that faces the light (thin, two-sided
+    // cards such as hair are lit from either side).
+    const facingSigned = dot(geometryNormal, state.shadowDirection);
+    const towardLight = geometryNormal.mul(select(facingSigned.lessThan(0), float(-1), float(1)));
+    const facing = abs(facingSigned).clamp(0, 1);
+    const receiver = worldPosition.add(towardLight.mul(u.characterShadowNormalBias));
+    const clip = state.shadowMatrix.mul(vec4(receiver, 1));
+    const coord = clip.xyz.div(clip.w).mul(0.5).add(0.5).toVar();
+    const inside = coord.x.greaterThanEqual(0).and(coord.x.lessThanEqual(1))
+      .and(coord.y.greaterThanEqual(0)).and(coord.y.lessThanEqual(1))
+      .and(coord.z.greaterThanEqual(0)).and(coord.z.lessThanEqual(1));
+    If(inside, () => {
+      const slope = float(1).add(float(1).sub(facing).mul(3));
+      const reference = coord.z.sub(u.characterShadowDepthBias.mul(slope).div(max(state.shadowDepthRange, 1e-4)));
+      // Bilinearly weighted comparisons of the 2×2 (softness-scaled) texels
+      // around the receiver: smooth edges from four taps.
+      const grid = state.shadowMapSize.div(max(u.characterShadowSoftness, 0.25));
+      const cell = coord.xy.mul(grid).sub(0.5);
+      const base = cell.floor();
+      const blend = cell.sub(base);
+      // Faces and eyes ignore face occluders (layered lashes, brows and
+      // eye whites a few millimetres apart must not shadow each other).
+      const ignoreFace = faceLike.greaterThan(0.5);
+      const tap = (x, y) => {
+        const stored = decodeStoredDepth(state.shadowMap.sample(base.add(vec2(x, y)).add(0.5).div(grid)).level(0).x);
+        return select(stored.face.and(ignoreFace), float(1), step(reference, stored.depth));
+      };
+      const lit = mix(
+        mix(tap(0, 0), tap(1, 0), blend.x),
+        mix(tap(0, 1), tap(1, 1), blend.x),
+        blend.y,
+      );
+      const edge = max(abs(coord.x.sub(0.5)), abs(coord.y.sub(0.5))).mul(2);
+      const coverage = float(1).sub(smoothstep(0.9, 1, edge));
+      visibility.assign(mix1(lit, coverage));
+    });
+  });
+  return visibility;
+}
+
+function mix1(value, amount) {
+  return float(1).add(value.sub(1).mul(amount));
+}
+
+/**
+ * Screen-space shadow toward the light against the depth prepass: something
+ * in front of the short ray toward the light (bangs over the forehead, hair
+ * on the cheek) shadows the pixel. Face receivers ignore face occluders
+ * (`faceWeight`), so a face never shadows itself.
+ */
+export function screenSpaceShadowVisibility(u, state, viewPosition, lightDirectionWorld, faceWeight, gate) {
+  const occlusion = float(0).toVar('toonScreenShadow');
+  If(state.depthReady.greaterThan(0.5).and(gate), () => {
+    const lightView = cameraViewMatrix.mul(vec4(lightDirectionWorld, 0)).xyz;
+    const baseUV = viewToScreenUV(viewPosition);
+    for (const fraction of [0.5, 1]) {
+      const rayPoint = viewPosition.add(lightView.mul(u.screenShadowWidth.mul(fraction)));
+      const stored = decodeStoredDepth(state.depthMap.sample(offsetScreenUV(viewPosition, lightView.mul(u.screenShadowWidth.mul(fraction)), baseUV)).level(0).x);
+      const nearer = rayPoint.z.negate().sub(prepassDistance(stored.depth));
+      const faceOccluder = select(stored.face, float(1), float(0));
+      const hit = smoothstep(0.002, 0.006, nearer)
+        .mul(float(1).sub(smoothstep(0.12, 0.25, nearer)))
+        .mul(float(1).sub(faceOccluder.mul(min(faceWeight.mul(2), 1))));
+      occlusion.assign(max(occlusion, hit));
+    }
+  });
+  return float(1).sub(occlusion);
+}