spine-rigc 1.5.2 → 1.6.1

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/rig.ts CHANGED
@@ -60,8 +60,8 @@
60
60
  * with no manifest at all declares them here.
61
61
  */
62
62
  import { CompileError, NotImplementedError } from './errors.ts';
63
- import { dottedPath, refuseNumbersTheFileCannotCarry, refuseUnknownKeys, refuseValuesOfTheWrongType } from './keys.ts';
64
- import type { ShapeVisit, SpecValueType } from './keys.ts';
63
+ import { dottedPath, refuseNumbersTheFileCannotCarry, refuseUnknownKeys, refuseValuesOfTheWrongType, refuseValuesOutsideTheirSet } from './keys.ts';
64
+ import type { ShapeVisit, SpecEnumTable, SpecValueType } from './keys.ts';
65
65
 
66
66
  export { CompileError, NotImplementedError };
67
67
 
@@ -289,11 +289,32 @@ export interface RigBone {
289
289
  // slots — `root.slots[]` (SkeletonJson.ts:121-141)
290
290
  // ---------------------------------------------------------------------------
291
291
 
292
- /** `SlotData.ts:64`. */
293
- export type RigSlotBlend = 'normal' | 'additive' | 'multiply' | 'screen';
294
-
292
+ /**
293
+ * `SlotData.ts:64`, read by `SkeletonJson.js:124` through `Utils.enumValue`, so
294
+ * only the first letter's case is free: `additive` and `Additive` read
295
+ * `Additive`, while `ADDITIVE`, `mUlTiPlY` and `foo` read as no mode with no
296
+ * error (issue #946, measured with `tools/pose_oracle.ts dump` on spine-core
297
+ * 4.3.13). The parser refuses those by name and the emitter writes the
298
+ * spelling as stated, which is one the runtime resolves.
299
+ */
300
+ export type RigSlotBlend =
301
+ | 'normal'
302
+ | 'additive'
303
+ | 'multiply'
304
+ | 'screen'
305
+ | 'Normal'
306
+ | 'Additive'
307
+ | 'Multiply'
308
+ | 'Screen';
309
+
310
+ /** The four modes, as a refusal names them; each also reads with its first letter upper-cased. */
295
311
  export const RIG_SLOT_BLEND: readonly RigSlotBlend[] = ['normal', 'additive', 'multiply', 'screen'];
296
312
 
313
+ /** Whether the runtime resolves a stated blend to a mode: its first letter folded, the rest exactly one of the four. */
314
+ export function isRigSlotBlend(value: unknown): value is RigSlotBlend {
315
+ return typeof value === 'string' && (RIG_SLOT_BLEND as readonly string[]).includes(value.charAt(0).toLowerCase() + value.slice(1));
316
+ }
317
+
297
318
  /**
298
319
  * One slot. **The array order IS the draw order** — there is no separate setup
299
320
  * draw-order field anywhere in the format.
@@ -338,7 +359,7 @@ export interface RigSlot {
338
359
  color?: string;
339
360
  /** Two-colour tint, `rrggbb`. 🚫 `A12_NO_DARK_COLOR` under `spine-html`. */
340
361
  dark?: string;
341
- /** Default `normal`. */
362
+ /** Default `normal`. Only the first letter's case is free (`RigSlotBlend`). */
342
363
  blend?: RigSlotBlend;
343
364
  }
344
365
 
