spine-rigc 2.57.0 → 2.58.0

package/src/stop.ts

@@ -147,7 +147,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
   const declared: unknown = spec.stops;
   if (declared === undefined) return spec;
   if (!Array.isArray(declared)) {
-    throw new CompileError(`${where}: "stops" is ${JSON.stringify(declared)}; it is an array of { "chain", "links", "against", "at", "inward", "outward", "lower"? }`);
+    throw new CompileError(`${where}: "stops" is ${JSON.stringify(declared)}; it is an array of { "chain", "links", "against", "at", "inward", "outward", "lower"? }`, 'CE_STOP_DECLARATIONS_ARRAY');
   }
   const authored = new Map<string, RigBone>();
   for (const bone of spec.bones) if (isObj(bone) && typeof bone.name === 'string') authored.set(bone.name, bone);
@@ -157,44 +157,44 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
   const stops: ReadStop[] = [];
   const stoppedBy = new Map<string, string>();
   for (const [i, entry] of declared.entries()) {
-    if (!isObj(entry)) throw new CompileError(`${where}: stops[${i}] is ${JSON.stringify(entry)}; a stop is an object`);
+    if (!isObj(entry)) throw new CompileError(`${where}: stops[${i}] is ${JSON.stringify(entry)}; a stop is an object`, 'CE_STOP_DECLARATION_OBJECT');
     const chain = entry.chain;
     if (typeof chain !== 'string' || chain.length === 0) {
-      throw new CompileError(`${where}: stops[${i}] needs a "chain" — the name its point, frame and aim are called after ("<chain>_touch", "<chain>_stop", "<chain>_stop_aim")`);
+      throw new CompileError(`${where}: stops[${i}] needs a "chain" — the name its point, frame and aim are called after ("<chain>_touch", "<chain>_stop", "<chain>_stop_aim")`, 'CE_STOP_CHAIN_NAME_REQUIRED');
     }
     const who = `${where}: stop "${chain}"`;
     const links: unknown = entry.links;
     if (!Array.isArray(links) || links.length === 0 || !links.every((l): l is string => typeof l === 'string')) {
-      throw new CompileError(`${who} states "links" ${JSON.stringify(links) ?? 'absent'}; it is the chain's swinging links, root first — a non-empty array of bone names`);
+      throw new CompileError(`${who} states "links" ${JSON.stringify(links) ?? 'absent'}; it is the chain's swinging links, root first — a non-empty array of bone names`, 'CE_STOP_LINKS_ARRAY');
     }
     for (const [k, link] of links.entries()) {
       const bone = authored.get(link);
-      if (bone === undefined) throw new CompileError(`${who}: links[${k}] names bone "${link}", which this rig does not declare`);
+      if (bone === undefined) throw new CompileError(`${who}: links[${k}] names bone "${link}", which this rig does not declare`, 'CE_STOP_LINK_UNKNOWN');
       const other = stoppedBy.get(link);
       if (other !== undefined) {
         throw new CompileError(
-          `${who}: links[${k}] "${link}" is already stopped by stop "${other}" — one drawn link "${link}_d" and one clamp "${link}_clamp" per link, so a link is stopped once`,
+          `${who}: links[${k}] "${link}" is already stopped by stop "${other}" — one drawn link "${link}_d" and one clamp "${link}_clamp" per link, so a link is stopped once`, 'CE_STOP_LINK_ALREADY_STOPPED',
         );
       }
       stoppedBy.set(link, chain);
       if (bone.from !== undefined) {
-        throw new CompileError(`${who}: links[${k}] "${link}" takes its place from the manifest ("from"), and a stop copies the link's stated x, y and rotation onto its drawn link — state them`);
+        throw new CompileError(`${who}: links[${k}] "${link}" takes its place from the manifest ("from"), and a stop copies the link's stated x, y and rotation onto its drawn link — state them`, 'CE_STOP_LINK_MANIFEST_POSITION');
       }
       if (bone.parent === undefined) {
-        throw new CompileError(`${who}: links[${k}] "${link}" is the skeleton's root, and a stop hangs its frame and its drawn link where the link hangs — a link has a parent`);
+        throw new CompileError(`${who}: links[${k}] "${link}" is the skeleton's root, and a stop hangs its frame and its drawn link where the link hangs — a link has a parent`, 'CE_STOP_LINK_ROOT');
       }
     }
     const against = entry.against;
     if (typeof against !== 'string' || against.length === 0) {
-      throw new CompileError(`${who} needs "against" — the bone the point rides on, the leg the chain is held off`);
+      throw new CompileError(`${who} needs "against" — the bone the point rides on, the leg the chain is held off`, 'CE_STOP_AGAINST_REQUIRED');
     }
-    if (!authored.has(against)) throw new CompileError(`${who}: "against" names bone "${against}", which this rig does not declare`);
+    if (!authored.has(against)) throw new CompileError(`${who}: "against" names bone "${against}", which this rig does not declare`, 'CE_STOP_AGAINST_UNKNOWN');
     const at: unknown = entry.at;
     if (at === undefined) {
-      throw new CompileError(`${who} states no "at" — the point on "${against}" the frame aims at, [x, y] in "${against}"'s local space; the compiler places no point of its own`);
+      throw new CompileError(`${who} states no "at" — the point on "${against}" the frame aims at, [x, y] in "${against}"'s local space; the compiler places no point of its own`, 'CE_STOP_AT_REQUIRED');
     }
     if (!Array.isArray(at) || at.length !== 2 || !at.every((v): v is number => typeof v === 'number')) {
-      throw new CompileError(`${who} states "at" ${JSON.stringify(at)}; it is [x, y], two numbers in "${against}"'s local space`);
+      throw new CompileError(`${who} states "at" ${JSON.stringify(at)}; it is [x, y], two numbers in "${against}"'s local space`, 'CE_STOP_AT_PAIR');
     }
     const range = (node: Record<string, unknown>, field: string): { inward: number; outward: number } => {
       const out: Record<'inward' | 'outward', number> = { inward: 0, outward: 0 };
@@ -202,14 +202,14 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
         const v = node[end];
         if (typeof v !== 'number') {
           throw new CompileError(
-            `${who} states no "${field}${end}" — degrees from the link's rest angle, counted positive away from "${against}"; the range is [inward, outward], and the compiler states neither end for you`,
+            `${who} states no "${field}${end}" — degrees from the link's rest angle, counted positive away from "${against}"; the range is [inward, outward], and the compiler states neither end for you`, 'CE_STOP_RANGE_END_REQUIRED',
           );
         }
         out[end] = v;
       }
       if (out.inward > out.outward) {
         throw new CompileError(
-          `${who}: "${field}inward" ${out.inward} is greater than "${field}outward" ${out.outward} — the range is [inward, outward] in degrees counted positive away from "${against}", and this one holds no angle`,
+          `${who}: "${field}inward" ${out.inward} is greater than "${field}outward" ${out.outward} — the range is [inward, outward] in degrees counted positive away from "${against}", and this one holds no angle`, 'CE_STOP_RANGE_REVERSED',
         );
       }
       return out;
@@ -219,11 +219,11 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     let lower: { inward: number; outward: number } | null = null;
     if (links.length > 1) {
       if (!isObj(lowerRaw)) {
-        throw new CompileError(`${who} states no "lower" — the range [inward, outward] each link below the first may turn through off its own rest bend; the chain has ${links.length - 1} of them`);
+        throw new CompileError(`${who} states no "lower" — the range [inward, outward] each link below the first may turn through off its own rest bend; the chain has ${links.length - 1} of them`, 'CE_STOP_LOWER_REQUIRED');
       }
       lower = range(lowerRaw, 'lower.');
     } else if (lowerRaw !== undefined) {
-      throw new CompileError(`${who} states "lower" and its chain has one link — there is no link below the first for it to hold`);
+      throw new CompileError(`${who} states "lower" and its chain has one link — there is no link below the first for it to hold`, 'CE_STOP_LOWER_WITH_ONE_LINK');
     }
     stops.push({ who, chain, links, against, at: [at[0], at[1]], inward: first.inward, outward: first.outward, lower, names: stopNames(chain, links) });
   }
