@call-me-sensei/toonlab 0.1.1

package/src/shaders-tsl/chunks/character-color.js

@@ -0,0 +1,64 @@
+// TSL port of src/shaders/chunks/character-fragment-color.glsl — albedo color
+// edits and HSV helpers shared by the toon character shader.
+//
+// GLSL's applyHSVChange returns the edited color and its original HSV through
+// an out-parameter; here the two are separate calls (rgbToHsv is cheap and the
+// builder de-duplicates identical subgraphs).
+
+import {
+  abs,
+  clamp,
+  dot,
+  float,
+  Fn,
+  fract,
+  max,
+  min,
+  mix,
+  pow,
+  select,
+  step,
+  vec3,
+  vec4,
+} from 'three/tsl';
+
+export const LUMA = vec3(0.2126, 0.7152, 0.0722);
+
+export const maxColorComponent = /*@__PURE__*/ Fn(([value]) => {
+  return max(value.r, max(value.g, value.b));
+});
+
+export const rgbToHsv = /*@__PURE__*/ Fn(([c]) => {
+  const K = vec4(0.0, -1.0 / 3.0, 2.0 / 3.0, -1.0);
+  const p = mix(vec4(c.bg, K.wz), vec4(c.gb, K.xy), step(c.b, c.g)).toVar();
+  const q = mix(vec4(p.xyw, c.r), vec4(c.r, p.yzx), step(p.x, c.r)).toVar();
+  const d = q.x.sub(min(q.w, q.y));
+  const e = float(1.0e-10);
+  return vec3(
+    abs(q.z.add(q.w.sub(q.y).div(d.mul(6.0).add(e)))),
+    d.div(q.x.add(e)),
+    q.x,
+  );
+});
+
+export const hsvToRgb = /*@__PURE__*/ Fn(([c]) => {
+  const p = abs(fract(c.xxx.add(vec3(0.0, 2.0 / 3.0, 1.0 / 3.0))).mul(6.0).sub(3.0));
+  return c.z.mul(mix(vec3(1.0), clamp(p.sub(1.0), 0.0, 1.0), c.y));
+});
+
+// GLSL applyHSVChange without the originalHSV out-param — callers that need
+// the original HSV call rgbToHsv themselves.
+export const applyHSVChange = /*@__PURE__*/ Fn(([color, hueOffset, saturationBoost, valueMul]) => {
+  const hsv = rgbToHsv(max(color, vec3(0.0))).toVar();
+  hsv.x.assign(fract(hsv.x.add(hueOffset)));
+  hsv.y.assign(clamp(hsv.y.add(saturationBoost), 0.0, 1.0));
+  hsv.z.mulAssign(valueMul);
+  return hsvToRgb(hsv);
+});
+
+export const adjustSaturation = /*@__PURE__*/ Fn(([color, saturation]) => {
+  const luma = dot(color, LUMA);
+  const adjusted = mix(vec3(luma), color, max(saturation, 0.0));
+  // GLSL early-outs when |saturation - 1| < 1e-4; same result via select.
+  return select(abs(saturation.sub(1.0)).lessThan(0.0001), color, adjusted);
+});

package/src/shaders-tsl/chunks/character-highlights.js

