@rig-c/parts 1.25.0 → 1.27.0

package/src/rig.ts

@@ -388,6 +388,57 @@ export function roundShares(list: readonly Influence[]): Influence[] {
   return kept;
 }
 
+/**
+ * Issue #392: on a lattice mesh whose segments include sibling branch chains
+ * forked from the same chain link with `r >= grid` (`split.hold_tip: true`),
+ * the distance rule still concentrates weights along the fork row where the
+ * trunk splits into branches and across adjacent trees' ruffled hem steps.
+ * Four Laplacian passes (`FORK_SMOOTH_PASSES`, self share 0.5, floor 0.005, cap
+ * 8 influences) diffuse each vertex's shares across its triangle neighbours
+ * before rounding with {@link roundShares}.
+ */
+export const FORK_SMOOTH_PASSES = 4;
+export const FORK_SMOOTH_SELF = 0.5;
+export const FORK_SMOOTH_FLOOR = 0.005;
+export const FORK_SMOOTH_MAX_INFLUENCES = 8;
+
+export function smoothForkShares(raw: ReadonlyArray<readonly Influence[]>, triangles: readonly number[]): Influence[][] {
+  const adj: number[][] = raw.map(() => []);
+  const addEdge = (u: number, v: number): void => {
+    if (!adj[u].includes(v)) adj[u].push(v);
+    if (!adj[v].includes(u)) adj[v].push(u);
+  };
+  for (let i = 0; i + 2 < triangles.length; i += 3) {
+    const a = triangles[i];
+    const b = triangles[i + 1];
+    const c = triangles[i + 2];
+    addEdge(a, b);
+    addEdge(b, c);
+    addEdge(c, a);
+  }
+  let cur: Influence[][] = raw.map((s) => [...s]);
+  for (let p = 0; p < FORK_SMOOTH_PASSES; p++) {
+    cur = cur.map((own, vi) => {
+      const nb = adj[vi];
+      if (nb.length === 0) return own;
+      const m = new Map<string, number>();
+      for (const { bone, weight } of own) m.set(bone, weight * FORK_SMOOTH_SELF);
+      const nbShare = (1 - FORK_SMOOTH_SELF) / nb.length;
+      for (const u of nb) {
+        for (const { bone, weight } of cur[u]) m.set(bone, (m.get(bone) ?? 0) + weight * nbShare);
+      }
+      const kept = [...m.entries()]
+        .filter(([, w]) => w >= FORK_SMOOTH_FLOOR)
+        .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .slice(0, FORK_SMOOTH_MAX_INFLUENCES);
+      const sum = kept.reduce((s, [, w]) => s + w, 0);
+      return roundShares(kept.map(([bone, w]) => ({ bone, weight: w / sum })));
+    });
+  }
+  return cur;
+}
+
+
 interface Bone {
   name: string;
   parent: string | null;
@@ -957,7 +1008,8 @@ export function buildRig(
       }
       e.points.forEach(([x, y], k) => {
         const n = `${e.chain}${k}`;
-        B.set(n, { name: n, parent: k === 0 ? e.parent : names[names.length - 1], x, y });
+        const inherit = e.link_inherit?.[n];
+        B.set(n, { name: n, parent: k === 0 ? e.parent : names[names.length - 1], x, y, ...(inherit === undefined ? {} : { inherit }) });
         if (names.length > 0) child.set(names[names.length - 1], [x, y]);
         names.push(n);
       });
@@ -1854,6 +1906,7 @@ export function buildRig(
     const segsAt = dressSegsAt(p, segs);
     let emptied: { vertex: number; at: Point; capped: Influence[] } | null = null;
     let emptiedMore = 0;
+    const rawShares: Influence[][] = [];
     for (const [vi, [vx0, vy0]] of lm.vertices.entries()) {
       const wx = vx0 + ox;
       const wy = vy0 + oy;
@@ -1865,7 +1918,26 @@ export function buildRig(
         else emptiedMore++;
         continue;
       }
-      const ent: WeightEntry[] = (limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares)).map(({ bone, weight }) => {
+      rawShares.push(limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares));
+    }
+    if (emptied !== null) {
+      problems.push(nothingKeptProblem(p.name, limits.floor, emptied, emptiedMore));
+      continue;
+    }
+    const allChainLinks = new Set([...chains.values()].flat());
+    const forkCounts = new Map<string, number>();
+    for (const sp of mesh.segments) {
+      if (typeof sp !== 'string') continue;
+      const links = chains.get(sp);
+      const par = links !== undefined && links.length > 0 ? (B.get(links[0])?.parent ?? null) : null;
+      if (par !== null && allChainLinks.has(par)) forkCounts.set(par, (forkCounts.get(par) ?? 0) + 1);
+    }
+    const heldFork = heat === null && mesh.r >= mesh.grid && mesh.influences === undefined && [...forkCounts.values()].some((c) => c >= 2);
+    const finalShares = heldFork ? smoothForkShares(rawShares, lm.triangles) : rawShares;
+    for (const [vi, [vx0, vy0]] of lm.vertices.entries()) {
+      const wx = vx0 + ox;
+      const wy = vy0 + oy;
+      const ent: WeightEntry[] = finalShares[vi].map(({ bone, weight }) => {
         const [x, y] = toBoneLocal(world.get(bone) as BoneTransform, spineX(wx), spineY(wy));
         return { bone, x: places(x), y: places(y), weight };
       });
@@ -1873,10 +1945,6 @@ export function buildRig(
       infl += ent.length;
       maxInfl = Math.max(maxInfl, ent.length);
     }
-    if (emptied !== null) {
-      problems.push(nothingKeptProblem(p.name, limits.floor, emptied, emptiedMore));
-      continue;
-    }
     const uvs: number[] = [];
     for (const [x, y] of lm.vertices) uvs.push(pyRound(x / w, 6), pyRound(y / h, 6));
     skin[p.name] = { [p.name]: { type: 'mesh', image: file, width: w, height: h, uvs, triangles: lm.triangles, hull: lm.hull, weights } };

package/src/scene.ts

@@ -16,12 +16,13 @@
  * `rig/images/`, `parts.json` and `check/check.json`:
  *
  * - **Names, totally.** Every bone, slot, attachment (skin entry), constraint
- *   (its name and every bone or slot it names), `invariants.detached` bone,
+ *   (its name and every bone or slot it names), `stops` entry (its `chain`,
+ *   its `links` and its `against`; issue #431), `invariants.detached` bone,
  *   `invariants.axes` entry (its name, its `through` and its `bones`; issue #239),
  *   track, group and easing of character `<id>` is renamed `<id>:<name>`
  *   ({@link prefixed}); `root` is the one shared root. A name resolves to
  *   exactly one character, and nothing resolves across characters without its
- *   prefix: a constraint naming a bone its own build does not declare is
+ *   prefix: a constraint or stop naming a bone its own build does not declare is
  *   refused (`SCENE_NAME_PREFIXED` when another character has it,
  *   `SCENE_NAME_RESOLVES` when none does).
  * - **Images are the one name that cannot carry `:`.** rig-c names an
@@ -44,8 +45,8 @@
  *   is local to a bone the shift already moved. In Spine's axes it is the
  *   character's stage corner carried to the canvas's ({@link rootShift}),
  *   through `src/coords.ts`. The root is shared, so a character whose idle
- *   keys it, or whose constraint names it, is refused (`SCENE_ROOT_SHARED`):
- *   it would move every character.
+ *   keys it, or whose constraint or stop names it, is refused
+ *   (`SCENE_ROOT_SHARED`): it would move every character.
  * - **The scale, with the offset (issue #197).** `characters[].scale`, a
  *   positive number and 1 when absent, sizes the character about its stage's
  *   top-left corner: a point p of its root frame lands at `scale * p + shift`
@@ -53,7 +54,8 @@
  *   Spine's own loader multiplies by its `scale` (`SkeletonJson.js`): bone
  *   `x`, `y`, `length`; region `x`, `y` (and its drawn size, through
  *   `scaleX`/`scaleY`); each weight's bind `x`, `y`; the constraints' lengths
- *   ({@link scaledConstraint}); the translate keys and their curves'
+ *   ({@link scaledConstraint}); each stop's `at` offset in its `against` bone's
+ *   local frame ({@link scaledStop}; issue #431); the translate keys and their curves'
  *   values. Spine also scales the skeleton's `referenceScale`, which the
  *   composed skeleton holds once for every character, so a physics
  *   constraint with a nonzero `wind` or `gravity` cannot be scaled per
@@ -91,6 +93,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import type { RigStop } from 'rig-c/src/rig.ts';
 import { checkStage, gateThroughRigc, type Log } from './build.ts';
 import { ACCEPTABLE_BARS, barsNotMet, type CheckReport, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, type PackMode, requirementsNotPass, type RigcRunner } from './check.ts';
 import { CONSTRAINT_BONE_FIELDS, ROOT_BONE } from './config.ts';
@@ -382,7 +385,9 @@ export interface CharacterBuild {
 const BONE_KEYS = ['name', 'parent', 'length', 'rotation', 'x', 'y'];
 const SLOT_KEYS = ['name', 'bone', 'attachment'];
 const ATTACHMENT_KEYS = ['type', 'image', 'width', 'height', 'uvs', 'triangles', 'hull', 'weights', 'x', 'y', 'rotation'];
-const RIG_KEYS = ['spec', 'name', 'images', 'skeleton', 'bones', 'slots', 'skins', 'constraints', 'invariants'];
+const RIG_KEYS = ['spec', 'name', 'images', 'skeleton', 'bones', 'slots', 'skins', 'constraints', 'stops', 'invariants'];
+const STOP_KEYS = ['chain', 'links', 'against', 'at', 'inward', 'outward', 'lower'];
+const STOP_LOWER_KEYS = ['inward', 'outward'];
 const INVARIANT_KEYS = ['idleDrivesMeshes', 'detached', 'axes'];
 const MOTION_KEYS = ['spec', 'archetype', 'cut', 'easings', 'groups', 'animations'];
 const IDLE_KEYS = ['duration', 'loop', 'note', 'tracks'];
@@ -501,6 +506,48 @@ export function readCharacterBuild(c: SceneCharacter, problems: Problem[], accep
         problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} rig.json bones[0]`, detail: `is ${show(root)}; {"name": "${ROOT_BONE}", "x": 0, "y": 0}, as the rig stage writes it, is required — the composed root is shared, so a character's root must carry no transform of its own` });
       }
       (Array.isArray(r.slots) ? r.slots : []).forEach((s, i) => unknown(`rig.json slots[${i}]`, s, SLOT_KEYS));
+      if ('stops' in r) {
+        if (!Array.isArray(r.stops)) {
+          problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} rig.json stops`, detail: `is ${show(r.stops)}; an array of stop entries is required` });
+        } else {
+          r.stops.forEach((st, i) => {
+            const where = `rig.json stops[${i}]`;
+            unknown(where, st, STOP_KEYS);
+            if (!isRecord(st)) return;
+            if (typeof st.chain !== 'string' || st.chain === '') {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.chain`, detail: `is ${show(st.chain)}; a non-empty chain name is required` });
+            }
+            if (!(Array.isArray(st.links) && st.links.length > 0 && st.links.every((l) => typeof l === 'string' && l !== ''))) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.links`, detail: `is ${show(st.links)}; a non-empty list of bone names is required` });
+            }
+            if (!('against' in st)) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.against`, detail: 'is absent; a bone name is required' });
+            }
+            if (!(Array.isArray(st.at) && st.at.length === 2 && st.at.every((n) => typeof n === 'number' && Number.isFinite(n)))) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.at`, detail: `is ${show(st.at)}; [x, y], two finite numbers in against's local frame, is required` });
+            }
+            const checkBounds = (bWhere: string, bObj: Record<string, unknown>): void => {
+              const inOk = typeof bObj.inward === 'number' && Number.isFinite(bObj.inward);
+              const outOk = typeof bObj.outward === 'number' && Number.isFinite(bObj.outward);
+              if (!inOk) problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${bWhere}.inward`, detail: `is ${show(bObj.inward)}; a finite number of degrees is required` });
+              if (!outOk) problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${bWhere}.outward`, detail: `is ${show(bObj.outward)}; a finite number of degrees is required` });
+              if (inOk && outOk && (bObj.inward as number) > (bObj.outward as number)) {
+                problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${bWhere}.inward`, detail: `is ${String(bObj.inward)}, above outward ${String(bObj.outward)}; inward <= outward is required` });
+              }
+            };
+            checkBounds(where, st);
+            if ('lower' in st) {
+              unknown(`${where}.lower`, st.lower, STOP_LOWER_KEYS);
+              if (isRecord(st.lower)) checkBounds(`${where}.lower`, st.lower);
+              if (Array.isArray(st.links) && st.links.length === 1) {
+                problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.lower`, detail: `is ${show(st.lower)} on a 1-link stop; lower holds the links below the first, so leave lower out when links has 1 bone` });
+              }
+            } else if (Array.isArray(st.links) && st.links.length > 1) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.lower`, detail: `is absent and required when the stop holds ${st.links.length} links (more than 1); state lower: { inward, outward } for the links below the first` });
+            }
+          });
+        }
+      }
       if (isRecord(r.invariants)) unknown('rig.json invariants', r.invariants, INVARIANT_KEYS);
       const skins = isRecord(r.skins) ? r.skins : {};
       unknown('rig.json skins', skins, ['default']);
@@ -732,6 +779,12 @@ export function scaledConstraint(con: Record<string, unknown>, s: number): Recor
   return out;
 }
 
+/** A stop of a character at scale `s` (issue #431): its `at` offset in `against`'s local frame scaled by `s`, its degree bounds unchanged; `s` 1 returns `stop` as given. */
+export function scaledStop(stop: RigStop, s: number): RigStop {
+  if (s === 1) return stop;
+  return { ...stop, at: [scaledBy(stop.at[0], s), scaledBy(stop.at[1], s)] };
+}
+
 /** A bone track's keys at scale `s`: a length property's values, and its curve's value control points, scaled; any other track as given. */
 function scaledTrack<T extends { property: string; keys: unknown[] }>(t: T, s: number): T {
   if (s === 1 || !SCALED_TRACK_PROPERTIES.includes(t.property)) return t;
@@ -962,6 +1015,11 @@ export function composeScene(
         fail('SCENE_NAME_RESOLVES', `${where}.slot`, `names the slot "${con.slot}", which character "${b.id}" does not declare`);
       }
     });
+    (b.rig.stops ?? []).forEach((st, k) => {
+      const where = `character "${b.id}" rig.json stops[${k}] (stop "${String(st.chain)}")`;
+      st.links.forEach((n, j) => ownBone(b.id, n, `${where}.links[${j}]`));
+      ownBone(b.id, st.against, `${where}.against`);
+    });
     for (const [k, d] of (b.rig.invariants?.detached ?? []).entries()) {
       ownBone(b.id, d.bone, `character "${b.id}" rig.json invariants.detached[${k}].bone`);
       ownBone(b.id, d.notUnder, `character "${b.id}" rig.json invariants.detached[${k}].notUnder`);
@@ -988,6 +1046,11 @@ export function composeScene(
       });
       if (named.includes(ROOT_BONE)) fail('SCENE_ROOT_SHARED', `${where} rig.json constraints[${k}] (${String(con.type)} "${String(con.name)}")`, `names "${ROOT_BONE}", which the scene shares by every character; a constraint on it, or following it, would reach every character — name a bone of the character's own`);
     });