@@ -236,16 +236,16 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     const { names } = stop;
     const lowerDrawn = names.drawn.slice(1);
     for (const name of [names.frame, names.rel, names.drawn[0], ...lowerDrawn, names.point]) {
-      if (authored.has(name)) throw new CompileError(`${stop.who} generates bone "${name}", which this rig already declares — rename the bone, or the stop's "chain"`);
+      if (authored.has(name)) throw new CompileError(`${stop.who} generates bone "${name}", which this rig already declares — rename the bone, or the stop's "chain"`, 'CE_STOP_GENERATED_BONE_DECLARED');
       const by = generatedBones.get(name);
-      if (by !== undefined) throw new CompileError(`${stop.who} generates bone "${name}", which stop "${by}" generates too — rename one "chain"`);
+      if (by !== undefined) throw new CompileError(`${stop.who} generates bone "${name}", which stop "${by}" generates too — rename one "chain"`, 'CE_STOP_GENERATED_BONE_COLLISION');
       generatedBones.set(name, stop.chain);
     }
     for (const [type, name] of [['ik', names.aim], ['transform', names.copy], ...names.clamp.map((c) => ['transform', c] as const)] as const) {
       const key = `${type} ${name}`;
-      if (authoredConstraints.has(key)) throw new CompileError(`${stop.who} generates ${type} constraint "${name}", which this rig already declares — rename the constraint, or the stop's "chain"`);
+      if (authoredConstraints.has(key)) throw new CompileError(`${stop.who} generates ${type} constraint "${name}", which this rig already declares — rename the constraint, or the stop's "chain"`, 'CE_STOP_GENERATED_CONSTRAINT_DECLARED');
       const by = generatedConstraints.get(key);
-      if (by !== undefined) throw new CompileError(`${stop.who} generates ${type} constraint "${name}", which stop "${by}" generates too — rename one "chain"`);
+      if (by !== undefined) throw new CompileError(`${stop.who} generates ${type} constraint "${name}", which stop "${by}" generates too — rename one "chain"`, 'CE_STOP_GENERATED_CONSTRAINT_COLLISION');
       generatedConstraints.set(key, stop.chain);
     }
   }