@@ -0,0 +1,174 @@
+// TSL port of src/shaders/chunks/character-fragment-highlights.glsl —
+// specular band, hair strand highlight, eye gloss, and procedural glitter.
+
+import {
+  abs,
+  clamp,
+  dot,
+  float,
+  Fn,
+  fract,
+  If,
+  length,
+  max,
+  min,
+  mix,
+  normalize,
+  pow,
+  reflect,
+  select,
+  smoothstep,
+  sqrt,
+  vec2,
+  vec3,
+} from 'three/tsl';
+
+function maskChannel(maskTexel, channelUniform) {
+  return select(channelUniform.equal(1), maskTexel.g,
+    select(channelUniform.equal(2), maskTexel.b,
+      select(channelUniform.equal(3), maskTexel.a, maskTexel.r)));
+}
+
+export function createHighlightsChunk({ u, tex, v, flags, toonEdgeSmooth }) {
+  const sampleSpecularMask = () => {
+    if (!flags.hasSpecularMask) return float(1.0);
+    const maskTexel = tex.specularMaskMap.sample(v.vUv);
+    const mask = maskChannel(maskTexel, u.specularMaskChannel);
+    return select(
+      u.useSpecularMask,
+      mix(1.0, clamp(mask, 0.0, 1.0), u.specularMaskStrength),
+      1.0,
+    );
+  };
+
+  const calculateSpecularArea = (NoH, NoV, finalShadowArea, roughnessValue) => {
+    const roughnessPower = mix(192.0, 8.0, clamp(roughnessValue, 0.0, 1.0));
+    const resolvedPower = mix(u.specularPower, roughnessPower, u.materialRoughnessStrength);
+    // View mode anchors the highlight to the surface instead of the light.
+    const specularSource = select(u.specularDirectionMode.equal(1), NoV, NoH);
+    const specularRaw = pow(specularSource, max(resolvedPower, 1.0));
+    const specStart = max(0.0, u.specularAreaRemapMidPoint.sub(u.specularAreaRemapRange));
+    const specEnd = min(1.0, u.specularAreaRemapMidPoint.add(u.specularAreaRemapRange));
+    const specularArea = toonEdgeSmooth(specularRaw, specStart, specEnd);
+    const specularShadowMask = mix(finalShadowArea, 1.0, u.specularShowInShadowArea);
+    const roughnessMask = mix(1.0, roughnessValue.mul(0.65).oneMinus(), u.materialRoughnessStrength);
+    const result = specularArea.mul(specularShadowMask).mul(roughnessMask).mul(sampleSpecularMask());
+    return select(u.useSpecular, result, 0.0);
+  };
+
+  const sampleHairHighlightMask = (uv) => {
+    if (!flags.hasHairHighlightMask) return float(1.0);
+    const maskTexel = tex.hairHighlightMaskMap.sample(uv);
+    const mask = maskChannel(maskTexel, u.hairHighlightMaskChannel);
+    return select(
+      u.useHairHighlightMask,
+      mix(1.0, clamp(mask, 0.0, 1.0), u.hairHighlightMaskStrength),
+      1.0,
+    );
+  };
+
+  const sampleEyeHighlightMask = (uv) => {
+    if (!flags.hasEyeHighlightMask) return float(1.0);
+    const maskTexel = tex.eyeHighlightMaskMap.sample(uv);
+    const mask = maskChannel(maskTexel, u.eyeHighlightMaskChannel);
+    return select(
+      u.useEyeHighlightMask,
+      mix(1.0, clamp(mask, 0.0, 1.0), u.eyeHighlightMaskStrength),
+      1.0,
+    );
+  };
+
+  const calculateHairHighlightMask = (V, N, H, uv, finalShadowArea) => {
+    const strandDirection = normalize(u.hairHighlightDirection);
+    const tangentHalf = dot(strandDirection, H);
+    const strandTangent = pow(
+      clamp(sqrt(max(0.0, tangentHalf.mul(tangentHalf).oneMinus())), 0.0, 1.0),
+      u.hairHighlightStrandPower,
+    );
+    const strandReflect = pow(
+      clamp(abs(dot(strandDirection, reflect(V.negate(), N))).oneMinus(), 0.0, 1.0),
+      u.hairHighlightStrandPower,
+    );
+    const strand = select(u.hairHighlightMode.equal(1), strandTangent, strandReflect);
+
+    const uvCoord = select(u.hairHighlightUvBandAxis.equal(1), uv.y, uv.x);
+    const sideBand = pow(
+      clamp(
+        abs(uvCoord.sub(u.hairHighlightUvBandCenter)).div(max(u.hairHighlightUvBandHalfWidth, 0.001)).oneMinus(),
+        0.0,
+        1.0,
+      ),
+      u.hairHighlightSideBandPower,
+    );
+    const result = strand.mul(sideBand)
+      .mul(sampleHairHighlightMask(uv))
+      .mul(mix(u.hairHighlightShadowFloor, 1.0, finalShadowArea));
+    return select(u.useHairHighlight, result, 0.0);
+  };
+
+  const calculateEyeHighlightMask = (L, N, V, uv) => {
+    const gloss = pow(clamp(dot(reflect(L.negate(), N), V), 0.0, 1.0), max(u.eyeHighlightPower, 1.0));
+    return select(u.useEyeHighlight, gloss.mul(sampleEyeHighlightMask(uv)), 0.0);
+  };
+
+  // Procedural glitter — one particle per UV cell with a random orientation,
+  // lit by a very tight reflection lobe. Only built when glitter is enabled
+  // on the material (GLSL: USE_TOON_GLITTER define).
+  const toonGlitterHash = /*@__PURE__*/ Fn(([p]) => {
+    const p3 = fract(vec3(p.x, p.y, p.x).mul(0.1031)).toVar();
+    p3.addAssign(dot(p3, p3.yzx.add(33.33)));
+    return fract(p3.x.add(p3.y).mul(p3.z));
+  });
+
+  const toonGlitterHash2 = /*@__PURE__*/ Fn(([p]) => {
+    const p3 = fract(vec3(p.x, p.y, p.x).mul(vec3(0.1031, 0.103, 0.0973))).toVar();
+    p3.addAssign(dot(p3, p3.yzx.add(33.33)));
+    return fract(p3.xx.add(p3.yz).mul(p3.zy));
+  });
+
+  const toonGlitterHash3 = /*@__PURE__*/ Fn(([p]) => {
+    const p3 = fract(vec3(p.x, p.y, p.x).mul(vec3(0.1031, 0.103, 0.0973))).toVar();
+    p3.addAssign(dot(p3, p3.yxz.add(33.33)));
+    return fract(p3.xxy.add(p3.yzz).mul(p3.zyx)).mul(2.0).sub(1.0);
+  });
+
+  const evaluateGlitter = (uv, V, N, L) => {
+    const particleSize = u.glitterSize.mul(0.25).toVar();
+    const scaledUv = uv.mul(u.glitterDensity).mul(1000.0).toVar();
+    const cellId = scaledUv.floor().toVar();
+    const cellUv = fract(scaledUv).toVar();
+    const glitter = vec3(0.0).toVar();
+
+    for (let y = -1; y <= 1; y += 1) {
+      for (let x = -1; x <= 1; x += 1) {
+        const neighborCell = cellId.add(vec2(x, y)).toVar();
+        const particlePos = vec2(x, y).add(toonGlitterHash2(neighborCell));
+        const dist = length(particlePos.sub(cellUv)).toVar();
+        If(dist.lessThan(particleSize), () => {
+          const particleNormal = normalize(mix(
+            N,
+            normalize(toonGlitterHash3(neighborCell)),
+            u.glitterRandomNormalStrength,
+          ));
+          const reflectDir = reflect(V.negate(), particleNormal);
+          const sparkle = pow(max(dot(reflectDir, L), 0.0), 1000.0);
+          const viewAlignment = pow(max(dot(V, particleNormal), 0.0), 5.0);
+          const fade = smoothstep(particleSize.mul(0.2), particleSize, dist).oneMinus();
+          const sparkleIntensity = sparkle.mul(viewAlignment).mul(fade).mul(100.0);
+          const colorSeed = toonGlitterHash(neighborCell.add(50.0));
+          glitter.addAssign(
+            mix(vec3(1.0, 0.98, 0.95), vec3(0.95, 0.97, 1.0), colorSeed).mul(sparkleIntensity),
+          );
+        });
+      }
+    }
+    return glitter;
+  };
+
+  return {
+    calculateEyeHighlightMask,
+    calculateHairHighlightMask,
+    calculateSpecularArea,
+    evaluateGlitter,
+  };
+}

