@call-me-sensei/toonlab 0.1.1

package/src/toon/settings/eyeHighlightSettings.js

@@ -0,0 +1,187 @@
+import * as THREE from 'three';
+
+export const DEFAULT_EYE_HIGHLIGHT_SETTINGS = Object.freeze({
+  color: [1, 1, 1],
+  enabled: true,
+  intensity: 0.58,
+  maskChannel: 0,
+  maskMap: null,
+  maskStrength: 1,
+  power: 22,
+  showInShadowArea: 0.4,
+  sourceMaskMode: 'off',
+});
+
+export const EYE_HIGHLIGHT_MASK_CHANNELS = Object.freeze({
+  r: 0,
+  red: 0,
+  x: 0,
+  g: 1,
+  green: 1,
+  y: 1,
+  b: 2,
+  blue: 2,
+  z: 2,
+  a: 3,
+  alpha: 3,
+  w: 3,
+});
+
+export const EYE_HIGHLIGHT_SOURCE_MASK_MODES = Object.freeze({
+  off: 'off',
+  source: 'source',
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function colorOption(value, fallback = DEFAULT_EYE_HIGHLIGHT_SETTINGS.color) {
+  if (value?.isColor) return value.clone();
+
+  if (Array.isArray(value) && value.length >= 3) {
+    return new THREE.Color(
+      numberOption(value[0], fallback[0] ?? fallback.r ?? 1),
+      numberOption(value[1], fallback[1] ?? fallback.g ?? 1),
+      numberOption(value[2], fallback[2] ?? fallback.b ?? 1),
+    );
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return new THREE.Color(
+      numberOption(value.r ?? value.x, fallback[0] ?? fallback.r ?? 1),
+      numberOption(value.g ?? value.y, fallback[1] ?? fallback.g ?? 1),
+      numberOption(value.b ?? value.z, fallback[2] ?? fallback.b ?? 1),
+    );
+  }
+
+  if (typeof value === 'string' || typeof value === 'number') {
+    try {
+      return new THREE.Color(value);
+    } catch {
+      // Fall through to fallback.
+    }
+  }
+
+  return Array.isArray(fallback)
+    ? new THREE.Color(fallback[0], fallback[1], fallback[2])
+    : fallback.clone();
+}
+
+function enabledOption(value) {
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    return normalized !== 'off' && normalized !== 'none' && normalized !== 'false' && normalized !== '0';
+  }
+  return value !== false;
+}
+
+function normalizeEyeHighlightOptions(options) {
+  if (options === false) return { enabled: false };
+  if (options === true) return { enabled: true };
+  if (typeof options === 'string') return { enabled: enabledOption(options) };
+  return options || {};
+}
+
+function normalizeMaskChannel(value, fallback = DEFAULT_EYE_HIGHLIGHT_SETTINGS.maskChannel) {
+  if (Number.isFinite(value)) return Math.min(3, Math.max(0, Math.round(value)));
+  const normalized = String(value ?? '').trim().toLowerCase();
+  return EYE_HIGHLIGHT_MASK_CHANNELS[normalized] ?? fallback;
+}
+
+function normalizeSourceMaskMode(value, fallback = DEFAULT_EYE_HIGHLIGHT_SETTINGS.sourceMaskMode) {
+  if (value === true) return EYE_HIGHLIGHT_SOURCE_MASK_MODES.source;
+  if (value === false) return EYE_HIGHLIGHT_SOURCE_MASK_MODES.off;
+  const normalized = String(value ?? fallback).trim().toLowerCase();
+  if (normalized === 'material' || normalized === 'map' || normalized === 'source') {
+    return EYE_HIGHLIGHT_SOURCE_MASK_MODES.source;
+  }
+  return EYE_HIGHLIGHT_SOURCE_MASK_MODES.off;
+}
+
+export function createEyeHighlightSettings(options = null) {
+  const source = normalizeEyeHighlightOptions(options);
+  const enabled = enabledOption(source.enabled);
+
+  return {
+    color: colorOption(
+      firstDefined(source, ['color', 'eyeHighlightColor', 'highlightColor', 'glossColor']),
+      DEFAULT_EYE_HIGHLIGHT_SETTINGS.color,
+    ),
+    enabled,
+    intensity: enabled
+      ? numberOption(
+        firstDefined(source, ['intensity', 'eyeHighlightIntensity', 'highlightIntensity', 'glossIntensity']),
+        DEFAULT_EYE_HIGHLIGHT_SETTINGS.intensity,
+        { min: 0, max: 8 },
+      )
+      : 0,
+    maskChannel: normalizeMaskChannel(firstDefined(source, ['maskChannel', 'eyeHighlightMaskChannel'])),
+    maskMap: firstDefined(source, ['maskMap', 'eyeHighlightMaskMap', 'catchlightMaskMap']) ??
+      DEFAULT_EYE_HIGHLIGHT_SETTINGS.maskMap,
+    maskStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['maskStrength', 'eyeHighlightMaskStrength', 'catchlightMaskStrength']),
+        DEFAULT_EYE_HIGHLIGHT_SETTINGS.maskStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    power: enabled
+      ? numberOption(
+        firstDefined(source, ['power', 'eyeHighlightPower', 'highlightPower', 'glossPower', 'shininess']),
+        DEFAULT_EYE_HIGHLIGHT_SETTINGS.power,
+        { min: 1, max: 512 },
+      )
+      : DEFAULT_EYE_HIGHLIGHT_SETTINGS.power,
+    showInShadowArea: enabled
+      ? numberOption(
+        firstDefined(source, [
+          'showInShadowArea',
+          'eyeHighlightShowInShadowArea',
+          'shadowBlend',
+          'shadowLift',
+          'shadowIndependence',
+        ]),
+        DEFAULT_EYE_HIGHLIGHT_SETTINGS.showInShadowArea,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    sourceMaskMode: normalizeSourceMaskMode(
+      firstDefined(source, [
+        'sourceMaskMode',
+        'sourceMask',
+        'useSourceMask',
+        'useSourceEyeHighlightMask',
+        'useSourceCatchlightMask',
+      ]),
+    ),
+  };
+}
+
+export function resolveEyeHighlightForMaterial(settings, {
+  isEye = false,
+  isOutline = false,
+  maskMap = null,
+} = {}) {
+  const resolvedMaskMap = settings.maskMap ?? maskMap;
+  return {
+    color: settings.color,
+    enabled: settings.enabled && isEye && !isOutline && settings.intensity > 0,
+    intensity: settings.intensity,
+    maskChannel: settings.maskChannel,
+    maskMap: resolvedMaskMap,
+    maskStrength: settings.maskStrength,
+    power: settings.power,
+    showInShadowArea: settings.showInShadowArea,
+    useMask: Boolean(resolvedMaskMap) && settings.maskStrength > 0,
+  };
+}

package/src/toon/settings/faceLightingSettings.js

@@ -0,0 +1,135 @@
+export const FACE_HEAD_SPACE_MODES = Object.freeze({
+  static: 'static',
+  headBone: 'headBone',
+});
+
+export const FACE_HEAD_SPACE_MODE_VALUES = Object.freeze({
+  [FACE_HEAD_SPACE_MODES.static]: 0,
+  [FACE_HEAD_SPACE_MODES.headBone]: 1,
+});
+
+export const DEFAULT_FACE_LIGHTING_SETTINGS = Object.freeze({
+  enabled: true,
+  faceCelMidPoint: -0.48,
+  faceCelSoftness: 0.22,
+  faceLocalLightLift: 0.22,
+  faceMainLightIgnoreCelShade: 0.45,
+  // How strongly the face lighting normal is replaced by the corrected face
+  // normal. In headBone mode this only activates when the runtime head tracker
+  // provides live head-bone data, so it is inert for plain applyToonShader use.
+  faceNormalProxyBlend: 0.75,
+  faceProxyNormal: [0, 0, 1],
+  faceSceneShadowStrength: 0.5,
+  // Blend between the flattened head-forward normal (0) and a proxy sphere
+  // around the head bone (1). The mix keeps the lit-to-shadow terminator
+  // sweeping smoothly across the face while preserving some roundness.
+  faceSphereBlend: 0.75,
+  headSpaceMode: FACE_HEAD_SPACE_MODES.headBone,
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function vectorOption(value, fallback) {
+  if (Array.isArray(value) && value.length >= 3) {
+    return [
+      numberOption(value[0], fallback[0]),
+      numberOption(value[1], fallback[1]),
+      numberOption(value[2], fallback[2]),
+    ];
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return [
+      numberOption(value.x ?? value.r, fallback[0]),
+      numberOption(value.y ?? value.g, fallback[1]),
+      numberOption(value.z ?? value.b, fallback[2]),
+    ];
+  }
+
+  return [...fallback];
+}
+
+function headSpaceModeOption(value, fallback) {
+  const key = String(value ?? '')
+    .trim()
+    .replace(/[\s_-]+/g, '')
+    .toLowerCase();
+  if (['headbone', 'head', 'dynamic', 'tracked'].includes(key)) return FACE_HEAD_SPACE_MODES.headBone;
+  if (['static', 'fixed', 'object', 'legacy'].includes(key)) return FACE_HEAD_SPACE_MODES.static;
+  return fallback;
+}
+
+export function createFaceLightingSettings(options = null) {
+  const source = options || {};
+  const enabled = source.enabled !== false;
+
+  return {
+    enabled,
+    faceCelMidPoint: enabled
+      ? numberOption(
+        firstDefined(source, ['faceCelMidPoint', 'faceCelThreshold', 'celMidPoint']),
+        DEFAULT_FACE_LIGHTING_SETTINGS.faceCelMidPoint,
+        { min: -1, max: 1 },
+      )
+      : DEFAULT_FACE_LIGHTING_SETTINGS.faceCelMidPoint,
+    faceCelSoftness: enabled
+      ? numberOption(
+        firstDefined(source, ['faceCelSoftness', 'faceCelFeather', 'celSoftness']),
+        DEFAULT_FACE_LIGHTING_SETTINGS.faceCelSoftness,
+        { min: 0.001, max: 1 },
+      )
+      : DEFAULT_FACE_LIGHTING_SETTINGS.faceCelSoftness,
+    faceLocalLightLift: enabled
+      ? numberOption(
+        firstDefined(source, ['faceLocalLightLift', 'faceLocalLightWrap', 'localLightLift']),
+        DEFAULT_FACE_LIGHTING_SETTINGS.faceLocalLightLift,
+        { min: 0, max: 1 },
+      )
+      : DEFAULT_FACE_LIGHTING_SETTINGS.faceLocalLightLift,
+    faceMainLightIgnoreCelShade: enabled
+      ? numberOption(
+        firstDefined(source, ['faceMainLightIgnoreCelShade', 'faceLightIgnoreCelShade', 'mainLightIgnoreCelShade']),
+        DEFAULT_FACE_LIGHTING_SETTINGS.faceMainLightIgnoreCelShade,
+        { min: 0, max: 1 },
+      )
+      : DEFAULT_FACE_LIGHTING_SETTINGS.faceMainLightIgnoreCelShade,
+    faceNormalProxyBlend: enabled
+      ? numberOption(
+        firstDefined(source, ['faceNormalProxyBlend', 'faceProxyBlend', 'proxyNormalBlend']),
+        DEFAULT_FACE_LIGHTING_SETTINGS.faceNormalProxyBlend,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    faceProxyNormal: vectorOption(
+      firstDefined(source, ['faceProxyNormal', 'faceNormalProxy', 'proxyNormal']),
+      DEFAULT_FACE_LIGHTING_SETTINGS.faceProxyNormal,
+    ),
+    faceSceneShadowStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['faceSceneShadowStrength', 'faceReceivedShadowStrength', 'sceneShadowStrength']),
+        DEFAULT_FACE_LIGHTING_SETTINGS.faceSceneShadowStrength,
+        { min: 0, max: 1 },
+      )
+      : DEFAULT_FACE_LIGHTING_SETTINGS.faceSceneShadowStrength,
+    faceSphereBlend: numberOption(
+      firstDefined(source, ['faceSphereBlend', 'sphereBlend', 'proxySphereBlend']),
+      DEFAULT_FACE_LIGHTING_SETTINGS.faceSphereBlend,
+      { min: 0, max: 1 },
+    ),
+    headSpaceMode: headSpaceModeOption(
+      firstDefined(source, ['headSpaceMode', 'faceShadingMode']),
+      DEFAULT_FACE_LIGHTING_SETTINGS.headSpaceMode,
+    ),
+  };
+}

package/src/toon/settings/furSettings.js

@@ -0,0 +1,112 @@
+// Shell fur.
+//
+// Renders N progressively-offset copies ("shells") of a mesh; each shell
+// discards fragments by a procedural noise threshold that tightens toward the
+// tip, so the surviving pixels read as fur strands. Fully procedural (no
+// noise texture, no extra samplers), cutout-based (depth-writes, so it sorts
+// correctly against outlines and transparents).
+//
+// Fur is strictly opt-in per material — a fuzzy collar should not make the
+// whole costume shaggy:
+//   - fur.materials: array of material name/uuid/regex patterns
+//   - fur.roles: array of material roles (e.g. ['costume'])
+//   - material.userData.toonFur = true
+//
+// Shells here are mesh clones since WebGL has no geometry shaders.
+
+export const DEFAULT_FUR_SETTINGS = Object.freeze({
+  enabled: false,
+  // Number of shell layers. Cost scales linearly (each shell re-renders the
+  // matched mesh), so keep modest; 8-12 reads well at toon scale.
+  shellCount: 8,
+  // World-space fur length at the outermost shell.
+  length: 0.02,
+  // 0 = fur sticks straight out; 1 = tips sag fully toward world-down.
+  gravity: 0.35,
+  // Strand density (noise cells per UV unit, scaled x100 internally).
+  density: 3,
+  // Shifts the discard threshold toward the roots; more negative = fuller coat.
+  rootOffset: -0.2,
+  // Darkens fur roots for cheap self-occlusion depth.
+  rootShade: 0.55,
+  materials: null,
+  roles: null,
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function patternListOption(value) {
+  if (!value) return null;
+  const list = Array.isArray(value) ? value : [value];
+  const normalized = list.filter((entry) => entry instanceof RegExp || (typeof entry === 'string' && entry.trim() !== ''));
+  return normalized.length > 0 ? normalized : null;
+}
+
+function roleListOption(value) {
+  if (!value) return null;
+  const list = (Array.isArray(value) ? value : [value])
+    .map((entry) => String(entry ?? '').trim().toLowerCase())
+    .filter(Boolean);
+  return list.length > 0 ? list : null;
+}
+
+function normalizeFurOptions(options) {
+  if (options === false) return { enabled: false };
+  if (options === true) return { enabled: true };
+  return options || {};
+}
+
+export function createFurSettings(options = null) {
+  const source = normalizeFurOptions(options);
+  const enabled = source.enabled === true ||
+    (source.enabled !== false && (Boolean(source.materials) || Boolean(source.roles)));
+
+  return {
+    density: numberOption(firstDefined(source, ['density']), DEFAULT_FUR_SETTINGS.density, { min: 0.1, max: 40 }),
+    enabled,
+    gravity: numberOption(firstDefined(source, ['gravity']), DEFAULT_FUR_SETTINGS.gravity, { min: 0, max: 1 }),
+    length: numberOption(firstDefined(source, ['length', 'furLength']), DEFAULT_FUR_SETTINGS.length, { min: 0, max: 1 }),
+    materials: patternListOption(firstDefined(source, ['materials', 'materialPatterns'])),
+    roles: roleListOption(firstDefined(source, ['roles', 'materialRoles'])),
+    rootOffset: numberOption(firstDefined(source, ['rootOffset']), DEFAULT_FUR_SETTINGS.rootOffset, { min: -1, max: 0 }),
+    rootShade: numberOption(firstDefined(source, ['rootShade', 'rootDarkening']), DEFAULT_FUR_SETTINGS.rootShade, { min: 0, max: 1 }),
+    shellCount: Math.round(numberOption(firstDefined(source, ['shellCount', 'shells', 'layers']), DEFAULT_FUR_SETTINGS.shellCount, { min: 1, max: 32 })),
+  };
+}
+
+function matchesPattern(patterns, name, uuid) {
+  if (!patterns) return false;
+  for (const pattern of patterns) {
+    if (pattern instanceof RegExp) {
+      if (pattern.test(name)) return true;
+    } else if (pattern === name || pattern === uuid) {
+      return true;
+    } else {
+      try {
+        if (new RegExp(pattern, 'i').test(name)) return true;
+      } catch {
+        // Invalid pattern strings fall through to exact-match behavior above.
+      }
+    }
+  }
+  return false;
+}
+
+export function materialUsesFur(settings, sourceMaterial, roleInfo = null) {
+  if (!settings?.enabled) return false;
+  if (sourceMaterial?.userData?.toonFur === true) return true;
+  const role = String(roleInfo?.role ?? '').toLowerCase();
+  if (settings.roles?.includes(role)) return true;
+  return matchesPattern(settings.materials, sourceMaterial?.name ?? '', sourceMaterial?.uuid ?? '');
+}

package/src/toon/settings/glitterSettings.js

@@ -0,0 +1,102 @@
+// Procedural glitter sparkles.
+//
+// Splits UV space into cells, gives each cell one particle with a random
+// orientation, and lights it with a tight reflection lobe — sparkles wink in
+// and out as the view or light moves. Entirely ALU (no textures), but the 3x3
+// neighbor loop is not free, so the whole path compiles out unless enabled.
+
+export const DEFAULT_GLITTER_SETTINGS = Object.freeze({
+  enabled: false,
+  intensity: 1,
+  // Cells per UV unit (scaled x1000 internally like typical glitter shaders).
+  density: 1,
+  size: 1,
+  // 0 = particles aligned to the surface, 1 = fully random orientation.
+  randomNormalStrength: 0.5,
+  // How much glitter survives inside the cel shadow band.
+  showInShadowArea: 0.15,
+  // UV channel: 0 = uv, 1 = uv2 (unique/non-overlapping UVs sparkle best).
+  uvChannel: 1,
+  // Role gates: sparkly costumes are the normal use; organic parts stay clean.
+  defaultIntensity: 1,
+  eyeIntensity: 0,
+  faceIntensity: 0,
+  hairIntensity: 0,
+  skinIntensity: 0,
+});
+
+function firstDefined(source, keys) {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) return source[key];
+  }
+  return undefined;
+}
+
+function numberOption(value, fallback, { min = -Infinity, max = Infinity } = {}) {
+  const nextValue = Number(value);
+  if (!Number.isFinite(nextValue)) return fallback;
+  return Math.min(max, Math.max(min, nextValue));
+}
+
+function normalizeGlitterOptions(options) {
+  if (options === false) return { enabled: false };
+  if (options === true) return { enabled: true };
+  if (typeof options === 'string') {
+    const key = options.trim().toLowerCase();
+    return { enabled: key !== 'off' && key !== 'none' && key !== 'false' && key !== '0' };
+  }
+  return options || {};
+}
+
+export function createGlitterSettings(options = null) {
+  const source = normalizeGlitterOptions(options);
+  const enabled = source.enabled === true;
+
+  return {
+    enabled,
+    intensity: numberOption(firstDefined(source, ['intensity', 'brightness']), DEFAULT_GLITTER_SETTINGS.intensity, { min: 0, max: 8 }),
+    density: numberOption(firstDefined(source, ['density']), DEFAULT_GLITTER_SETTINGS.density, { min: 0.01, max: 8 }),
+    size: numberOption(firstDefined(source, ['size', 'particleSize']), DEFAULT_GLITTER_SETTINGS.size, { min: 0.05, max: 4 }),
+    randomNormalStrength: numberOption(
+      firstDefined(source, ['randomNormalStrength', 'randomness']),
+      DEFAULT_GLITTER_SETTINGS.randomNormalStrength,
+      { min: 0, max: 1 },
+    ),
+    showInShadowArea: numberOption(
+      firstDefined(source, ['showInShadowArea', 'shadowVisibility']),
+      DEFAULT_GLITTER_SETTINGS.showInShadowArea,
+      { min: 0, max: 1 },
+    ),
+    uvChannel: numberOption(firstDefined(source, ['uvChannel']), DEFAULT_GLITTER_SETTINGS.uvChannel, { min: 0, max: 1 }) >= 0.5 ? 1 : 0,
+    defaultIntensity: numberOption(firstDefined(source, ['defaultIntensity']), DEFAULT_GLITTER_SETTINGS.defaultIntensity, { min: 0, max: 8 }),
+    eyeIntensity: numberOption(firstDefined(source, ['eyeIntensity']), DEFAULT_GLITTER_SETTINGS.eyeIntensity, { min: 0, max: 8 }),
+    faceIntensity: numberOption(firstDefined(source, ['faceIntensity']), DEFAULT_GLITTER_SETTINGS.faceIntensity, { min: 0, max: 8 }),
+    hairIntensity: numberOption(firstDefined(source, ['hairIntensity']), DEFAULT_GLITTER_SETTINGS.hairIntensity, { min: 0, max: 8 }),
+    skinIntensity: numberOption(firstDefined(source, ['skinIntensity']), DEFAULT_GLITTER_SETTINGS.skinIntensity, { min: 0, max: 8 }),
+  };
+}
+
+export function resolveGlitterForMaterial(settings, {
+  isEye = false,
+  isFace = false,
+  isHair = false,
+  isOutline = false,
+  isSkin = false,
+} = {}) {
+  let roleIntensity = settings.defaultIntensity;
+  if (isEye) roleIntensity = settings.eyeIntensity;
+  else if (isFace) roleIntensity = settings.faceIntensity;
+  else if (isSkin) roleIntensity = settings.skinIntensity;
+  else if (isHair) roleIntensity = settings.hairIntensity;
+
+  const intensity = settings.intensity * roleIntensity;
+  return {
+    density: settings.density,
+    enabled: settings.enabled && !isOutline && intensity > 0,
+    intensity,
+    randomNormalStrength: settings.randomNormalStrength,
+    showInShadowArea: settings.showInShadowArea,
+    size: settings.size,
+    uvChannel: settings.uvChannel,
+  };
+}