@rig-c/parts 1.31.0 → 1.33.0

package/src/turn.ts

@@ -29,6 +29,7 @@
  * one piece. Pure: no file, no clock.
  */
 import { computeWorldTransforms, toBoneLocalVector, toWorld, type BoneTransform } from './coords.ts';
+import { type Problem, refuseIfAny } from './errors.ts';
 import { pyRound } from './round.ts';
 
 /**
@@ -165,10 +166,29 @@ export function resolveFaceDeformFractions(overrides?: Readonly<Partial<FaceDefo
   return out;
 }
 
-/** `config.turn`: the pivot depth, each carried part's See-through `depth_median`, and optional face surface deform overrides. */
+/**
+ * Issue #472: the rated band of a single face plate — yaw `±15°`, pitch `±12°`.
+ * Beyond this band on one plate, the foreshortened far eye runs out of cheek to
+ * sit on; going further takes an alternate face set (`assemble.alternates`),
+ * whose swap threshold is this band edge.
+ */
+export const FACE_RATED_YAW_BAND = 15;
+export const FACE_RATED_PITCH_BAND = 12;
+export const FACE_RATED_BAND = { yaw: FACE_RATED_YAW_BAND, pitch: FACE_RATED_PITCH_BAND } as const;
+
+/**
+ * Issue #477: allowed `[min, max]` range (in rig px) for an authored ear
+ * `derive.depth` in `turn` or `tilt`. Ears sit at or behind the head pivot
+ * (`depth <= 0`, where `-14` moves the ears slightly against the face turn); a
+ * depth outside `[-50, 0]` is refused by `CONFIG_TURN_EAR_DEPTH_RANGE`.
+ */
+export const EAR_DEPTH_RANGE: readonly [number, number] = [-50, 0];
+
+/** `config.turn`: the pivot depth, each carried part's See-through `depth_median`, optional rated band, and optional face surface deform overrides. */
 export interface TurnSpec {
   pivot: number;
   depths: Record<string, number>;
+  band?: number | { yaw?: number; pitch?: number };
   deform?: Partial<FaceDeformFractions>;
 }
 
