@call-me-sensei/toonlab 0.1.1

package/src/toon/settings/skinToneSettings.js

@@ -0,0 +1,150 @@
+import * as THREE from 'three';
+
+export const DEFAULT_SKIN_TONE_SETTINGS = Object.freeze({
+  enabled: true,
+  faceMaxDirectLight: 100,
+  faceMinimumIndirectLight: 0.35,
+  faceShadowBrightness: 1.0,
+  faceShadowSaturation: 1.0,
+  faceShadowTint: [1.0, 0.92, 0.9],
+  faceShadowTintStrength: 1.0,
+  skinMaxDirectLight: 100,
+  skinMinimumIndirectLight: 0.35,
+  skinShadowBrightness: 0.92,
+  skinShadowSaturation: 1.0,
+  skinShadowTint: [1.0, 0.76, 0.74],
+  skinShadowTintStrength: 1.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 THREE.MathUtils.clamp(nextValue, min, max);
+}
+
+function colorOption(value, fallback) {
+  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) {
+    const r = numberOption(value.r, fallback[0] ?? fallback.r ?? 1);
+    const g = numberOption(value.g, fallback[1] ?? fallback.g ?? 1);
+    const b = numberOption(value.b, fallback[2] ?? fallback.b ?? 1);
+    return new THREE.Color(r, g, b);
+  }
+
+  if (typeof value === 'string' || typeof value === 'number') {
+    try {
+      return new THREE.Color(value);
+    } catch {
+      // Fall through to the normalized fallback below.
+    }
+  }
+
+  return Array.isArray(fallback)
+    ? new THREE.Color(fallback[0], fallback[1], fallback[2])
+    : fallback.clone();
+}
+
+export function createSkinToneSettings(options = null) {
+  const source = options || {};
+  const enabled = source.enabled !== false;
+  const skinShadowTintStrength = enabled
+    ? numberOption(
+      firstDefined(source, ['skinShadowTintStrength', 'skinShadowStrength', 'skinTintStrength']),
+      DEFAULT_SKIN_TONE_SETTINGS.skinShadowTintStrength,
+      { min: 0, max: 1 },
+    )
+    : 0;
+  const faceShadowTintStrength = enabled
+    ? numberOption(
+      firstDefined(source, ['faceShadowTintStrength', 'faceShadowStrength', 'faceTintStrength']),
+      DEFAULT_SKIN_TONE_SETTINGS.faceShadowTintStrength,
+      { min: 0, max: 1 },
+    )
+    : 0;
+
+  return {
+    enabled,
+    faceMaxDirectLight: enabled
+      ? numberOption(
+        firstDefined(source, ['faceMaxDirectLight', 'faceDirectLightMax', 'maxFaceDirectLight']),
+        DEFAULT_SKIN_TONE_SETTINGS.faceMaxDirectLight,
+        { min: 0.05, max: 100 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.faceMaxDirectLight,
+    faceMinimumIndirectLight: enabled
+      ? numberOption(
+        firstDefined(source, ['faceMinimumIndirectLight', 'faceMinIndirectLight', 'faceIndirectLightMin']),
+        DEFAULT_SKIN_TONE_SETTINGS.faceMinimumIndirectLight,
+        { min: 0, max: 1 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.faceMinimumIndirectLight,
+    faceShadowBrightness: enabled
+      ? numberOption(
+        firstDefined(source, ['faceShadowBrightness', 'faceShadowValue', 'faceShadowLightness']),
+        DEFAULT_SKIN_TONE_SETTINGS.faceShadowBrightness,
+        { min: 0, max: 4 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.faceShadowBrightness,
+    faceShadowSaturation: enabled
+      ? numberOption(
+        firstDefined(source, ['faceShadowSaturation', 'faceShadowSat', 'shadowSaturation']),
+        DEFAULT_SKIN_TONE_SETTINGS.faceShadowSaturation,
+        { min: 0, max: 4 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.faceShadowSaturation,
+    faceShadowTint: colorOption(
+      firstDefined(source, ['faceShadowTint', 'faceShadowColor', 'faceTint']),
+      DEFAULT_SKIN_TONE_SETTINGS.faceShadowTint,
+    ),
+    faceShadowTintStrength,
+    skinMaxDirectLight: enabled
+      ? numberOption(
+        firstDefined(source, ['skinMaxDirectLight', 'skinDirectLightMax', 'maxSkinDirectLight']),
+        DEFAULT_SKIN_TONE_SETTINGS.skinMaxDirectLight,
+        { min: 0.05, max: 100 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.skinMaxDirectLight,
+    skinMinimumIndirectLight: enabled
+      ? numberOption(
+        firstDefined(source, ['skinMinimumIndirectLight', 'skinMinIndirectLight', 'skinIndirectLightMin']),
+        DEFAULT_SKIN_TONE_SETTINGS.skinMinimumIndirectLight,
+        { min: 0, max: 1 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.skinMinimumIndirectLight,
+    skinShadowBrightness: enabled
+      ? numberOption(
+        firstDefined(source, ['skinShadowBrightness', 'skinShadowValue', 'skinShadowLightness']),
+        DEFAULT_SKIN_TONE_SETTINGS.skinShadowBrightness,
+        { min: 0, max: 4 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.skinShadowBrightness,
+    skinShadowSaturation: enabled
+      ? numberOption(
+        firstDefined(source, ['skinShadowSaturation', 'skinShadowSat', 'shadowSaturation']),
+        DEFAULT_SKIN_TONE_SETTINGS.skinShadowSaturation,
+        { min: 0, max: 4 },
+      )
+      : DEFAULT_SKIN_TONE_SETTINGS.skinShadowSaturation,
+    skinShadowTint: colorOption(
+      firstDefined(source, ['skinShadowTint', 'skinShadowColor', 'skinTint']),
+      DEFAULT_SKIN_TONE_SETTINGS.skinShadowTint,
+    ),
+    skinShadowTintStrength,
+  };
+}

package/src/toon/settings/specularSettings.js

@@ -0,0 +1,314 @@
+import * as THREE from 'three';
+
+export const SPECULAR_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 SPECULAR_SOURCE_MASK_MODES = Object.freeze({
+  off: 'off',
+  source: 'source',
+});
+
+// 'light': classic Blinn-style highlight from the half vector (moves with the
+//          light). 'view': uses the view angle instead, so the highlight stays
+//          anchored to the surface as lights animate — a stable, matcap-like
+//          response that suits eyes and metal trim.
+export const SPECULAR_DIRECTION_MODES = Object.freeze({
+  light: 'light',
+  view: 'view',
+});
+
+export const SPECULAR_DIRECTION_MODE_VALUES = Object.freeze({
+  [SPECULAR_DIRECTION_MODES.light]: 0,
+  [SPECULAR_DIRECTION_MODES.view]: 1,
+});
+
+export const DEFAULT_SPECULAR_SETTINGS = Object.freeze({
+  defaultColor: [1, 0.96, 0.9],
+  defaultIntensity: 0.075,
+  defaultMidPoint: 0.72,
+  defaultPower: 56,
+  defaultRange: 0.12,
+  defaultShowInShadowArea: 0.25,
+  directionMode: SPECULAR_DIRECTION_MODES.light,
+  enabled: true,
+  eyeIntensity: 0.62,
+  eyeMidPoint: 0.35,
+  eyePower: 18,
+  eyeRange: 0.18,
+  eyeShowInShadowArea: 1,
+  faceIntensity: 0.025,
+  hairIntensity: 0.18,
+  hairPower: 40,
+  maskChannel: SPECULAR_MASK_CHANNELS.r,
+  maskMap: null,
+  maskStrength: 1,
+  metalIntensity: 0.075,
+  skinIntensity: 0.025,
+  sourceMaskMode: SPECULAR_SOURCE_MASK_MODES.off,
+});
+
+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) {
+  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 normalizeSpecularOptions(options) {
+  if (options === false) return { enabled: false };
+  if (options === true) return { enabled: true };
+  if (typeof options === 'string') return { enabled: enabledOption(options) };
+  return options || {};
+}
+
+function normalizeSourceMaskMode(value) {
+  if (value === true) return SPECULAR_SOURCE_MASK_MODES.source;
+  if (value === false) return SPECULAR_SOURCE_MASK_MODES.off;
+  const normalized = String(value ?? SPECULAR_SOURCE_MASK_MODES.off).trim().toLowerCase();
+  if (normalized === 'material' || normalized === 'map' || normalized === 'source') {
+    return SPECULAR_SOURCE_MASK_MODES.source;
+  }
+  return SPECULAR_SOURCE_MASK_MODES.off;
+}
+
+function normalizeMaskChannel(value) {
+  if (Number.isFinite(value)) return Math.min(3, Math.max(0, Math.round(value)));
+  const normalized = String(value ?? '').trim().toLowerCase();
+  return SPECULAR_MASK_CHANNELS[normalized] ?? DEFAULT_SPECULAR_SETTINGS.maskChannel;
+}
+
+function roleNumber(source, role, property, fallback, aliases = [], bounds = {}) {
+  const rolePrefix = role ? `${role}${property[0].toUpperCase()}${property.slice(1)}` : property;
+  return numberOption(firstDefined(source, [rolePrefix, ...aliases]), fallback, bounds);
+}
+
+function normalizeDirectionMode(value) {
+  const key = String(value ?? '')
+    .trim()
+    .replace(/[\s_-]+/g, '')
+    .toLowerCase();
+  if (['view', 'nov', 'stable', 'matcaplike', 'lv', 'lequalsv'].includes(key)) {
+    return SPECULAR_DIRECTION_MODES.view;
+  }
+  return SPECULAR_DIRECTION_MODES.light;
+}
+
+export function createSpecularSettings(options = null) {
+  const source = normalizeSpecularOptions(options);
+  const enabled = enabledOption(source.enabled);
+  const defaultIntensity = enabled
+    ? roleNumber(
+      source,
+      'default',
+      'intensity',
+      DEFAULT_SPECULAR_SETTINGS.defaultIntensity,
+      ['intensity', 'specularIntensity'],
+      { min: 0, max: 8 },
+    )
+    : 0;
+  const defaultMidPoint = enabled
+    ? roleNumber(
+      source,
+      'default',
+      'midPoint',
+      DEFAULT_SPECULAR_SETTINGS.defaultMidPoint,
+      ['midPoint', 'specularMidPoint', 'specularAreaRemapMidPoint'],
+      { min: 0, max: 1 },
+    )
+    : DEFAULT_SPECULAR_SETTINGS.defaultMidPoint;
+  const defaultRange = enabled
+    ? roleNumber(
+      source,
+      'default',
+      'range',
+      DEFAULT_SPECULAR_SETTINGS.defaultRange,
+      ['range', 'specularRange', 'specularAreaRemapRange'],
+      { min: 0.001, max: 1 },
+    )
+    : DEFAULT_SPECULAR_SETTINGS.defaultRange;
+  const defaultPower = enabled
+    ? roleNumber(
+      source,
+      'default',
+      'power',
+      DEFAULT_SPECULAR_SETTINGS.defaultPower,
+      ['power', 'specularPower', 'shininess'],
+      { min: 1, max: 512 },
+    )
+    : DEFAULT_SPECULAR_SETTINGS.defaultPower;
+  const defaultShowInShadowArea = enabled
+    ? roleNumber(
+      source,
+      'default',
+      'showInShadowArea',
+      DEFAULT_SPECULAR_SETTINGS.defaultShowInShadowArea,
+      ['showInShadowArea', 'specularShowInShadowArea', 'shadowVisibility'],
+      { min: 0, max: 1 },
+    )
+    : 0;
+
+  return {
+    defaultColor: colorOption(
+      firstDefined(source, ['color', 'specularColor', 'defaultColor']),
+      DEFAULT_SPECULAR_SETTINGS.defaultColor,
+    ),
+    defaultIntensity,
+    defaultMidPoint,
+    defaultPower,
+    defaultRange,
+    defaultShowInShadowArea,
+    directionMode: normalizeDirectionMode(
+      firstDefined(source, ['directionMode', 'specularMode', 'highlightMode']),
+    ),
+    enabled,
+    eyeIntensity: enabled
+      ? roleNumber(source, 'eye', 'intensity', DEFAULT_SPECULAR_SETTINGS.eyeIntensity, [], { min: 0, max: 8 })
+      : 0,
+    eyeMidPoint: enabled
+      ? roleNumber(source, 'eye', 'midPoint', DEFAULT_SPECULAR_SETTINGS.eyeMidPoint, [], { min: 0, max: 1 })
+      : DEFAULT_SPECULAR_SETTINGS.eyeMidPoint,
+    eyePower: enabled
+      ? roleNumber(source, 'eye', 'power', DEFAULT_SPECULAR_SETTINGS.eyePower, [], { min: 1, max: 512 })
+      : DEFAULT_SPECULAR_SETTINGS.eyePower,
+    eyeRange: enabled
+      ? roleNumber(source, 'eye', 'range', DEFAULT_SPECULAR_SETTINGS.eyeRange, [], { min: 0.001, max: 1 })
+      : DEFAULT_SPECULAR_SETTINGS.eyeRange,
+    eyeShowInShadowArea: enabled
+      ? roleNumber(source, 'eye', 'showInShadowArea', DEFAULT_SPECULAR_SETTINGS.eyeShowInShadowArea, [], { min: 0, max: 1 })
+      : 0,
+    faceIntensity: enabled
+      ? roleNumber(source, 'face', 'intensity', DEFAULT_SPECULAR_SETTINGS.faceIntensity, [], { min: 0, max: 8 })
+      : 0,
+    hairIntensity: enabled
+      ? roleNumber(source, 'hair', 'intensity', DEFAULT_SPECULAR_SETTINGS.hairIntensity, [], { min: 0, max: 8 })
+      : 0,
+    hairPower: enabled
+      ? roleNumber(source, 'hair', 'power', DEFAULT_SPECULAR_SETTINGS.hairPower, [], { min: 1, max: 512 })
+      : DEFAULT_SPECULAR_SETTINGS.hairPower,
+    maskChannel: normalizeMaskChannel(firstDefined(source, ['maskChannel', 'specularMaskChannel'])),
+    maskMap: firstDefined(source, ['maskMap', 'specularMaskMap']) ?? DEFAULT_SPECULAR_SETTINGS.maskMap,
+    maskStrength: enabled
+      ? numberOption(
+        firstDefined(source, ['maskStrength', 'specularMaskStrength']),
+        DEFAULT_SPECULAR_SETTINGS.maskStrength,
+        { min: 0, max: 1 },
+      )
+      : 0,
+    metalIntensity: enabled
+      ? roleNumber(source, 'metal', 'intensity', DEFAULT_SPECULAR_SETTINGS.metalIntensity, [], { min: 0, max: 8 })
+      : 0,
+    skinIntensity: enabled
+      ? roleNumber(source, 'skin', 'intensity', DEFAULT_SPECULAR_SETTINGS.skinIntensity, [], { min: 0, max: 8 })
+      : 0,
+    sourceMaskMode: normalizeSourceMaskMode(
+      firstDefined(source, ['sourceMaskMode', 'sourceMask', 'useSourceMask', 'useSourceSpecularMap']),
+    ),
+  };
+}
+
+export function resolveSpecularForMaterial(settings, {
+  isEye = false,
+  isFace = false,
+  isHair = false,
+  isMetal = false,
+  isOutline = false,
+  isSkin = false,
+  maskMap = null,
+} = {}) {
+  let intensity = settings.defaultIntensity;
+  let midPoint = settings.defaultMidPoint;
+  let power = settings.defaultPower;
+  let range = settings.defaultRange;
+  let showInShadowArea = settings.defaultShowInShadowArea;
+
+  if (isEye) {
+    intensity = settings.eyeIntensity;
+    midPoint = settings.eyeMidPoint;
+    power = settings.eyePower;
+    range = settings.eyeRange;
+    showInShadowArea = settings.eyeShowInShadowArea;
+  } else if (isFace) {
+    intensity = settings.faceIntensity;
+  } else if (isSkin) {
+    intensity = settings.skinIntensity;
+  } else if (isHair) {
+    intensity = settings.hairIntensity;
+    power = settings.hairPower;
+  } else if (isMetal) {
+    intensity = settings.metalIntensity;
+  }
+
+  const resolvedMaskMap = settings.maskMap ?? maskMap;
+  return {
+    color: settings.defaultColor,
+    directionModeValue: SPECULAR_DIRECTION_MODE_VALUES[settings.directionMode] ?? 0,
+    enabled: settings.enabled && !isOutline && intensity > 0,
+    intensity,
+    maskChannel: settings.maskChannel,
+    maskMap: resolvedMaskMap,
+    maskStrength: settings.maskStrength,
+    midPoint,
+    power,
+    range,
+    showInShadowArea,
+    useMask: Boolean(resolvedMaskMap) && settings.maskStrength > 0,
+  };
+}

package/src/toon/settings/stickerSettings.js

@@ -0,0 +1,102 @@
+// Sticker / decal overlay.
+//
+// Blends an overlay texture into the albedo before lighting, so the sticker
+// shades with the same cel bands as the rest of the surface. Covers the
+// "runtime texture overlay" use case (ice, rock, tattoos, damage decals).
+// The sampler is compiled in per material only when a map is present.
+//
+// Map sources, in priority order:
+//   1. settings.map (applies to every matching material)
+//   2. material.userData.toonStickerMap / stickerMap (per-material)
+
+export const STICKER_BLEND_MODES = Object.freeze({
+  normal: 'normal',
+  add: 'add',
+  multiply: 'multiply',
+});
+
+export const STICKER_BLEND_MODE_VALUES = Object.freeze({
+  [STICKER_BLEND_MODES.normal]: 0,
+  [STICKER_BLEND_MODES.add]: 1,
+  [STICKER_BLEND_MODES.multiply]: 2,
+});
+
+export const DEFAULT_STICKER_SETTINGS = Object.freeze({
+  blendMode: STICKER_BLEND_MODES.normal,
+  enabled: false,
+  map: null,
+  offset: [0, 0],
+  repeat: [1, 1],
+  strength: 1,
+  // 0 = uv, 1 = uv2.
+  uvChannel: 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 vector2Option(value, fallback) {
+  if (Array.isArray(value) && value.length >= 2) {
+    return [numberOption(value[0], fallback[0]), numberOption(value[1], fallback[1])];
+  }
+  if (typeof value === 'object' && value !== null) {
+    return [numberOption(value.x, fallback[0]), numberOption(value.y, fallback[1])];
+  }
+  return [...fallback];
+}
+
+function blendModeOption(value, fallback) {
+  const key = String(value ?? '').trim().toLowerCase();
+  if (['add', 'additive', 'screen'].includes(key)) return STICKER_BLEND_MODES.add;
+  if (['multiply', 'mul', 'darken'].includes(key)) return STICKER_BLEND_MODES.multiply;
+  if (['normal', 'blend', 'alpha', 'alphablend'].includes(key)) return STICKER_BLEND_MODES.normal;
+  return fallback;
+}
+
+function normalizeStickerOptions(options) {
+  if (options === false) return { enabled: false };
+  if (options === true) return { enabled: true };
+  return options || {};
+}
+
+export function createStickerSettings(options = null) {
+  const source = normalizeStickerOptions(options);
+  const enabled = source.enabled === true || (source.enabled !== false && Boolean(source.map));
+
+  return {
+    blendMode: blendModeOption(firstDefined(source, ['blendMode', 'blend', 'mode']), DEFAULT_STICKER_SETTINGS.blendMode),
+    enabled,
+    map: firstDefined(source, ['map', 'stickerMap', 'texture']) ?? DEFAULT_STICKER_SETTINGS.map,
+    offset: vector2Option(firstDefined(source, ['offset', 'uvOffset']), DEFAULT_STICKER_SETTINGS.offset),
+    repeat: vector2Option(firstDefined(source, ['repeat', 'uvRepeat', 'tiling']), DEFAULT_STICKER_SETTINGS.repeat),
+    strength: numberOption(firstDefined(source, ['strength', 'intensity', 'opacity']), DEFAULT_STICKER_SETTINGS.strength, { min: 0, max: 1 }),
+    uvChannel: numberOption(firstDefined(source, ['uvChannel']), DEFAULT_STICKER_SETTINGS.uvChannel, { min: 0, max: 1 }) >= 0.5 ? 1 : 0,
+  };
+}
+
+export function resolveStickerForMaterial(settings, { isOutline = false, sourceMaterial = null } = {}) {
+  const materialMap = sourceMaterial?.userData?.toonStickerMap ??
+    sourceMaterial?.userData?.stickerMap ??
+    null;
+  const map = settings.map ?? materialMap;
+
+  return {
+    blendModeValue: STICKER_BLEND_MODE_VALUES[settings.blendMode] ?? 0,
+    enabled: settings.enabled && !isOutline && Boolean(map) && settings.strength > 0,
+    map,
+    offset: settings.offset,
+    repeat: settings.repeat,
+    strength: settings.strength,
+    uvChannel: settings.uvChannel,
+  };
+}