spine-rigc 1.8.0 → 1.9.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.
Files changed (63) hide show
  1. package/cli.ts +2 -2
  2. package/docs/AUTHORING.md +3 -3
  3. package/package.json +1 -1
  4. package/src/assertions/bodies/a04.ts +40 -0
  5. package/src/assertions/bodies/a06.ts +195 -0
  6. package/src/assertions/bodies/a08.ts +76 -0
  7. package/src/assertions/bodies/a13.ts +51 -0
  8. package/src/assertions/bodies/a14.ts +35 -0
  9. package/src/assertions/bodies/a15.ts +97 -0
  10. package/src/assertions/bodies/a19.ts +295 -0
  11. package/src/assertions/bodies/a20.ts +122 -0
  12. package/src/assertions/bodies/a21.ts +190 -0
  13. package/src/assertions/bodies/a22.ts +39 -0
  14. package/src/assertions/bodies/a23.ts +255 -0
  15. package/src/assertions/bodies/a27.ts +33 -0
  16. package/src/assertions/bodies/a28.ts +70 -0
  17. package/src/assertions/bodies/a33.ts +110 -0
  18. package/src/assertions/bodies/a36.ts +81 -0
  19. package/src/assertions/bodies/a37.ts +77 -0
  20. package/src/assertions/bodies/a38.ts +73 -0
  21. package/src/assertions/bodies/a41.ts +83 -0
  22. package/src/assertions/bodies/a42.ts +97 -0
  23. package/src/assertions/bodies/a44.ts +23 -0
  24. package/src/assertions/bodies/a47.ts +59 -0
  25. package/src/assertions/bodies/a48.ts +83 -0
  26. package/src/assertions/constraint_words.ts +177 -0
  27. package/src/assertions/facts/animated_bones.ts +28 -0
  28. package/src/assertions/facts/atlas_regions.ts +52 -0
  29. package/src/assertions/facts/constraints.ts +131 -0
  30. package/src/assertions/facts/linked_meshes.ts +38 -0
  31. package/src/assertions/facts/mesh_attachments.ts +71 -0
  32. package/src/assertions/facts/region_joins.ts +34 -0
  33. package/src/assertions/facts/skin_entries.ts +4 -2
  34. package/src/assertions/facts/skin_members.ts +53 -0
  35. package/src/assertions/facts/skin_meshes.ts +49 -0
  36. package/src/assertions/facts/stage.ts +24 -0
  37. package/src/assertions/facts/vertex_polygons.ts +53 -0
  38. package/src/assertions/mesh_kinds.ts +56 -0
  39. package/src/assertions/model/animated_bones.ts +30 -0
  40. package/src/assertions/model/atlas_regions.ts +76 -0
  41. package/src/assertions/model/constraints.ts +207 -0
  42. package/src/assertions/model/given.ts +45 -0
  43. package/src/assertions/model/index.ts +130 -13
  44. package/src/assertions/model/linked_meshes.ts +24 -0
  45. package/src/assertions/model/mesh_attachments.ts +90 -0
  46. package/src/assertions/model/parse.ts +2 -0
  47. package/src/assertions/model/region_joins.ts +59 -0
  48. package/src/assertions/model/skin_entries.ts +2 -1
  49. package/src/assertions/model/skin_members.ts +62 -0
  50. package/src/assertions/model/skin_meshes.ts +90 -0
  51. package/src/assertions/model/stage.ts +28 -0
  52. package/src/assertions/model/vertex_polygons.ts +71 -0
  53. package/src/assertions/region_lookups.ts +61 -0
  54. package/src/check.ts +8 -6
  55. package/src/compile.ts +145 -38
  56. package/src/core/index.ts +154 -24
  57. package/src/deformstructure.ts +16 -7
  58. package/src/emit_spine.ts +21 -41
  59. package/src/keyorder.ts +40 -0
  60. package/src/model.ts +183 -20
  61. package/src/render.ts +66 -25
  62. package/src/render_core.ts +41 -13
  63. package/src/validate.ts +601 -2328
package/src/compile.ts CHANGED
@@ -128,13 +128,15 @@ import {
128
128
  TransformError,
129
129
  type BoneTransform,
130
130
  } from './transform.ts';
131
- import { emitSkeleton, PHYSICS_PARAMS, UNSTATED_REFERENCE_SCALE, type SkeletonHeader } from './emit_spine.ts';
131
+ import { emitSkeleton, type SkeletonHeader } from './emit_spine.ts';
132
+ import { PHYSICS_PARAMS, UNSTATED_REFERENCE_SCALE } from './keyorder.ts';
132
133
  import { curveLengthTable } from './core/constraints_path.ts';
133
134
  import { frameRegionName } from './core/uvs.ts';