package/src/shaders-tsl/chunks/character-lighting.js

@@ -0,0 +1,309 @@
+// TSL port of src/shaders/chunks/character-fragment-lighting.glsl — cel
+// banding, face proxy normals, screen-space depth rim + contact shadow, the
+// character-only shadow map, average-shadow blending, and the rim mask.
+//
+// GLSL out-parameters (evaluateDepthEffects) become returned node pairs.
+// Uniform-driven early returns become select()/If() with identical operand
+// math. Screen-space reads use three's screenUV node, which resolves the
+// per-backend viewport orientation the GLSL handled implicitly through
+// gl_FragCoord.
+
+import {
+  abs,
+  clamp,
+  dFdx,
+  dFdy,
+  dot,
+  float,
+  Fn,
+  If,
+  length,
+  max,
+  min,
+  mix,
+  normalize,
+  perspectiveDepthToViewZ,
+  pow,
+  screenUV,
+  select,
+  smoothstep,
+  step,
+  vec2,
+  vec3,
+  vec4,
+} from 'three/tsl';
+
+export function createLightingChunk({ u, tex, v, flags, frontFacingNode, cameraViewMatrixNode }) {
+  // Widens a smoothstep transition by the value's screen derivative so the
+  // edge stays ~1px feathered. edgeAntiAliasStrength = 0 → plain smoothstep.
+  const toonEdgeSmooth = (value, edgeMin, edgeMax) => {
+    const derivative = min(
+      abs(dFdx(value)).add(abs(dFdy(value))).mul(u.edgeAntiAliasStrength),
+      0.25,
+    );
+    return smoothstep(edgeMin.sub(derivative), edgeMax.add(derivative), value);
+  };
+
+  // NOTE (docs/tsl-conventions.md): select() operands must stay pure
+  // expressions — branches that create vars or call Fn()s crash the GLSL
+  // builder's detached type-resolution flow (ConditionalNode fallback setup).
+  const resolveLightingNormal = (normal) => {
+    const flattenWS = normalize(u.headForwardWS);
+    const sphereWS = normalize(v.vWorldPosition.sub(u.headPositionWS));
+    const fixedWS = normalize(mix(flattenWS, sphereWS, clamp(u.faceSphereBlend, 0.0, 1.0)));
+    const headTracked = normalize(cameraViewMatrixNode.mul(vec4(fixedWS, 0.0)).xyz);
+
+    const staticProxy = normalize(v.vFaceProxyNormal);
+    // faceHeadSpaceMode 1 uses head-bone data (inert until headDataReady).
+    const proxyNormal = select(u.faceHeadSpaceMode.equal(1), headTracked, staticProxy);
+    const blended = normalize(mix(normal, proxyNormal, clamp(u.faceNormalProxyBlend, 0.0, 1.0)));
+
+    const headModeUnready = u.faceHeadSpaceMode.equal(1).and(u.headDataReady.not());
+    const inactive = u.isFace.not()
+      .or(u.faceNormalProxyBlend.lessThanEqual(0.0))
+      .or(headModeUnready);
+    return select(inactive, normal, blended);
+  };
+
+  const calcCelShade = (N, L) => {
+    const NoL = dot(N, L);
+    const bodyCel = mix(
+      toonEdgeSmooth(NoL, u.celShadeMidPoint.sub(u.celShadeSoftness), u.celShadeMidPoint.add(u.celShadeSoftness)),
+      1.0,
+      u.mainLightIgnoreCelShade,
+    );
+    const faceCel = mix(
+      toonEdgeSmooth(
+        NoL,
+        u.celShadeMidPointForFaceArea.sub(u.celShadeSoftnessForFaceArea),
+        u.celShadeMidPointForFaceArea.add(u.celShadeSoftnessForFaceArea),
+      ),
+      1.0,
+      u.mainLightIgnoreCelShadeForFaceArea,
+    );
+    return select(u.isFace, faceCel, bodyCel);
+  };
+
+  const localLightBand = (normal, lightDirection) => {
+    const halfLambert = dot(normal, lightDirection).mul(0.5).add(0.5);
+    const softBand = smoothstep(0.08, 0.92, halfLambert);
+    const faceBand = smoothstep(-0.15, 0.85, halfLambert);
+    return select(u.isFace, mix(faceBand, 1.0, u.faceLocalLightLift), softBand);
+  };
+
+  const safeNormalizeDir2 = (value) => value.div(max(length(value), 1e-5));
+
+  // Render-target reads sample at explicit level 0: the RTs have no mips and
+  // WGSL forbids implicit-derivative sampling inside non-uniform control flow.
+  // Pass targets are float COLOR textures (vec4 on both builders), so .x is
+  // the depth channel — depth-texture sampling types differently per builder.
+  const readSceneLinearDepth = (screenUv) => {
+    const depthSample = tex.sceneDepthTexture.sample(clamp(screenUv, vec2(0.0), vec2(1.0))).level(0).x;
+    return perspectiveDepthToViewZ(depthSample, u.cameraNearPlane, u.cameraFarPlane).negate();
+  };
+
+  // depthRim < 0 signals "depth data unavailable" (fresnel rim fallback);
+  // contactShadow is 1 when unshadowed.
+  const evaluateDepthEffects = (N, L, NoL, NoV) => {
+    const depthRim = float(-1.0).toVar();
+    const contactShadow = float(1.0).toVar();
+
+    const allowed = flags.isOutlinePass
+      ? null
+      : u.sceneDepthReady.and(u.ditherOpacity.greaterThanEqual(1.0));
+
+    if (allowed !== null) {
+      If(allowed, () => {
+        const selfDepth = v.vViewPos.z.negate().toVar();
+        const screenUv = screenUV.toVar();
+
+        const safeDistance = max(u.rimDepthSafeDistance, 0.05);
+        const closeCurve = float(2.0).div(safeDistance)
+          .sub(selfDepth.div(safeDistance.mul(safeDistance)));
+        const distanceFix = select(
+          selfDepth.greaterThan(safeDistance),
+          float(1.0).div(selfDepth),
+          mix(float(1.0).div(selfDepth), closeCurve, u.rimDepthCloseWidthReduce),
+        ).toVar();
+
+        const fovFix = abs(u.cameraProjection11).mul(0.0054);
+        const aspectFix = vec2(u.sceneDepthResolution.y.div(u.sceneDepthResolution.x), 1.0);
+        const offsetScale = aspectFix.mul(fovFix.mul(distanceFix)).mul(0.707).toVar();
+        offsetScale.y.mulAssign(smoothstep(1.0, 0.95, screenUv.y));
+
+        const faceWidthFix = select(u.isFace, float(0.66666), float(1.0));
+
+        // ---- Rim light ----
+        const rimDir = safeNormalizeDir2(L.xy);
+        const rimUvOffset = offsetScale.mul(rimDir).mul(u.rimDepthWidth.mul(faceWidthFix)).toVar();
+        const rimThreshold = clamp(u.rimDepthThresholdOffset.add(0.05), 0.0, 1.0);
+        const selfDepthForRim = selfDepth.add(rimThreshold).toVar();
+        const rimFade = float(10.0).div(max(u.rimDepthFadeRange, 1e-3)).toVar();
+
+        const rim = clamp(
+          readSceneLinearDepth(screenUv.add(rimUvOffset)).sub(selfDepthForRim).mul(rimFade),
+          0.0,
+          1.0,
+        ).toVar();
+
+        If(u.rimDepthDottedLineFix, () => {
+          const extend = offsetScale.mul(u.rimDepthWidth).mul(0.5);
+          const rimA = clamp(readSceneLinearDepth(screenUv.add(rimUvOffset).add(vec2(-1.0, 0.0).mul(extend))).sub(selfDepthForRim).mul(rimFade), 0.0, 1.0);
+          const rimB = clamp(readSceneLinearDepth(screenUv.add(rimUvOffset).add(vec2(1.0, 0.0).mul(extend))).sub(selfDepthForRim).mul(rimFade), 0.0, 1.0);
+          const rimC = clamp(readSceneLinearDepth(screenUv.add(rimUvOffset).add(vec2(0.0, 1.0).mul(extend))).sub(selfDepthForRim).mul(rimFade), 0.0, 1.0);
+          rim.assign(min(min(rim, rimA), min(rimB, rimC)));
+        });
+
+        If(u.rimDepthMask3D, () => {
+          const blur = 0.025;
+          rim.mulAssign(smoothstep(0.075 - blur, 0.075 + blur, clamp(NoL, 0.0, 1.0).mul(NoV.oneMinus())));
+        });
+
+        rim.mulAssign(smoothstep(u.rimDepthFadeEndDistance, u.rimDepthFadeStartDistance, selfDepth));
+        depthRim.assign(rim);
+
+        // ---- Contact shadow ----
+        If(u.contactShadowStrength.greaterThan(0.0), () => {
+          const shadowDirVS = vec3(L).toVar();
+          If(u.isFace.and(u.contactShadowFaceHeadUpBlend.greaterThan(0.0)).and(u.headDataReady), () => {
+            const headUpVS = normalize(cameraViewMatrixNode.mul(vec4(u.headUpWS, 0.0)).xyz);
+            shadowDirVS.assign(normalize(mix(L, headUpVS, u.contactShadowFaceHeadUpBlend)));
+          });
+          const shadowUvOffset = offsetScale
+            .mul(safeNormalizeDir2(shadowDirVS.xy))
+            .mul(u.contactShadowWidth.mul(faceWidthFix));
+          const shadowThreshold = select(u.isFace, float(0.01), float(0.03)).add(u.contactShadowThresholdOffset);
+          const shadowFade = float(50.0).div(max(u.contactShadowFadeRange, 1e-3));
+          const unshadowed = clamp(
+            readSceneLinearDepth(screenUv.add(shadowUvOffset)).sub(selfDepth.sub(shadowThreshold)).mul(shadowFade),
+            0.0,
+            1.0,
+          );
+          contactShadow.assign(mix(1.0, unshadowed, u.contactShadowStrength));
+        });
+      });
+    }
+
+    return { contactShadow, depthRim };
+  };
+
+  // ---- Character-only shadow map ----
+
+  const charSelfShadowCompare = (coord) => {
+    return step(coord.z, tex.charSelfShadowMap.sample(coord.xy).level(0).x);
+  };
+
+  const evaluateCharSelfShadowMap = Fn(() => {
+    const shadow = float(1.0).toVar();
+
+    If(u.charSelfShadowReady, () => {
+      const worldN = normalize(v.vWorldNormal).mul(select(frontFacingNode, 1.0, -1.0)).toVar();
+
+      const slopeBias = float(1.1).sub(dot(worldN, u.charSelfShadowLightDirection));
+      const samplePosition = v.vWorldPosition
+        .add(worldN.mul(slopeBias).mul(u.charSelfShadowNormalBias))
+        .add(u.charSelfShadowLightDirection.mul(slopeBias).mul(u.charSelfShadowDepthBias));
+
+      // Orthographic shadow camera: w is 1, so clip position is already NDC.
+      const shadowNdc = u.charSelfShadowMatrix.mul(vec4(samplePosition, 1.0));
+      const coord = shadowNdc.xyz.mul(0.5).add(0.5).toVar();
+
+      const outside = coord.x.lessThan(0.0)
+        .or(coord.x.greaterThan(1.0))
+        .or(coord.y.lessThan(0.0))
+        .or(coord.y.greaterThan(1.0))
+        .or(coord.z.greaterThan(1.0))
+        .or(coord.z.lessThan(0.0));
+
+      If(outside.not(), () => {
+        const sampled = float(0.0).toVar();
+        If(u.charSelfShadowQuality.greaterThanEqual(2.0), () => {
+          // 9-tap box PCF (unrolled).
+          for (let x = -1; x <= 1; x += 1) {
+            for (let y = -1; y <= 1; y += 1) {
+              sampled.addAssign(charSelfShadowCompare(
+                coord.add(vec3(vec2(x, y).mul(u.charSelfShadowTexelSize), 0.0)),
+              ));
+            }
+          }
+          sampled.divAssign(9.0);
+        }).ElseIf(u.charSelfShadowQuality.greaterThanEqual(1.0), () => {
+          const halfTexel = u.charSelfShadowTexelSize.mul(0.5);
+          const total = charSelfShadowCompare(coord.add(vec3(halfTexel.negate(), halfTexel.negate(), 0.0)))
+            .add(charSelfShadowCompare(coord.add(vec3(halfTexel, halfTexel.negate(), 0.0))))
+            .add(charSelfShadowCompare(coord.add(vec3(halfTexel.negate(), halfTexel, 0.0))))
+            .add(charSelfShadowCompare(coord.add(vec3(halfTexel, halfTexel, 0.0))));
+          sampled.assign(total.mul(0.25));
+        }).Else(() => {
+          sampled.assign(charSelfShadowCompare(coord));
+        });
+
+        If(u.charSelfShadowSharpen.greaterThan(0.0), () => {
+          sampled.assign(smoothstep(
+            float(0.5).sub(u.charSelfShadowSharpen),
+            float(0.5).add(u.charSelfShadowSharpen),
+            sampled,
+          ));
+        });
+
+        const selfDepth = v.vViewPos.z.negate();
+        sampled.assign(mix(sampled, 1.0, clamp(selfDepth.sub(u.charSelfShadowFadeDistance.sub(1.0)), 0.0, 1.0)));
+
+        If(u.charSelfShadowNdotLFix, () => {
+          sampled.assign(mix(
+            1.0,
+            sampled,
+            smoothstep(0.05, 0.2, clamp(dot(worldN, u.charSelfShadowLightDirection), 0.0, 1.0)),
+          ));
+        });
+
+        shadow.assign(sampled);
+      });
+    });
+
+    return shadow;
+  });
+
+  const getCharacterSelfShadowVisibility = (sceneShadowVisibility) => {
+    // The shadow-map evaluation is hoisted into an If-assigned var: an Fn call
+    // inside a select() operand breaks the GLSL builder (see NOTE above), and
+    // this also skips the map taps entirely unless sourceMode is 2 — the same
+    // shape as the GLSL if-chain.
+    const mapVisibility = float(1.0).toVar();
+    If(u.selfShadowSourceMode.equal(2), () => {
+      mapVisibility.assign(evaluateCharSelfShadowMap());
+    });
+    return select(u.selfShadowSourceMode.equal(1), sceneShadowVisibility, mapVisibility);
+  };
+
+  const applyAverageShadowVisibility = (visibility, sceneShadowVisibility, selfShadowVisibility) => {
+    const sourceAverage = visibility.add(sceneShadowVisibility).add(selfShadowVisibility).div(3.0);
+    const liftedAverage = max(sourceAverage, u.averageShadowMinLight);
+    const easedAverage = mix(liftedAverage, smoothstep(0.0, 1.0, liftedAverage), u.averageShadowSoftness);
+    const applied = mix(visibility, easedAverage, u.averageShadowStrength);
+    return select(u.averageShadowStrength.lessThanEqual(0.0), visibility, applied);
+  };
+
+  const calculateRimMask = (NoV, NoL, finalShadowArea, depthRim) => {
+    const rimRaw = NoV.oneMinus().mul(NoL.mul(0.25).add(0.75));
+    const fresnelRim = toonEdgeSmooth(rimRaw, u.rimMidPoint.sub(u.rimSoftness), u.rimMidPoint.add(u.rimSoftness));
+    const rim = select(
+      u.rimLightMode.equal(1).and(depthRim.greaterThanEqual(0.0)),
+      depthRim,
+      fresnelRim,
+    );
+    const masked = rim.mul(mix(1.0, finalShadowArea, u.rimBlockByShadow));
+    return select(u.useRimLight, masked, 0.0);
+  };
+
+  return {
+    applyAverageShadowVisibility,
+    calcCelShade,
+    calculateRimMask,
+    evaluateDepthEffects,
+    getCharacterSelfShadowVisibility,
+    localLightBand,
+    resolveLightingNormal,
+    toonEdgeSmooth,
+  };
+}

