@rig-c/parts 1.67.0 → 1.69.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/config.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { baseAnchorProblems, type BaseAnchor } from './baseanchor.ts';
2
+ import type { DepthConfig } from './depthsheets.ts';
1
3
  /**
2
4
  * The character config: everything character-specific the CPU stages read,
3
5
  * plus the optional blocks for the two GPU stages.
@@ -97,7 +99,7 @@ import { edgeLength } from './length.ts';
97
99
  import { setFocusProblems } from './setfocus.ts';
98
100
  import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, scaledPoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
99
101
  import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
100
- 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';
102
+ import { EAR_DEPTH_RANGE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, FACESHIFT_BONE, REAR_SHIFT_BONE, TURN_BONE, TURN_ROLES, type TurnSpec, turnNearest, turnSurfaceBone } from './turn.ts';
101
103
  import { FLOOR_FORMS, type FloorForm, type MeshInfluences } from './weights.ts';
102
104
 
103
105
  export type Point = [number, number];
@@ -266,6 +268,8 @@ export interface Cut {
266
268
 
267
269
  export interface AlternateSetConfig {
268
270
  name: string;
271
+ /** Opt-in base region offsets on explicitly selected local axes, with paired painting patches. */
272
+ base_anchor?: BaseAnchor;
269
273
  /** Authored point on this painting, x right/y down; omitted means no focus. */
270
274
  focus?: Point;
271
275
  source?: string;
@@ -1039,6 +1043,7 @@ export type LimbLayout = { parts?: string[] } & (
1039
1043
  );
1040
1044
 