@@ -265,7 +265,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     });
     if (at < 0) {
       throw new CompileError(
-        `${stop.who}: links[${k}] "${link}" is written by no constraint of this rig spec — a stop holds a link something swings (a physics, ik, transform or path constraint in "constraints"), and its copy and clamp run right after that. A physics constraint in the motion spec's table is emitted after every rig constraint, past the clamp; declare it here`,
+        `${stop.who}: links[${k}] "${link}" is written by no constraint of this rig spec — a stop holds a link something swings (a physics, ik, transform or path constraint in "constraints"), and its copy and clamp run right after that. A physics constraint in the motion spec's table is emitted after every rig constraint, past the clamp; declare it here`, 'CE_STOP_LINK_UNDRIVEN',
       );
     }
     return at;
@@ -296,14 +296,14 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     for (let k = 1; k < links.length; k++) {
       if (!ancestry(links[k]).includes(names.drawn[k - 1])) {
         throw new CompileError(
-          `${stop.who}: links[${k}] "${links[k]}" does not hang below "${names.drawn[k - 1]}", the drawn link of links[${k - 1}] — a chain's next link hangs from the drawn link above it, so the clamp that holds that one carries this one; parent it there`,
+          `${stop.who}: links[${k}] "${links[k]}" does not hang below "${names.drawn[k - 1]}", the drawn link of links[${k - 1}] — a chain's next link hangs from the drawn link above it, so the clamp that holds that one carries this one; parent it there`, 'CE_STOP_LINK_PARENT_CHAIN',
         );
       }
     }
     const held = new Set([names.frame, names.rel, ...names.drawn, ...links]);
     const under = [stop.against, ...ancestry(stop.against)].find((b) => held.has(b));
     if (under !== undefined) {
-      throw new CompileError(`${stop.who}: "against" "${stop.against}" hangs below "${under}", which the stop moves — the point would swing with the chain it holds off; name the leg`);
+      throw new CompileError(`${stop.who}: "against" "${stop.against}" hangs below "${under}", which the stop moves — the point would swing with the chain it holds off; name the leg`, 'CE_STOP_AGAINST_MOVES_WITH_STOP');
     }
   }
 
