@rig-c/parts 1.34.0 → 1.36.0

package/src/config.ts

@@ -91,6 +91,7 @@ import { pyRound } from './round.ts';
 import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING, springStable } from './cloth.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
+import { edgeLength } from './length.ts';
 import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
 import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
 import { EAR_DEPTH_RANGE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
@@ -392,6 +393,76 @@ export interface ContourSpec {
   bridges?: true;
   /** Local deformation regions; absent is none. */
   regions?: ContourRegionSpec[];
+  /**
+   * Issue #475: derives the `bust_r` and `bust_l` circle regions from three required landmarks (`apex_r`, `apex_l`,
+   * `cleavage`) and two constants (`alpha`, `clearance`). Mutually exclusive with hand-written `bust_r` or `bust_l`
+   * in `regions`.
+   */
+  bust?: ContourBustSpec;
+}
+
+/** Default solid-core ratio `α = r / (r + band)` fitted across the five calibrated example characters (issue #475). */
+export const DEFAULT_BUST_ALPHA = 0.22;
+/** Default cleavage clearance `ε` (rig px) fitted across the five calibrated example characters (issue #475). */
+export const DEFAULT_BUST_CLEARANCE = 3.8;
+/** Default interior refinement spacing (rig px) for derived `bust_r` and `bust_l` regions (issue #475). */
+export const DEFAULT_BUST_SPACING = 14;
+/** Default control bone names for derived `bust_r` and `bust_l` regions (issue #475). */
+export const DEFAULT_BUST_BONE_R = 'boob_r';
+export const DEFAULT_BUST_BONE_L = 'boob_l';
+
+/**
+ * Landmark shorthand for the `bust_r` and `bust_l` contour regions (issue #475):
+ * `R_s = round(|apex_s - cleavage| - clearance)`, `r_s = round(alpha * R_s)`, `band_s = R_s - r_s`.
+ */
+export interface ContourBustSpec {
+  apex_r: Point;
+  apex_l: Point;
+  cleavage: Point;
+  /** Core-to-outer radius ratio `r / (r + band)` in `(0, 1)`; absent is {@link DEFAULT_BUST_ALPHA} (`0.22`). */
+  alpha?: number;
+  /** Cleavage clearance `ε` in rig px (`> 0`, with `R_r + R_l < D`); absent is {@link DEFAULT_BUST_CLEARANCE} (`3.8`). */
+  clearance?: number;
+  /** Control bone for `bust_r`; absent is {@link DEFAULT_BUST_BONE_R} (`"boob_r"`). */
+  bone_r?: string;
+  /** Control bone for `bust_l`; absent is {@link DEFAULT_BUST_BONE_L} (`"boob_l"`). */
+  bone_l?: string;
+  /** Region refinement spacing in rig px (`> 0`); absent is {@link DEFAULT_BUST_SPACING} (`14`). */
+  spacing?: number;
+}
+
+/**
+ * Derive the `[bust_r, bust_l]` circle contour regions from {@link ContourBustSpec} (issue #475).
+ * Read by both `propose` and `rig` through {@link contourRegionsOf}.
+ */
+export function deriveBustRegions(bust: ContourBustSpec): [ContourRegionSpec, ContourRegionSpec] {
+  const alpha = bust.alpha ?? DEFAULT_BUST_ALPHA;
+  const clearance = bust.clearance ?? DEFAULT_BUST_CLEARANCE;
+  const spacing = bust.spacing ?? DEFAULT_BUST_SPACING;
+  const boneR = bust.bone_r ?? DEFAULT_BUST_BONE_R;
+  const boneL = bust.bone_l ?? DEFAULT_BUST_BONE_L;
+  const [rx, ry] = bust.apex_r;
+  const [lx, ly] = bust.apex_l;
+  const [kx, ky] = bust.cleavage;
+  const dR = edgeLength(kx - rx, ky - ry);
+  const dL = edgeLength(kx - lx, ky - ly);
+  const RR = Math.round(dR - clearance);
+  const RL = Math.round(dL - clearance);
+  const rR = Math.round(alpha * RR);
+  const rL = Math.round(alpha * RL);
+  return [
+    { name: 'bust_r', shape: 'circle', cx: rx, cy: ry, r: rR, spacing, band: RR - rR, bone: boneR },
+    { name: 'bust_l', shape: 'circle', cx: lx, cy: ly, r: rL, spacing, band: RL - rL, bone: boneL },
+  ];
+}
+
+/**
+ * Every contour region on `spec`: its hand-given `regions` (in declared order) followed by `deriveBustRegions(spec.bust)`
+ * when `spec.bust` is declared (issue #475). When `spec.bust` is absent, returns `spec.regions ?? []`.
+ */
+export function contourRegionsOf(spec: ContourSpec): ContourRegionSpec[] {
+  if (spec.bust === undefined) return spec.regions ?? [];
+  return [...(spec.regions ?? []), ...deriveBustRegions(spec.bust)];
 }
 
 /**
@@ -1139,13 +1210,14 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
     if ('scene' in t) checkScene(c, t.scene);
     // Issue #349: the limbs' joints are their bones' origins, so the bones are read with them, and only then.
     let limbs: LimbNames | null = null;
+    let names: { bones: Set<string>; chains: Map<string, number>; parents: Map<string, string> } | null = null;
     if ('limbs' in t) {
       if (!('bones' in t)) c.fail('CONFIG_FIELD_PRESENT', 'config.bones', 'is absent; config.limbs names bones, and each joint is its bone\'s origin, so assemble reads the bones with the limbs');
-      const names = 'bones' in t ? checkBones(c, t.bones) : null;
+      names = 'bones' in t ? checkBones(c, t.bones) : null;
       limbs = checkLimbs(c, t.limbs, made, names);
     }
     if (isPlainObject(t.assemble) && 'alternates' in t.assemble) {
-      checkAlternates(c, t.assemble.alternates, made, limbs, null);
+      checkAlternates(c, t.assemble.alternates, made, limbs, names?.bones ?? null, names?.chains ?? null, t.regions, t.meshes);
     }
   }
   if ('cloth' in t) checkCloth(c, t.cloth);
@@ -1297,7 +1369,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   const names = 'bones' in t ? checkBones(c, t.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
   const limbs = 'limbs' in t ? checkLimbs(c, t.limbs, { parts, patches, cuts }, 'bones' in t ? names : null) : null;
   if (isPlainObject(t.assemble) && 'alternates' in t.assemble) {
-    checkAlternates(c, t.assemble.alternates, { parts, patches, cuts }, limbs, names.bones);
+    checkAlternates(c, t.assemble.alternates, { parts, patches, cuts }, limbs, names.bones, names.chains, t.regions, t.meshes);
   }
   if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains);
   if ('regions' in t) checkRegions(c, t.regions, names.bones);
@@ -1312,7 +1384,10 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('cloth' in t) checkCloth(c, t.cloth);
   const from = isPlainObject(t.motion) ? t.motion.animations_from : undefined;
   const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, resolve(base, from)) : null;
-  if (animations !== null) checkFaceAnimationBand(c, animations, hasAltFace, t.turn, attached);
+  if (animations !== null) {
+    checkFaceAnimationBand(c, animations, hasAltFace, t.turn, attached);
+    checkAnimationSetKeys(c, animations, t.assemble, new Set<string>([...parts, ...patches, ...cuts, ...(limbs?.parts.keys() ?? [])]));
+  }
   if (base !== null) poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
   return { config: raw as CharacterConfig, animations };
@@ -1828,10 +1903,18 @@ function checkAlternates(
   made: { parts: string[]; patches: string[]; cuts: string[] },
   limbs: LimbNames | null,
   bones: Set<string> | null = null,
+  chains: Map<string, number> | null = null,
+  regions: Json = undefined,
+  meshes: Json = undefined,
 ): void {
   const p = 'config.assemble.alternates';
   if (!c.array(p, v, true)) return;
-  const allSlots = new Set<string>([...made.parts, ...made.patches, ...made.cuts, ...(limbs?.parts.keys() ?? [])]);
+  const allSlots = new Set<string>([
+    ...made.parts.filter((n) => !(limbs?.consumed.has(n) ?? false)),
+    ...made.patches,
+    ...made.cuts,
+    ...(limbs?.parts.keys() ?? []),
+  ]);
   const seenNames = new Map<string, number>();
   (v as Json[]).forEach((entry, i) => {
     const at = `${p}[${i}]`;
@@ -1860,29 +1943,135 @@ function checkAlternates(
     }
     if ('head_box' in e) checkHeadBox(c, `${at}.head_box`, e.head_box);
     const altCuts = 'cuts' in e ? checkCuts(c, e.cuts, made.parts, [], `${at}.cuts`) : [];
+    let cutsConsumedLimb = false;
+    if (limbs !== null && 'cuts' in e && Array.isArray(e.cuts)) {
+      e.cuts.forEach((ce, ci) => {
+        if (!isPlainObject(ce) || typeof ce.from !== 'string') return;
+        const byLimb = limbs.consumed.get(ce.from);
+        if (byLimb !== undefined) {
+          cutsConsumedLimb = true;
+          const segList = (limbs.chains.get(byLimb)?.parts ?? []).map((s) => `"${s}"`).join(', ');
+          c.fail(
+            'CONFIG_LIMB_SET_JOINTS',
+            `${at}.cuts[${ci}].from`,
+            `cuts "${ce.from}", which config.limbs.${byLimb} cuts at the base's joints into ${segList}; a gesture set over a limb chain is cut at the base's joints and may not declare its own polygon cuts for that layer`,
+          );
+        }
+      });
+    }
     const validParts = new Set<string>([...allSlots, ...altCuts]);
+    const seenParts = new Set<string>();
     if ('parts' in e && c.array(`${at}.parts`, e.parts, true)) {
-      const seen = new Set<string>();
       (e.parts as Json[]).forEach((pn, k) => {
         if (!c.string(`${at}.parts[${k}]`, pn)) return;
-        if (!validParts.has(pn)) {
+        const byLimb = limbs?.consumed.get(pn);
+        if (byLimb !== undefined) {
+          const segList = (limbs?.chains.get(byLimb)?.parts ?? []).map((s) => `"${s}"`).join(', ');
+          c.fail(
+            'CONFIG_LIMB_SET_JOINTS',
+            `${at}.parts[${k}]`,
+            `names "${pn}", which config.limbs.${byLimb} cuts at the base's joints into ${segList}; a gesture set covers the limb chain's segment parts at the base's joints, not the unsplit layer`,
+          );
+        } else if (!validParts.has(pn)) {
           c.fail('CONFIG_NAME_RESOLVES', `${at}.parts[${k}]`, `is ${show(pn)}; a slot of the base rig (or a part made by this alternate's cuts) is required`);
-        } else if (seen.has(pn)) {
+        } else if (seenParts.has(pn)) {
           c.fail('CONFIG_PART_UNIQUE', `${at}.parts[${k}]`, `repeats "${pn}"; each covered part is named once`);
-        } else seen.add(pn);
+        } else seenParts.add(pn);
       });
     }
+    const seenHides = new Set<string>();
     if ('hides' in e && c.array(`${at}.hides`, e.hides, false)) {
-      const seen = new Set<string>();
       (e.hides as Json[]).forEach((hn, k) => {
         if (!c.string(`${at}.hides[${k}]`, hn)) return;
-        if (!allSlots.has(hn)) {
+        const byLimb = limbs?.consumed.get(hn);
+        if (byLimb !== undefined) {
+          const segList = (limbs?.chains.get(byLimb)?.parts ?? []).map((s) => `"${s}"`).join(', ');
+          c.fail(
+            'CONFIG_LIMB_SET_JOINTS',
+            `${at}.hides[${k}]`,
+            `names "${hn}", which config.limbs.${byLimb} cuts at the base's joints into ${segList}; a gesture set covers the limb chain's segment parts at the base's joints, not the unsplit layer`,
+          );
+        } else if (!allSlots.has(hn)) {
           c.fail('CONFIG_NAME_RESOLVES', `${at}.hides[${k}]`, `is ${show(hn)}; a slot of the base rig is required`);
-        } else if (seen.has(hn)) {
+        } else if (seenHides.has(hn)) {
           c.fail('CONFIG_PART_UNIQUE', `${at}.hides[${k}]`, `repeats "${hn}"; each hidden slot is named once`);
-        } else seen.add(hn);
+        } else seenHides.add(hn);
       });
     }
+    if ('parts' in e && limbs !== null) {
+      for (const [limbName, chain] of limbs.chains) {
+        const coveredSegs = chain.parts.filter((sp) => seenParts.has(sp) && !seenHides.has(sp));
+        const hiddenSegs = chain.parts.filter((sp) => seenHides.has(sp));
+        if ((coveredSegs.length > 0 || hiddenSegs.length > 0) && coveredSegs.length !== chain.parts.length) {
+          c.fail(
+            'CONFIG_LIMB_SET_JOINTS',
+            `${at}.parts`,
+            `covers [${coveredSegs.map((s) => `"${s}"`).join(', ')}]${hiddenSegs.length > 0 ? ` (and hides [${hiddenSegs.map((s) => `"${s}"`).join(', ')}])` : ''} of config.limbs.${limbName}, which cuts at the base's joints into [${chain.parts.map((s) => `"${s}"`).join(', ')}]; a gesture set over a limb chain must cover all ${chain.parts.length} of its segment parts so it is cut at the base's joints`,
+          );
+        } else if (coveredSegs.length === chain.parts.length && !cutsConsumedLimb && 'cuts' in e && Array.isArray(e.cuts) && e.cuts.length > 0) {
+          c.fail(
+            'CONFIG_LIMB_SET_JOINTS',
+            `${at}.cuts`,
+            `declares custom polygon cuts on a gesture set covering config.limbs.${limbName}; a gesture set is cut at the base's joints and declares no cuts of its own`,
+          );
+        }
+      }
+    }
+    if ('parts' in e && 'drawn' in e && isPlainObject(e.drawn)) {
+      const activeParts = [...seenParts].filter((pn) => !seenHides.has(pn));
+      const coveredBones = new Set<string>();
+      let allPartsResolved = activeParts.length > 0;
+      for (const pn of activeParts) {
+        const limbSeg = limbs?.parts.get(pn);
+        if (limbSeg !== undefined) {
+          coveredBones.add(limbSeg.bone);
+        } else if (isPlainObject(regions) && typeof regions[pn] === 'string') {
+          coveredBones.add(regions[pn]);
+        } else if (isPlainObject(meshes) && isPlainObject(meshes[pn])) {
+          const m = meshes[pn] as Record<string, Json>;
+          if (Array.isArray(m.segments)) {
+            for (const s of m.segments) {
+              if (typeof s === 'string') {
+                const links = chains?.get(s);
+                if (links !== undefined) {
+                  for (let lk = 0; lk < links; lk++) coveredBones.add(`${s}${lk}`);
+                } else {
+                  coveredBones.add(s);
+                }
+              } else if (Array.isArray(s) && typeof s[0] === 'string') {
+                coveredBones.add(s[0]);
+              }
+            }
+          }
+          if (isPlainObject(m.contour)) {
+            if (Array.isArray(m.contour.regions)) {
+              for (const rg of m.contour.regions) if (isPlainObject(rg) && typeof rg.bone === 'string') coveredBones.add(rg.bone);
+            }
+            if (isPlainObject(m.contour.bust)) {
+              coveredBones.add(typeof m.contour.bust.bone_r === 'string' ? m.contour.bust.bone_r : DEFAULT_BUST_BONE_R);
+              coveredBones.add(typeof m.contour.bust.bone_l === 'string' ? m.contour.bust.bone_l : DEFAULT_BUST_BONE_L);
+            }
+          }
+          if (isPlainObject(m.auto) && Array.isArray(m.auto.regions)) {
+            for (const rg of m.auto.regions) if (isPlainObject(rg) && typeof rg.bone === 'string') coveredBones.add(rg.bone);
+          }
+        } else {
+          allPartsResolved = false;
+        }
+      }
+      if (allPartsResolved) {
+        const coveredList = [...coveredBones].map((b) => `"${b}"`).join(', ') || 'none';
+        for (const bName of Object.keys(e.drawn)) {
+          if ((bones === null || bones.has(bName)) && !coveredBones.has(bName)) {
+            c.fail(
+              'CONFIG_SET_COVERS_BONE',
+              `${at}.drawn.${bName}`,
+              `names "${bName}", which alternate set "${String(e.name ?? '')}" does not cover (covered bones: ${coveredList}); a subset set may state drawn angles only for the bones its covered parts ride`,
+            );
+          }
+        }
+      }
+    }
   });
 }
 
@@ -2199,7 +2388,7 @@ function checkRibs(c: Check, at: string, m: Record<string, Json>, chains: Map<st
  * the grid every region number must sit on.
  */
 function checkContour(c: Check, at: string, v: Json, bones: Set<string>): void {
-  const o = c.object(at, v, ['tolerance', 'margin', 'spacing'], ['maxEdge', 'budget', 'stray', 'bridges', 'regions']);
+  const o = c.object(at, v, ['tolerance', 'margin', 'spacing'], ['maxEdge', 'budget', 'stray', 'bridges', 'regions', 'bust']);
   if (o === null) return;
   if ('tolerance' in o) c.number(`${at}.tolerance`, o.tolerance, 'non-negative');
   if ('margin' in o && c.number(`${at}.margin`, o.margin, 'non-negative') && (o.margin as number) > 0 && (o.margin as number) < 1) {
@@ -2210,46 +2399,117 @@ function checkContour(c: Check, at: string, v: Json, bones: Set<string>): void {
   if ('budget' in o) c.int(`${at}.budget`, o.budget, 3);
   if ('stray' in o) c.int(`${at}.stray`, o.stray, 0);
   if ('bridges' in o && o.bridges !== true) c.fail('CONFIG_FIELD_TYPE', `${at}.bridges`, `is ${show(o.bridges)}; true is required (every island joined into one outline by bridges, issue #326) — remove the field for the one-island rule`);
-  if (!('regions' in o) || !c.array(`${at}.regions`, o.regions, false)) return;
+  const onGrid = (path: string, n: Json, rule: 'any' | 'positive' | 'non-negative'): void => {
+    if (!c.number(path, n, rule)) return;
+    const v2 = n as number;
+    if (!Number.isInteger(v2 * GRID) || Math.abs(v2) > MAX_SIDE) {
+      c.fail('CONFIG_FIELD_TYPE', path, `is ${v2}; a multiple of 1/${GRID} px within ±${MAX_SIDE} px is required — a region's weight is 1 inside it and 0 past its band, and those two are decided exactly on that grid`);
+    }
+  };
   const names = new Set<string>();
-  (o.regions as Json[]).forEach((rv, i) => {
-    const rat = `${at}.regions[${i}]`;
-    const shape = typeof rv === 'object' && rv !== null && !Array.isArray(rv) ? (rv as Record<string, Json>).shape : undefined;
-    const own = shape === 'circle' ? ['cx', 'cy', 'r'] : shape === 'polygon' ? ['points'] : [];
-    const r = c.object(rat, rv, ['name', 'shape', 'bone', 'spacing', 'band', ...own], []);
-    if (r === null) return;
-    if ('shape' in r && own.length === 0) c.fail('CONFIG_FIELD_TYPE', `${rat}.shape`, `is ${show(r.shape)}; "circle" (with cx, cy, r) or "polygon" (with points) is required`);
-    if ('name' in r && c.string(`${rat}.name`, r.name)) {
-      if (names.has(r.name)) c.fail('CONFIG_REGION_NAME_UNIQUE', `${rat}.name`, `"${r.name}" is declared twice in this mesh; each region needs its own name`);
-      names.add(r.name);
-    }
-    if ('bone' in r && (typeof r.bone !== 'string' || !bones.has(r.bone))) {
-      c.fail('CONFIG_NAME_RESOLVES', `${rat}.bone`, `is ${show(r.bone)}; a bone config.bones declares is required — the region's control bone`);
-    }
-    const onGrid = (path: string, n: Json, rule: 'any' | 'positive' | 'non-negative'): void => {
-      if (!c.number(path, n, rule)) return;
-      const v2 = n as number;
-      if (!Number.isInteger(v2 * GRID) || Math.abs(v2) > MAX_SIDE) {
-        c.fail('CONFIG_FIELD_TYPE', path, `is ${v2}; a multiple of 1/${GRID} px within ±${MAX_SIDE} px is required — a region's weight is 1 inside it and 0 past its band, and those two are decided exactly on that grid`);
+  if ('regions' in o && c.array(`${at}.regions`, o.regions, false)) {
+    (o.regions as Json[]).forEach((rv, i) => {
+      const rat = `${at}.regions[${i}]`;
+      const shape = typeof rv === 'object' && rv !== null && !Array.isArray(rv) ? (rv as Record<string, Json>).shape : undefined;
+      const own = shape === 'circle' ? ['cx', 'cy', 'r'] : shape === 'polygon' ? ['points'] : [];
+      const r = c.object(rat, rv, ['name', 'shape', 'bone', 'spacing', 'band', ...own], []);
+      if (r === null) return;
+      if ('shape' in r && own.length === 0) c.fail('CONFIG_FIELD_TYPE', `${rat}.shape`, `is ${show(r.shape)}; "circle" (with cx, cy, r) or "polygon" (with points) is required`);
+      if ('name' in r && c.string(`${rat}.name`, r.name)) {
+        if (names.has(r.name)) c.fail('CONFIG_REGION_NAME_UNIQUE', `${rat}.name`, `"${r.name}" is declared twice in this mesh; each region needs its own name`);
+        names.add(r.name);
+      }
+      if ('bone' in r && (typeof r.bone !== 'string' || !bones.has(r.bone))) {
+        c.fail('CONFIG_NAME_RESOLVES', `${rat}.bone`, `is ${show(r.bone)}; a bone config.bones declares is required — the region's control bone`);
+      }
+      if ('spacing' in r) c.number(`${rat}.spacing`, r.spacing, 'positive');
+      if ('band' in r) onGrid(`${rat}.band`, r.band, 'non-negative');
+      if (shape === 'circle') {
+        if ('cx' in r) onGrid(`${rat}.cx`, r.cx, 'any');
+        if ('cy' in r) onGrid(`${rat}.cy`, r.cy, 'any');
+        if ('r' in r) onGrid(`${rat}.r`, r.r, 'positive');
+      }
+      if (shape === 'polygon' && 'points' in r && c.array(`${rat}.points`, r.points, true)) {
+        const pts = r.points as Json[];
+        if (pts.length < 3) c.fail('CONFIG_FIELD_TYPE', `${rat}.points`, `has ${pts.length} point(s); 3 or more [x, y] in rig pixels are required`);
+        pts.forEach((p, k) => {
+          if (!c.point(`${rat}.points[${k}]`, p)) return;
+          onGrid(`${rat}.points[${k}][0]`, (p as Point)[0], 'any');
+          onGrid(`${rat}.points[${k}][1]`, (p as Point)[1], 'any');
+        });
+      }
+    });
+  }
+  if ('bust' in o) {
+    const bat = `${at}.bust`;
+    const b = c.object(bat, o.bust, ['apex_r', 'apex_l', 'cleavage'], ['alpha', 'clearance', 'bone_r', 'bone_l', 'spacing']);
+    if (b === null) return;
+    for (const dup of ['bust_r', 'bust_l'] as const) {
+      if (names.has(dup)) {
+        c.fail('CONFIG_REGION_NAME_UNIQUE', bat, `"${dup}" is declared in both ${at}.regions and ${bat}; give either ${bat} or hand-written bust_r/bust_l in ${at}.regions, not both`);
       }
-    };
-    if ('spacing' in r) c.number(`${rat}.spacing`, r.spacing, 'positive');
-    if ('band' in r) onGrid(`${rat}.band`, r.band, 'non-negative');
-    if (shape === 'circle') {
-      if ('cx' in r) onGrid(`${rat}.cx`, r.cx, 'any');
-      if ('cy' in r) onGrid(`${rat}.cy`, r.cy, 'any');
-      if ('r' in r) onGrid(`${rat}.r`, r.r, 'positive');
-    }
-    if (shape === 'polygon' && 'points' in r && c.array(`${rat}.points`, r.points, true)) {
-      const pts = r.points as Json[];
-      if (pts.length < 3) c.fail('CONFIG_FIELD_TYPE', `${rat}.points`, `has ${pts.length} point(s); 3 or more [x, y] in rig pixels are required`);
-      pts.forEach((p, k) => {
-        if (!c.point(`${rat}.points[${k}]`, p)) return;
-        onGrid(`${rat}.points[${k}][0]`, (p as Point)[0], 'any');
-        onGrid(`${rat}.points[${k}][1]`, (p as Point)[1], 'any');
-      });
     }
-  });
+    let ptsOk = true;
+    for (const k of ['apex_r', 'apex_l', 'cleavage'] as const) {
+      if (!(k in b)) {
+        ptsOk = false;
+        continue;
+      }
+      if (!c.point(`${bat}.${k}`, b[k])) {
+        ptsOk = false;
+        continue;
+      }
+      onGrid(`${bat}.${k}[0]`, (b[k] as Point)[0], 'any');
+      onGrid(`${bat}.${k}[1]`, (b[k] as Point)[1], 'any');
+    }
+    let alpha = DEFAULT_BUST_ALPHA;
+    let alphaOk = true;
+    if ('alpha' in b) {
+      if (!c.number(`${bat}.alpha`, b.alpha, 'positive')) alphaOk = false;
+      else if ((b.alpha as number) >= 1) {
+        c.fail('CONFIG_FIELD_TYPE', `${bat}.alpha`, `is ${b.alpha as number}; a core ratio in (0, 1) is required (default ${DEFAULT_BUST_ALPHA})`);
+        alphaOk = false;
+      } else alpha = b.alpha as number;
+    }
+    let clearance = DEFAULT_BUST_CLEARANCE;
+    let clearanceOk = true;
+    if ('clearance' in b) {
+      if (!c.number(`${bat}.clearance`, b.clearance, 'any')) clearanceOk = false;
+      else clearance = b.clearance as number;
+    }
+    if ('spacing' in b) c.number(`${bat}.spacing`, b.spacing, 'positive');
+    for (const [k, def, regName] of [
+      ['bone_r', DEFAULT_BUST_BONE_R, 'bust_r'],
+      ['bone_l', DEFAULT_BUST_BONE_L, 'bust_l'],
+    ] as const) {
+      const bone = k in b ? b[k] : def;
+      if (typeof bone !== 'string' || !bones.has(bone)) {
+        c.fail('CONFIG_NAME_RESOLVES', `${bat}.${k}`, `is ${show(bone)}; a bone config.bones declares is required — ${regName}'s control bone`);
+      }
+    }
+    if (ptsOk && alphaOk && clearanceOk) {
+      const [rx, ry] = b.apex_r as Point;
+      const [lx, ly] = b.apex_l as Point;
+      const [kx, ky] = b.cleavage as Point;
+      const D = edgeLength(lx - rx, ly - ry);
+      const dR = edgeLength(kx - rx, ky - ry);
+      const dL = edgeLength(kx - lx, ky - ly);
+      const RR = Math.round(dR - clearance);
+      const RL = Math.round(dL - clearance);
+      const rR = Math.round(alpha * RR);
+      const rL = Math.round(alpha * RL);
+      const bandR = RR - rR;
+      const bandL = RL - rL;
+      if (clearance <= 0 || RR + RL >= D || rR <= 0 || rL <= 0 || bandR < 0 || bandL < 0) {
+        const minClearance = Math.max(0, (dR + dL - D) / 2);
+        c.fail(
+          'CONFIG_BUST_CLEARANCE',
+          `${bat}.clearance`,
+          `is ${clearance} (giving R_r = ${RR}, R_l = ${RL}, R_r + R_l = ${RR + RL} px against apex distance D = ${pyRound(D, 2)} px, r_r = ${rR}, band_r = ${bandR}, r_l = ${rL}, band_l = ${bandL}); a clearance > 0 with R_r + R_l < D (clearance > ${pyRound(minClearance, 2)} px) and positive radii is required`,
+        );
+      }
+    }
+  }
 }
 
 /**
@@ -2448,6 +2708,7 @@ function checkRegions(c: Check, v: Json, bones: Set<string>): void {
 interface LimbNames {
   parts: Map<string, { bone: string; at: string }>;
   consumed: Map<string, string>;
+  chains: Map<string, { parts: string[]; bones: string[]; froms: string[] }>;
 }
 
 /**
@@ -2473,7 +2734,7 @@ interface LimbNames {
  * resolved. Returns the limb parts and the parts the limbs take.
  */
 function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[]; cuts: string[] }, names: { bones: Set<string>; parents: Map<string, string> } | null): LimbNames {
-  const out: LimbNames = { parts: new Map(), consumed: new Map() };
+  const out: LimbNames = { parts: new Map(), consumed: new Map(), chains: new Map() };
   if (!isPlainObject(v)) {
     c.fail('CONFIG_FIELD_TYPE', 'config.limbs', `is ${show(v)}; an object of limb name -> {"segments": [...]} is required`);
     return out;
@@ -2518,11 +2779,13 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
       continue;
     }
     const segs = o.segments as Json[];
+    const segParts: Array<string | null> = [];
     const froms: Array<string | null> = [];
     const bones: Array<string | null> = [];
     segs.forEach((entry, i) => {
       const sat = `${at}.segments[${i}]`;
       const e = c.object(sat, entry, ['part', 'from', 'bone'], ['joint', 'range', 'cap', 'edge', 'cap_shape', 'cut_band']);
+      segParts.push(null);
       froms.push(null);
       bones.push(null);
       if (e === null) return;
@@ -2538,6 +2801,7 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
         } else if (firstAt.has(name)) c.fail('CONFIG_PART_UNIQUE', `${sat}.part`, `names the part "${name}" again (first at ${firstAt.get(name)})`);
         else {
           firstAt.set(name, sat);
+          segParts[i] = name;
           if ('bone' in e && typeof e.bone === 'string') out.parts.set(name, { bone: e.bone, at: `config.limbs.${limb} segment ${i}` });
         }
       }
@@ -2582,6 +2846,11 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
         }
       }
     });