@@ -1866,29 +1887,20 @@ export const RIG_KEYS = {
1866
1887
  * field declared `number` and typed `string` here is a red run rather than a
1867
1888
  * refusal of correct work.
1868
1889
  *
1869
- * Where an unchecked type (`object`, `enum`, `mixed` — see `SPEC_VALUE_TYPES`)
1870
- * is refused, and by what:
1871
- *
1872
- * - the version tag `spec` — `parseRigSpec`, before anything else;
1873
- * - `inherit` — `resolveBoneInherit`; `blend` — the slot loop
1874
- * (`RIG_SLOT_BLEND`); `consumerDrivenMix[].type` — the invariants block;
1875
- * - a constraint's `type` — `buildRigConstraint`; `scaleY` on ik, a path
1876
- * constraint's three modes and a slider's `property` — the builder of that
1877
- * constraint kind, each listing the names that exist;
1878
- * - an attachment's `type` — the attachment reader; `depth.near` — the depth
1879
- * map reader;
1880
- * - `RigSegmentsGenerator.bones` (`mixed`: a name, a chain of names or a span)
1881
- * — the segments generator, by index.
1882
- *
1883
- * 🚨 Measured when this table was written, three `enum` keys have **no** owner,
1884
- * and the table does not pretend otherwise: `boneIndexing` built green at `5`
1885
- * and at `"foo"` (on a weighted mesh too), `from.rotation` built green at `5`
1886
- * and at `"foo"` on an anchored bone, and a generator `kind` of `5` or `"foo"`
1887
- * threw a `TypeError` (*undefined is not an object (evaluating
1888
- * 'generator.size')*) rather than the mesh builder's refusal. Each is a closed
1889
- * set of names with nobody holding the name, which is a value refusal and not a
1890
- * type one, so it is not fixed here. `scaleY` on a physics constraint was not
1891
- * measured.
1890
+ * Where an unchecked `object` or `mixed` row is refused: a nested shape by the
1891
+ * reader that walks it; `RigSegmentsGenerator.bones` (`mixed`: a name, a chain
1892
+ * of names or a span) by the segments generator, by index. Where an `enum` row
1893
+ * is refused is not a list in prose any more: `RIG_ENUMS`, below, has one entry
1894
+ * per `enum` row — a set refused by `refuseValuesOutsideTheirSet`, or the
1895
+ * reader that refuses it — and `satisfies` makes a row without one a type error.
1896
+ *
1897
+ * ⚠️ Until issue #900 this comment carried that list, and ended by naming three
1898
+ * `enum` keys with **no** owner: `boneIndexing`, `from.rotation` and a
1899
+ * generator `kind`. The list was right about the three and wrong by omission
1900
+ * about a fourth — the cut manifest's `mesh.kind`, which `MANIFEST_TYPES` said
1901
+ * "the manifest mesh reader" held and which that reader read as a ribbon in one
1902
+ * place and a ring in another. A list of owners in a comment is a claim nothing
1903
+ * checks; the table is one a control reads.
1892
1904
  */
1893
1905
  type RigTypeTable = {
1894
1906
  readonly [S in keyof typeof RIG_KEYS]: { readonly [K in (typeof RIG_KEYS)[S][number]]: SpecValueType };
@@ -1998,6 +2010,70 @@ export const RIG_TYPES = {
1998
2010
  RigSoftRegion: { bone: 'string', mask: 'string' },
1999
2011
  } as const satisfies RigTypeTable;
2000
2012
 
2013
+ /** The two sources a bone's `from.rotation` names (`RigBoneFrom.rotation`). */
2014
+ export const RIG_FROM_ROTATIONS = ['axis', 'anchor'] as const satisfies ReadonlyArray<NonNullable<RigBoneFrom['rotation']>>;
2015
+
2016
+ /** The two ways a weighted `vertices` run names its bones (`RigMeshAttachment.boneIndexing`). */
2017
+ export const RIG_BONE_INDEXING = ['name', 'raw'] as const satisfies ReadonlyArray<NonNullable<RigMeshAttachment['boneIndexing']>>;
2018
+
2019
+ /** What `boneIndexing` outside its set was read as, measured before issue #900. */
2020
+ const BONE_INDEXING_READ_AS =
2021
+ 'anything else was read as the default "name" in silence: a weighted "vertices" run was refused as unflagged, ' +
2022
+ 'and every other attachment built byte for byte as if the key were absent';
2023
+
2024
+ /**
2025
+ * Who refuses each `enum` row of `RIG_TYPES` outside its set (issue #900) —
2026
+ * `SpecEnumTable` in [`keys.ts`](keys.ts) says what the two kinds of entry
2027
+ * mean, and `satisfies` makes an `enum` row without one a type error.
2028
+ *
2029
+ * ⭐ A `set` is stated for exactly the rows nobody held: measured when this
2030
+ * table was written, `boneIndexing` built green at `5`, `"foo"` and `"named"`
2031
+ * (the spelling the issue itself used) as the default, and `from.rotation`
2032
+ * built green at `5` and `"foo"` with the bone's setup rotation dropped. Every
2033
+ * other row already had a reader that refused a planted `5` and `"foo"` by
2034
+ * name, and keeps it; the generator's `kind` is the one of those that is a
2035
+ * dispatch, and its refusal is new — it threw a `TypeError` (*undefined is not
2036
+ * an object (evaluating 'generator.size')*), because the scan skipped a `kind`
2037
+ * it had no row for and the mesh builder fell through to the ring branch.
2038
+ */
2039
+ export const RIG_ENUMS = {
2040
+ RigSpec: { spec: { owner: 'parseRigSpec' } },
2041
+ RigBone: { inherit: { owner: 'parseRigSpec' } },
2042
+ RigBoneFrom: {
2043
+ rotation: {
2044
+ set: RIG_FROM_ROTATIONS,
2045
+ readAs: 'anything else was read as no rotation source, and the bone was emitted without the setup rotation it asked for',
2046
+ },
2047
+ },
2048
+ RigSlot: { blend: { owner: 'parseRigSpec' } },
2049
+ RigConsumerDrivenMix: { type: { owner: 'parseRigSpec' } },
2050
+ RigIkConstraint: { type: { owner: 'buildRigConstraint' }, scaleY: { owner: 'buildRigConstraint' } },
2051
+ RigTransformConstraint: { type: { owner: 'buildRigConstraint' } },
2052
+ RigPathConstraint: {
2053
+ type: { owner: 'buildRigConstraint' },
2054
+ positionMode: { owner: 'buildRigConstraint' },
2055
+ spacingMode: { owner: 'buildRigConstraint' },
2056
+ rotateMode: { owner: 'buildRigConstraint' },
2057
+ },
2058
+ RigPhysicsConstraint: { type: { owner: 'buildRigConstraint' }, scaleY: { owner: 'buildRigConstraint' } },
2059
+ RigSliderConstraint: { type: { owner: 'buildRigConstraint' }, property: { owner: 'buildRigConstraint' } },
2060
+ RigRegionAttachment: { type: { owner: 'buildRigAttachment' } },
2061
+ RigMeshAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
2062
+ RigLinkedMeshAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
2063
+ RigBoundingBoxAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
2064
+ RigClippingAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
2065
+ RigPathAttachment: { type: { owner: 'buildRigAttachment' }, boneIndexing: { set: RIG_BONE_INDEXING, readAs: BONE_INDEXING_READ_AS } },
2066
+ // The generator's `kind` chooses the row its other keys are checked against,
2067
+ // so a `kind` outside the five has no row to be visited in: the scan that
2068
+ // dispatches on it is where it is refused.
2069
+ RigRingGenerator: { kind: { owner: 'checkRigSpecKeys' } },
2070
+ RigRibbonGenerator: { kind: { owner: 'checkRigSpecKeys' } },
2071
+ RigContourGenerator: { kind: { owner: 'checkRigSpecKeys' } },
2072
+ RigGridGenerator: { kind: { owner: 'checkRigSpecKeys' } },
2073
+ RigSegmentsGenerator: { kind: { owner: 'checkRigSpecKeys' } },
2074
+ RigDepthMap: { near: { owner: 'sampleMeshDepth' } },
2075
+ } as const satisfies SpecEnumTable<typeof RIG_TYPES>;
2076
+
2001
2077
  /**
2002
2078
  * The five constraint `type` names, and the shape each one's keys come from.
2003
2079
  *
@@ -2024,7 +2100,7 @@ const ATTACHMENT_SHAPE: Record<string, keyof typeof RIG_KEYS> = {
2024
2100
  };
2025
2101
 
2026
2102
  /** The generator `kind` names, and the shape each one's keys come from. */
2027
- const GENERATOR_SHAPE: Record<string, keyof typeof RIG_KEYS> = {
2103
+ const GENERATOR_SHAPE: Record<(typeof RIG_GENERATOR_KINDS)[number], keyof typeof RIG_KEYS> = {
2028
2104
  ring: 'RigRingGenerator',
2029
2105
  ribbon: 'RigRibbonGenerator',
2030
2106
  contour: 'RigContourGenerator',
@@ -2239,10 +2315,21 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): Array<{
2239
2315
  }
2240
2316
  if (!isObj(att.generator)) continue;
2241
2317
  const gen = att.generator;
2242
- const genShape = GENERATOR_SHAPE[String(gen.kind)];
2243
- // Same rule as an unknown attachment type: an unknown `kind` is the mesh
2244
- // builder's refusal, which can name the four that exist.
2245
- if (genShape === undefined) continue;
2318
+ const kind = RIG_GENERATOR_KINDS.find((k) => k === gen.kind);
2319
+ const genShape = kind === undefined ? undefined : GENERATOR_SHAPE[kind];
2320
+ // 🚨 An unknown `kind` used to be skipped here as "the mesh builder's
2321
+ // refusal", and the mesh builder had none: `buildGeneratedMesh` fell
2322
+ // through to the ring branch and threw a TypeError reading
2323
+ // `generator.size` (issue #900). `kind` chooses the row every other key
2324
+ // of the generator is checked against, so this dispatch is the one
2325
+ // place that can refuse it — before any of those keys is judged.
2326
+ if (genShape === undefined) {
2327
+ const stated = gen.kind === undefined ? 'absent' : (JSON.stringify(gen.kind) ?? String(gen.kind));
2328
+ throw new CompileError(
2329
+ `${where}: ${who} generator.kind is ${stated}; one of ${RIG_GENERATOR_KINDS.map((k) => JSON.stringify(k)).join(', ')} — ` +
2330
+ 'the kind names the builder, and each builder reads its own keys, so nothing about the mesh can be checked or built without one',
2331
+ );
2332
+ }
2246
2333
  at(gen, genShape, `${who} generator (${String(gen.kind)})`, [...here, 'generator']);
2247
2334
  at(gen.bias, 'RigMeshBias', `${who} generator.bias`, [...here, 'generator', 'bias']);
2248
2335
  at(gen.depth, 'RigDepthMap', `${who} generator.depth`, [...here, 'generator', 'depth']);
@@ -2338,11 +2425,13 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
2338
2425
  // `constraint.skin === true` reads `"skin": "true"` as a constraint that asks
2339
2426
  // for no skin. The price, measured, is three controls whose type half pinned an
2340
2427
  // older sentence (RF86, PS177, PS189); their other halves are unchanged.
2341
- refuseValuesOfTheWrongType(
2342
- visits.map((v) => ({ node: v.node, shape: v.shape, name: (tail) => place([...v.path, ...tail]) })),
2343
- RIG_TYPES,
2344
- where,
2345
- );
2428
+ const shapeVisits: ShapeVisit[] = visits.map((v) => ({ node: v.node, shape: v.shape, name: (tail) => place([...v.path, ...tail]) }));
2429
+ refuseValuesOfTheWrongType(shapeVisits, RIG_TYPES, where);
2430
+ // A name outside an `enum` row's stated set (issue #900), after the type walk
2431
+ // and over the same visits: `boneIndexing: "foo"` built as the default and
2432
+ // `from.rotation: "foo"` as no rotation, both green. A row whose entry names
2433
+ // an owner is that reader's to refuse, in its own words.
2434
+ refuseValuesOutsideTheirSet(shapeVisits, RIG_TYPES, RIG_ENUMS, where);
2346
2435
  // After the key check, so a misspelled key is named as a misspelling before
2347
2436
  // its value is judged, and before every reader below, so no range rule or
2348
2437
  // derived number ever meets a value the file cannot carry (issue #881).
@@ -2449,8 +2538,15 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
2449
2538
  `${where}: slot "${slot.name}" names bone ${JSON.stringify(slot.bone)}, which this rig does not declare`,
2450
2539
  );
2451
2540
  }
2452
- if (slot.blend !== undefined && !RIG_SLOT_BLEND.some((v) => v.toLowerCase() === String(slot.blend).toLowerCase())) {
2453
- throw new CompileError(`${where}: slot "${slot.name}" has blend ${JSON.stringify(slot.blend)}; known: ${RIG_SLOT_BLEND.join(', ')}`);
2541
+ // Issue #946: this used to compare case-insensitively, so `ADDITIVE` built
2542
+ // green and the runtime read the slot as no mode at all. The rule is now the
2543
+ // runtime's own, the one `buildRigConstraint`'s enums state.
2544
+ if (slot.blend !== undefined && !isRigSlotBlend(slot.blend)) {
2545
+ throw new CompileError(
2546
+ `${where}: slot "${slot.name}" has blend ${JSON.stringify(slot.blend)}; known: ${RIG_SLOT_BLEND.join(', ')} ` +
2547
+ "(only the first letter's case is free — the parser's enumValue uppercases that one character and nothing " +
2548
+ 'else, and an unresolved name becomes undefined without an error)',
2549
+ );
2454
2550
  }
2455
2551
  }
2456
2552
 
package/src/transform.ts CHANGED
@@ -31,7 +31,29 @@
31
31
  * wrong. `computeWorldTransforms` below is `BonePose.updateWorldTransform`
32
32
  * (spine-core 4.3.13, `BonePose.js:110-216`) at setup, with a skeleton scale of 1.
33
33
  */
34
- import type { SpineBone } from './types.ts';
34
+ /**
35
+ * What `computeWorldTransforms` reads off a bone — a structural type, so both a
36
+ * Spine bone (`SpineBone`, what spine-parts and every skeleton reader hold) and
37
+ * a compiled-model bone (`ModelBone`, what `compile` holds) satisfy it as they
38
+ * are, without a cast.
39
+ *
40
+ * The two differ in one key, the inherit mode: Spine 4.3 spells it `inherit`
41
+ * and the model `inheritMode`. The union below admits exactly one of the two on
42
+ * any one bone (the other is `never`), so a bone carrying both is a type error
43
+ * rather than a question of which one wins, and the mode is read as
44
+ * `inheritMode ?? inherit` — whichever the bone has.
45
+ */
46
+ export type PosableBone = {
47
+ name: string;
48
+ parent?: string;
49
+ x?: number;
50
+ y?: number;
51
+ rotation?: number;
52
+ scaleX?: number;
53
+ scaleY?: number;
54
+ shearX?: number;
55
+ shearY?: number;
56
+ } & ({ inherit?: string; inheritMode?: never } | { inheritMode?: string; inherit?: never });
35
57
 
36
58
  export interface BoneTransform {
37
59
  a: number;
@@ -79,7 +101,7 @@ export function cropToSpineY(cropY: number, cropHeight: number): number {
79
101
  * inheriting rig emits moves by a byte. The five `inherit` cases are the
80
102
  * runtime's, transcribed.
81
103
  */
82
- export function computeWorldTransforms(bones: SpineBone[]): Map<string, BoneTransform> {
104
+ export function computeWorldTransforms(bones: readonly PosableBone[]): Map<string, BoneTransform> {
83
105
  const out = new Map<string, BoneTransform>();
84
106
  for (const bone of bones) {
85
107
  const rotation = bone.rotation ?? 0;
@@ -144,8 +166,8 @@ const INHERIT_MODES: readonly InheritMode[] = ['normal', 'onlyTranslation', 'noR
144
166
  * leaves the matrix where it was, and the rig spec's parse refuses that
145
167
  * spelling first (issue #733), so reaching this throw is rigc's own defect.
146
168
  */
147
- function inheritMode(bone: SpineBone): InheritMode {
148
- const value = bone.inherit;
169
+ function inheritMode(bone: PosableBone): InheritMode {
170
+ const value = bone.inheritMode ?? bone.inherit;
149
171
  if (value === undefined) return 'normal';
150
172
  const folded = value.length === 0 ? value : value[0].toLowerCase() + value.slice(1);
151
173
  const mode = INHERIT_MODES.find((m) => m === folded);
package/src/types.ts CHANGED
@@ -17,8 +17,9 @@
17
17
  import type { AtlasRegion } from './atlas.ts';
18
18
  import type { DeformTransform, DeformTransformReport } from './deformgen.ts';
19
19
  import type { TurnCeiling } from './depth.ts';
20
- import type { SpecTypeRow } from './keys.ts';
20
+ import type { SpecEnumTable, SpecTypeRow } from './keys.ts';
21
21
  import type { MeshKind } from './mesh.ts';
22
+ import type { CompiledModel } from './model.ts';
22
23
  import type { TrackDerive, TrackDeriveReport } from './trackgen.ts';
23
24
 
24
25
  // ---------------------------------------------------------------------------
@@ -185,9 +186,9 @@ export interface FaceManifest {
185
186
  * wrong-typed plants on the three fixture manifests built green —
186
187
  * `crop.h: "256"` among them — and 4 threw a TypeError from `node:path`.
187
188
  *
188
- * Unchecked: `mesh.kind` and `mesh.hull` (`enum`) — the manifest mesh reader;
189
- * `crop` and the other nested shapes, `parts` and `mesh` (`object`) — the
190
- * readers that walk them.
189
+ * Unchecked by this walk: `mesh.kind` and `mesh.hull` (`enum`) — see
190
+ * `MANIFEST_ENUMS`, below; `crop` and the other nested shapes, `parts` and
191
+ * `mesh` (`object`) — the readers that walk them.
191
192
  */
192
193
  export const MANIFEST_TYPES = {
193
194
  FaceManifest: {
@@ -211,6 +212,34 @@ export const MANIFEST_TYPES = {
211
212
  'FaceManifestMesh.bias': { axis_deg: 'number', ramp: 'number[]', note: 'string' },
212
213
  } as const satisfies Record<string, SpecTypeRow>;
213
214
 
215
+ /** The two mesh generators a manifest part may name (`FaceManifestMesh.kind`); absent means `ring`. */
216
+ export const MANIFEST_MESH_KINDS = ['ring', 'ribbon'] as const satisfies ReadonlyArray<NonNullable<FaceManifestMesh['kind']>>;
217
+
218
+ /**
219
+ * Who refuses each `enum` row of `MANIFEST_TYPES` outside its set (issue #900);
220
+ * `SpecEnumTable` in [`keys.ts`](keys.ts) says what an entry means.
221
+ *
222
+ * 🚨 `mesh.kind` was listed as held by "the manifest mesh reader", and it was
223
+ * not held at all: that reader has three places that ask the kind, and they
224
+ * disagreed about a value outside the two. The mesh checks read `"foo"` as a
225
+ * ribbon, while the control-bone reader and the geometry builder read it as a
226
+ * ring — so a ring part was refused as *a ribbon mesh needs mesh.rows and a
227
+ * mesh.chain*, and a ribbon part as *a mesh with no control bone deforms
228
+ * nothing*, both naming a fault the part did not have. `hull` is held: the ring
229
+ * check refuses anything but `"polygon"` by name, and keeps that sentence.
230
+ */
231
+ export const MANIFEST_ENUMS = {
232
+ FaceManifestMesh: {
233
+ kind: {
234
+ set: MANIFEST_MESH_KINDS,
235
+ readAs:
236
+ 'anything else was read as a ribbon by the mesh checks and as a ring by the control-bone reader and the ' +
237
+ 'geometry builder, so the refusal it got named a fault the part did not have',
238
+ },
239
+ hull: { owner: 'compileInto' },
240
+ },
241
+ } as const satisfies SpecEnumTable<typeof MANIFEST_TYPES>;
242
+
214
243
  // ---------------------------------------------------------------------------
215
244
  // Motion spec (spec: "rigc-motion/1")
216
245
  // ---------------------------------------------------------------------------
@@ -1292,6 +1321,12 @@ export interface SpineSkeletonJson {
1292
1321
  >;
1293
1322
  }
1294
1323
 
1324
+ /** One entry of the emitted `skins` array — what `emitSkins` in `src/emit_spine.ts` writes per skin. */
1325
+ export type SpineSkin = SpineSkeletonJson['skins'][number];
1326
+
1327
+ /** One animation of the emitted `animations` object — what `emitAnimations` in `src/emit_spine.ts` writes per animation. */
1328
+ export type SpineAnimation = SpineSkeletonJson['animations'][string];
1329
+
1295
1330
  /** One entry of the emitted `events` map: the payload a firing inherits. */
1296
1331
  export interface SpineEvent {
1297
1332
  int?: number;
@@ -1522,6 +1557,17 @@ export interface DroppedState {
1522
1557
  }
1523
1558
 
1524
1559
  export interface CompileResult {
1560
+ /**
1561
+ * The compiled model (`src/model.ts`): what the skeleton below was emitted
1562
+ * from. This cut fills its `bones` and `setupWorld`; every other field is
1563
+ * this result's own, carried by reference.
1564
+ */
1565
+ model: CompiledModel;
1566
+ /**
1567
+ * The Spine 4.3 skeleton: `emitSkeleton`'s value over `model` (issue #922),
1568
+ * the one call the assembly makes. `build` writes its text, and beside it
1569
+ * `modelDocument(model)` as `skeleton.model.json`.
1570
+ */
1525
1571
  skeleton: SpineSkeletonJson;
1526
1572
  skeletonText: string;
1527
1573
  atlasText: string;
package/src/validate.ts CHANGED
@@ -289,16 +289,17 @@ export const SKIP_NO_ATLAS = 'the round trip did not produce an atlas to measure
289
289
  * `A15_IDLE_NO_MESH_BONE_KEYS` is the pattern and already reads this way: no
290
290
  * `idle` animation, or an `idle` with no bone timeline, is the named subject
291
291
  * absent and SKIPs; no mesh-driving bone among the bones `idle` does key is
292
- * the construct absent and passes. `A10_NO_NAN_AFTER_STEPPING` is the same
293
- * shape — the stepping is per animation, so a skeleton with none has not
294
- * been stepped.
292
+ * the construct absent and passes. `A10_NO_NAN_AFTER_STEPPING` was the same
293
+ * shape until issue #902, and is the next bullet's now: #882 gave it a
294
+ * setup-pose clause whose subject is the bones, beside the stepping clause
295
+ * whose subject is the animations.
295
296
  * * An assertion with more than one clause SKIPs only when EVERY clause had
296
297
  * nothing to measure, which is the shape `A09`, `A33` and `A38` already
297
- * carry (`polygons.length === 0 && endsChecked === 0`). `A13_MESH_BUDGET` is
298
- * why the clause is stated: a declared slot budget is measured against a
299
- * count of mesh slots, and zero is a count, so that half passes on a rig
300
- * with no mesh — while a rig that declares only a TRIANGLE budget has
301
- * nothing left to measure and skips.
298
+ * carry (`polygons.length === 0 && endsChecked === 0`), and `A10` since #902.
299
+ * `A13_MESH_BUDGET` is why the clause is stated: a declared slot budget is
300
+ * measured against a count of mesh slots, and zero is a count, so that half
301
+ * passes on a rig with no mesh — while a rig that declares only a TRIANGLE
302
+ * budget has nothing left to measure and skips.
302
303
  *
303
304
  * ⚠️ What the criterion is not allowed to become is a table of assertions with
304
305
  * their verdicts written beside them. Every row above is decided by reading the
@@ -318,6 +319,13 @@ export const SKIP_NO_ATLAS = 'the round trip did not produce an atlas to measure
318
319
  export const SKIP_NO_REGION_ATTACHMENT = 'the skeleton carries no region attachment';
319
320
  export const SKIP_NO_MESH_ATTACHMENT = 'the skeleton carries no mesh attachment';
320
321
  export const SKIP_NO_ANIMATION = 'the skeleton carries no animation';
322
+ /**
323
+ * A10's (issue #902): its setup clause reads the bones and its stepping clause
324
+ * the animations, so it skips only when the skeleton carries neither — and the
325
+ * sentence is `SKIP_NO_ANIMATION`'s with the second subject added, so the two
326
+ * cannot drift into different words for the same absence.
327
+ */
328
+ export const SKIP_NO_POSE = `${SKIP_NO_ANIMATION} and no bone, so there is no setup pose to read and nothing to step`;
321
329
  export const SKIP_NO_TIMELINE = 'no animation here carries a timeline';
322
330
  export const SKIP_NO_PHYSICS_CONSTRAINT = 'the skeleton declares no physics constraint';
323
331
  export const SKIP_NO_ATLAS_PAGE = 'the atlas declares no page';
@@ -347,8 +355,14 @@ export interface ValidateInput {
347
355
  atlasDir: string;
348
356
  /** Declared durations from the motion spec. */
349
357
  declaredDurations?: Record<string, number>;
350
- /** Re-emitted artifacts, for the determinism check. */
351
- reEmit?: { skeletonText: string; atlasText: string };
358
+ /**
359
+ * The compiled model's document (`modelDocument`, `rigc-compiled/1`) — the
360
+ * third file `build` writes. Required whenever `reEmit` is given, since `A18`
361
+ * compares it with the second compile's (issue #922).
362
+ */
363
+ modelText?: string;
364
+ /** Re-emitted artifacts, for the determinism check: a second, independent compile's three texts. */
365
+ reEmit?: { skeletonText: string; atlasText: string; modelText: string };
352
366
  /**
353
367
  * Structural expectations the artifact cannot state about itself: which mesh is
354
368
  * a ribbon, which bone carries the axis, which parentage is forbidden, what the
@@ -1115,6 +1129,19 @@ export function timelineAddBehaviour(data: ReturnType<SkeletonJson['readSkeleton
1115
1129
  return wrote ? 'overwrites' : 'inert';
1116
1130
  }
1117
1131
 
1132
+ /**
1133
+ * Where two texts first differ, as A18 names it: the 1-based line and each
1134
+ * side's line, trimmed and cut to 120 characters.
1135
+ */
1136
+ function firstDifferingLine(first: string, second: string): string {
1137
+ const a = first.split('\n');
1138
+ const b = second.split('\n');
1139
+ let i = 0;
1140
+ while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
1141
+ const cut = (line: string | undefined): string => (line === undefined ? '(end of text)' : JSON.stringify(line.trim().slice(0, 120)));
1142
+ return `${i + 1}: ${cut(a[i])} first, ${cut(b[i])} second`;
1143
+ }
1144
+
1118
1145
  export function validate(input: ValidateInput): ValidateReport {
1119
1146
  const failures: Failure[] = [];
1120
1147
  const passed: string[] = [];
@@ -4336,13 +4363,31 @@ export function validate(input: ValidateInput): ValidateReport {
4336
4363
 
4337
4364
  // --- A10: step every animation and look for NaN ------------------------
4338
4365
  check('A10_NO_NAN_AFTER_STEPPING', () => {
4339
- // The name carries a subject as well as a construct, and A15 is the
4340
- // pattern (#580): the NaN is produced by STEPPING, which happens once per
4341
- // animation, so a skeleton with none has not been stepped and has no pose
4342
- // to find non-finite. A09 already reads the same subject this way — a
4343
- // static rig has no duration to compare — and the two must not print
4344
- // different verdicts over one skeleton's empty animation list.
4345
- if (data.animations.length === 0) return skip('A10_NO_NAN_AFTER_STEPPING', SKIP_NO_ANIMATION);
4366
+ // Two clauses, and since issue #902 each is read on its own subject. The
4367
+ // SETUP POSE is posed from the bones, so it has something to read on any
4368
+ // skeleton that carries one; the STEPPED FRAMES are posed once per
4369
+ // animation, so a skeleton with none has nothing to step. This used to
4370
+ // skip the whole rule on the second fact alone, which was A15's pattern
4371
+ // (#580) for a rule whose only clause was the stepping — and #882 gave it
4372
+ // the setup clause without moving the skip. Measured on the static probe
4373
+ // with a leaf bone at `rotation: 1e309` in its emitted file: `validate`
4374
+ // printed this rule as SKIP and the run green under both profiles, and
4375
+ // `render` refused the same file by the bone. A static rig's setup pose
4376
+ // is the whole of what it shows, so that was the one pose nothing read.
4377
+ //
4378
+ // ⇒ The multi-clause rule of #580 now governs, the shape A09, A13, A33
4379
+ // and A38 carry: the rule SKIPs only when neither clause has anything to
4380
+ // measure, the clause that ran decides PASS or FAIL, and the clause that
4381
+ // had nothing is named on the stats line (`nanStepping=skipped`, beside
4382
+ // `animations=0`) the way A47 names a constraint it did not measure. A
4383
+ // PASS row carries no detail, which is why the stats line is where.
4384
+ //
4385
+ // ⚠️ A09 does not follow, and that is its own name read at its word: a
4386
+ // declared duration is a fact about an animation and nothing else, so a
4387
+ // static rig still gives it nothing at all.
4388
+ if (data.animations.length === 0 && data.bones.length === 0) {
4389
+ return skip('A10_NO_NAN_AFTER_STEPPING', SKIP_NO_POSE);
4390
+ }
4346
4391
  /** Is this a mode `updateWorldTransform`'s switch has a case for? Read off the runtime's own enum. */
4347
4392
  const isMode = (inherit: unknown): boolean => typeof inherit === 'number' && Inherit[inherit] !== undefined;
4348
4393
 
@@ -4421,6 +4466,73 @@ export function validate(input: ValidateInput): ValidateReport {
4421
4466
  // below is posed AFTER `state.apply`, so a bone the animation keys from
4422
4467
  // t=0 never shows its setup value to the loop, and a runtime that shows
4423
4468
  // the rig at rest does show it.
4469
+ //
4470
+ // 🔸 Posed once, before any animation is set, rather than once per
4471
+ // animation as it was until #902: `setAnimation` does not touch the
4472
+ // skeleton, so every animation's copy of this pose was the same pose, and
4473
+ // the first of them was the only one ever read.
4474
+ if (data.animations.length === 0) stats.nanStepping = 'skipped';
4475
+ const atRest = new Skeleton(data);
4476
+ atRest.setupPose();
4477
+ atRest.update(0);
4478
+ atRest.updateWorldTransform(Physics.reset);
4479
+ const atSetup = nonFiniteOfPosed('the setup pose', atRest);
4480
+ if (atSetup !== null) {
4481
+ fail('A10_NO_NAN_AFTER_STEPPING', atSetup);
4482
+ return;
4483
+ }
4484
+
4485
+ /**
4486
+ * What a posed frame shows that the world-transform scan does not read: a
4487
+ * bone posing no inheritance mode, and a slot colour that is not finite.
4488
+ * `where` leads the sentence — the animation's name at a stepped frame,
4489
+ * as it always has, or `the setup pose` on a skeleton with no animation.
4490
+ */
4491
+ const poseDefect = (where: string, skeleton: Skeleton): string | null => {
4492
+ for (const bone of skeleton.bones) {
4493
+ const pose = bone.appliedPose;
4494
+ // The setup half of the inherit-key clause above: a bone's own
4495
+ // `inherit` goes through the same lookup, and a miss there loads
4496
+ // `undefined` into the setup pose, which every frame copies. Only
4497
+ // reachable on a file rigc did not write — `parseRigSpec` refuses the
4498
+ // spelling.
4499
+ if (!isMode(pose.inherit)) {
4500
+ const rawBone = Array.isArray(raw?.bones)
4501
+ ? (raw.bones as unknown[]).find((b) => isObj(b) && b.name === bone.data.name)
4502
+ : undefined;
4503
+ return (
4504
+ `${where}: bone "${bone.data.name}" poses inheritance mode ${String(pose.inherit)} — its setup ` +
4505
+ `spells inherit ${JSON.stringify(isObj(rawBone) ? rawBone.inherit : undefined)}, which the ` +
4506
+ `runtime's mode lookup does not resolve (${BONE_INHERIT_KNOWN}), so its world rotation, scale and shear ` +
4507
+ 'are never computed — they stay 0 and everything the bone carries collapses to a point'
4508
+ );
4509
+ }
4510
+ }
4511
+ for (const slot of skeleton.slots) {
4512
+ const c = slot.appliedPose.color;
4513
+ if (![c.r, c.g, c.b, c.a].every(Number.isFinite)) return `${where}: slot "${slot.data.name}" colour is non-finite`;
4514
+ // The other colour a slot poses, and it was outside this loop until
4515
+ // issue #690 for the reason every gap here has: nothing emitted one.
4516
+ // `null` is the ordinary case — a slot with no `dark` allocates no
4517
+ // dark colour at all — and is not a reading to make, so it is
4518
+ // skipped rather than treated as zero.
4519
+ const d = slot.appliedPose.darkColor;
4520
+ if (d !== null && ![d.r, d.g, d.b].every(Number.isFinite)) {
4521
+ return `${where}: slot "${slot.data.name}" dark colour is non-finite`;
4522
+ }
4523
+ }
4524
+ return null;
4525
+ };
4526
+
4527
+ // The stepping half, and on a static rig there is nothing to step: the
4528
+ // setup pose is then the only frame the skeleton has, and the two readings
4529
+ // a stepped frame gets are made on it instead, so a colour or an
4530
+ // inheritance mode the rig shows at rest is not left to `render`.
4531
+ if (data.animations.length === 0) {
4532
+ const atRestDefect = poseDefect('the setup pose', atRest);
4533
+ if (atRestDefect !== null) fail('A10_NO_NAN_AFTER_STEPPING', atRestDefect);
4534
+ return;
4535
+ }
4424
4536
  for (const anim of data.animations) {
4425
4537
  const skeleton = new Skeleton(data);
4426
4538
  const state = new AnimationState(new AnimationStateData(data));
@@ -4428,11 +4540,6 @@ export function validate(input: ValidateInput): ValidateReport {
4428
4540
  skeleton.setupPose();
4429
4541
  skeleton.update(0);
4430
4542
  skeleton.updateWorldTransform(Physics.reset);
4431
- const atSetup = nonFiniteOfPosed('the setup pose', skeleton);
4432
- if (atSetup !== null) {
4433
- fail('A10_NO_NAN_AFTER_STEPPING', atSetup);
4434
- return;
4435
- }
4436
4543
  const step = Math.max(anim.duration, 1) / STEP_FRAMES;
4437
4544
  for (let i = 0; i < STEP_FRAMES; i++) {
4438
4545
  state.update(step);
@@ -4447,42 +4554,10 @@ export function validate(input: ValidateInput): ValidateReport {
4447
4554
  fail('A10_NO_NAN_AFTER_STEPPING', found);
4448
4555
  return;
4449
4556
  }
4450
- for (const bone of skeleton.bones) {
4451
- const pose = bone.appliedPose;
4452
- // The setup half of the clause above: a bone's own `inherit` goes
4453
- // through the same lookup, and a miss there loads `undefined` into
4454
- // the setup pose, which every frame copies. Only reachable on a
4455
- // file rigc did not write — `parseRigSpec` refuses the spelling.
4456
- if (!isMode(pose.inherit)) {
4457
- const rawBone = Array.isArray(raw?.bones)
4458
- ? (raw.bones as unknown[]).find((b) => isObj(b) && b.name === bone.data.name)
4459
- : undefined;
4460
- fail(
4461
- 'A10_NO_NAN_AFTER_STEPPING',
4462
- `${anim.name}: bone "${bone.data.name}" poses inheritance mode ${String(pose.inherit)} — its setup ` +
4463
- `spells inherit ${JSON.stringify(isObj(rawBone) ? rawBone.inherit : undefined)}, which the ` +
4464
- `runtime's mode lookup does not resolve (${BONE_INHERIT_KNOWN}), so its world rotation, scale and shear ` +
4465
- 'are never computed — they stay 0 and everything the bone carries collapses to a point',
4466
- );
4467
- return;
4468
- }
4469
- }
4470
- for (const slot of skeleton.slots) {
4471
- const c = slot.appliedPose.color;
4472
- if (![c.r, c.g, c.b, c.a].every(Number.isFinite)) {
4473
- fail('A10_NO_NAN_AFTER_STEPPING', `${anim.name}: slot "${slot.data.name}" colour is non-finite`);
4474
- return;
4475
- }
4476
- // The other colour a slot poses, and it was outside this loop until
4477
- // issue #690 for the reason every gap here has: nothing emitted one.
4478
- // `null` is the ordinary case — a slot with no `dark` allocates no
4479
- // dark colour at all — and is not a reading to make, so it is
4480
- // skipped rather than treated as zero.
4481
- const d = slot.appliedPose.darkColor;
4482
- if (d !== null && ![d.r, d.g, d.b].every(Number.isFinite)) {
4483
- fail('A10_NO_NAN_AFTER_STEPPING', `${anim.name}: slot "${slot.data.name}" dark colour is non-finite`);
4484
- return;
4485
- }
4557
+ const defect = poseDefect(anim.name, skeleton);
4558
+ if (defect !== null) {
4559
+ fail('A10_NO_NAN_AFTER_STEPPING', defect);
4560
+ return;
4486
4561
  }
4487
4562
  }
4488
4563
  }
@@ -6093,6 +6168,15 @@ export function validate(input: ValidateInput): ValidateReport {
6093
6168
  if (input.reEmit.atlasText !== input.atlasText) {
6094
6169
  fail('A18_DETERMINISTIC_EMIT', 'recompiling produced a different skeleton.atlas');
6095
6170
  }
6171
+ // The model document is compared like the Spine pair (issue #922): it is
6172
+ // written beside them, and a map iterated in an order nothing fixed would
6173
+ // reach it before it reached either of them — the document writes every
6174
+ // `Map` of the model as an array in the map's order.
6175
+ if (input.modelText === undefined) {
6176
+ fail('A18_DETERMINISTIC_EMIT', 'a second compile was handed over with no first model document to compare its skeleton.model.json against');
6177
+ } else if (input.reEmit.modelText !== input.modelText) {
6178
+ fail('A18_DETERMINISTIC_EMIT', `recompiling produced a different skeleton.model.json (first differing line ${firstDifferingLine(input.modelText, input.reEmit.modelText)})`);
6179
+ }
6096
6180
  });
6097
6181
 
6098
6182
  // --- every assertion leaves a row ----------------------------------------