+    (b.rig.stops ?? []).forEach((st, k) => {
+      if ([...st.links, st.against].includes(ROOT_BONE)) {
+        fail('SCENE_ROOT_SHARED', `${where} rig.json stops[${k}] (stop "${String(st.chain)}")`, `names "${ROOT_BONE}", which the scene shares by every character; a stop on it, or against it, would reach every character — name a bone of the character's own`);
+      }
+    });
   }
   const whys = [...new Set(ready.map((b) => b.rig.invariants?.idleDrivesMeshes?.why).filter((w): w is string => w !== undefined))];
   if (whys.length > 1) {
@@ -1034,6 +1097,7 @@ export function composeScene(
     images.push([PLATE_IMAGE, plate.bytes]);
   }
   const constraints: Array<Record<string, unknown>> = [];
+  const stops: RigStop[] = [];
   const detached: NonNullable<NonNullable<RigSpec['invariants']>['detached']> = [];
   const axes: NonNullable<NonNullable<RigSpec['invariants']>['axes']> = [];
   scene.characters.forEach((c) => {
@@ -1043,7 +1107,8 @@ export function composeScene(
     const [dx, dy] = rootShift(b.rig.skeleton, stage, c.offset, s);
     // At a scale other than 1 every length the character carries is scaled (issue #197): each bone's x, y and length,
     // each region's x, y (and its drawn size, by scaleX/scaleY), each weight's bind x, y, the constraints' lengths
-    // (scaledConstraint) and the translate keys (scaledTrack); what sits in root's own frame is then shifted.
+    // (scaledConstraint), each stop's at offset in against's local frame (scaledStop; issue #431) and the translate keys
+    // (scaledTrack); what sits in root's own frame is then shifted.
     for (const bone of b.rig.bones) {
       if (bone.name === ROOT_BONE) continue;
       const first = bone.parent === ROOT_BONE;
@@ -1095,6 +1160,15 @@ export function composeScene(
       if (type === 'path' && typeof con.slot === 'string') out.slot = prefixed(id, con.slot);
       constraints.push(out);
     }
+    for (const st of b.rig.stops ?? []) {
+      const scaled = scaledStop(st, s);
+      stops.push({
+        ...scaled,
+        chain: prefixed(id, st.chain),
+        links: st.links.map((l) => P(id, l)),
+        against: P(id, st.against),
+      });
+    }
     for (const d of b.rig.invariants?.detached ?? []) detached.push({ ...d, bone: P(id, d.bone), notUnder: P(id, d.notUnder) });
     // An axis entry's name is unique within one rig, and two characters each carry a "face": the name is prefixed too.
     for (const ax of b.rig.invariants?.axes ?? []) axes.push({ name: prefixed(id, ax.name), through: [P(id, ax.through[0]), P(id, ax.through[1])], bones: ax.bones.map((n) => P(id, n)), tolerance: ax.tolerance });
@@ -1106,6 +1180,7 @@ export function composeScene(
   const name = ids.join('+');
   const rig: RigSpec = { spec: 'rigc-rig/1', name, images: 'images', skeleton: stage, bones, slots, skins: { default: skin as unknown as RigSpec['skins']['default'] } };
   if (constraints.length > 0) rig.constraints = constraints;
+  if (stops.length > 0) rig.stops = stops;
   const invariants: NonNullable<RigSpec['invariants']> = {};
   if (whys.length === 1) invariants.idleDrivesMeshes = { why: whys[0] };
   if (detached.length > 0) invariants.detached = detached;
@@ -1251,6 +1326,11 @@ export function unprefixedNames(rig: RigSpec, motion: MotionSpec, ids: readonly
     }
     if (c.type === 'path') name(`constraint ${String(c.name)} slot`, c.slot, false);
   }
+  for (const s of rig.stops ?? []) {
+    name('stop chain', s.chain, false);
+    for (const l of s.links) name(`stop ${s.chain} link`, l, false);
+    name(`stop ${s.chain} against`, s.against, false);
+  }
   for (const d of rig.invariants?.detached ?? []) {
     name('invariants.detached bone', d.bone, false);
     name('invariants.detached notUnder', d.notUnder, false);

package/src/squeeze.ts

@@ -318,7 +318,7 @@ export function branchSqueezes(
   }
 
   for (const [mname, m] of Object.entries(spec.meshes)) {
-    if ('contour' in m || 'auto' in m || m.rule === 'heat') continue;
+    if ('contour' in m || 'auto' in m || m.rule === 'heat' || m.r >= m.grid) continue;
     const byFork = new Map<string, string[]>();
     for (const sp of m.segments) {
       if (typeof sp !== 'string') continue;