134
135
  import {
135
136
  isModelVertexAttachment,
136
137
  type CarriedFromCompileResult,
137
138
  type CompiledAnimation,
139
+ type CompiledModel,
138
140
  type ModelAttachmentTimelines,
139
141
  type ModelBinding,
140
142
  type ModelBone,
@@ -142,6 +144,7 @@ import {
142
144
  type ModelClippingAttachment,
143
145
  type ModelConstraint,
144
146
  type ModelConstraintKind,
147
+ type ModelEditorOrder,
145
148
  type ModelEvent,
146
149
  type ModelKey,
147
150
  type ModelLinkedMeshAttachment,
@@ -153,6 +156,7 @@ import {
153
156
  type ModelSequence,
154
157
  type ModelSkin,
155
158
  type ModelSlot,
159
+ type ModelStage,
156
160
  type ModelTimelines,
157
161
  type ModelVertices,
158
162
  type SkinTable,
@@ -1217,7 +1221,7 @@ const BONE_TRACKS: Record<string, ValueTrackShape> = {
1217
1221
  * `:1062` and only `mix` reassigns it (`:1090`), so an `inertia` key that omits
1218
1222
  * `value` reads **0** — not the 0.5 that `:306` gives a constraint that states
1219
1223
  * no `inertia`. Two different tables of defaults sit forty lines apart in one
1220
- * file (`PHYSICS_PARAMS` in `src/emit_spine.ts` holds the other one), and reading the setup
1224
+ * file (`PHYSICS_PARAMS` in `src/keyorder.ts` holds the other one), and reading the setup
1221
1225
  * column into this one would emit a `damping` timeline whose omitted keys mean
1222
1226
  * 0.85 to the author and 0 to the runtime. Nothing here depends on the number,
1223
1227
  * because `compileValueTrack` writes every field explicitly — it is recorded
@@ -1450,7 +1454,9 @@ const CONSTRAINT_TIMELINES: Record<'ik' | 'transform', ConstraintTimelineShape>
1450
1454
  /**
1451
1455
  * The five components a physics constraint drives. The parameters and their
1452
1456
  * parser defaults are `PHYSICS_PARAMS`, which moved to `src/emit_spine.ts` with
1453
- * the omission it decides (issue #919).
1457
+ * the omission it decides (issue #919) and to `src/keyorder.ts`, beside the
1458
+ * parser's other defaults, when the compiler stopped importing the emitter for
1459
+ * it (issue #1026).
1454
1460
  *
1455
1461
  * `PHYSICS_COMPONENTS` is exported for `ingest.ts`, which omits a constraint that
1456
1462
  * drives none of them (issue #731) and must read "drives" off the same five
@@ -2047,26 +2053,89 @@ function manifestShapeVisits(manifest: unknown): ShapeVisit[] {
2047
2053
  /**
2048
2054
  * Compile a rig spec and a motion spec into Spine 4.3 skeleton data.
2049
2055
  *
2050
- * The body is `compileInto`; this wrapper exists for one reason, and it is the
2051
- * whole of issue #671's second half: the states a manifest listed and the art
2052
- * was missing for are reported from the compile RESULT, which a throw never
2053
- * returns. So the run whose refusal was CAUSED by a missing file was the one
2054
- * run that never named the file. Annotating whatever was thrown — rather than
2055
- * re-wrapping it, which would cost a `NotImplementedError` its class — carries
2056
- * those facts out of every refusal raised after the drop was recorded, not only
2057
- * out of the one that consults them.
2056
+ * `compileModel` followed by the emission (issue #1026): the model and what
2057
+ * goes beside it come from the one entry that does not call the Spine
2058
+ * emitter, and this function hands that model to `emitSkeleton` once. Its
2059
+ * result is the shape it always had. Both run under `withDroppedStates`, so a
2060
+ * refusal raised after a dropped state was recorded names the missing file
2061
+ * (issue #671).
2058
2062
  */
2059
2063
  export function compile(opts: CompileOptions): CompileResult {
2064
+ return withDroppedStates((droppedStates) => {
2065
+ const { model, header, atlasText, declaredDurations } = compileInto(opts, droppedStates);
2066
+ // The skeleton: the Spine emitter's one entry (issue #922), which writes
2067
+ // every section from the model, in the order and under the spellings the
2068
+ // file has, and runs the parser-default and key-order passes on the
2069
+ // finished object. What it is handed besides the model is what the model
2070
+ // does not hold — the rest of the header — and the editor's orders, the
2071
+ // same functions `compileModel` stated the model's `editorOrder` with: the
2072
+ // sorts are applied at emission, so the model's `skins` and `animations`
2073
+ // keep the spec's own order.
2074
+ const skeleton = emitSkeleton(model, header, EDITOR_ORDERS);
2075
+ return {
2076
+ skeleton,
2077
+ skeletonText: `${JSON.stringify(skeleton, null, 2)}\n`,
2078
+ atlasText,
2079
+ declaredDurations,
2080
+ ...carriedOf(model),
2081
+ model,
2082
+ };
2083
+ });
2084
+ }
2085
+
2086
+ /**
2087
+ * What `compileModel` returns: the compiled model, and what a caller needs
2088
+ * beside it to gate it, write its document and — if it asks — emit it.
2089
+ */
2090
+ export interface CompiledBuild {
2091
+ /** The compiled model (`src/model.ts`), `stage` and `editorOrder` included (issue #1026). */
2092
+ model: CompiledModel;
2093
+ /** The rest of the Spine header the model does not hold (`SkeletonHeader`): what `compile` hands the emitter beside the model. */
2094
+ header: SkeletonHeader;
2095
+ /** The atlas text the compile measured its art against — `CompileResult.atlasText`. */
2096
+ atlasText: string;
2097
+ /** Declared durations, carried into the validator (rule 4) — `CompileResult.declaredDurations`. */
2098
+ declaredDurations: Record<string, number>;
2099
+ }
2100
+
2101
+ /**
2102
+ * Compile a rig spec and a motion spec into the compiled model WITHOUT calling
2103
+ * the Spine emitter (issue #1026, step 4a of #380): everything `compile` does
2104
+ * up to the one `emitSkeleton` call, and nothing after it. `compile` is this
2105
+ * entry followed by the emission, so the model a caller gets here is the model
2106
+ * `compile` emits from — the same refusals, in the same order, raised from the
2107
+ * same place (the editor's orders included: `editorOrder` is computed here, by
2108
+ * the functions the emitter is then handed).
2109
+ *
2110
+ * What it does not return is what only the emission makes: the Spine skeleton
2111
+ * and its text, and with them the digest a model document records of the
2112
+ * skeleton written beside it (`spine.sha256`). A command that writes a build
2113
+ * with no Spine pair is not this entry's: `build` still emits (issue #1026).
2114
+ */
2115
+ export function compileModel(opts: CompileOptions): CompiledBuild {
2116
+ return withDroppedStates((droppedStates) => compileInto(opts, droppedStates));
2117
+ }
2118
+
2119
+ /**
2120
+ * Run a compile, annotating whatever it throws with the states a manifest
2121
+ * listed and the art was missing for (`CompileError.droppedStates`): the
2122
+ * whole of issue #671's second half — those states are reported from the
2123
+ * compile RESULT, which a throw never returns, so the run whose refusal was
2124
+ * caused by a missing file was the one run that never named the file.
2125
+ * Annotating rather than re-wrapping keeps a `NotImplementedError` its class.
2126
+ * A refusal the emission raises after the drop was recorded is annotated too.
2127
+ */
2128
+ function withDroppedStates<T>(run: (droppedStates: DroppedState[]) => T): T {
2060
2129
  const droppedStates: DroppedState[] = [];
2061
2130
  try {
2062
- return compileInto(opts, droppedStates);
2131
+ return run(droppedStates);
2063
2132
  } catch (err) {
2064
2133
  if (err instanceof CompileError && droppedStates.length > 0) err.droppedStates = [...droppedStates];
2065
2134
  throw err;
2066
2135
  }
2067
2136
  }
2068
2137
 
2069
- function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): CompileResult {
2138
+ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): CompiledBuild {
2070
2139
  const rigPath = resolve(opts.rigPath);
2071
2140
  const motionPath = resolve(opts.motionPath);
2072
2141
  const outDir = resolve(opts.outDir);
@@ -3390,16 +3459,18 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
3390
3459
 
3391
3460
  // -- 6. assemble -----------------------------------------------------------
3392
3461
  //
3393
- // What the skeleton carries that the model does not hold: the header. The
3394
- // stage is four fields or none of them — `x`/`y` are the origin of the box
3395
- // `width`/`height` give an extent to, so a header carrying an origin for a box
3396
- // it does not declare would be a shape no export has (issue #578).
3462
+ // The stage is four fields or none of them — `x`/`y` are the origin of the
3463
+ // box `width`/`height` give an extent to, so a header carrying an origin for
3464
+ // a box it does not declare would be a shape no export has (issue #578). The
3465
+ // model holds it since issue #1026 (`ModelStage`), and the emitter writes the
3466
+ // model's value into the header, as it writes `referenceScale`.
3467
+ const stage: ModelStage | null =
3468
+ stageWidth !== undefined && stageHeight !== undefined
3469
+ ? { x: rig.skeleton?.x ?? 0, y: rig.skeleton?.y ?? 0, width: stageWidth, height: stageHeight }
3470
+ : null;
3471
+ // What the skeleton carries that the model does not hold: the rest of the header.
3397
3472
  const header: SkeletonHeader = {
3398
3473
  spine: SPINE_VERSION,
3399
- stage:
3400
- stageWidth !== undefined && stageHeight !== undefined
3401
- ? { x: rig.skeleton?.x ?? 0, y: rig.skeleton?.y ?? 0, width: stageWidth, height: stageHeight }
3402
- : null,
3403
3474
  fps: rig.skeleton?.fps,
3404
3475
  images: skeletonImagesPath(rig.skeleton?.images, opts, outDir, partDirs),
3405
3476
  audio: rig.skeleton?.audio,
@@ -3431,24 +3502,29 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
3431
3502
  };
3432
3503
  });
3433
3504
 
3434
- // The skeleton: the Spine emitter's one entry (issue #922), which writes every
3435
- // section from the model, in the order and under the spellings the file has,
3436
- // and runs the parser-default and key-order passes on the finished object.
3437
- // What it is handed besides the model is what the model does not hold: the
3438
- // header above, and the editor's orders, which stay here (see `editorSkinOrder` and
3439
- // `editorAnimationOrder`): the sorts are applied at emission, so everything
3440
- // this function reads, and the model's `skins` and `animations`, keep the
3441
- // spec's own order.
3442
3505
  // The skeleton's reference scale, which wind and gravity act over (issue
3443
3506
  // #958): the rig's stated number as it is, or the value the parser reads a
3444
3507
  // header stating none as. The model holds it; the emitter writes it into the
3445
3508
  // header, where the parser-default pass drops it at 100 as before.
3446
3509
  const referenceScale = rig.skeleton?.referenceScale ?? UNSTATED_REFERENCE_SCALE;
3447
- const skeleton = emitSkeleton(
3448
- { referenceScale, bones, slots, skins, constraints, events, animations },
3449
- header,
3450
- { skins: editorSkinOrder, slotKeys: editorSlotKeyOrder, animations: editorAnimationOrder },
3451
- );
3510
+ // The editor's orders (issue #1026, `ModelEditorOrder`): the three functions
3511
+ // `compile` hands the Spine emitter (`EDITOR_ORDERS`), run here over the same
3512
+ // model, so the order the document states and the order `skeleton.json` keys
3513
+ // are one computation. Skins first and animations second, as the emitter
3514
+ // applies them, so a name pair the editor could key two ways is refused here
3515
+ // in the order it was refused at emission before this entry existed.
3516
+ //
3517
+ // ⚠️ A name list the file KEYS is stated as the keys of an object filled in
3518
+ // that order, not as the sorted list: the file's `animations` and a skin's
3519
+ // `attachments` are JSON objects, and an object lists an integer-like key
3520
+ // ("2", "10") before every other key, in ascending order, whatever order it
3521
+ // was filled in. That is the order `skeleton.json` spells and its parser
3522
+ // reads, so it is the order stated here; the skins are an array and keep the
3523
+ // sort's.
3524
+ const editorOrder: ModelEditorOrder = {
3525
+ skins: EDITOR_ORDERS.skins(skins).map((skin) => ({ name: skin.name, slots: Object.keys(EDITOR_ORDERS.slotKeys(skin.attachments)) })),
3526
+ animations: keyedOrder(EDITOR_ORDERS.animations([...animations.keys()])),
3527
+ };
3452
3528
 
3453
3529
  for (const slot of slots) {
3454
3530
  if (!boneNames.has(slot.bone)) throw new CompileError(`slot "${slot.name}" has no bone`);
@@ -3469,12 +3545,43 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
3469
3545
  rig: buildRigInfo(rig, bones, meshes, manifest, images),
3470
3546
  };
3471
3547
  return {
3472
- skeleton,
3473
- skeletonText: `${JSON.stringify(skeleton, null, 2)}\n`,
3548
+ model: { referenceScale, stage, bones, setupWorld: transforms, slots, skins, constraints, events, animations, editorOrder, ...carried },
3549
+ header,
3474
3550
  atlasText,
3475
3551
  declaredDurations,
3476
- ...carried,
3477
- model: { referenceScale, bones, setupWorld: transforms, slots, skins, constraints, events, animations, ...carried },
3552
+ };
3553
+ }
3554
+
3555
+ /**
3556
+ * The editor's orders, as `compile` hands them to the Spine emitter and as
3557
+ * `compileModel` states them in the model (`editorOrder`, issue #1026) — one
3558
+ * object, so the two cannot be handed different functions.
3559
+ */
3560
+ const EDITOR_ORDERS = { skins: editorSkinOrder, slotKeys: editorSlotKeyOrder, animations: editorAnimationOrder } as const;
3561
+
3562
+ /** The order an object filled with `names`, in that order, lists its keys in — the order a JSON object keyed by them is spelled in. */
3563
+ function keyedOrder(names: readonly string[]): string[] {
3564
+ const keyed: Record<string, true> = {};
3565
+ for (const name of names) keyed[name] = true;
3566
+ return Object.keys(keyed);
3567
+ }
3568
+
3569
+ /**
3570
+ * The fields `CompileResult` carries from the model, in the order it has
3571
+ * always carried them (`CarriedFromCompileResult`), by reference.
3572
+ */
3573
+ function carriedOf(model: CompiledModel): CarriedFromCompileResult {
3574
+ return {
3575
+ images: model.images,
3576
+ pageGrids: model.pageGrids,
3577
+ droppedStates: model.droppedStates,
3578
+ absentParts: model.absentParts,
3579
+ meshBones: model.meshBones,
3580
+ meshes: model.meshes,
3581
+ physics: model.physics,
3582
+ deformTransforms: model.deformTransforms,
3583
+ trackDerivations: model.trackDerivations,
3584
+ rig: model.rig,
3478
3585
  };
3479
3586
  }
3480
3587
 
package/src/core/index.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * rigc's own core: it reads the compiled model as `build` writes it
3
- * (`rigc-compiled/2`, and `/1` before issue #1016; `skeleton.model.json`)
3
+ * (`rigc-compiled/3`, and `/2` before issue #1026 and `/1` before issue #1016;
4
+ * `skeleton.model.json`)
4
5
  * and poses it (issue #925, step 2a
5
6
  * of issue #380). It is the second dumper `tools/pose_oracle.ts` was shaped
6
7
  * for: what it poses is written into the same `pose-oracle/2` document the
@@ -171,7 +172,7 @@
171
172
  * child process, no file system — `readModel` takes the document's TEXT — and
172
173
  * nothing from the Spine runtime package, as a value or as a type.
173
174
  */
174
- import type { ModelAtlasRect, ModelBone, ModelPage, ModelPageRegion, ModelSlot, ModelVertices, SkinTableEntry } from '../model.ts';
175
+ import type { ModelAtlasRect, ModelBone, ModelEditorOrder, ModelPage, ModelPageRegion, ModelSlot, ModelStage, ModelVertices, SkinTableEntry } from '../model.ts';
175
176
  import { worldTransforms, type CoreWorld } from './world.ts';
176
177
  import { readAnimationTimelines, type CoreAnimationTimelines } from './animation.ts';
177
178
  import { readEventDefs, type CoreEventDef } from './events.ts';
@@ -187,19 +188,32 @@ import { drawOrderAt, type DrawOrderEvaluator } from './draw_order.ts';
187
188
  import type { EventsFired } from './events.ts';
188
189
 
189
190
  /**
190
- * The document spec `build` writes today, and the one this reader takes with
191
- * the `pages` section (issue #1016).
191
+ * The document spec `build` writes today (issue #1026): the `pages` section
192
+ * (issue #1016) with each page's `pma` and `scale`, and the `stage` and
193
+ * `editorOrder` sections — what only the Spine files beside a `/2` document
194
+ * state.
192
195
  */
193
- export const CORE_DOCUMENT_SPEC = 'rigc-compiled/2';
196
+ export const CORE_DOCUMENT_SPEC = 'rigc-compiled/3';
194
197
 
195
198
  /**
196
- * The spec before issue #1016: the same sections without `pages`. Read as
197
- * before — the draw then takes where each region sits from the atlas beside
198
- * the document (`corePoser` in `src/render_core.ts` says so by name), because
199
- * a `/1` document does not state it.
199
+ * The spec before issue #1026: `/3` without `stage`, `editorOrder` and the
200
+ * pages' `pma` and `scale`. Read as before, with `stated` null — a reader that
201
+ * needs those reads them off the Spine files beside the document, and says so
202
+ * (`src/render.ts`'s poser line, the survey's order).
203
+ */
204
+ export const CORE_DOCUMENT_SPEC_2 = 'rigc-compiled/2';
205
+
206
+ /**
207
+ * The spec before issue #1016: `/2` without `pages`. Read as before — the
208
+ * draw then takes where each region sits from the atlas beside the document
209
+ * (`corePoser` in `src/render_core.ts` says so by name), because a `/1`
210
+ * document does not state it.
200
211
  */
201
212
  export const CORE_DOCUMENT_SPEC_1 = 'rigc-compiled/1';
202
213
 
214
+ /** Every spec this reader takes, newest first. */
215
+ export const CORE_DOCUMENT_SPECS: readonly string[] = [CORE_DOCUMENT_SPEC, CORE_DOCUMENT_SPEC_2, CORE_DOCUMENT_SPEC_1];
216
+
203
217
  /** Who posed a dump the core wrote — the oracle document's `dumper`. */
204
218
  export const CORE_DUMPER = 'rigc-core';
205
219
 
@@ -208,7 +222,8 @@ export class CoreInputError extends Error {}
208
222
 
209
223
  /** The document's sections after `spec`, in its key order (`modelDocument` in `src/model.ts`). */
210
224
  export const CORE_SECTIONS = [
211
- 'referenceScale', 'bones', 'slots', 'skins', 'constraints', 'events', 'animations',
225
+ // Issue #1026: `stage` (the header's setup-pose box, or null) and `editorOrder` (the order the Spine file lists skins, slot keys and animations in). `/3` only.
226
+ 'referenceScale', 'stage', 'bones', 'slots', 'skins', 'constraints', 'events', 'animations', 'editorOrder',
212
227
  'images', 'pageGrids', 'droppedStates', 'absentParts', 'meshBones', 'meshes', 'physics', 'deformTransforms', 'trackDerivations', 'rig',
213
228
  // Issue #1016: where each region sits on its page, in the atlas written beside the document (`pagesOfAtlas` in `src/model.ts`). `/2` only.
214
229
  'pages',
@@ -216,11 +231,18 @@ export const CORE_SECTIONS = [
216
231
  'spine',
217
232
  ] as const;
218
233
 
219
- /** The sections of a `rigc-compiled/1` document: `CORE_SECTIONS` without `pages`. */
220
- export const CORE_SECTIONS_1: readonly string[] = CORE_SECTIONS.filter((key) => key !== 'pages');
234
+ /** The sections of a `rigc-compiled/2` document: `CORE_SECTIONS` without `stage` and `editorOrder`. */
235
+ export const CORE_SECTIONS_2: readonly string[] = CORE_SECTIONS.filter((key) => key !== 'stage' && key !== 'editorOrder');
236
+
237
+ /** The sections of a `rigc-compiled/1` document: `CORE_SECTIONS_2` without `pages`. */
238
+ export const CORE_SECTIONS_1: readonly string[] = CORE_SECTIONS_2.filter((key) => key !== 'pages');
221
239
 
222
240
  /** The fields of a page and of a region in the `pages` section, as the writer lists them (`MODEL_PAGE_FIELDS`, `MODEL_PAGE_REGION_FIELDS` in `src/model.ts`, mirrored). */
223
- export const CORE_PAGE_FIELDS = ['name', 'width', 'height', 'regions'] as const;
241
+ export const CORE_PAGE_FIELDS = ['name', 'width', 'height', 'pma', 'scale', 'regions'] as const;
242
+ /** A `rigc-compiled/2` page's fields: `CORE_PAGE_FIELDS` without `pma` and `scale` (issue #1026). */
243
+ export const CORE_PAGE_FIELDS_2: readonly string[] = CORE_PAGE_FIELDS.filter((key) => key !== 'pma' && key !== 'scale');
244
+ /** The stage's fields, as the writer lists them (`MODEL_STAGE_FIELDS` in `src/model.ts`, mirrored). */
245
+ export const CORE_STAGE_FIELDS = ['x', 'y', 'width', 'height'] as const;
224
246
  export const CORE_PAGE_REGION_FIELDS = ['name', 'x', 'y', 'width', 'height', 'offsetX', 'offsetY', 'originalWidth', 'originalHeight', 'degrees', 'index'] as const;
225
247
 
226
248
  /** The fields a bone record may carry, as the writer lists them. A field outside this list is refused. */
@@ -320,7 +342,7 @@ export interface CoreAnimation {
320
342
  }
321
343
 
322
344
  /**
323
- * A `rigc-compiled/2` (or `/1`) document, read. `bones` and `slots` are checked field by
345
+ * A `rigc-compiled/3` (or `/2`, or `/1`) document, read. `bones` and `slots` are checked field by
324
346
  * field against the writer's own records; skins and constraints are read as
325
347
  * far as their names and memberships, and every other section is only
326
348
  * required to be present — no construct this card admits reads it.
@@ -346,9 +368,23 @@ export interface CompiledDocument {
346
368
  * Every page of the atlas `build` wrote beside the document and every region
347
369
  * on it, in file order (issue #1016) — where each drawing sits, which the
348
370
  * draw's page UVs read. `null` for a `rigc-compiled/1` document, which does
349
- * not state it.
371
+ * not state it. A `rigc-compiled/3` document's pages carry `pma` and `scale`
372
+ * too (issue #1026); a `/2` document's carry neither.
350
373
  */
351
374
  pages: ModelPage[] | null;
375
+ /**
376
+ * What a `rigc-compiled/3` document states that only the Spine files beside
377
+ * a `/2` or `/1` document hold (issue #1026): the setup-pose box the header
378
+ * declares, or `null` for none, and the order the editor lists skins, their
379
+ * slot keys and animations in. `null` for a `/2` or `/1` document.
380
+ */
381
+ stated: CoreStated | null;
382
+ }
383
+
384
+ /** A `rigc-compiled/3` document's `stage` and `editorOrder`, read (`CompiledDocument.stated`). */
385
+ export interface CoreStated {
386
+ stage: ModelStage | null;
387
+ editorOrder: ModelEditorOrder;
352
388
  }
353
389
 
354
390
  /**
@@ -359,7 +395,7 @@ export interface CompiledDocument {
359
395
  * fault is named by its path. Nothing is defaulted: a field the writer always
360
396
  * writes is required here.
361
397
  */
362
- function readPages(value: unknown, problems: string[]): ModelPage[] {
398
+ function readPages(value: unknown, problems: string[], flags: boolean): ModelPage[] {
363
399
  if (!Array.isArray(value)) {
364
400
  problems.push(`pages is ${JSON.stringify(value) ?? 'absent'}, not a list of pages`);
365
401
  return [];
@@ -373,12 +409,17 @@ function readPages(value: unknown, problems: string[]): ModelPage[] {
373
409
  }
374
410
  const before = problems.length;
375
411
  const label = typeof raw.name === 'string' ? `${where} "${raw.name}"` : where;
376
- unknownFields(raw, CORE_PAGE_FIELDS, label, problems);
412
+ unknownFields(raw, flags ? CORE_PAGE_FIELDS : CORE_PAGE_FIELDS_2, label, problems);
377
413
  if (typeof raw.name !== 'string' || raw.name === '') problems.push(`${where}: name is ${JSON.stringify(raw.name) ?? 'absent'}, not a non-empty string`);
378
414
  for (const key of ['width', 'height'] as const) {
379
415
  const v = raw[key];
380
416
  if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) problems.push(`${label}: ${key} is ${JSON.stringify(v) ?? 'absent'}, not a positive finite number — a page UV divides by it`);
381
417
  }
418
+ // Issue #1026: a /3 page states its `pma:` as the runtime reads it and the number its own `scale:` line states, or null for none.
419
+ if (flags) {
420
+ if (typeof raw.pma !== 'boolean') problems.push(`${label}: pma is ${JSON.stringify(raw.pma) ?? 'absent'}, not true or false — whether the page's texels are premultiplied`);
421
+ if (raw.scale !== null && (typeof raw.scale !== 'number' || !Number.isFinite(raw.scale))) problems.push(`${label}: scale is ${JSON.stringify(raw.scale) ?? 'absent'}, not a finite number or null — the number the page's scale: line states, null where it has none`);
422
+ }
382
423
  const regions: ModelPageRegion[] = [];
383
424
  if (!Array.isArray(raw.regions)) problems.push(`${label}: regions is not a list`);
384
425
  else {
@@ -399,7 +440,13 @@ function readPages(value: unknown, problems: string[]): ModelPage[] {
399
440
  regions.push(region as unknown as ModelPageRegion);
400
441
  });
401
442
  }
402
- if (problems.length === before) out.push({ name: raw.name as string, width: raw.width as number, height: raw.height as number, regions });
443
+ if (problems.length === before) {
444
+ out.push(
445
+ flags
446
+ ? { name: raw.name as string, width: raw.width as number, height: raw.height as number, pma: raw.pma as boolean, scale: raw.scale as number | null, regions }
447
+ : { name: raw.name as string, width: raw.width as number, height: raw.height as number, regions },
448
+ );
449
+ }
403
450
  });
404
451
  return out;
405
452
  }
@@ -420,6 +467,80 @@ function readSpineDigest(value: unknown, problems: string[]): string {
420
467
  return sha;
421
468
  }
422
469
 
470
+ /**
471
+ * The `stage` section, checked (issue #1026): `null` — the header declares no
472
+ * stage — or exactly `CORE_STAGE_FIELDS`, four finite numbers, each fault
473
+ * named by path. Nothing is defaulted: the writer always writes all four.
474
+ */
475
+ function readStage(value: unknown, problems: string[]): ModelStage | null {
476
+ if (value === null) return null;
477
+ if (!isRecord(value)) {
478
+ problems.push(`stage is ${JSON.stringify(value) ?? 'absent'}, not null or { x, y, width, height } — the setup-pose box the Spine header declares`);
479
+ return null;
480
+ }
481
+ const before = problems.length;
482
+ unknownFields(value, CORE_STAGE_FIELDS, 'stage', problems);
483
+ for (const key of CORE_STAGE_FIELDS) {
484
+ const v = value[key];
485
+ if (typeof v !== 'number' || !Number.isFinite(v)) problems.push(`stage: ${key} is ${JSON.stringify(v) ?? 'absent'}, not a finite number`);
486
+ }
487
+ return problems.length === before ? { x: value.x as number, y: value.y as number, width: value.width as number, height: value.height as number } : null;
488
+ }
489
+
490
+ /**
491
+ * The `editorOrder` section, checked against the records the document holds
492
+ * (issue #1026): `skins`, every skin exactly once as `{ name, slots }` with
493
+ * `slots` its table's slot keys exactly once each, and `animations`, every
494
+ * animation's name exactly once. An order naming a skin, slot key or
495
+ * animation the document does not hold, or leaving one out, is refused by
496
+ * path — it would be another rig's order.
497
+ */
498
+ function readEditorOrder(value: unknown, skins: readonly CoreSkin[], animations: readonly CoreAnimation[], problems: string[]): ModelEditorOrder {
499
+ const out: ModelEditorOrder = { skins: [], animations: [] };
500
+ if (!isRecord(value)) {
501
+ problems.push(`editorOrder is ${JSON.stringify(value) ?? 'absent'}, not { skins, animations }`);
502
+ return out;
503
+ }
504
+ unknownFields(value, ['skins', 'animations'], 'editorOrder', problems);
505
+ const names = (list: unknown, where: string): string[] | null => {
506
+ if (!Array.isArray(list) || list.some((n) => typeof n !== 'string')) {
507
+ problems.push(`${where} is ${JSON.stringify(list) ?? 'absent'}, not a list of names`);
508
+ return null;
509
+ }
510
+ return list as string[];
511
+ };
512
+ /** `stated` lists exactly the names of `held`, each once — else one problem naming the first difference. */
513
+ const permutation = (stated: readonly string[], held: readonly string[], where: string, what: string): void => {
514
+ const seen = new Set<string>();
515
+ for (const name of stated) {
516
+ if (seen.has(name)) return void problems.push(`${where} lists ${what} "${name}" twice`);
517
+ seen.add(name);
518
+ if (!held.includes(name)) return void problems.push(`${where} lists ${what} "${name}", which the document does not hold`);
519
+ }
520
+ const missing = held.find((name) => !seen.has(name));
521
+ if (missing !== undefined) problems.push(`${where} leaves out ${what} "${missing}"`);
522
+ };
523
+ if (!Array.isArray(value.skins)) problems.push(`editorOrder.skins is ${JSON.stringify(value.skins) ?? 'absent'}, not a list`);
524
+ else {
525
+ value.skins.forEach((entry, i) => {
526
+ const at = `editorOrder.skins[${i}]`;
527
+ if (!isRecord(entry) || typeof entry.name !== 'string') return void problems.push(`${at} is not { name, slots }`);
528
+ unknownFields(entry, ['name', 'slots'], at, problems);
529
+ const slots = names(entry.slots, `${at}.slots`);
530
+ const skin = skins.find((k) => k.name === entry.name);
531
+ if (slots !== null && skin !== undefined) permutation(slots, Object.keys(skin.attachments), `${at}.slots`, 'slot key');
532
+ out.skins.push({ name: entry.name, slots: slots ?? [] });
533
+ });
534
+ permutation(out.skins.map((k) => k.name), skins.map((k) => k.name), 'editorOrder.skins', 'skin');
535
+ }
536
+ const order = names(value.animations, 'editorOrder.animations');
537
+ if (order !== null) {
538
+ permutation(order, animations.map((a) => a.name), 'editorOrder.animations', 'animation');
539
+ out.animations = order;
540
+ }
541
+ return out;
542
+ }
543
+
423
544
  const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
424
545
 
425
546
  /** The mode a stated `inheritMode` folds to — the first letter lower-cased and nothing else — or null. */
@@ -698,8 +819,10 @@ function readConstraints(value: unknown, animations: readonly CoreAnimation[], b
698
819
  }
699
820
 
700
821
  /**
701
- * Read a `rigc-compiled/2` document — or a `rigc-compiled/1` one, which has
702
- * no `pages` and is read with `pages: null` — from its text, refusing by name a text
822
+ * Read a `rigc-compiled/3` document — or a `rigc-compiled/2` one, which has
823
+ * no `stage`, `editorOrder` or page `pma`/`scale` and is read with `stated:
824
+ * null`, or a `rigc-compiled/1` one, which has no `pages` either and is read
825
+ * with `pages: null` — from its text, refusing by name a text
703
826
  * that is not JSON, a wrong `spec`, a missing section (`referenceScale`
704
827
  * among them, issue #958), a section the document does not have, a
705
828
  * `referenceScale` that is not a finite number, and — in the records these constructs read (bones, slots,
@@ -717,15 +840,20 @@ export function readModel(text: string, where = 'the model document'): CompiledD
717
840
  throw new CoreInputError(`${where}: not JSON — ${(err as Error).message}`);
718
841
  }
719
842
  if (!isRecord(value)) throw new CoreInputError(`${where}: not a JSON object`);
720
- if (value.spec !== CORE_DOCUMENT_SPEC && value.spec !== CORE_DOCUMENT_SPEC_1) throw new CoreInputError(`${where}: spec is ${JSON.stringify(value.spec)}, not "${CORE_DOCUMENT_SPEC}" (or "${CORE_DOCUMENT_SPEC_1}", read without its pages)`);
843
+ if (typeof value.spec !== 'string' || !CORE_DOCUMENT_SPECS.includes(value.spec)) {
844
+ throw new CoreInputError(
845
+ `${where}: spec is ${JSON.stringify(value.spec)}, not "${CORE_DOCUMENT_SPEC}" (or "${CORE_DOCUMENT_SPEC_2}", read without its stage, editor order and page flags, or "${CORE_DOCUMENT_SPEC_1}", read without its pages too)`,
846
+ );
847
+ }
721
848
  const spec = value.spec;
722
- const sections: readonly string[] = spec === CORE_DOCUMENT_SPEC ? CORE_SECTIONS : CORE_SECTIONS_1;
849
+ const sections: readonly string[] = spec === CORE_DOCUMENT_SPEC ? CORE_SECTIONS : spec === CORE_DOCUMENT_SPEC_2 ? CORE_SECTIONS_2 : CORE_SECTIONS_1;
723
850
  const problems: string[] = [];
724
851
  for (const key of sections) if (!(key in value)) problems.push(`section "${key}" is missing`);
725
852
  for (const key of Object.keys(value)) {
726
853
  if (key !== 'spec' && !sections.includes(key)) problems.push(`section "${key}" is not one a ${spec} document has`);
727
854
  }
728
- const pages = spec === CORE_DOCUMENT_SPEC && 'pages' in value ? readPages(value.pages, problems) : null;
855
+ const pages = spec !== CORE_DOCUMENT_SPEC_1 && 'pages' in value ? readPages(value.pages, problems, spec === CORE_DOCUMENT_SPEC) : null;
856
+ const stage = spec === CORE_DOCUMENT_SPEC && 'stage' in value ? readStage(value.stage, problems) : null;
729
857
  // The skeleton's reference scale (issue #958): wind and gravity act over it, so a missing one is the section refusal above, and a value the runtime could not read as a number is refused here by name.
730
858
  const referenceScale = typeof value.referenceScale === 'number' && Number.isFinite(value.referenceScale) ? value.referenceScale : NaN;
731
859
  if ('referenceScale' in value && Number.isNaN(referenceScale)) problems.push(`referenceScale is ${JSON.stringify(value.referenceScale)}, not a finite number — wind and gravity act over it`);
@@ -752,8 +880,10 @@ export function readModel(text: string, where = 'the model document'): CompiledD
752
880
  if (isRecord(raw) && animations[i] !== undefined) animations[i].constraints = readConstraintTimelines(raw.constraints, `animations[${i}] "${animations[i].name}"`, constraints, problems);
753
881
  });
754
882
  }
883
+ const editorOrder = spec === CORE_DOCUMENT_SPEC && 'editorOrder' in value ? readEditorOrder(value.editorOrder, skins, animations, problems) : null;
755
884
  if (problems.length > 0) throw new CoreInputError(`${where}: ${problems.length} problem(s): ${problems.join('; ')}`);
756
- const doc: CompiledDocument = { spec, skin: CORE_ALL_SKINS, referenceScale, bones, slots, skins, constraints, animations, spine: { sha256: spine }, pages };
885
+ const stated: CoreStated | null = editorOrder === null ? null : { stage, editorOrder };
886
+ const doc: CompiledDocument = { spec, skin: CORE_ALL_SKINS, referenceScale, bones, slots, skins, constraints, animations, spine: { sha256: spine }, pages, stated };
757
887
  resolveSkinView(doc);
758
888
  return doc;
759
889
  }
@@ -49,7 +49,10 @@
49
49
  * the emitter keys `animations` in the editor's order over the model's names
50
50
  * (`editorAnimationOrder` in `src/compile.ts`, the one call `emitAnimations`
51
51
  * is handed), and the survey iterates the file's order. The model's own order
52
- * was the file's on 14 of 19 rows. Every other order the survey reads — a
52
+ * was the file's on 14 of 19 rows. Since issue #1026 a `rigc-compiled/3`
53
+ * document states that order (`editorOrder.animations`, computed by the
54
+ * same function at compile time) and the survey reads it; a `/2` or `/1`
55
+ * document is ordered by the comparator as before. Every other order the survey reads — a
53
56
  * skin's, an animation's deform timelines, the sliders — the file keeps from
54
57
  * the model.
55
58
  * - **A slider's duration** is the runtime's (`CoreAnimationTimelines.duration`:
@@ -291,12 +294,18 @@ export function modelStructure(doc: CompiledDocument): SurveyStructure {
291
294
  },
292
295
  };
293
296
  };
294
- let order: string[];
295
- try {
296
- order = editorAnimationOrder(doc.animations.map((a) => a.name));
297
- } catch (err) {
298
- if (!(err instanceof CompileError)) throw err;
299
- throw new CoreInputError(`the animations' order in the Spine file is not settled by the model's names — ${err.message}`);
297
+ // The order the Spine file lists the animations in: stated by a
298
+ // `rigc-compiled/3` document (`editorOrder`, issue #1026), and derived for a
299
+ // `/2` or `/1` one, which does not state it, by the emitter's own comparator.
300
+ let order: readonly string[];
301
+ if (doc.stated !== null) order = doc.stated.editorOrder.animations;
302
+ else {
303
+ try {
304
+ order = editorAnimationOrder(doc.animations.map((a) => a.name));
305
+ } catch (err) {
306
+ if (!(err instanceof CompileError)) throw err;
307
+ throw new CoreInputError(`the animations' order in the Spine file is not settled by the model's names — ${err.message}`);
308
+ }
300
309
  }
301
310
  const animations = order.map((name) => {
302
311
  const a = doc.animations.find((x) => x.name === name);