+    out.chains.set(limb, {
+      parts: segParts.filter((q): q is string => q !== null),
+      bones: bones.filter((q): q is string => q !== null),
+      froms: [...new Set(froms.filter((q): q is string => q !== null))],
+    });
     limbFroms.set(limb, new Set(froms.filter((f): f is string => f !== null)));
     froms.forEach((f, i) => {
       if (f === null || i === 0 || froms[i - 1] === f) return;
@@ -3294,6 +3563,103 @@ function checkFaceAnimationBand(c: Check, animations: AnimationsFrom, hasAltFace
   }
 }
 
+/**
+ * Issue #473: an attachment track key in `motion.animations_from` may name an
+ * alternate set (`{"t": …, "set": "<name>" | null}`) instead of spelling out the
+ * `<set>_<slot>` attachment name. Refuses (`CONFIG_SET_COVERS_SLOT`) when `"set"`
+ * appears on a non-attachment track, names an undeclared alternate set, or keys a
+ * slot the set does not cover (`slots` or `hides`).
+ */
+function checkAnimationSetKeys(
+  c: Check,
+  animations: AnimationsFrom,
+  assemble: Json,
+  allSlots: Set<string>,
+): void {
+  const at = `config.motion.animations_from (${animations.file}).animations`;
+  const sets = new Map<string, { slots: Set<string>; hides: Set<string> }>();
+  if (isPlainObject(assemble) && Array.isArray(assemble.alternates)) {
+    for (const alt of assemble.alternates) {
+      if (!isPlainObject(alt) || typeof alt.name !== 'string' || alt.name === '') continue;
+      const hides = new Set<string>(
+        Array.isArray(alt.hides) ? alt.hides.filter((h): h is string => typeof h === 'string') : [],
+      );
+      const altCuts = Array.isArray(alt.cuts)
+        ? alt.cuts.filter(isPlainObject).map((cu) => cu.into).filter((s): s is string => typeof s === 'string')
+        : [];
+      const slots = Array.isArray(alt.parts)
+        ? new Set<string>(alt.parts.filter((p): p is string => typeof p === 'string' && !hides.has(p)))
+        : new Set<string>([...allSlots, ...altCuts].filter((p) => !hides.has(p)));
+      sets.set(alt.name, { slots, hides });
+    }
+  }
+  const declaredSets = sets.size === 0 ? 'none' : [...sets.keys()].map((n) => `"${n}"`).join(', ');
+  for (const [animName, anim] of Object.entries(animations.table)) {
+    if (!isPlainObject(anim) || !Array.isArray(anim.tracks)) continue;
+    anim.tracks.forEach((tr, ti) => {
+      if (!isPlainObject(tr) || !Array.isArray(tr.keys)) return;
+      const slot = typeof tr.slot === 'string' && tr.slot !== '' ? tr.slot : null;
+      const isAttachmentTrack = tr.property === 'attachment' && slot !== null;
+      tr.keys.forEach((k, ki) => {
+        if (!isPlainObject(k) || !('set' in k)) return;
+        const keyAt = `${at}.${animName}.tracks[${ti}].keys[${ki}].set`;
+        if (!isAttachmentTrack || slot === null) {
+          c.fail(
+            'CONFIG_SET_COVERS_SLOT',
+            keyAt,
+            `is ${show(k.set)} on a ${show(tr.property)} track${slot === null ? '' : ` for slot "${slot}"`}; a "set" key belongs on a slot attachment track ({"slot": "<part>", "property": "attachment", "keys": [{"t": …, "set": "<name>" | null}]})`,
+          );
+          return;
+        }
+        if ('v' in k) {
+          c.fail(
+            'CONFIG_FIELD_TYPE',
+            keyAt,
+            `is declared beside v (${show(k.v)}); state either "set": "<name>" | null or "v": "<attachment>" | null on an attachment key, not both`,
+          );
+          return;
+        }
+        const setVal = k.set;
+        if (setVal === null) {
+          if (!allSlots.has(slot)) {
+            c.fail(
+              'CONFIG_SET_COVERS_SLOT',
+              keyAt,
+              `restores the base attachment on slot "${slot}", which is not a declared slot of the rig (declared slots: ${[...allSlots].map((s) => `"${s}"`).join(', ')})`,
+            );
+          }
+          return;
+        }
+        if (typeof setVal !== 'string' || setVal === '') {
+          c.fail(
+            'CONFIG_FIELD_TYPE',
+            keyAt,
+            `is ${show(setVal)}; a non-empty alternate set name or null (the base pose) is required`,
+          );
+          return;
+        }
+        const entry = sets.get(setVal);
+        if (entry === undefined) {
+          c.fail(
+            'CONFIG_SET_COVERS_SLOT',
+            keyAt,
+            `names alternate set "${setVal}" for slot "${slot}", which config.assemble.alternates does not declare (declared sets: ${declaredSets})`,
+          );
+          return;
+        }
+        if (!entry.slots.has(slot) && !entry.hides.has(slot)) {
+          const covered = [...entry.slots, ...entry.hides].map((s) => `"${s}"`).join(', ') || 'none';
+          c.fail(
+            'CONFIG_SET_COVERS_SLOT',
+            keyAt,
+            `names alternate set "${setVal}" on slot "${slot}", which set "${setVal}" does not cover (set "${setVal}" covers: ${covered}); add "${slot}" to that set's parts (or hides) in config.assemble.alternates, or key a slot the set covers`,
+          );
+        }
+      });
+    });
+  }
+}
+
 function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>, hasAltFace: boolean): void {
   const at = 'config.turn';
   const o = c.object(at, v, ['pivot', 'depths'], ['head', 'deform', 'band', 'radius', 'surface']);