@rig-c/parts 1.70.0 → 1.71.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/turn.ts CHANGED
@@ -232,6 +232,10 @@ export const FACESHIFT_BONE = 'faceshift';
232
232
  export const REAR_SHIFT_BONE = 'rear_shift';
233
233
  export const YAW_DIAL_BONE = 'yaw_dial';
234
234
  export const PITCH_DIAL_BONE = 'pitch_dial';
235
+ export const BODYSHIFT_BONE = 'bodyshift';
236
+ export const BODY_REAR_SHIFT_BONE = 'body_rear_shift';
237
+ export const BODY_YAW_DIAL_BONE = 'body_yaw_dial';
238
+ export const BODY_TURN_ANIM = 'body_turn';
235
239
  export const TURN_DIAL_SCALE = 0.0625;
236
240
  export const TURN_GRID_MAX_TRIANGLES_PER_SLOT = 2400;
237
241
  export const TURN_GRID_MAX_TRIANGLES_TOTAL = 4000;
@@ -241,11 +245,23 @@ export function turnSurfaceBone(part: string): string {
241
245
  return `${part}_surface`;
242
246
  }
243
247
 
244
- /** `config.turn`: either the legacy `{ pivot, depths }` turn spec or the 2.5D depth-sampled `{ roles, pivot?, counter?, grid?, unitDepths?, band? }` spec (#763). */
248
+ /** Optional 2.5D body-yaw turn block under `config.turn.body` (#787). */
249
+ export interface TurnBodySpec {
250
+ pivot?: number;
251
+ roles: Record<string, TurnRole>;
252
+ bone?: string;
253
+ slider?: string;
254
+ counter?: number;
255
+ grid?: [number, number] | Record<string, [number, number]>;
256
+ unitDepths?: Record<string, number>;
257
+ }
258
+
259
+ /** `config.turn`: either the legacy `{ pivot, depths }` turn spec or the 2.5D depth-sampled `{ roles, body?, pivot?, counter?, grid?, unitDepths?, band? }` spec (#763, #787). */
245
260
  export interface TurnSpec {
246
261
  pivot?: number;
247
262
  depths?: Record<string, number>;
248
263
  roles?: Record<string, TurnRole>;
264
+ body?: TurnBodySpec;
249
265
  counter?: number;
250
266
  grid?: [number, number] | Record<string, [number, number]>;
251
267
  unitDepths?: Record<string, number>;
@@ -256,13 +272,19 @@ export interface TurnSpec {
256
272
  deform?: Partial<FaceDeformFractions>;
257
273
  }
258
274
 
259
- /** Resolve `[cols, rows]` for a `'surface'` part under `config.turn`. */
260
- export function resolveTurnGrid(spec: TurnSpec | null | undefined, part: string): [number, number] {
261
- const g = spec?.grid;
262
- if (Array.isArray(g) && g.length === 2) return [g[0], g[1]];
263
- if (g !== undefined && !Array.isArray(g) && Object.hasOwn(g, part)) {
264
- const entry = g[part];
265
- return [entry[0], entry[1]];
275
+ /** Resolve `[cols, rows]` for a `'surface'` part under `config.turn` or `config.turn.body`. */
276
+ export function resolveTurnGrid(
277
+ spec: { grid?: [number, number] | Record<string, [number, number]> } | null | undefined,
278
+ part: string,
279
+ fallback?: { grid?: [number, number] | Record<string, [number, number]> } | null,
280
+ ): [number, number] {
281
+ for (const s of [spec, fallback]) {
282
+ const g = s?.grid;
283
+ if (Array.isArray(g) && g.length === 2) return [g[0], g[1]];
284
+ if (g !== undefined && !Array.isArray(g) && Object.hasOwn(g, part)) {
285
+ const entry = g[part];
286
+ return [entry[0], entry[1]];
287
+ }
266
288
  }
267
289
  return [DEFAULT_TURN_GRID_25D[0], DEFAULT_TURN_GRID_25D[1]];
268
290
  }
@@ -1455,12 +1477,27 @@ export interface Depth25DTurnOptions {
1455
1477
  hasAlternateFaceSet: boolean;
1456
1478
  }
1457
1479
 
1458
- /**
1459
- * Issue #763 (Stage 2): build the 2.5D head-turn `turn` and `tilt` animations
1460
- * and `yaw` / `pitch` slider constraints using Core's native `derive` and
1461
- * `deform` `transform` (`depth: true, narrowing: false`).
1462
- */
1463
- export function buildDepth25DTurn(
1480
+ interface Depth25DGroupSpec {
1481
+ fieldPrefix: 'config.turn' | 'config.turn.body';
1482
+ roles: Record<string, TurnRole>;
1483
+ pivot: number;
1484
+ counter: number;
1485
+ unitDepths?: Record<string, number>;
1486
+ carrierBone: string;
1487
+ rearCarrierBone: string;
1488
+ unitGroupName: string;
1489
+ useEyeLandmarksForZRef: boolean;
1490
+ checkEarBehindCheek: boolean;
1491
+ axes: ReadonlyArray<{
1492
+ kind: 'yaw' | 'pitch';
1493
+ animName: string;
1494
+ sliderName: string;
1495
+ dialBone: string;
1496
+ maxDeg: number;
1497
+ }>;
1498
+ }
1499
+
1500
+ function buildDepth25DTurnGroup(
1464
1501
  rig: {
1465
1502
  bones: Array<{ name: string; parent?: string; x: number; y: number; rotation?: number; length?: number }>;
1466
1503
  slots: Array<{ name: string; bone: string; attachment: string | null }>;
@@ -1471,13 +1508,14 @@ export function buildDepth25DTurn(
1471
1508
  animations: Record<string, unknown>;
1472
1509
  },
1473
1510
  opts: Depth25DTurnOptions,
1511
+ group: Depth25DGroupSpec,
1512
+ problems: Problem[],
1474
1513
  ): void {
1475
- const roles = opts.turn.roles;
1476
- if (roles === undefined) return;
1477
- const problems: Problem[] = [];
1514
+ const { roles } = group;
1478
1515
  const partMap = new Map(opts.parts.map((p) => [p.name, p]));
1516
+ const startProblems = problems.length;
1479
1517
 
1480
- // Gap 3 check: all turn-bound parts that carry a depth sheet must share one near and one zScale.
1518
+ // All turn-bound parts in the group that carry a depth sheet must share one near and one zScale.
1481
1519
  let sharedNear: PartDepthReference['near'] | null = null;
1482
1520
  let sharedZScale: number | null = null;
1483
1521
  let sharedFirstPart: string | null = null;
@@ -1492,7 +1530,7 @@ export function buildDepth25DTurn(
1492
1530
  problems.push({
1493
1531
  code: 'RIG_TURN_SHARED_DEPTH_SCALE',
1494
1532
  object: `parts.json part "${part}".depth`,
1495
- detail: `states near="${rec.depth.near}", zScale=${rec.depth.zScale}, which disagrees with "${sharedFirstPart}" (near="${sharedNear}", zScale=${sharedZScale}); all parts bound to one head turn must share one near polarity and one zScale so Core's sampled z values are in one coordinate space`,
1533
+ detail: `states near="${rec.depth.near}", zScale=${rec.depth.zScale}, which disagrees with "${sharedFirstPart}" (near="${sharedNear}", zScale=${sharedZScale}); all parts bound to one 2.5D turn group must share one near polarity and one zScale so Core's sampled z values are in one coordinate space`,
1496
1534
  });
1497
1535
  }
1498
1536
  }
@@ -1514,7 +1552,7 @@ export function buildDepth25DTurn(
1514
1552
  if (rec === undefined || rec.depth === undefined || art === undefined || scalar === undefined) {
1515
1553
  problems.push({
1516
1554
  code: 'RIG_TURN_SURFACE_DEPTH_REQUIRED',
1517
- object: `config.turn.roles.${part}`,
1555
+ object: `${group.fieldPrefix}.roles.${part}`,
1518
1556
  detail: `declares role "surface" for "${part}", which requires a depth sheet in parts.json; run assemble with config.depth or provide "${part}_depth.png"`,
1519
1557
  });
1520
1558
  continue;
@@ -1527,8 +1565,8 @@ export function buildDepth25DTurn(
1527
1565
  const ly = Math.max(0, Math.min(ext.height - 1, Math.round(cy - rec.y + padY)));
1528
1566
  return levelToDepthZ(ext.data[(ly * ext.width + lx) * 4], rec.depth as PartDepthReference);
1529
1567
  };
1530
- const eyeR = opts.boneLandmarks.get('eye_r');
1531
- const eyeL = opts.boneLandmarks.get('eye_l');
1568
+ const eyeR = group.useEyeLandmarksForZRef ? opts.boneLandmarks.get('eye_r') : undefined;
1569
+ const eyeL = group.useEyeLandmarksForZRef ? opts.boneLandmarks.get('eye_l') : undefined;
1532
1570
  let zRef: number;
1533
1571
  if (eyeR !== undefined && eyeL !== undefined) {
1534
1572
  zRef = pyRound(0.5 * (sampleExtAtCrop(eyeR[0], eyeR[1]) + sampleExtAtCrop(eyeL[0], eyeL[1])), 4);
@@ -1537,20 +1575,20 @@ export function buildDepth25DTurn(
1537
1575
  }
1538
1576
  surfaceSheets.set(part, { rec: rec as { name: string; x: number; y: number; w: number; h: number; depth: PartDepthReference }, ext, zRef });
1539
1577
  }
1540
- refuseIfAny(problems);
1578
+ if (problems.length > startProblems) return;
1541
1579
 
1542
- const primarySurface = surfaceSheets.get('face') ?? [...surfaceSheets.values()][0];
1543
- const pivot = pyRound(opts.turn.pivot ?? DEFAULT_TURN_PIVOT_25D, 4);
1544
- const counter = opts.turn.counter ?? DEFAULT_TURN_COUNTER_25D;
1580
+ const primarySurface = (group.useEyeLandmarksForZRef ? surfaceSheets.get('face') : undefined) ?? [...surfaceSheets.values()][0];
1581
+ const pivot = pyRound(group.pivot, 4);
1582
+ const counter = group.counter;
1545
1583
  const rearDepth = pyRound(-counter * pivot, 4);
1546
1584
  const hasRear = Object.values(roles).includes('rear');
1547
1585
 
1548
- // Collect unit bones that sit directly under faceshift and resolve one scalar depth per unit bone.
1549
- const faceshiftChildren = new Set(rig.bones.filter((b) => b.parent === FACESHIFT_BONE).map((b) => b.name));
1586
+ // Collect unit bones that sit directly under carrierBone and resolve one scalar depth per unit bone.
1587
+ const carrierChildren = new Set(rig.bones.filter((b) => b.parent === group.carrierBone).map((b) => b.name));
1550
1588
  const unitDepthMap: Record<string, number> = {};
1551
1589
  const unitBones: string[] = [];
1552
1590
  const addUnitBone = (bone: string, depth: number): void => {
1553
- if (!faceshiftChildren.has(bone)) return;
1591
+ if (!carrierChildren.has(bone)) return;
1554
1592
  if (!unitBones.includes(bone)) unitBones.push(bone);
1555
1593
  unitDepthMap[bone] = pyRound(depth, 4);
1556
1594
  };
@@ -1561,12 +1599,12 @@ export function buildDepth25DTurn(
1561
1599
  if (regSpec === undefined) continue;
1562
1600
  const baseBone = typeof regSpec === 'string' ? regSpec : regSpec.bone;
1563
1601
  const stillBone = opts.stills[part]?.bone;
1564
- const candidateBones = [baseBone, ...(stillBone === undefined ? [] : [stillBone])].filter((b) => faceshiftChildren.has(b));
1602
+ const candidateBones = [baseBone, ...(stillBone === undefined ? [] : [stillBone])].filter((b) => carrierChildren.has(b));
1565
1603
  if (candidateBones.length === 0) continue;
1566
1604
 
1567
1605
  for (const bName of candidateBones) {
1568
- const explicitPartDepth = opts.turn.unitDepths?.[part];
1569
- const explicitBoneDepth = opts.turn.unitDepths?.[bName];
1606
+ const explicitPartDepth = group.unitDepths?.[part];
1607
+ const explicitBoneDepth = group.unitDepths?.[bName];
1570
1608
  let resolved: number | null = null;
1571
1609
  if (typeof explicitPartDepth === 'number' && Number.isFinite(explicitPartDepth)) {
1572
1610
  resolved = explicitPartDepth;
@@ -1595,12 +1633,12 @@ export function buildDepth25DTurn(
1595
1633
  if (resolved === null) {
1596
1634
  problems.push({
1597
1635
  code: 'RIG_TURN_UNIT_DEPTH_REQUIRED',
1598
- object: `config.turn.roles.${part}`,
1599
- detail: `declares role "unit" for "${part}" (bone "${bName}"), and neither a surface depth sheet nor a part depth sheet nor config.turn.unitDepths.${part} provides its depth`,
1636
+ object: `${group.fieldPrefix}.roles.${part}`,
1637
+ detail: `declares role "unit" for "${part}" (bone "${bName}"), and neither a surface depth sheet nor a part depth sheet nor ${group.fieldPrefix}.unitDepths.${part} provides its depth`,
1600
1638
  });
1601
1639
  continue;
1602
1640
  }
1603
- if ((bName === 'ear_r' || bName === 'ear_l') && primarySurface !== undefined) {
1641
+ if (group.checkEarBehindCheek && (bName === 'ear_r' || bName === 'ear_l') && primarySurface !== undefined) {
1604
1642
  const pt = opts.boneLandmarks.get(bName);
1605
1643
  if (pt !== undefined) {
1606
1644
  const { rec, ext, zRef } = primarySurface;
@@ -1612,7 +1650,7 @@ export function buildDepth25DTurn(
1612
1650
  if (resolved > cheekDepth) {
1613
1651
  problems.push({
1614
1652
  code: 'RIG_TURN_EAR_DEPTH_BEHIND_CHEEK',
1615
- object: `config.turn.unitDepths.${part}`,
1653
+ object: `${group.fieldPrefix}.unitDepths.${part}`,
1616
1654
  detail: `places "${bName}" at depth ${pyRound(resolved, 4)}, which is in front of the adjacent cheek edge (${cheekDepth}); an ear depth at or behind ${cheekDepth} is required so the ear recedes behind the cheek`,
1617
1655
  });
1618
1656
  continue;
@@ -1622,7 +1660,7 @@ export function buildDepth25DTurn(
1622
1660
  addUnitBone(bName, resolved);
1623
1661
  }
1624
1662
  }
1625
- refuseIfAny(problems);
1663
+ if (problems.length > startProblems) return;
1626
1664
 
1627
1665
  // Order unitBones in rig.bones declaration order for determinism.
1628
1666
  const boneIndex = new Map(rig.bones.map((b, i) => [b.name, i]));
@@ -1632,12 +1670,10 @@ export function buildDepth25DTurn(
1632
1670
 
1633
1671
  if (unitBones.length > 0) {
1634
1672
  motion.groups ??= {};
1635
- motion.groups.turn_units = unitBones;
1673
+ motion.groups[group.unitGroupName] = unitBones;
1636
1674
  }
1637
1675
 
1638
- const { yaw: yawMax, pitch: pitchMax } = resolveTurnBands(opts.turn);
1639
- const buildAxisAnim = (kind: 'yaw' | 'pitch', maxDeg: number): void => {
1640
- const animName = kind === 'yaw' ? 'turn' : 'tilt';
1676
+ const buildAxisAnim = (kind: 'yaw' | 'pitch', animName: string, maxDeg: number): void => {
1641
1677
  const prop = kind === 'yaw' ? 'translatex' : 'translatey';
1642
1678
  const duration = pyRound(2 * maxDeg * TURN_DIAL_SCALE, 6);
1643
1679
  const step = maxDeg / 2;
@@ -1665,7 +1701,7 @@ export function buildDepth25DTurn(
1665
1701
  }>;
1666
1702
  }> = [
1667
1703
  {
1668
- bone: FACESHIFT_BONE,
1704
+ bone: group.carrierBone,
1669
1705
  property: prop,
1670
1706
  keys: keyList.map(({ t, deg }) =>
1671
1707
  deg === 0
@@ -1676,7 +1712,7 @@ export function buildDepth25DTurn(
1676
1712
  ];
1677
1713
  if (hasRear && rearDepth !== 0) {
1678
1714
  tracks.push({
1679
- bone: REAR_SHIFT_BONE,
1715
+ bone: group.rearCarrierBone,
1680
1716
  property: prop,
1681
1717
  keys: keyList.map(({ t, deg }) =>
1682
1718
  deg === 0
@@ -1701,7 +1737,7 @@ export function buildDepth25DTurn(
1701
1737
  }
1702
1738
  if (unitBones.length > 0) {
1703
1739
  tracks.push({
1704
- group: 'turn_units',
1740
+ group: group.unitGroupName,
1705
1741
  property: prop,
1706
1742
  keys: keyList.map(({ t, deg }) =>
1707
1743
  deg === 0
@@ -1762,11 +1798,17 @@ export function buildDepth25DTurn(
1762
1798
  };
1763
1799
  };
1764
1800
 
1765
- buildAxisAnim('yaw', yawMax);
1766
- buildAxisAnim('pitch', pitchMax);
1767
-
1768
1801
  rig.constraints ??= [];
1769
1802
  const upsertSlider = (name: string, animName: string, dialBone: string, maxDeg: number): void => {
1803
+ const colliding = rig.constraints?.find((c) => c.type === 'slider' && c.name === name && c.animation !== animName);
1804
+ if (colliding !== undefined) {
1805
+ problems.push({
1806
+ code: 'CONFIG_TURN_SLIDER_NAME_FREE',
1807
+ object: `${group.fieldPrefix}.slider`,
1808
+ detail: `is "${name}", which collides with an existing slider constraint "${name}"; choose a distinct slider name`,
1809
+ });
1810
+ return;
1811
+ }
1770
1812
  const existing = rig.constraints?.find((c) => c.type === 'slider' && c.animation === animName);
1771
1813
  if (existing !== undefined) {
1772
1814
  existing.bone = dialBone;
@@ -1795,6 +1837,83 @@ export function buildDepth25DTurn(
1795
1837
  });
1796
1838
  }
1797
1839
  };
1798
- upsertSlider('yaw', 'turn', YAW_DIAL_BONE, yawMax);
1799
- upsertSlider('pitch', 'tilt', PITCH_DIAL_BONE, pitchMax);
1840
+
1841
+ for (const axis of group.axes) {
1842
+ buildAxisAnim(axis.kind, axis.animName, axis.maxDeg);
1843
+ upsertSlider(axis.sliderName, axis.animName, axis.dialBone, axis.maxDeg);
1844
+ }
1845
+ }
1846
+
1847
+ /**
1848
+ * Issues #763 & #787: build the 2.5D head-turn (`turn`, `tilt`) and optional
1849
+ * body-turn (`body_turn`) animations and slider constraints using Core's native
1850
+ * `derive` and `deform` `transform` (`depth: true, narrowing: false`).
1851
+ */
1852
+ export function buildDepth25DTurn(
1853
+ rig: {
1854
+ bones: Array<{ name: string; parent?: string; x: number; y: number; rotation?: number; length?: number }>;
1855
+ slots: Array<{ name: string; bone: string; attachment: string | null }>;
1856
+ constraints?: Array<Record<string, unknown>>;
1857
+ },
1858
+ motion: {
1859
+ groups?: Record<string, string[]>;
1860
+ animations: Record<string, unknown>;
1861
+ },
1862
+ opts: Depth25DTurnOptions,
1863
+ ): void {
1864
+ const problems: Problem[] = [];
1865
+ const { yaw: yawMax, pitch: pitchMax } = resolveTurnBands(opts.turn);
1866
+
1867
+ if (opts.turn.roles !== undefined) {
1868
+ buildDepth25DTurnGroup(
1869
+ rig,
1870
+ motion,
1871
+ opts,
1872
+ {
1873
+ fieldPrefix: 'config.turn',
1874
+ roles: opts.turn.roles,
1875
+ pivot: opts.turn.pivot ?? DEFAULT_TURN_PIVOT_25D,
1876
+ counter: opts.turn.counter ?? DEFAULT_TURN_COUNTER_25D,
1877
+ unitDepths: opts.turn.unitDepths,
1878
+ carrierBone: FACESHIFT_BONE,
1879
+ rearCarrierBone: REAR_SHIFT_BONE,
1880
+ unitGroupName: 'turn_units',
1881
+ useEyeLandmarksForZRef: true,
1882
+ checkEarBehindCheek: true,
1883
+ axes: [
1884
+ { kind: 'yaw', animName: 'turn', sliderName: 'yaw', dialBone: YAW_DIAL_BONE, maxDeg: yawMax },
1885
+ { kind: 'pitch', animName: 'tilt', sliderName: 'pitch', dialBone: PITCH_DIAL_BONE, maxDeg: pitchMax },
1886
+ ],
1887
+ },
1888
+ problems,
1889
+ );
1890
+ }
1891
+
1892
+ if (opts.turn.body !== undefined) {
1893
+ const body = opts.turn.body;
1894
+ const bodySlider = typeof body.slider === 'string' && body.slider.trim().length > 0 ? body.slider : BODY_YAW_DIAL_BONE;
1895
+ buildDepth25DTurnGroup(
1896
+ rig,
1897
+ motion,
1898
+ opts,
1899
+ {
1900
+ fieldPrefix: 'config.turn.body',
1901
+ roles: body.roles,
1902
+ pivot: body.pivot ?? opts.turn.pivot ?? DEFAULT_TURN_PIVOT_25D,
1903
+ counter: body.counter ?? opts.turn.counter ?? DEFAULT_TURN_COUNTER_25D,
1904
+ unitDepths: body.unitDepths ?? opts.turn.unitDepths,
1905
+ carrierBone: BODYSHIFT_BONE,
1906
+ rearCarrierBone: BODY_REAR_SHIFT_BONE,
1907
+ unitGroupName: 'body_turn_units',
1908
+ useEyeLandmarksForZRef: false,
1909
+ checkEarBehindCheek: false,
1910
+ axes: [
1911
+ { kind: 'yaw', animName: BODY_TURN_ANIM, sliderName: bodySlider, dialBone: bodySlider, maxDeg: yawMax },
1912
+ ],
1913
+ },
1914
+ problems,
1915
+ );
1916
+ }
1917
+
1918
+ refuseIfAny(problems);
1800
1919
  }