package/src/shaders-tsl/chunks/character-material-maps.js

@@ -0,0 +1,146 @@
+// TSL port of src/shaders/chunks/character-fragment-material-maps.glsl.
+//
+// GLSL compiles each optional sampler in via a USE_TOON_* define so unused
+// units are never declared (ANGLE's 16-sampler limit). Here the same
+// conditions become JS guards: when a map is absent the no-map stub result is
+// baked into the graph, so the WGSL/GLSL the builder emits never references
+// the texture. The `has*`/strength uniforms stay runtime-tweakable exactly
+// like the GLSL versions.
+//
+// The factory receives:
+//   u     — uniform-node map (GLSL uniform names)
+//   tex   — texture nodes (only the ones the material actually carries)
+//   v     — varyings ({ vUv, vUv2, vViewPos })
+//   flags — compile-time booleans mirroring the GLSL defines
+
+import {
+  clamp,
+  cross,
+  dFdx,
+  dFdy,
+  dot,
+  Fn,
+  inverseSqrt,
+  max,
+  mix,
+  normalize,
+  select,
+  vec2,
+  vec3,
+} from 'three/tsl';
+
+export function createMaterialMapChunk({ u, tex, v, flags }) {
+  const sampleMaterialNormalMapColor = () => {
+    if (!flags.hasNormalMap) return vec3(0.5, 0.5, 1.0);
+    return select(u.hasMaterialNormalMap, tex.materialNormalMap.sample(v.vUv).rgb, vec3(0.5, 0.5, 1.0));
+  };
+
+  // Pure dataflow (no Fn wrapper, no toVar) — see the select() purity note in
+  // character-lighting.js.
+  const applyMaterialNormalMap = (N) => {
+    if (!flags.hasNormalMap) return N;
+    const raw = sampleMaterialNormalMapColor().mul(2.0).sub(1.0);
+    const scaledXY = raw.xy.mul(u.materialNormalScale.mul(u.materialNormalStrength));
+    const mapN = normalize(vec3(scaledXY, raw.z));
+
+    // cotangentFrame(N, vViewPos.xyz, vUv), written out inline.
+    const p = v.vViewPos.xyz;
+    const dp1 = dFdx(p);
+    const dp2 = dFdy(p);
+    const duv1 = dFdx(v.vUv);
+    const duv2 = dFdy(v.vUv);
+    const dp2perp = cross(dp2, N);
+    const dp1perp = cross(N, dp1);
+    const T = dp2perp.mul(duv1.x).add(dp1perp.mul(duv2.x));
+    const B = dp2perp.mul(duv1.y).add(dp1perp.mul(duv2.y));
+    const invMax = inverseSqrt(max(max(dot(T, T), dot(B, B)), 1.0e-6));
+    // mat3(T*invMax, B*invMax, N) * mapN, expanded column-wise.
+    const perturbed = normalize(
+      T.mul(invMax).mul(mapN.x)
+        .add(B.mul(invMax).mul(mapN.y))
+        .add(N.mul(mapN.z)),
+    );
+    const blended = normalize(mix(N, perturbed, clamp(u.materialNormalStrength, 0.0, 1.0)));
+    return select(u.useMaterialNormalMap, blended, N);
+  };
+
+  const sampleMaterialAo = () => {
+    if (!flags.hasAoMap) return null; // caller substitutes 1.0
+    return select(u.hasMaterialAoMap, clamp(tex.materialAoMap.sample(v.vUv2).r, 0.0, 1.0), 1.0);
+  };
+
+  const sampleMaterialDetail = () => {
+    if (!flags.hasDetailMap) return vec3(0.5);
+    return select(
+      u.hasMaterialDetailMap,
+      tex.materialDetailMap.sample(v.vUv.mul(u.materialDetailRepeat)).rgb,
+      vec3(0.5),
+    );
+  };
+
+  const applyMaterialDetail = (albedo) => {
+    if (!flags.hasDetailMap) return albedo;
+    const detail = sampleMaterialDetail().mul(2.0);
+    const applied = albedo.mul(mix(vec3(1.0), detail, clamp(u.materialDetailStrength, 0.0, 1.0)));
+    const active = u.hasMaterialDetailMap.and(u.materialDetailStrength.greaterThan(0.0));
+    return select(active, applied, albedo);
+  };
+
+  const sampleMaterialEmissive = () => {
+    if (!flags.hasEmissiveMap) return u.materialEmissiveColor;
+    const texel = select(u.hasMaterialEmissiveMap, tex.materialEmissiveMap.sample(v.vUv).rgb, vec3(1.0));
+    return texel.mul(u.materialEmissiveColor);
+  };
+
+  const sampleMaterialMatcap = (N) => {
+    if (!flags.hasMatcapMap) return vec3(0.0);
+    const matcapUv = N.xy.mul(0.5).add(0.5);
+    return select(u.hasMaterialMatcapMap, tex.materialMatcapMap.sample(vec2(matcapUv)).rgb, vec3(0.0));
+  };
+
+  const sampleMaterialRamp = (shadeArea) => {
+    if (!flags.hasRampMap) return vec3(1.0);
+    return select(
+      u.hasMaterialRampMap,
+      tex.materialRampMap.sample(vec2(clamp(shadeArea, 0.0, 1.0), 0.5)).rgb,
+      vec3(1.0),
+    );
+  };
+
+  const sampleMaterialRoughness = () => {
+    if (!flags.hasRoughnessMap) return clamp(u.materialRoughness, 0.0, 1.0);
+    return select(
+      u.hasMaterialRoughnessMap,
+      clamp(tex.materialRoughnessMap.sample(v.vUv).g, 0.0, 1.0),
+      clamp(u.materialRoughness, 0.0, 1.0),
+    );
+  };
+
+  const sampleMaterialMetalness = () => {
+    if (!flags.hasMetalnessMap) return clamp(u.materialMetalness, 0.0, 1.0);
+    return select(
+      u.hasMaterialMetalnessMap,
+      clamp(tex.materialMetalnessMap.sample(v.vUv).b, 0.0, 1.0),
+      clamp(u.materialMetalness, 0.0, 1.0),
+    );
+  };
+
+  const sampleMaterialSpecularColor = () => {
+    if (!flags.hasSpecularColorMap) return vec3(1.0);
+    return select(u.hasMaterialSpecularColorMap, tex.materialSpecularColorMap.sample(v.vUv).rgb, vec3(1.0));
+  };
+
+  return {
+    applyMaterialDetail,
+    applyMaterialNormalMap,
+    sampleMaterialAo,
+    sampleMaterialDetail,
+    sampleMaterialEmissive,
+    sampleMaterialMatcap,
+    sampleMaterialMetalness,
+    sampleMaterialNormalMapColor,
+    sampleMaterialRamp,
+    sampleMaterialRoughness,
+    sampleMaterialSpecularColor,
+  };
+}