spine-rigc 0.30.0 → 0.32.0

package/src/deformmeasure.ts

@@ -94,6 +94,7 @@ import {
   type Attachment,
   AtlasAttachmentLoader,
   type Bone,
+  type CurveTimeline,
   DeformTimeline,
   FromProperty,
   FromRotate,
@@ -1937,7 +1938,7 @@ function curveLegs(timeline: DeformTimeline, frame: number): { kind: DeformSpanC
 }
 
 /** Points `CurveTimeline.setBezier` stores per curve — `BEZIER_SIZE / 2`. */
-const BEZIER_POINTS = 9;
+export const BEZIER_POINTS = 9;
 
 /**
  * `CurveTimeline.curves`, which is `protected` and is read anyway.
@@ -1956,8 +1957,12 @@ const BEZIER_POINTS = 9;
  *
  * `A05` already gates the emitted curve arrays, and `DW18` is the control that
  * the reading here matches what the runtime does with them.
+ *
+ * Exported for `validate.ts`'s `curveChannelValues` (issue #752), which asks the
+ * same array what values a constraint's `mix` timeline poses between its keys —
+ * so the reach into protected storage stays one reach, in this file.
  */
-function curveStorage(timeline: DeformTimeline): ArrayLike<number> {
+export function curveStorage(timeline: CurveTimeline): ArrayLike<number> {
   return (timeline as unknown as { curves: ArrayLike<number> }).curves;
 }
 

package/src/ingest.ts

@@ -44,7 +44,13 @@
  * break `A18_DETERMINISTIC_EMIT` the first time anybody rebuilt from an ingested
  * spec.
  */
-import { PHYSICS_COMPONENTS, SLOT_TRACKS as EMITTED_SLOT_TRACKS, SPINE_VERSION } from './compile.ts';
+import {
+  composeSkinAttachmentName,
+  DEFAULT_SKIN,
+  PHYSICS_COMPONENTS,
+  SLOT_TRACKS as EMITTED_SLOT_TRACKS,
+  SPINE_VERSION,
+} from './compile.ts';
 import { CompileError } from './errors.ts';
 import { CHANNELS_BY_KIND } from './timelines.ts';
 import {
@@ -54,8 +60,8 @@ import {
   spineGeneration,
   TOPLEVEL_CONSTRAINT_ARRAYS,
 } from './generation.ts';
-import { MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
-import { parseRigSpec, RIG_KEYS, RIG_SPEC_VERSION, type RigSpec } from './rig.ts';
+import { EVERY_GLOBAL_PHYSICS, MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
+import { parseRigSpec, resolveBoneInherit, RIG_KEYS, RIG_SPEC_VERSION, type RigSpec } from './rig.ts';
 import type { MotionSpec } from './types.ts';
 
 /**
@@ -374,6 +380,18 @@ const BONE_TRACKS: Record<string, TrackShape> = {
   rotate: [['value', 0]],
 };
 
+/**
+ * The bone timeline whose key holds a NAME rather than numbers — `inherit`,
+ * `{ time, inherit }`, stepped by the format (its reader builds no curve). The
+ * field and the default `SkeletonJson`'s `inherit` branch reads where a key
+ * omits it: `getValue(aFrame, "inherit", "Normal")`, which the table spells
+ * `normal`. Inverts `compileValueTrack`'s named branch (issue #733).
+ */
+const INHERIT_TRACK = { property: 'inherit', field: 'inherit', dflt: 'normal' } as const;
+
+/** Every bone timeline the motion spec has a track for, in the order the refusal prints them. */
+const BONE_TRACK_NAMES = [...Object.keys(BONE_TRACKS), INHERIT_TRACK.property];
+
 /**
  * The eight physics timelines — `PHYSICS_TRACKS` in `compile.ts`, same order.
  * `reset` carries no value at all — `compileValueTrack`'s zero-field branch.
@@ -516,7 +534,7 @@ export const UNSPELT_SLOT_TRACKS = Object.keys(CHANNELS_BY_KIND.slot).filter((na
 export const INGEST_VOCABULARY = {
   attachments: ATTACHMENT_TYPES,
   constraints: Object.keys(CONSTRAINT_FIELDS),
-  boneTracks: Object.keys(BONE_TRACKS),
+  boneTracks: BONE_TRACK_NAMES,
   slotTracks: SLOT_TRACKS,
   path: Object.keys(PATH_TRACKS),
   physics: Object.keys(PHYSICS_TRACKS),
@@ -694,6 +712,7 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
         perSlot[placeholder] = ingestAttachment(obj(att), placeholder, boneNames, opts, note, {
           where: `skin "${nameOf(entry)}" slot "${slot}" attachment "${placeholder}"`,
           contested: contested.get(slot)?.has(placeholder) === true,
+          skin: nameOf(entry),
         });
       }
       table[slot] = perSlot;
@@ -1152,7 +1171,7 @@ function ingestAttachment(
   boneNames: readonly string[],
   opts: IngestOptions,
   note: Note,
-  at: { where: string; contested: boolean },
+  at: { where: string; contested: boolean; skin: string },
 ): JsonObject {
   // `readAttachment` reads no `type` as `region` (`SkeletonJson:539`), and so
   // does `checkRigSpecKeys`. Both defaults are the parser's, not a guess.
@@ -1206,10 +1225,28 @@ function ingestAttachment(
       ? att.name
       : undefined;
 
+  /** What became of the atlas region once the name is gone — the same four shapes wherever the name is lost. */
+  const regionFate =
+    keptPath !== undefined
+      ? `That name was also the ATLAS REGION this attachment resolves, because \`path\` defaults to the name and ` +
+        `not to the placeholder (\`SkeletonJson.js:526\`, \`:529\`, \`:560\`) — so the region key is KEPT as ` +
+        `"path": ${JSON.stringify(keptPath)} and the name alone is lost`
+      : att.path !== undefined
+        ? `The region key is the source's own \`path\` ${JSON.stringify(att.path)}, carried unchanged, so the ` +
+          'name alone is lost'
+        : resolvesRegion
+          ? at.contested
+            ? 'The region is the placeholder\'s either way — the compiler pins a composed name\'s `path` at the ' +
+              'placeholder — so the name alone is lost'
+            : 'The name is the placeholder itself, so the rebuild resolves the same atlas region and no `path` is ' +
+              'written for it'
+          : `An attachment of type ${JSON.stringify(type)} resolves no atlas region — the parser builds it from ` +
+            'the name alone — so there is no region key to keep and the name is the whole loss';
+
   // `name` is DERIVED by rigc — `composeSkinAttachmentName` writes one exactly
   // where a placeholder is contested — so the rig spec has no field for it and
-  // it is dropped. Where the contest survives the round trip the same name comes
-  // back; anywhere else it is a real loss and is reported.
+  // it is dropped. Where one skin fills the placeholder every stated name is a
+  // loss, because the rebuild writes none.
   if (att.name !== undefined && !at.contested) {
     note(
       'lossy',
@@ -1217,18 +1254,43 @@ function ingestAttachment(
       at.where,
       `the attachment states name ${JSON.stringify(att.name)} and only ONE skin fills this placeholder, so rigc ` +
         'writes no name on the rebuild — it composes "<skin>/<placeholder>" only for a contested placeholder (#541). ' +
-        (keptPath !== undefined
-          ? `That name was also the ATLAS REGION this attachment resolves, because \`path\` defaults to the name and ` +
-            `not to the placeholder (\`SkeletonJson.js:526\`, \`:529\`, \`:560\`) — so the region key is KEPT as ` +
-            `"path": ${JSON.stringify(keptPath)} and the name alone is lost`
-          : att.path !== undefined
-            ? `The region key is the source's own \`path\` ${JSON.stringify(att.path)}, carried unchanged, so the ` +
-              'name alone is lost'
-            : resolvesRegion
-              ? 'The name is the placeholder itself, so the rebuild resolves the same atlas region and no `path` is ' +
-                'written for it'
-              : `An attachment of type ${JSON.stringify(type)} resolves no atlas region — the parser builds it from ` +
-                'the name alone — so there is no region key to keep and the name is the whole loss'),
+        regionFate,
+    );
+  }
+
+  /**
+   * 🚨 Where a placeholder IS contested the name is re-derived, and re-derived is
+   * not the same as kept (issue #746). The rebuild's attachment answers to what
+   * `composeSkinAttachmentName` returns; the source's answers to what it states,
+   * or to its placeholder where it states nothing (`readAttachment`'s
+   * `getValue(map, "name", placeholder)`, `SkeletonJson.js:526`). Only where
+   * those two strings differ is anything renamed, so only there is a line.
+   *
+   * ⚠️ Comparing is the whole rule, and its cheap neighbour was measured and
+   * rejected on #742: firing whenever a contested entry states a name puts a
+   * `LOSS` on every contested round trip of rigc's own emits, which state
+   * exactly the composed name and rebuild byte for byte.
+   *
+   * ⚠️ A contested placeholder the DEFAULT skin fills gets no line here: the
+   * compiler composes nothing for it — `refuseDefaultSkinContest` refuses the
+   * rebuild by name — so a line claiming a composed name would state one no
+   * build will ever emit.
+   */
+  const composed = composeSkinAttachmentName(at.skin, placeholder, at.contested);
+  const sourceName = att.name === undefined ? placeholder : att.name;
+  if (composed !== null && at.skin !== DEFAULT_SKIN && sourceName !== composed) {
+    note(
+      'lossy',
+      'ATTACHMENT_NAME',
+      at.where,
+      (att.name === undefined
+        ? `the attachment states no name, so the source names it by its placeholder ${JSON.stringify(placeholder)} ` +
+          '(`SkeletonJson.js:526`)'
+        : `the attachment states name ${JSON.stringify(att.name)}`) +
+        `, and more than one skin fills this placeholder, so rigc composes the name ${JSON.stringify(composed)} ` +
+        `on the rebuild (#541) — the rig spec has no field for a name, so the rebuilt attachment answers to ` +
+        `${JSON.stringify(composed)} where the source's answered to ${JSON.stringify(sourceName)}. ` +
+        regionFate,
     );
   }
 
@@ -1340,18 +1402,67 @@ function ingestAttachment(
     return out;
   }
 
-  if (att.sequence !== undefined) {
-    note(
-      'blocker',
-      'ATTACHMENT_SEQUENCE',
-      at.where,
-      'the attachment carries a `sequence` block (a numbered image series), which the rig spec cannot say; ' +
-        'the rebuild draws the single region this attachment names',
-    );
+  // A numbered image series (issue #729). Carried as the file states it —
+  // the four fields `readSequence` reads — wherever the rig spec can say it;
+  // what is left for the blocker is a block the parser reads into a series
+  // that is not the one written, or one on a kind the parser never reads it on.
+  // `null` is the parser's own absent (`getValue(map, "sequence", null)`), so it
+  // is read as no series rather than as a malformed one.
+  if (att.sequence !== undefined && att.sequence !== null) {
+    const refusal = resolvesRegion
+      ? sequenceBlockRefusal(att.sequence)
+      : `the attachment is a ${type}, and \`readAttachment\` reads a \`sequence\` only on a region or a mesh ` +
+        '(`SkeletonJson.js:530`, `:561`) — the parser never read this one, and the rig spec refuses it there by name';
+    if (refusal === null) {
+      const seq = att.sequence as JsonObject;
+      const carried: JsonObject = {};
+      for (const field of ['count', 'start', 'digits', 'setup']) if (seq[field] !== undefined) carried[field] = seq[field];
+      out.sequence = carried;
+      // The frames ARE the art: `<path><number>` regions, which on the loose
+      // route are PNGs of those names. A single `image` would name one region
+      // the series does not have, and the rig spec refuses the pair.
+      delete out.image;
+    } else {
+      note(
+        'blocker',
+        'ATTACHMENT_SEQUENCE',
+        at.where,
+        `the attachment's \`sequence\` block is ${JSON.stringify(att.sequence)}: ${refusal}. The rebuild draws the ` +
+          'single region this attachment names instead of a series',
+      );
+    }
   }
   return out;
 }
 
+/**
+ * Why a `sequence` block cannot be carried as written, or `null` when it can —
+ * the rig spec's own refusals (`checkRigSequence`), stated about a file.
+ *
+ * Every one of them is a series the parser loads into something other than
+ * what the file says (issue #729): no `count` is 0 regions, a `setup` past the
+ * end is clamped, a fraction names a region like `stem1.5`.
+ */
+function sequenceBlockRefusal(seq: unknown): string | null {
+  if (typeof seq !== 'object' || seq === null || Array.isArray(seq)) {
+    return 'a sequence is an object of `count`, `start`, `digits` and `setup`';
+  }
+  const block = seq as JsonObject;
+  if (block.count === undefined) {
+    return 'it states no `count`, and `readSequence` reads 0 — the attachment loads holding no region and draws nothing';
+  }
+  for (const [field, min] of [['count', 1], ['start', 0], ['digits', 0], ['setup', 0]] as const) {
+    const value = block[field];
+    if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < min)) {
+      return `\`${field}\` is ${JSON.stringify(value)}, and the rig spec takes a whole number of at least ${min} there`;
+    }
+  }
+  if (typeof block.setup === 'number' && block.setup >= (block.count as number)) {
+    return `\`setup\` ${block.setup} is past the end of a ${String(block.count)}-frame series, and \`Sequence.resolveIndex\` clamps it to the last frame`;
+  }
+  return null;
+}
+
 /** One animation. Inverts step 5 of `compile()` — the whole timeline half. */
 function ingestAnimation(
   animName: string,
@@ -1448,6 +1559,16 @@ function ingestAnimation(
    * `lossy`, on the argument that the rebuilt skeleton plays identically — is
    * a decision about all three families and is not made here.
    */
+  /**
+   * The physics constraints the rebuild carries — every one the file declares
+   * but those `ingest` omits as inert — which is what an unnamed physics
+   * timeline can reach in it.
+   */
+  const carriedPhysics = arr(root.constraints)
+    .map(obj)
+    .filter((one) => one.type === 'physics' && !(typeof one.name === 'string' && inert.has(one.name)));
+  /** Unnamed physics timelines that reach nothing in the rebuild, said once the duration is known. */
+  const unreached: Array<{ property: string; lastKey: number }> = [];
   const family = (group: 'path' | 'physics' | 'slider', shapes: Record<string, TrackShape>): void => {
     for (const [name, timelines] of objEntries(anim[group])) {
       for (const [property, keys] of arrEntries(timelines)) {
@@ -1471,6 +1592,26 @@ function ingestAnimation(
           note('blocker', `${group.toUpperCase()}_TIMELINE`, where, `timeline "${property}" is not in the motion spec`);
           continue;
         }
+        // The empty name is the physics group's timeline that names no
+        // constraint (issue #726), which the motion spec spells `"*"`. It
+        // writes every carried constraint declaring the property global —
+        // `reset` every one — and one that reaches none is a no-op the rebuild
+        // would be refused over by name, so it goes, and is said, instead.
+        if (group === 'physics' && name === '') {
+          const reaches =
+            property === 'reset' ? carriedPhysics.length > 0 : carriedPhysics.some((one) => Boolean(one[`${property}Global`]));
+          if (!reaches) {
+            let lastKey = 0;
+            for (const raw of keys) {
+              const t = obj(raw).time;
+              if (typeof t === 'number' && t > lastKey) lastKey = t;
+            }
+            unreached.push({ property, lastKey });
+            continue;
+          }
+          valueTrack({ physics: EVERY_GLOBAL_PHYSICS }, property, keys, shape, where);
+          continue;
+        }
         valueTrack({ [group]: name }, property, keys, shape, where);
       }
     }
@@ -1480,12 +1621,46 @@ function ingestAnimation(
     for (const [property, keys] of arrEntries(timelines)) {
       const shape = BONE_TRACKS[property];
       const where = `animation "${animName}" bone "${bone}" ${property}`;
+      if (property === INHERIT_TRACK.property) {
+        // `{ time, inherit }` -> `{ t, v: mode }`. The mode is carried in the
+        // table's spelling, which is what `build` writes back; a key that omits
+        // it, or spells it with a capital the runtime also folds, is a key the
+        // rebuild states differently and is counted as such. A spelling the
+        // runtime cannot resolve at all is carried as written — the file plays
+        // no mode there, and `build` refuses it by name rather than guessing one.
+        let restated = 0;
+        const out = keys.map((raw) => {
+          const key = obj(raw);
+          const entry: JsonObject = { t: timeOf(key) };
+          const written = key[INHERIT_TRACK.field];
+          const mode = written === undefined ? INHERIT_TRACK.dflt : resolveBoneInherit(written);
+          if (mode !== written && mode !== undefined) restated++;
+          entry.v = mode ?? (written as JsonObject[string]);
+          for (const field of Object.keys(key)) {
+            if (field === 'time' || field === INHERIT_TRACK.field) continue;
+            note('blocker', 'TIMELINE_FIELD', where, `key field "${field}" is not part of this timeline's shape`);
+          }
+          return entry;
+        });
+        if (restated > 0) {
+          note(
+            'lossy',
+            'TIMELINE_KEY_RESTATED',
+            where,
+            `${restated} key(s) omit the mode or spell it with a capital first letter, and are written out as the ` +
+              `mode the runtime reads there (an omitted one is ${INHERIT_TRACK.dflt}) — the same mode, in the ` +
+              'spelling the editor writes',
+          );
+        }
+        tracks.push({ bone, property, keys: out });
+        continue;
+      }
       if (shape === undefined) {
         note(
           'blocker',
           'BONE_TIMELINE',
           where,
-          `timeline "${property}" has no track in the motion spec — a bone track is ${Object.keys(BONE_TRACKS).join(', ')} ` +
+          `timeline "${property}" has no track in the motion spec — a bone track is ${BONE_TRACK_NAMES.join(', ')} ` +
             'and nothing else, so the rebuild plays nothing here',
         );
         continue;
@@ -1608,13 +1783,42 @@ function ingestAnimation(
   // Inverts `compileDeformTrack`, whose emitted key is `{time, offset?, vertices?}`
   // and whose `offset` is omitted at 0 (the parser's default).
   const deform: JsonObject[] = [];
+  // sequence — the other attachment timeline, inverting `compileSequenceTrack`:
+  // `{time, mode?, index?, delay?}` with each field written only where the file
+  // wrote it, because each has a parser default (`"hold"`, 0, the previous
+  // key's delay) and restating one would be a rebuild saying more than the file.
+  const sequence: JsonObject[] = [];
   for (const [skinName, perSkin] of objEntries(anim.attachments)) {
     for (const [slot, perSlot] of objEntries(perSkin)) {
       for (const [attachment, timelines] of objEntries(perSlot)) {
         for (const [property, keys] of arrEntries(timelines)) {
           const where = `animation "${animName}" ${skinName}/${slot}/${attachment}`;
+          if (property === 'sequence') {
+            const entry: JsonObject = {
+              slot,
+              attachment,
+              keys: keys.map((raw) => {
+                const key = obj(raw);
+                const out: JsonObject = { t: timeOf(key) };
+                for (const field of ['mode', 'index', 'delay']) if (key[field] !== undefined) out[field] = key[field];
+                return out;
+              }),
+            };
+            if (skinName !== 'default') entry.skin = skinName;
+            sequence.push(entry);
+            continue;
+          }
           if (property !== 'deform') {
-            note('blocker', 'ATTACHMENT_TIMELINE', where, `timeline "${property}" (the motion spec carries \`deform\` only)`);
+            // Reached only by a name OUTSIDE the format: `readAnimation` tests
+            // an attachment timeline for "deform" and "sequence" and reads
+            // nothing else (`SkeletonJson.js:1147-1201`), so no player plays it.
+            note(
+              'blocker',
+              'ATTACHMENT_TIMELINE',
+              where,
+              `timeline "${property}" is not an attachment timeline the format has — the runtime's reader tests for ` +
+                '"deform" and "sequence" and ignores anything else, and those two are what the motion spec carries',
+            );
             continue;
           }
           const entry: JsonObject = {
@@ -1667,6 +1871,26 @@ function ingestAnimation(
     });
   }
 
+  for (const { property, lastKey } of unreached) {
+    const flag = `${property}Global`;
+    note(
+      'lossy',
+      'PHYSICS_GLOBAL_REACHES_NOTHING',
+      `animation "${animName}" physics "" ${property}`,
+      'names no constraint, so the runtime writes it into every physics constraint ' +
+        (property === 'reset' ? 'the skeleton has' : `declaring "${flag}"`) +
+        ', and the rebuild carries ' +
+        (carriedPhysics.length === 0
+          ? 'no physics constraint'
+          : `none that does (${carriedPhysics.map((one) => `"${String(one.name)}"`).join(', ')})`) +
+        ` — it moves nothing, and \`build\` would refuse its \`"physics": "${EVERY_GLOBAL_PHYSICS}"\` track by name. ` +
+        'The motion spec omits it' +
+        (lastKey > maxT
+          ? `, and an animation's duration is the last key it has left, so the rebuilt animation ends at ${maxT}s rather than ${lastKey}s`
+          : '; the rebuild differs from the source by exactly this no-op'),
+    );
+  }
+
   for (const group of Object.keys(anim)) {
     if (ANIMATION_GROUPS.includes(group)) continue;
     note(
@@ -1694,6 +1918,7 @@ function ingestAnimation(
   if (ik.length) out.ik = ik;
   if (transform.length) out.transform = transform;
   if (deform.length) out.deform = deform;
+  if (sequence.length) out.sequence = sequence;
   if (drawOrder !== undefined) out.drawOrder = drawOrder;
   if (events !== undefined) out.events = events;
   return out;

package/src/motion.ts

@@ -55,10 +55,29 @@
  */
 import { CompileError } from './errors.ts';
 import { refuseUnknownKeys } from './keys.ts';
+import { SEQUENCE_MODES } from './timelines.ts';
 import type { MotionSpec } from './types.ts';
 
 export const MOTION_SPEC_VERSION = 'rigc-motion/1';
 
+/**
+ * A track's `physics` target for the timeline that names NO constraint (issue
+ * #726) — the one the runtime applies to every physics constraint whose own data
+ * declares the keyed property global (`"strengthGlobal": true` for `strength`,
+ * and so on; `reset` resets every physics constraint and asks no flag).
+ * `compile` emits it under the empty name, which is the skeleton file's own
+ * spelling of it (`SkeletonJson.js:1048-1054`).
+ *
+ * 🔑 Not the empty string itself, and that is the choice rather than a detail:
+ * `""` is the likeliest shape of a value somebody forgot to fill in, and a
+ * forgotten target that silently became "every global constraint" is the exact
+ * silence this format exists to name. So `"physics": ""` is refused by name and
+ * points here, and `"*"` is reserved the other way round: `compile` refuses a
+ * physics constraint that is CALLED `"*"`, because a track naming it could not
+ * say which of the two it meant.
+ */
+export const EVERY_GLOBAL_PHYSICS = '*';
+
 /**
  * The six fields that pick a track's target family. Listed here as well as in
  * `compile`'s `resolveTargets` because the two ask different questions of it:
@@ -112,7 +131,7 @@ export const MOTION_KEYS = {
     'bone', 'x', 'y', 'rotate', 'scaleX', 'shearX', 'inertia', 'strength', 'damping', 'mass', 'wind', 'gravity',
     'mix', 'fps', 'limit', 'note',
   ],
-  MotionAnimation: ['duration', 'loop', 'note', 'tracks', 'ik', 'transform', 'deform', 'drawOrder', 'events'],
+  MotionAnimation: ['duration', 'loop', 'note', 'tracks', 'ik', 'transform', 'deform', 'sequence', 'drawOrder', 'events'],
   MotionTrack: ['slot', 'group', 'bone', 'physics', 'path', 'slider', 'property', 'lag', 'stagger', 'keys'],
   MotionKey: ['t', 'v', 'derive', 'ease', 'curve'],
   MotionIkTrack: ['constraint', 'keys'],
@@ -121,6 +140,8 @@ export const MOTION_KEYS = {
   MotionTransformKey: ['t', 'mixRotate', 'mixX', 'mixY', 'mixScaleX', 'mixScaleY', 'mixShearY', 'ease', 'curve'],
   MotionDeformTrack: ['skin', 'slot', 'attachment', 'keys'],
   MotionDeformKey: ['t', 'offset', 'fromVertex', 'vertices', 'transform', 'ease', 'curve'],
+  MotionSequenceTrack: ['skin', 'slot', 'attachment', 'keys'],
+  MotionSequenceKey: ['t', 'mode', 'index', 'delay'],
   MotionDrawOrderKey: ['t', 'offsets'],
   MotionDrawOrderOffset: ['slot', 'offset'],
   MotionEventKey: ['t', 'name', 'int', 'float', 'string', 'volume', 'balance'],
@@ -292,7 +313,15 @@ function parsePhysics(raw: unknown, where: string): void {
   const table = needObj(raw, where, 'physics', 'it is a table keyed by constraint name, `{ "<name>": { "bone": … } }`');
   for (const [name, entry] of Object.entries(table)) {
     const key = `physics."${name}"`;
-    const spec = needObj(entry, where, key, 'a physics constraint is an object naming the bone it drives and the components it drives it in');
+    if (name === EVERY_GLOBAL_PHYSICS) {
+      throw new CompileError(
+        `${where}: \`${key}\` names a physics constraint "${EVERY_GLOBAL_PHYSICS}", and that name is reserved: a ` +
+          `track's \`"physics": "${EVERY_GLOBAL_PHYSICS}"\` is the timeline that names no constraint and drives ` +
+          'every one declaring the keyed property global, so a constraint called ' +
+          `"${EVERY_GLOBAL_PHYSICS}" could not be keyed by name. Give it another name`,
+      );
+    }
+    const spec = needObj(entry, where, key,'a physics constraint is an object naming the bone it drives and the components it drives it in');
     known(spec, 'MotionPhysics', where, key);
     needString(spec.bone, where, `${key}.bone`, 'a physics constraint drives one bone, named here');
     for (const field of PHYSICS_NUMBERS) {
@@ -378,6 +407,17 @@ function parseTracks(raw: unknown, where: string, at: string): void {
     for (const field of TARGET_FIELDS) {
       optString(track[field], where, `${key}.${field}`, `a track's "${field}" is the name of the ${field === 'slot' || field === 'bone' ? field : `${field} it targets`}`);
     }
+    if (track.physics === '') {
+      refuse(
+        where,
+        `${key}.physics`,
+        track.physics,
+        'the empty name is how a skeleton file spells a physics timeline that names no constraint, and a motion ' +
+          `spec spells that "${EVERY_GLOBAL_PHYSICS}" — it drives every physics constraint that declares the keyed ` +
+          'property global (`"strengthGlobal": true` for `strength`). Name one constraint, or write ' +
+          `"${EVERY_GLOBAL_PHYSICS}"`,
+      );
+    }
     optFinite(track.lag, where, `${key}.lag`, '"lag" is seconds added to every key time of this track, so a finite number — a string is CONCATENATED onto each time and a boolean adds 1');
     optFinite(track.stagger, where, `${key}.stagger`, '"stagger" is the extra per-member delay inside a group, in seconds, so a finite number');
     const keys = needArray(track.keys, where, `${key}.keys`, 'it is an array of `{ t, v }` keys');
@@ -442,6 +482,83 @@ function parseDeform(raw: unknown, where: string, at: string): void {
   }
 }
 
+/**
+ * `sequence` — which frame of an attachment's numbered series shows.
+ *
+ * Everything decidable from the key alone is decided here; what needs the rig
+ * (does the attachment carry a `sequence` block, is `index` inside its `count`)
+ * is `compile`'s. Each refusal is a key the parser loads without a word and
+ * plays as something else — measured on spine-core 4.3.13 (issue #729):
+ *
+ *   - a `mode` outside the seven — `SequenceMode[name]` is `undefined`, the mode
+ *     bits store 0, and the key plays as `hold`;
+ *   - an `index` that is not a whole number of at least 0 — it is stored as
+ *     `index << 4`, so `1.5` shows frame 1 and a negative one indexes before the
+ *     series;
+ *   - a `delay` that is not a number of at least 0 — and, under a mode that
+ *     advances, an EFFECTIVE delay of 0: the parser carries a key's delay from
+ *     the key before (`lastDelay`, 0 on the first), `(time - keyTime) / 0` is
+ *     `Infinity` and `Infinity | 0` is 0, so a `loop` at delay 0 shows its
+ *     first frame for the whole key.
+ */
+function parseSequence(raw: unknown, where: string, at: string): void {
+  if (raw === undefined) return;
+  const entries = needArray(raw, where, `${at}.sequence`, 'it is an array of `{ slot, attachment, keys }` entries — one per skin/slot/attachment triple');
+  for (const [i, entry] of entries.entries()) {
+    const key = `${at}.sequence[${i}]`;
+    const track = needObj(entry, where, key, 'a sequence timeline is an object of `{ skin?, slot, attachment, keys }`');
+    known(track, 'MotionSequenceTrack', where, key);
+    optString(track.skin, where, `${key}.skin`, 'it names the skin the attachment lives in; absent means "default"');
+    needString(track.slot, where, `${key}.slot`, 'a sequence timeline steps one attachment of one slot, named here');
+    needString(track.attachment, where, `${key}.attachment`, "it is the attachment's placeholder name inside that skin and slot");
+    const keys = needArray(track.keys, where, `${key}.keys`, 'it is an array of `{ t, mode?, index?, delay? }` keys');
+    // The delay the PARSER will read at each key: the stated one, else the
+    // previous key's, else 0 (`lastDelay` in `readAnimation`).
+    let carried = 0;
+    for (const [j, k] of keys.entries()) {
+      const kat = `${key}.keys[${j}]`;
+      const parsed = parseKey(k, where, kat, 'a sequence key is an object of `{ t, mode?, index?, delay? }`', 'MotionSequenceKey');
+      if (parsed.mode !== undefined && !(SEQUENCE_MODES as readonly unknown[]).includes(parsed.mode)) {
+        refuse(
+          where,
+          `${kat}.mode`,
+          parsed.mode,
+          `a sequence mode is one of the ${SEQUENCE_MODES.length} the format has — ${SEQUENCE_MODES.join(', ')} ` +
+            '(absent means "hold"). The parser reads `SequenceMode[mode]`, which is undefined for anything else, and ' +
+            'stores mode bits 0: the key would load without a word and play as "hold"',
+        );
+      }
+      const index = parsed.index;
+      if (index !== undefined && (typeof index !== 'number' || !Number.isInteger(index) || index < 0)) {
+        refuse(
+          where,
+          `${kat}.index`,
+          index,
+          'it is the 0-based frame this key starts on, so a whole number of at least 0 — the runtime stores it as ' +
+            '`index << 4`, which truncates a fraction (1.5 showed frame 1) and puts a negative one before the series',
+        );
+      }
+      const delay = parsed.delay;
+      if (delay !== undefined && (typeof delay !== 'number' || !Number.isFinite(delay) || delay < 0)) {
+        refuse(where, `${kat}.delay`, delay, 'it is the seconds each frame shows for, so a finite number of at least 0');
+      }
+      if (typeof delay === 'number') carried = delay;
+      const mode = typeof parsed.mode === 'string' ? parsed.mode : 'hold';
+      if (mode !== 'hold' && carried === 0) {
+        throw new CompileError(
+          `${where}: \`${kat}\` plays "${mode}" at a delay of 0` +
+            (delay === undefined
+              ? ` — it states none, and the parser carries the previous key's (${j === 0 ? 'there is none, so 0' : '0'})`
+              : '') +
+            '. The runtime advances the frame by `(time - keyTime) / delay`, which is Infinity at 0, and ' +
+            '`Infinity | 0` is 0 — so the key shows its first frame for as long as it lasts, which is "hold" spelt ' +
+            `as "${mode}". State the seconds per frame, or write "hold"`,
+        );
+      }
+    }
+  }
+}
+
 function parseEvents(raw: unknown, where: string, at: string): void {
   if (raw === undefined) return;
   const keys = needArray(raw, where, `${at}.events`, 'it is an array of `{ t, name }` firings — one timeline per animation, naming no target');
@@ -503,6 +620,7 @@ function parseAnimation(raw: unknown, where: string, name: string): void {
   parseTracks(anim.tracks, where, at);
   for (const group of CONSTRAINT_GROUPS) parseConstraintTracks(anim[group], where, at, group);
   parseDeform(anim.deform, where, at);
+  parseSequence(anim.sequence, where, at);
   parseDrawOrder(anim.drawOrder, where, at);
   parseEvents(anim.events, where, at);
 }