@@ -338,7 +338,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     for (const [end, value] of [['outward', a], ['inward', b]] as const) {
       if (Math.abs(value) > BOUND) {
         throw new CompileError(
-          `${stop.who}: "${field}${end}" ${range[end]} puts ${what}'s bound at ${value}°, past ±${BOUND}° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds`,
+          `${stop.who}: "${field}${end}" ${range[end]} puts ${what}'s bound at ${value}°, past ±${BOUND}° — the clamp reads a local rotation in (-180, 180], so a bound past it is never reached and the range it states is not the one that holds`, 'CE_STOP_LOCAL_BOUND_RANGE',
         );
       }
     }
@@ -358,10 +358,10 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
         if (listed.has(name)) continue;
         const bone = known(name);
         if (bone === undefined) {
-          throw new CompileError(`${who}: "${tip}" hangs below "${name}", which a later stop generates — declare that stop first, so its angles are known when this one is read`);
+          throw new CompileError(`${who}: "${tip}" hangs below "${name}", which a later stop generates — declare that stop first, so its angles are known when this one is read`, 'CE_STOP_DEPENDENCY_ORDER');
         }
         if (bone.from !== undefined) {
-          throw new CompileError(`${who}: "${name}" takes its place from the manifest ("from"), and a stop's angles are read off the setup pose this rig spec states — state its x, y and rotation`);
+          throw new CompileError(`${who}: "${name}" takes its place from the manifest ("from"), and a stop's angles are read off the setup pose this rig spec states — state its x, y and rotation`, 'CE_STOP_ANCESTOR_MANIFEST_POSITION');
         }
         listed.add(name);
         chain.push(bone);
@@ -371,7 +371,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     const parentFrame = frames.get(parent) as BoneTransform;
     if (!conformal(parentFrame)) {
       throw new CompileError(
-        `${who}: "${parent}", where the frame hangs, is scaled unevenly, sheared or reflected at the setup pose — the frame's angles add to its parent's only through a rotation and an even scale, and inward is a turn's sense`,
+        `${who}: "${parent}", where the frame hangs, is scaled unevenly, sheared or reflected at the setup pose — the frame's angles add to its parent's only through a rotation and an even scale, and inward is a turn's sense`, 'CE_STOP_FRAME_PARENT_TRANSFORM',
       );
     }
     for (let k = 1; k < links.length; k++) {
@@ -381,7 +381,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
         const plain = (bone.scaleX ?? 1) === (bone.scaleY ?? 1) && (bone.scaleX ?? 1) > 0 && (bone.shearX ?? 0) === 0 && (bone.shearY ?? 0) === 0 && (bone.inherit ?? 'normal') === 'normal';
         if (!plain) {
           throw new CompileError(
-            `${who}: "${at}", between links[${k}] "${links[k]}" and the drawn link above it, is scaled unevenly, sheared, reflected or inherits other than normally — a lower clamp reads the link's turn in its parent, and inward is a turn's sense`,
+            `${who}: "${at}", between links[${k}] "${links[k]}" and the drawn link above it, is scaled unevenly, sheared, reflected or inherits other than normally — a lower clamp reads the link's turn in its parent, and inward is a turn's sense`, 'CE_STOP_LOWER_PARENT_TRANSFORM',
           );
         }
       }