@@ -291,6 +311,13 @@ export interface FaceSurfaceDeformOptions {
   opaqueHeight?: number;
   /** Recipe overrides for {@link FACE_DEFORM_FRACTIONS}. */
   overrides?: Readonly<Partial<FaceDeformFractions>> | null;
+  /**
+   * Issue #472: true when `assemble.alternates` declares an alternate face set
+   * for the overflow beyond `±15°` yaw / `±12°` pitch. When false or absent,
+   * any `yaw` / `pitch` slider constraints on the rig are preceded by clamping
+   * transform constraints holding the dial bones to `[-15, 15]` and `[-12, 12]`.
+   */
+  hasAlternateFaceSet?: boolean;
 }
 
 interface DeformWeight {
@@ -328,7 +355,7 @@ interface DeriveSpec {
 
 interface SliderKey {
   t: number;
-  v?: number[];
+  v?: number[] | Record<string, number[]>;
   derive?: DeriveSpec;
 }
 
@@ -390,14 +417,16 @@ function buildFaceGrid(width: number, height: number): { points: Array<[number,
 /**
  * Promote the `face` region on `head` to a 5×5 grid mesh and populate the
  * `tilt` and `turn` slider animations with the Set B ×2.5 face and hair mesh
- * deform timelines and ear/topknot tracks (issue #436). When `motion` holds
- * neither `tilt` nor `turn` with slider `derive` keys, neither `rig` nor
- * `motion` is touched.
+ * deform timelines, feature field-sampled tracks (#468) and ear/topknot tracks
+ * (issue #436). When `motion` holds neither `tilt` nor `turn` with slider
+ * `derive` keys, neither `rig` nor `motion` is touched.
  */
 export function applyFaceSurfaceDeform(
   rig: {
     bones: Array<{ name: string; parent?: string; x: number; y: number; rotation?: number; length?: number; inherit?: string }>;
+    slots?: Array<{ name: string; bone: string }>;
     skins: { default: Record<string, Record<string, DeformMeshAttachment | DeformRegionAttachment>> };
+    constraints?: Array<Record<string, unknown>>;
     invariants?: Record<string, unknown>;
   },
   motion: {
@@ -413,6 +442,44 @@ export function applyFaceSurfaceDeform(
     (rawTilt?.tracks?.some((tr) => tr.keys?.some((k) => k.derive !== undefined)) ?? false) ||
     (rawTurn?.tracks?.some((tr) => tr.keys?.some((k) => k.derive !== undefined)) ?? false);
   if (!hasDerive) return;
+
+  // Issue #477: refuse an out-of-range ear derive.depth by name before touching rig or motion.
+  const earProblems: Problem[] = [];
+  const [earLo, earHi] = EAR_DEPTH_RANGE;
+  for (const [animName, anim] of [
+    ['tilt', rawTilt],
+    ['turn', rawTurn],
+  ] as const) {
+    if (anim === undefined) continue;
+    anim.tracks.forEach((tr, ti) => {
+      const isEarTrack = tr.group === 'ears' || tr.bone === 'ear_r' || tr.bone === 'ear_l';
+      if (!isEarTrack) return;
+      tr.keys.forEach((k, ki) => {
+        const d = k.derive?.depth;
+        if (typeof d === 'number') {
+          if (d < earLo || d > earHi) {
+            earProblems.push({
+              code: 'CONFIG_TURN_EAR_DEPTH_RANGE',
+              object: `animations.${animName}.tracks[${ti}].keys[${ki}].derive.depth`,
+              detail: `is ${d}; an ear depth in [${earLo}, ${earHi}] (at or behind the head pivot) is required`,
+            });
+          }
+        } else if (d !== undefined && typeof d === 'object') {
+          for (const [member, val] of Object.entries(d)) {
+            if (typeof val === 'number' && (val < earLo || val > earHi)) {
+              earProblems.push({
+                code: 'CONFIG_TURN_EAR_DEPTH_RANGE',
+                object: `animations.${animName}.tracks[${ti}].keys[${ki}].derive.depth.${member}`,
+                detail: `is ${val}; an ear depth in [${earLo}, ${earHi}] (at or behind the head pivot) is required`,
+              });
+            }
+          }
+        }
+      });
+    });
+  }
+  refuseIfAny(earProblems);
+
   const tiltAnim = rawTilt === undefined ? undefined : structuredClone(rawTilt);
   const turnAnim = rawTurn === undefined ? undefined : structuredClone(rawTurn);
   if (tiltAnim !== undefined) motion.animations.tilt = tiltAnim;
@@ -421,10 +488,63 @@ export function applyFaceSurfaceDeform(
   const isOpts =
     options !== undefined &&
     options !== null &&
-    ('imageWidth' in options || 'imageHeight' in options || 'opaqueWidth' in options || 'opaqueHeight' in options || 'overrides' in options);
+    ('imageWidth' in options ||
+      'imageHeight' in options ||
+      'opaqueWidth' in options ||
+      'opaqueHeight' in options ||
+      'overrides' in options ||
+      'hasAlternateFaceSet' in options);
   const opts: FaceSurfaceDeformOptions = isOpts ? (options as FaceSurfaceDeformOptions) : { overrides: options as Readonly<Partial<FaceDeformFractions>> | null | undefined };
   const f = resolveFaceDeformFractions(opts.overrides);
 
+  // Issue #472: when no alternate face set is declared, clamp dial bones to the single-plate rated band (±15° yaw, ±12° pitch).
+  if (!opts.hasAlternateFaceSet && Array.isArray(rig.constraints)) {
+    const nextConstraints: Array<Record<string, unknown>> = [];
+    const existingNames = new Set(rig.constraints.map((c) => c.name));
+    const makeClampConstraint = (name: string, bone: string, prop: unknown, band: number): Record<string, unknown> => {
+      const useX = prop === 'x' || prop === 'translatex';
+      const key = useX ? 'x' : 'rotate';
+      const mixKey = useX ? 'mixX' : 'mixRotate';
+      return {
+        name,
+        type: 'transform',
+        source: bone,
+        bones: [bone],
+        localSource: true,
+        localTarget: true,
+        clamp: true,
+        properties: {
+          [key]: {
+            offset: -band,
+            to: {
+              [key]: {
+                offset: -band,
+                max: band,
+                scale: 1,
+              },
+            },
+          },
+        },
+        [mixKey]: 1,
+      };
+    };
+    for (const c of rig.constraints) {
+      if (c.type === 'slider' && typeof c.bone === 'string') {
+        const isYaw = c.name === 'yaw' || c.animation === 'turn';
+        const isPitch = c.name === 'pitch' || c.animation === 'tilt';
+        if (isYaw && !existingNames.has('yaw_clamp')) {
+          existingNames.add('yaw_clamp');
+          nextConstraints.push(makeClampConstraint('yaw_clamp', c.bone, c.property, FACE_RATED_YAW_BAND));
+        } else if (isPitch && !existingNames.has('pitch_clamp')) {
+          existingNames.add('pitch_clamp');
+          nextConstraints.push(makeClampConstraint('pitch_clamp', c.bone, c.property, FACE_RATED_PITCH_BAND));
+        }
+      }
+      nextConstraints.push(c);
+    }
+    rig.constraints = nextConstraints;
+  }
+
   const faceSlot = rig.skins.default.face;
   if (faceSlot === undefined || faceSlot.face === undefined) return;
   const faceAtt = faceSlot.face;
@@ -434,13 +554,15 @@ export function applyFaceSurfaceDeform(
   let faceRegX = -1;
   let faceRegY = 49;
 
+  const faceBone = rig.slots?.find((s) => s.name === 'face')?.bone ?? (rig.bones.some((b) => b.name === 'turn_face_head') ? 'turn_face_head' : 'head');
+
   if (!('type' in faceAtt)) {
     faceRegX = faceAtt.x;
     faceRegY = faceAtt.y;
     const grid = buildFaceGrid(faceW, faceH);
     const faceWeights: DeformWeight[][] = grid.points.map(([px, py]) => [
       {
-        bone: 'head',
+        bone: faceBone,
         x: pyRound(faceRegX - faceW / 2 + px, 6),
         y: pyRound(faceRegY + faceH / 2 - py, 6),
         weight: 1,
@@ -531,8 +653,31 @@ export function applyFaceSurfaceDeform(
   };
 
   const boneMap = new Map(rig.bones.map((b) => [b.name, b]));
+  const referencedGroups = new Set<string>();
+  for (const anim of [tiltAnim, turnAnim]) {
+    for (const tr of anim?.tracks ?? []) {
+      if (tr.group !== undefined) referencedGroups.add(tr.group);
+    }
+  }
+  const defaultGroups: Readonly<Record<string, readonly string[]>> = {
+    features: ['eye_r', 'eye_l', 'brow_r', 'brow_l', 'pupil_r', 'pupil_l', 'eyelash_r', 'eyelash_l', 'eyebrow_r', 'eyebrow_l', 'nose', 'mouth'],
+    ears: ['ear_r', 'ear_l'],
+    bangs: ['bang_r0', 'bang_c0', 'bang_l0'].map((b) => (boneMap.has(`${b}_ctl`) ? `${b}_ctl` : b)),
+    topknot: ['bun_ctl', 'hairpin', 'headwear'],
+  };
+  for (const g of referencedGroups) {
+    if (motion.groups?.[g] === undefined && defaultGroups[g] !== undefined) {
+      const members = defaultGroups[g].filter((b) => boneMap.has(b));
+      if (members.length > 0) {
+        motion.groups ??= {};
+        motion.groups[g] = members;
+      }
+    }
+  }
+
   const evalDeriveKey = (boneName: string, k: SliderKey): number => {
     if (Array.isArray(k.v)) return k.v[0] ?? 0;
+    if (k.v !== undefined && typeof k.v === 'object') return k.v[boneName]?.[0] ?? 0;
     const d = k.derive;
     if (d === undefined) return 0;
     const b = boneMap.get(boneName);
@@ -546,17 +691,18 @@ export function applyFaceSurfaceDeform(
   };
 
   const mapParent: Readonly<Record<string, string>> = {
-    bang_r0: 'bang_r0_ctl',
-    bang_r1: 'bang_r0_ctl',
-    bang_c0: 'bang_c0_ctl',
-    bang_c1: 'bang_c0_ctl',
-    bang_l0: 'bang_l0_ctl',
-    bang_l1: 'bang_l0_ctl',
-    bun: 'bun_ctl',
+    bang_r0: boneMap.has('bang_r0_ctl') ? 'bang_r0_ctl' : 'bang_r0',
+    bang_r1: boneMap.has('bang_r0_ctl') ? 'bang_r0_ctl' : 'bang_r0',
+    bang_c0: boneMap.has('bang_c0_ctl') ? 'bang_c0_ctl' : 'bang_c0',
+    bang_c1: boneMap.has('bang_c0_ctl') ? 'bang_c0_ctl' : 'bang_c0',
+    bang_l0: boneMap.has('bang_l0_ctl') ? 'bang_l0_ctl' : 'bang_l0',
+    bang_l1: boneMap.has('bang_l0_ctl') ? 'bang_l0_ctl' : 'bang_l0',
+    bun: boneMap.has('bun_ctl') ? 'bun_ctl' : 'bun',
   };
 
   const getBoneDeltaAtTime = (tracks: readonly SliderTrack[], t: number, boneName: string): [number, number] => {
-    const driver = mapParent[boneName] ?? boneName;
+    const baseBone = boneName.replace(/^turn_[^_]+_/, '');
+    const driver = mapParent[baseBone] ?? baseBone;
     let dx = 0;
     let dy = 0;
     for (const tr of tracks) {
@@ -598,16 +744,37 @@ export function applyFaceSurfaceDeform(
   const hyEar = Y0 - (16 / 128) * H;
   const earRx = boneMap.get('ear_r')?.x ?? -51;
   const earLx = boneMap.get('ear_l')?.x ?? 47.5;
+  const featRx = (24 / 106) * W;
+  const featRy = (12 / 128) * H;
+  const featMembers = motion.groups?.features ?? [];
+
+  const minDepthOf = (depth: number | Readonly<Record<string, number>> | undefined, fallback: number): number => {
+    if (typeof depth === 'number') return depth > 0 ? depth : fallback;
+    if (depth === undefined) return fallback;
+    const vals = Object.values(depth).filter((v): v is number => typeof v === 'number' && v > 0);
+    return vals.length > 0 ? Math.min(...vals) : fallback;
+  };
+
+  const memberDepthOf = (depth: number | Readonly<Record<string, number>> | undefined, boneName: string, zRef: number): number => {
+    if (typeof depth === 'number') return depth;
+    return depth?.[boneName] ?? zRef;
+  };
 
   if (tiltAnim !== undefined) {
     const origTiltTracks = tiltAnim.tracks.map((tr) => ({ ...tr, keys: [...tr.keys] }));
-    const tiltKeys: Array<{ t: number; deg: number }> = [
-      { t: 0, deg: -25 },
-      { t: 0.75, deg: -10 },
-      { t: 1.25, deg: 0 },
-      { t: 2.0, deg: 15 },
-      { t: 2.5, deg: 25 },
-    ];
+    const refTiltTrack = origTiltTracks.find((tr) => tr.keys.some((k) => k.derive !== undefined)) ?? origTiltTracks[0];
+    const isLegacyTilt =
+      tiltAnim.duration === 2.5 &&
+      Math.abs(refTiltTrack?.keys[0]?.derive?.degrees ?? 0) === 25;
+    const tiltKeys: Array<{ t: number; deg: number }> = isLegacyTilt
+      ? [
+          { t: 0, deg: -25 },
+          { t: 0.75, deg: -10 },
+          { t: 1.25, deg: 0 },
+          { t: 2.0, deg: 15 },
+          { t: 2.5, deg: 25 },
+        ]
+      : (refTiltTrack?.keys ?? []).map((k) => ({ t: k.t, deg: k.derive?.degrees ?? 0 }));
     const tiltDeform: DeformTimelineEntry[] = [
       {
         slot: 'face',
@@ -657,6 +824,31 @@ export function applyFaceSurfaceDeform(
       });
     }
     for (const tr of tiltAnim.tracks) {
+      if (tr.group === 'features' && (tr.property === 'translatey' || tr.property === 'scaley') && featMembers.length > 0) {
+        const zRef = minDepthOf(tr.keys[0]?.derive?.depth, 34);
+        tr.keys = tr.keys.map((k) => {
+          const deg = k.derive?.degrees ?? 0;
+          if (deg === 0) return { t: k.t, v: tr.property === 'scaley' ? [1] : [0] };
+          const vMap: Record<string, number[]> = {};
+          for (const bname of featMembers) {
+            const b = boneMap.get(bname);
+            const bx = b?.x ?? 0;
+            const by = b?.y ?? Y0;
+            const z = memberDepthOf(k.derive?.depth, bname, zRef);
+            const dFrac = zRef > 0 ? z / zRef : 1;
+            const uy = Math.max(-1, Math.min(1, (by - Y0) / (H / 2)));
+            const effDeg = deg * (1 + (dFrac - 1) * Math.max(0, 1 - uy * uy));
+            const [, dyD] = evalPitchFaceSurface(bx, by - featRy, effDeg, W, H, X0, Y0, f);
+            const [, dyU] = evalPitchFaceSurface(bx, by + featRy, effDeg, W, H, X0, Y0, f);
+            if (tr.property === 'translatey') {
+              vMap[bname] = [pyRound(0.5 * (dyD + dyU), 4)];
+            } else {
+              vMap[bname] = [pyRound(Math.max(0.2, 1 + (dyU - dyD) / (2 * featRy)), 4)];
+            }
+          }
+          return { t: k.t, v: vMap };
+        });
+      }
       if (tr.group === 'ears' && tr.property === 'translatey') {
         tr.keys = tr.keys.map((k) => {
           const deg = k.derive?.degrees ?? 0;
@@ -674,7 +866,7 @@ export function applyFaceSurfaceDeform(
         });
       }
     }
-    const refTiltKeys = origTiltTracks[0]?.keys ?? [];
+    const refTiltKeys = refTiltTrack?.keys ?? [];
     for (const [earBone, earHx] of [
       ['ear_r', earRx],
       ['ear_l', earLx],
@@ -696,13 +888,19 @@ export function applyFaceSurfaceDeform(
 
   if (turnAnim !== undefined) {
     const origTurnTracks = turnAnim.tracks.map((tr) => ({ ...tr, keys: [...tr.keys] }));
-    const turnKeys: Array<{ t: number; deg: number }> = [
-      { t: 0, deg: -30 },
-      { t: 0.75, deg: -15 },
-      { t: 1.5, deg: 0 },
-      { t: 2.25, deg: 15 },
-      { t: 3.0, deg: 30 },
-    ];
+    const refTurnTrack = origTurnTracks.find((tr) => tr.keys.some((k) => k.derive !== undefined)) ?? origTurnTracks[0];
+    const isLegacyTurn =
+      turnAnim.duration === 3.0 &&
+      Math.abs(refTurnTrack?.keys[0]?.derive?.degrees ?? 0) === 30;
+    const turnKeys: Array<{ t: number; deg: number }> = isLegacyTurn
+      ? [
+          { t: 0, deg: -30 },
+          { t: 0.75, deg: -15 },
+          { t: 1.5, deg: 0 },
+          { t: 2.25, deg: 15 },
+          { t: 3.0, deg: 30 },
+        ]
+      : (refTurnTrack?.keys ?? []).map((k) => ({ t: k.t, deg: k.derive?.degrees ?? 0 }));
     const turnDeform: DeformTimelineEntry[] = [
       {
         slot: 'face',
@@ -753,25 +951,84 @@ export function applyFaceSurfaceDeform(
         ),
       });
     }
-    const refTurnKeys = origTurnTracks[0]?.keys ?? [];
+    const refTurnKeys = refTurnTrack?.keys ?? [];
+    const earMembers = motion.groups?.ears ?? ['ear_r', 'ear_l'].filter((b) => boneMap.has(b));
+    const hasAuthoredEarTurnTx = turnAnim.tracks.some(
+      (tr) => tr.property === 'translatex' && (tr.group === 'ears' || tr.bone === 'ear_r' || tr.bone === 'ear_l'),
+    );
     turnAnim.tracks = turnAnim.tracks.filter(
-      (tr) => !(tr.group === 'ears' && tr.property === 'translatex') && !(tr.group === 'topknot' && tr.property === 'translatex'),
+      (tr) => !(tr.group === 'topknot' && tr.property === 'translatex'),
     );
-    for (const [earBone, earHx] of [
-      ['ear_r', earRx],
-      ['ear_l', earLx],
-    ] as const) {
-      if (!boneMap.has(earBone)) continue;
-      turnAnim.tracks.push({
-        bone: earBone,
-        property: 'translatex',
-        keys: refTurnKeys.map((k) => {
+    for (const tr of turnAnim.tracks) {
+      if (tr.group === 'features' && (tr.property === 'translatex' || tr.property === 'scalex') && featMembers.length > 0) {
+        const zRef = minDepthOf(tr.keys[0]?.derive?.depth, 36);
+        tr.keys = tr.keys.map((k) => {
           const deg = k.derive?.degrees ?? 0;
+          if (deg === 0) return { t: k.t, v: tr.property === 'scalex' ? [1] : [0] };
+          const vMap: Record<string, number[]> = {};
+          const s = Math.sign(deg);
+          for (const bname of featMembers) {
+            const b = boneMap.get(bname);
+            const bx = b?.x ?? X0;
+            const by = b?.y ?? Y0;
+            const z = memberDepthOf(k.derive?.depth, bname, zRef);
+            const dFrac = zRef > 0 ? z / zRef : 1;
+            const ux = Math.max(-1, Math.min(1, (bx - X0) / (W / 2)));
+            const effDeg = deg * (1 + (dFrac - 1) * Math.max(0, 1 - ux * ux));
+            const [dxL] = evalYawFaceSurface(bx - featRx, by, effDeg, W, H, X0, Y0, f);
+            const [dxR] = evalYawFaceSurface(bx + featRx, by, effDeg, W, H, X0, Y0, f);
+            const rawDelta = (dxR - dxL) / (2 * featRx);
+            const isTrailing = s * (bx - X0) > featRx * 0.5;
+            const sx = isTrailing ? 1 + Math.abs(rawDelta) : Math.max(0.2, 1 + rawDelta);
+            const dx = isTrailing
+              ? (s > 0 ? dxR - featRx * (sx - 1) : dxL + featRx * (sx - 1))
+              : 0.5 * (dxL + dxR);
+            if (tr.property === 'translatex') {
+              vMap[bname] = [pyRound(dx, 4)];
+            } else {
+              vMap[bname] = [pyRound(sx, 4)];
+            }
+          }
+          return { t: k.t, v: vMap };
+        });
+      } else if (tr.group === 'ears' && tr.property === 'translatex' && earMembers.length > 0) {
+        tr.keys = tr.keys.map((k) => {
+          if (k.derive === undefined) return k;
+          const deg = k.derive.degrees;
           if (deg === 0) return { t: k.t, v: [0] };
-          const [dxCheekEdge] = evalYawFaceSurface(earHx, hyEar, deg, W, H, X0, Y0, f);
-          return { t: k.t, v: [pyRound(dxCheekEdge * f.turn_ear_x, 4)] };
-        }),
-      });
+          const vMap: Record<string, number[]> = {};
+          for (const bname of earMembers) {
+            vMap[bname] = [evalDeriveKey(bname, k)];
+          }
+          return { t: k.t, v: vMap };
+        });
+      } else if ((tr.bone === 'ear_r' || tr.bone === 'ear_l') && tr.property === 'translatex') {
+        const bname = tr.bone;
+        tr.keys = tr.keys.map((k) => {
+          if (k.derive === undefined) return k;
+          const deg = k.derive.degrees;
+          if (deg === 0) return { t: k.t, v: [0] };
+          return { t: k.t, v: [evalDeriveKey(bname, k)] };
+        });
+      }
+    }
+    if (!hasAuthoredEarTurnTx) {
+      for (const [earBone, earHx] of [
+        ['ear_r', earRx],
+        ['ear_l', earLx],
+      ] as const) {
+        if (!boneMap.has(earBone)) continue;
+        turnAnim.tracks.push({
+          bone: earBone,
+          property: 'translatex',
+          keys: refTurnKeys.map((k) => {
+            const deg = k.derive?.degrees ?? 0;
+            if (deg === 0) return { t: k.t, v: [0] };
+            const [dxCheekEdge] = evalYawFaceSurface(earHx, hyEar, deg, W, H, X0, Y0, f);
+            return { t: k.t, v: [pyRound(dxCheekEdge * f.turn_ear_x, 4)] };
+          }),
+        });
+      }
     }
     for (const [tkBone, tkFrac] of [
       ['bun_ctl', f.turn_bun_counter_x],