1041
1045
  export interface CharacterConfig {
1046
+ depth?: DepthConfig;
1042
1047
  key: string;
1043
1048
  note?: string;
1044
1049
  generation?: Generation;
@@ -1378,6 +1383,7 @@ export interface PaintConfig {
1378
1383
  * bones, meshes, regions and motion that are written only after them.
1379
1384
  */
1380
1385
  export interface EarlyConfig {
1386
+ depth?: DepthConfig;
1381
1387
  key: string;
1382
1388
  seethrough: SeeThrough;
1383
1389
  assemble: { rig_scale: number; head_face_underfill?: boolean };
@@ -1385,6 +1391,7 @@ export interface EarlyConfig {
1385
1391
 
1386
1392
  /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
1387
1393
  export interface AssembleConfig {
1394
+ depth?: DepthConfig;
1388
1395
  key: string;
1389
1396
  seethrough: SeeThrough;
1390
1397
  assemble: Assemble;
@@ -1397,7 +1404,7 @@ export interface AssembleConfig {
1397
1404
  proposed_rig_scale?: number;
1398
1405
  }
1399
1406
 
1400
- const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale', 'requirements', 'motion_seams'] as const;
1407
+ const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale', 'requirements', 'motion_seams', 'depth'] as const;
1401
1408
 
1402
1409
  /**
1403
1410
  * The one partial entry point. It validates exactly what its door requires —
@@ -1428,6 +1435,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
1428
1435
  const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
1429
1436
  if (top === null) refuseIfAny(c.problems);
1430
1437
  const t = top as Record<string, Json>;
1438
+ if ('depth' in t) checkDepthConfig(c, t.depth);
1431
1439
  if ('key' in t) c.string('config.key', t.key);
1432
1440
  if ('generation' in t) checkGeneration(c, t.generation);
1433
1441
  else if (needed.includes('generation')) {
@@ -1651,6 +1659,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
1651
1659
  const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
1652
1660
  if (top === null) refuseIfAny(c.problems);
1653
1661
  const t = top as Record<string, Json>;
1662
+ if ('depth' in t) checkDepthConfig(c, t.depth);
1654
1663
  if ('key' in t) c.string('config.key', t.key);
1655
1664
  if ('generation' in t) checkGeneration(c, t.generation);
1656
1665
  if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
@@ -1670,7 +1679,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
1670
1679
  const attached = attachedParts(t.meshes, t.regions);
1671
1680
  if ('motion_seams' in t) c.problems.push(...motionSeamProblems(t.motion_seams, attached, 'config.motion_seams', 'CONFIG_MOTION_SEAM'));
1672
1681
  const hasAltFace = hasAlternateFaceSet(t.assemble, [...parts, ...cuts]);
1673
- if ('turn' in t) checkTurn(c, t.turn, attached, names.bones, hasAltFace);
1682
+ if ('turn' in t) checkTurn(c, t.turn, attached, names.bones, hasAltFace, parts);
1674
1683
  if ('scene' in t) checkScene(c, t.scene);
1675
1684
  if ('cloth' in t) checkCloth(c, t.cloth);
1676
1685
  if ('requirements' in t && c.string('config.requirements', t.requirements) && base !== null) checkRequirementsFile(c, resolve(base, t.requirements));
@@ -2261,7 +2270,7 @@ function checkAlternates(
2261
2270
  const seenNames = new Map<string, number>();
2262
2271
  (v as Json[]).forEach((entry, i) => {
2263
2272
  const at = `${p}[${i}]`;
2264
- const e = c.object(at, entry, ['name'], ['source', 'full', 'head', 'parts', 'hides', 'head_box', 'cuts', 'skeleton', 'anchor', 'drawn', 'tips', 'front', 'layers', 'focus']);
2273
+ const e = c.object(at, entry, ['name'], ['source', 'full', 'head', 'parts', 'hides', 'head_box', 'cuts', 'skeleton', 'anchor', 'drawn', 'tips', 'front', 'layers', 'focus', 'base_anchor']);
2265
2274
  if (e === null) return;
2266
2275
  if ('name' in e && c.string(`${at}.name`, e.name)) {
2267
2276
  if (!partNameOk(e.name)) c.fail('CONFIG_PART_NAME', `${at}.name`, `names the set ${show(e.name)}; a set name is a file prefix, so it may not be empty, start with "." or hold a slash`);
@@ -2374,6 +2383,7 @@ function checkAlternates(
2374
2383
  if (typeof layer !== 'string' || readLayerTag(layer) === null) c.fail('CONFIG_TAG_KNOWN', path, `is ${show(layer)}; a See-through v3 tag or "${AUTHOR_PREFIX}<label>" is required; ${AUTHOR_LABEL_RULE}`);
2375
2384
  }
2376
2385
  }
2386
+ if ('base_anchor' in e) c.problems.push(...baseAnchorProblems(e.base_anchor, `${at}.base_anchor`, new Set([...('parts' in e ? seenParts : baseSlots)].filter(n => !seenHides.has(n))), new Set(made.patches), isPlainObject(regions) ? new Set(Object.keys(regions).filter(n => !isPlainObject(meshes) || !Object.hasOwn(meshes, n))) : undefined));
2377
2387
  // Issue #664: a part the set draws on its front slot is one the set covers and a limb declares a front slot for.
2378
2388
  if ('front' in e) {
2379
2389
  if (!Array.isArray(e.front) || e.front.length === 0) {
@@ -4125,6 +4135,7 @@ export function loadClothConfig(path: string): { key: string; cloth: ClothRecipe
4125
4135
  const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
4126
4136
  if (top === null) refuseIfAny(c.problems);
4127
4137
  const t = top as Record<string, Json>;
4138
+ if ('depth' in t) checkDepthConfig(c, t.depth);
4128
4139
  if ('key' in t) c.string('config.key', t.key);
4129
4140
  if ('cloth' in t) checkCloth(c, t.cloth);
4130
4141
  refuseIfAny(c.problems);
@@ -4189,7 +4200,7 @@ function checkFaceAnimationBand(c: Check, animations: AnimationsFrom, hasAltFace
4189
4200
  'config.turn',
4190
4201
  "is absent and required when motion.animations_from carries a turn or tilt slider animation with derive keys; copy the turn block propose drafted into config.turn so the head pivot and each head part's depth are declared",
4191
4202
  );
4192
- } else if (isPlainObject(turn) && isPlainObject(turn.depths) && attached !== undefined) {
4203
+ } else if (isPlainObject(turn) && isPlainObject(turn.depths) && !isPlainObject(turn.roles) && attached !== undefined) {
4193
4204
  for (const reqPart of ['face', 'hair_front', 'hair_back'] as const) {
4194
4205
  if (attached.has(reqPart) && !(reqPart in turn.depths)) {
4195
4206
  c.fail(
@@ -4353,11 +4364,98 @@ function checkAnimationSetKeys(
4353
4364
  }
4354
4365
  }
4355
4366
 
4356
- function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>, hasAltFace: boolean): void {
4367
+ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>, hasAltFace: boolean, parts: readonly string[] = []): void {
4357
4368
  const at = 'config.turn';
4358
- const o = c.object(at, v, ['pivot', 'depths'], ['head', 'deform', 'band', 'radius', 'surface']);
4369
+ const hasRoles = isPlainObject(v) && 'roles' in v;
4370
+ const o = hasRoles
4371
+ ? c.object(at, v, ['roles'], ['pivot', 'depths', 'counter', 'grid', 'unitDepths', 'head', 'deform', 'band', 'radius', 'surface'])
4372
+ : c.object(at, v, ['pivot', 'depths'], ['roles', 'counter', 'grid', 'unitDepths', 'head', 'deform', 'band', 'radius', 'surface']);
4359
4373
  if (o === null) return;
4360
4374
  const pivot = 'pivot' in o && c.number(`${at}.pivot`, o.pivot) ? (o.pivot as number) : null;
4375
+ if ('counter' in o && c.number(`${at}.counter`, o.counter)) {
4376
+ const cnt = o.counter as number;
4377
+ if (cnt < 0 || cnt > 1) {
4378
+ c.fail('CONFIG_TURN_COUNTER_RANGE', `${at}.counter`, `is ${cnt}; a rear counter fraction in [0, 1] is required`);
4379
+ }
4380
+ }
4381
+ if ('grid' in o) {
4382
+ const checkGridPair = (gAt: string, gv: Json): void => {
4383
+ if (!Array.isArray(gv) || gv.length !== 2 || !gv.every((n) => typeof n === 'number' && Number.isInteger(n) && n >= 2)) {
4384
+ c.fail('CONFIG_FIELD_TYPE', gAt, `is ${show(gv)}; a [cols, rows] pair of integers >= 2 is required`);
4385
+ }
4386
+ };
4387
+ if (Array.isArray(o.grid)) {
4388
+ checkGridPair(`${at}.grid`, o.grid);
4389
+ } else if (isPlainObject(o.grid)) {
4390
+ for (const [part, gv] of Object.entries(o.grid)) {
4391
+ if (isRecordKey(part)) continue;
4392
+ if (!attached.has(part)) {
4393
+ c.fail('CONFIG_NAME_RESOLVES', `${at}.grid.${part}`, `names "${part}", which neither config.meshes nor config.regions attaches`);
4394
+ }
4395
+ checkGridPair(`${at}.grid.${part}`, gv);
4396
+ }
4397
+ } else {
4398
+ c.fail('CONFIG_FIELD_TYPE', `${at}.grid`, `is ${show(o.grid)}; a [cols, rows] pair or object of part -> [cols, rows] is required`);
4399
+ }
4400
+ }
4401
+ if ('unitDepths' in o) {
4402
+ if (!isPlainObject(o.unitDepths)) {
4403
+ c.fail('CONFIG_FIELD_TYPE', `${at}.unitDepths`, `is ${show(o.unitDepths)}; an object of part or bone name -> scalar depth is required`);
4404
+ } else {
4405
+ for (const [k, dv] of Object.entries(o.unitDepths)) {
4406
+ if (isRecordKey(k)) continue;
4407
+ if (!attached.has(k) && !bones.has(k)) {
4408
+ c.fail('CONFIG_NAME_RESOLVES', `${at}.unitDepths.${k}`, `names "${k}", which is neither an attached part nor a declared bone`);
4409
+ }
4410
+ c.number(`${at}.unitDepths.${k}`, dv);
4411
+ }
4412
+ }
4413
+ }
4414
+ if ('roles' in o) {
4415
+ const r = o.roles;
4416
+ if (!isPlainObject(r) || Object.keys(r).length === 0) {
4417
+ c.fail('CONFIG_FIELD_TYPE', `${at}.roles`, `is ${show(r)}; a non-empty object of part name -> ("surface" | "unit" | "rear") is required`);
4418
+ } else {
4419
+ const surfaceParts: string[] = [];
4420
+ const earParts: string[] = [];
4421
+ for (const [part, role] of Object.entries(r)) {
4422
+ if (isRecordKey(part)) continue;
4423
+ if (!attached.has(part)) {
4424
+ c.fail('CONFIG_NAME_RESOLVES', `${at}.roles.${part}`, `names "${part}", which neither config.meshes nor config.regions attaches; a part the rig draws is required`);
4425
+ }
4426
+ if (typeof role !== 'string' || !(TURN_ROLES as readonly string[]).includes(role)) {
4427
+ c.fail('CONFIG_TURN_ROLE_UNKNOWN', `${at}.roles.${part}`, `is ${show(role)}; expected one of ${TURN_ROLES.map((x) => `"${x}"`).join(', ')}`);
4428
+ } else {
4429
+ if (role === 'surface') surfaceParts.push(part);
4430
+ if (role === 'unit' && (part === 'ear_r' || part === 'ear_l')) earParts.push(part);
4431
+ }
4432
+ }
4433
+ if (surfaceParts.length === 0) {
4434
+ c.fail('CONFIG_TURN_SURFACE_REQUIRED', `${at}.roles`, 'declares no part with role "surface"; at least one surface part (such as "face") is required for 2.5D head turn');
4435
+ }
4436
+ for (const ear of earParts) {
4437
+ const earIdx = parts.indexOf(ear);
4438
+ for (const surf of surfaceParts) {
4439
+ const surfIdx = parts.indexOf(surf);
4440
+ if (earIdx !== -1 && surfIdx !== -1 && earIdx > surfIdx) {
4441
+ c.fail(
4442
+ 'CONFIG_TURN_EAR_DRAW_ORDER',
4443
+ `${at}.roles.${ear}`,
4444
+ `draws "${ear}" (plan index ${earIdx}) after surface part "${surf}" (plan index ${surfIdx}); place "${ear}" before "${surf}" in config.assemble.plan so the ear is occluded behind the face`,
4445
+ );
4446
+ }
4447
+ }
4448
+ }
4449
+ if (!bones.has('head')) {
4450
+ c.fail('CONFIG_TURN_HEAD_BONE', `${at}.roles`, 'requires a declared "head" bone in config.bones to parent the 2.5D turn carriers');
4451
+ }
4452
+ for (const reserved of [FACESHIFT_BONE, REAR_SHIFT_BONE, ...surfaceParts.map(turnSurfaceBone)]) {
4453
+ if (bones.has(reserved)) {
4454
+ c.fail('CONFIG_TURN_BONE_FREE', `bone "${reserved}"`, `is a carrier bone the rig stage adds under head for config.turn.roles, and config.bones already declares a bone of that name; rename it`);
4455
+ }
4456
+ }
4457
+ }
4458
+ }
4361
4459
  if ('radius' in o) c.number(`${at}.radius`, o.radius, 'positive');
4362
4460
  if ('surface' in o) {
4363
4461
  const so = c.object(`${at}.surface`, o.surface, [], ['radius']);
@@ -4453,7 +4551,7 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>,
4453
4551
  }
4454
4552
  }
4455
4553
  }
4456
- if (pivot !== null && depthsOk) {
4554
+ if (!hasRoles && pivot !== null && depthsOk) {
4457
4555
  const nearest = turnNearest(depths);
4458
4556
  if (nearest !== null && !(pivot > nearest.depth)) {
4459
4557
  c.fail(
@@ -4463,7 +4561,7 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>,
4463
4561
  );
4464
4562
  }
4465
4563
  }
4466
- if (headPivot !== null && depthsOk) {
4564
+ if (!hasRoles && headPivot !== null && depthsOk) {
4467
4565
  const nearest = turnNearest(depths);
4468
4566
  if (nearest !== null && !(headPivot > nearest.depth)) {
4469
4567
  c.fail(
@@ -4473,7 +4571,34 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>,
4473
4571
  );
4474
4572
  }
4475
4573
  }
4476
- if (bones.has(TURN_BONE)) {
4574
+ if (!hasRoles && bones.has(TURN_BONE)) {
4477
4575
  c.fail('CONFIG_TURN_BONE_FREE', `bone "${TURN_BONE}"`, `is the control the rig stage adds under root for config.turn, and config.bones already declares a bone of that name; rename it`);
4478
4576
  }
4479
4577
  }
4578
+
4579
+ /** #773: all scalar units and user polarity are authored, never inferred. */
4580
+ function checkDepthConfig(c: Check, raw: Json): void {
4581
+ const d = c.object('config.depth', raw, [], ['zScale', 'full', 'head']);
4582
+ if (d === null) return;
4583
+ const scale = (path: string, v: Json | undefined): void => {
4584
+ if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) c.fail('DEPTH_ZSCALE_REQUIRED', path, `is ${show(v)}; positive finite authored world units are required`);
4585
+ };
4586
+ if ('zScale' in d) scale('config.depth.zScale', d.zScale);
4587
+ const sheet = (path: string, value: Json): void => {
4588
+ const q = c.object(path, value, ['image'], ['near', 'zScale']);
4589
+ if (q === null) return;
4590
+ if ('image' in q) c.string(`${path}.image`, q.image);
4591
+ if (q.near !== 'black' && q.near !== 'white') c.fail('DEPTH_NEAR_REQUIRED', `${path}.near`, `is ${show(q.near)}; a user sheet must declare black or white, with no guessed convention`);
4592
+ scale(`${path}.zScale`, q.zScale);
4593
+ };
4594
+ for (const run of ['full', 'head']) if (run in d) {
4595
+ const path = `config.depth.${run}`, q = c.object(path, d[run], [], ['layers', 'atlas']);
4596
+ if (q === null) continue;
4597
+ if ('atlas' in q) sheet(`${path}.atlas`, q.atlas);
4598
+ if ('layers' in q) {
4599
+ if (!isPlainObject(q.layers)) c.fail('CONFIG_FIELD_TYPE', `${path}.layers`, 'requires an object keyed by exact source layer name');
4600
+ else for (const [layer, value] of Object.entries(q.layers)) sheet(`${path}.layers.${layer}`, value);
4601
+ }
4602
+ if ('atlas' in q && isPlainObject(q.layers) && Object.keys(q.layers).length > 0) c.fail('DEPTH_SOURCE_AMBIGUOUS', path, 'declares canvas and per-layer sheets together; choose one fallback explicitly');
4603
+ }
4604
+ }