@@ -392,7 +392,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     const dx = target[0] - linkFrame.worldX;
     const dy = target[1] - linkFrame.worldY;
     if (dx === 0 && dy === 0) {
-      throw new CompileError(`${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" sits on the root of "${links[0]}" at the setup pose — the frame aims from the root at the point, and there is no direction to a point it stands on`);
+      throw new CompileError(`${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" sits on the root of "${links[0]}" at the setup pose — the frame aims from the root at the point, and there is no direction to a point it stands on`, 'CE_STOP_POINT_AT_ROOT');
     }
     const aim = directionDegrees(dx, dy);
     // Each angle is brought into (-180, 180] by one whole turn at most, so a
@@ -401,7 +401,7 @@ export function expandStops(spec: RigSpec, where: string, plant: StopPlant = {})
     const rest = halfTurn(halfTurn(linkFrame.worldRotation) - aim);
     if (rest === 0) {
       throw new CompileError(
-        `${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" lies on "${links[0]}"'s own line at the setup pose — inward is the turn from the link toward the point, and a point on the link's line has no side`,
+        `${who}: "at" [${stop.at.join(', ')}] on "${stop.against}" lies on "${links[0]}"'s own line at the setup pose — inward is the turn from the link toward the point, and a point on the link's line has no side`, 'CE_STOP_POINT_ON_LINK_LINE',
       );
     }
     // Inward turns the link toward the aim line: counter-clockwise when the link

package/src/trackgen.ts

@@ -199,13 +199,13 @@ export function evaluateTrackDerive(
   where: string,
 ): TrackDeriveReport {
   if (derive === null || typeof derive !== 'object' || Array.isArray(derive)) {
-    throw new CompileError(`${where}: "derive" is ${JSON.stringify(derive)}; it is an object with a "kind"`);
+    throw new CompileError(`${where}: "derive" is ${JSON.stringify(derive)}; it is an object with a "kind"`, 'CE_TRACK_DERIVE_OBJECT');
   }
   const kind = (derive as { kind?: unknown }).kind;
   if (typeof kind !== 'string' || !(TRACK_DERIVE_KINDS as readonly string[]).includes(kind)) {
     throw new CompileError(
       `${where}: "derive" has kind ${JSON.stringify(kind)}; this spec evaluates ${TRACK_DERIVE_KINDS.join(', ')}. ` +
-        'A model that is none of those is still authorable as a per-member "v" map, or as one track per member.',
+        'A model that is none of those is still authorable as a per-member "v" map, or as one track per member.', 'CE_TRACK_DERIVE_KIND',
     );
   }
   const turn = derive as TrackDeriveTurn;
@@ -223,7 +223,7 @@ export function evaluateTrackDerive(
     throw new CompileError(
       `${where}: derive ${kind} states carried=${JSON.stringify(turn.carried)} on a "${property}" track, and the ` +
         'foreshortening reads no depth difference — it is cos(α − t)/cos α, where α is the member\'s own angle off the ' +
-        `axis. "carried" belongs on the "${projections.shift}" track, whose shared shift is the thing it names.`,
+        `axis. "carried" belongs on the "${projections.shift}" track, whose shared shift is the thing it names.`, 'CE_TRACK_CARRIED_PROJECTION',
     );
   }
   const carried = turn.carried === undefined ? 0 : num(turn.carried, 'carried', where);
@@ -249,7 +249,7 @@ export function evaluateTrackDerive(
         `${where}: derive ${kind} projects onto "${property}" and member "${member.name}" states depth ${depth}. ` +
           'Foreshortening is cos(α − t)/cos α with α = atan2(coordinate, depth), which needs the part to be IN FRONT ' +
           'of the axis; at or behind it there is no front surface to narrow. A part behind the axis still takes the ' +
-          `"${projections.shift}" projection, where a negative depth is exactly what swings it the other way.`,
+          `"${projections.shift}" projection, where a negative depth is exactly what swings it the other way.`, 'CE_TRACK_FORESHORTEN_DEPTH',
       );
     }
     const alpha = Math.atan2(u, depth);
@@ -260,7 +260,7 @@ export function evaluateTrackDerive(
           `its own edge: α = ${round(alpha)} rad and the turn is ${round(rad)} rad, so cos(α − t) is ` +
           `${round(Math.cos(alpha - rad))} and the scale would be ${round(scale)}. A scale at or below 0 mirrors the ` +
           'drawing rather than narrowing it. The part has turned edge-on — the turn is past what this construction ' +
-          'carries, and FACE §8 is the page that picks a construction from the angle.',
+          'carries, and FACE §8 is the page that picks a construction from the angle.', 'CE_TRACK_FORESHORTEN_EDGE_ON',
       );
     }
     values.push({ member: member.name, at: u, depth, value: round(scale) });
@@ -298,7 +298,7 @@ function refuseProperty(kind: string, property: string, where: string): never {
     `${where}: derive ${kind} has no projection onto "${property}". It projects onto "${p.shift}" (the displacement, ` +
       `FACE §3) and "${p.foreshorten}" (the narrowing, FACE §5), and onto nothing else — a turn about one axis moves ` +
       `nothing along it, so a paired "translate"/"scale" would need a second channel this model does not state. ` +
-      'State the axis, or write the values as a per-member "v" map.',
+      'State the axis, or write the values as a per-member "v" map.', 'CE_TRACK_PROPERTY_PROJECTION',
   );
 }
 
@@ -322,7 +322,7 @@ function depthOf(
       throw new CompileError(
         `${where}: derive ${kind} states one depth ${depth} for ${members.length} members ` +
           `(${members.map((m) => m.name).join(', ')}). One number for every member is the shared value a plain "v" ` +
-          'already keys — state a depth per member, as { "member": z, … }.',
+          'already keys — state a depth per member, as { "member": z, … }.', 'CE_TRACK_GROUP_SHARED_DEPTH',
       );
     }
     return num(depth, 'depth', where);
@@ -330,7 +330,7 @@ function depthOf(
   if (depth === null || typeof depth !== 'object' || Array.isArray(depth)) {
     throw new CompileError(
       `${where}: derive ${kind} has depth ${JSON.stringify(depth)}; it is a number on a bone track and ` +
-        '{ "member": z, … } on a group track',
+        '{ "member": z, … } on a group track', 'CE_TRACK_DEPTH_SHAPE',
     );
   }
   const table = depth as Record<string, unknown>;
@@ -340,7 +340,7 @@ function depthOf(
     if (!known.has(name)) {
       throw new CompileError(
         `${where}: derive ${kind} states a depth for "${name}", which this track does not key ` +
-          `(its members are: ${members.map((m) => m.name).join(', ')})`,
+          `(its members are: ${members.map((m) => m.name).join(', ')})`, 'CE_TRACK_DEPTH_MEMBER_UNKNOWN',
       );
     }
   }
@@ -349,7 +349,7 @@ function depthOf(
       `${where}: derive ${kind} states no depth for member "${member}" ` +
         `(it states: ${stated.length ? stated.join(', ') : 'nothing'}). ` +
         'A depth is refused rather than defaulted: a member silently at depth 0 would be keyed with a DIFFERENT ' +
-        'model from the ones beside it, and that is exactly the error a table of six is written to make visible.',
+        'model from the ones beside it, and that is exactly the error a table of six is written to make visible.', 'CE_TRACK_DEPTH_MEMBER_REQUIRED',
     );
   }
   return num(table[member], `depth.${member}`, where);
@@ -358,7 +358,7 @@ function depthOf(
 /** One required finite number, refused by field name rather than compiled as a NaN. */
 function num(value: unknown, field: string, where: string): number {
   if (typeof value !== 'number' || !Number.isFinite(value)) {
-    throw new CompileError(`${where}: derive field "${field}" is ${JSON.stringify(value)}; it is a finite number the spec has to state`);
+    throw new CompileError(`${where}: derive field "${field}" is ${JSON.stringify(value)}; it is a finite number the spec has to state`, 'CE_TRACK_FIELD_NUMBER_FINITE');
   }
   return value;
 }