spine-rigc 1.7.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 (79) hide show
  1. package/cli.ts +88 -21
  2. package/docs/AUTHORING.md +18 -12
  3. package/package.json +1 -1
  4. package/src/assertions/bodies/a03.ts +27 -0
  5. package/src/assertions/bodies/a04.ts +40 -0
  6. package/src/assertions/bodies/a06.ts +195 -0
  7. package/src/assertions/bodies/a08.ts +76 -0
  8. package/src/assertions/bodies/a11.ts +15 -0
  9. package/src/assertions/bodies/a13.ts +51 -0
  10. package/src/assertions/bodies/a14.ts +35 -0
  11. package/src/assertions/bodies/a15.ts +97 -0
  12. package/src/assertions/bodies/a17.ts +26 -0
  13. package/src/assertions/bodies/a19.ts +295 -0
  14. package/src/assertions/bodies/a20.ts +122 -0
  15. package/src/assertions/bodies/a21.ts +190 -0
  16. package/src/assertions/bodies/a22.ts +39 -0
  17. package/src/assertions/bodies/a23.ts +255 -0
  18. package/src/assertions/bodies/a27.ts +33 -0
  19. package/src/assertions/bodies/a28.ts +70 -0
  20. package/src/assertions/bodies/a33.ts +110 -0
  21. package/src/assertions/bodies/a36.ts +81 -0
  22. package/src/assertions/bodies/a37.ts +77 -0
  23. package/src/assertions/bodies/a38.ts +73 -0
  24. package/src/assertions/bodies/a41.ts +83 -0
  25. package/src/assertions/bodies/a42.ts +97 -0
  26. package/src/assertions/bodies/a44.ts +23 -0
  27. package/src/assertions/bodies/a45.ts +172 -0
  28. package/src/assertions/bodies/a47.ts +59 -0
  29. package/src/assertions/bodies/a48.ts +83 -0
  30. package/src/assertions/constraint_words.ts +177 -0
  31. package/src/assertions/facts/animated_bones.ts +28 -0
  32. package/src/assertions/facts/atlas_pages.ts +19 -0
  33. package/src/assertions/facts/atlas_regions.ts +52 -0
  34. package/src/assertions/facts/constraints.ts +131 -0
  35. package/src/assertions/facts/linked_meshes.ts +38 -0
  36. package/src/assertions/facts/mesh_attachments.ts +71 -0
  37. package/src/assertions/facts/region_joins.ts +34 -0
  38. package/src/assertions/facts/skin_entries.ts +37 -0
  39. package/src/assertions/facts/skin_members.ts +53 -0
  40. package/src/assertions/facts/skin_meshes.ts +49 -0
  41. package/src/assertions/facts/slot_colour.ts +43 -0
  42. package/src/assertions/facts/stage.ts +24 -0
  43. package/src/assertions/facts/vertex_polygons.ts +53 -0
  44. package/src/assertions/harness.ts +109 -0
  45. package/src/assertions/kinds.ts +102 -0
  46. package/src/assertions/mesh_kinds.ts +56 -0
  47. package/src/assertions/model/animated_bones.ts +30 -0
  48. package/src/assertions/model/atlas_pages.ts +15 -0
  49. package/src/assertions/model/atlas_regions.ts +76 -0
  50. package/src/assertions/model/constraints.ts +207 -0
  51. package/src/assertions/model/given.ts +45 -0
  52. package/src/assertions/model/index.ts +247 -0
  53. package/src/assertions/model/linked_meshes.ts +24 -0
  54. package/src/assertions/model/mesh_attachments.ts +90 -0
  55. package/src/assertions/model/parse.ts +138 -0
  56. package/src/assertions/model/region_joins.ts +59 -0
  57. package/src/assertions/model/skin_entries.ts +59 -0
  58. package/src/assertions/model/skin_members.ts +62 -0
  59. package/src/assertions/model/skin_meshes.ts +90 -0
  60. package/src/assertions/model/slot_colour.ts +80 -0
  61. package/src/assertions/model/stage.ts +28 -0
  62. package/src/assertions/model/vertex_polygons.ts +71 -0
  63. package/src/assertions/reasons.ts +127 -0
  64. package/src/assertions/region_lookups.ts +61 -0
  65. package/src/assertions/values.ts +39 -0
  66. package/src/check.ts +36 -9
  67. package/src/compile.ts +204 -57
  68. package/src/core/index.ts +161 -29
  69. package/src/core/world.ts +21 -20
  70. package/src/deformmeasure.ts +377 -154
  71. package/src/deformreport.ts +3 -0
  72. package/src/deformstructure.ts +344 -0
  73. package/src/emit_spine.ts +21 -41
  74. package/src/keyorder.ts +40 -0
  75. package/src/model.ts +188 -22
  76. package/src/render.ts +243 -54
  77. package/src/render_core.ts +101 -13
  78. package/src/transform.ts +79 -30
  79. package/src/validate.ts +742 -2781
package/src/transform.ts CHANGED
@@ -33,13 +33,38 @@
33
33
  * ⭐ **`computeWorldTransforms` is the core's evaluator** (`worldTransforms` in
34
34
  * [`src/core/world.ts`](core/world.ts), issue #1015), whose every rule — the five
35
35
  * inherit modes, the collapsed parent axis, the operation orders — was measured
36
- * against the runtime's pose dump and is held there by the core suite. This file
37
- * hands it the compiler's arithmetic (`COMPILER_ARITHMETIC`, below) and keeps
38
- * what is the compiler's own: the coordinate contract, the refusals by name, the
39
- * world rotation a region cancels, and the inverses.
36
+ * against the runtime's pose dump and is held there by the core suite. Since
37
+ * issue #1021 it runs under the runtime's own arithmetic (`RUNTIME_ARITHMETIC`,
38
+ * the evaluator's default), so the matrices every point is bound through are the
39
+ * ones the runtime poses the build with, to the bit. This file keeps what is the
40
+ * compiler's own: the coordinate contract, the refusals by name, the world
41
+ * rotation a region cancels, and the inverses.
42
+ *
43
+ * ⚠️ **Why the runtime's arithmetic and not the textbook's** (issue #1021). A
44
+ * point is bound by inverting a setup matrix; the runtime then poses it through
45
+ * its own. The two used to differ in the last bits — `Math.PI` against the
46
+ * runtime's 3.1415927, `[cos, −sin, sin, cos]` against the y column taken at
47
+ * `rotation + 90`, radians to degrees by division against multiplication — and
48
+ * that is not noise below the file's precision: an unrotated root reads
49
+ * `b = −2.3e-8` in the runtime, so a point 256 units above its bone was bound
50
+ * 5.9e-6 off before the float32 spelling was even applied. Measured from inside
51
+ * `compile` (every authored world position `toBoneLocal` was handed) against
52
+ * spine-core's pose of the emitted build, the old arithmetic put `gallery/look`'s
53
+ * 312 bound points up to 8.6e-5 from where they were authored (RMS 5.1e-5) and
54
+ * `gallery/flex`'s 258 up to 2.3e-5; the runtime's puts every one of them at the
55
+ * float32 floor — the distance the float32 spelling of the exact inverse alone
56
+ * accounts for (look 8.1e-6, flex 4.1e-6). `CO24` holds it.
57
+ *
58
+ * 🔸 **The rule has a second half: what is MEASURED reads the exact frame.**
59
+ * The runtime's arithmetic is for what is bound — the matrices a point is
60
+ * inverted through. Anything the compiler measures of the authored rig and
61
+ * reports, compares against a threshold, sorts by or refuses on is a statement
62
+ * about the spec, and reads `computeExactFrameTransforms` (below): a depth turn
63
+ * ceiling, a ring's control angles, a `segments` mesh's segments and falloff.
64
+ * An angle the author stated as 90 has to print as 90.
40
65
  */
41
66
  import type { ModelBone } from './model.ts';
42
- import { modeMatrix, worldTransforms, type CoreWorld, type WorldArithmetic } from './core/world.ts';
67
+ import { modeMatrix, RUNTIME_ARITHMETIC, worldTransforms, type CoreWorld, type WorldArithmetic } from './core/world.ts';
43
68
 
44
69
  /**
45
70
  * What `computeWorldTransforms` reads off a bone — a structural type, so both a
@@ -78,26 +103,6 @@ export interface BoneTransform {
78
103
 
79
104
  export class TransformError extends Error {}
80
105
 
81
- const DEG = Math.PI / 180;
82
-
83
- /**
84
- * The arithmetic every figure rigc emits was computed with, handed to the core's
85
- * evaluator (issue #1015). It differs from the runtime's in the last bit and in
86
- * no matrix: degrees to radians with `Math.PI` rather than the runtime's
87
- * 3.1415927, radians back to degrees by dividing by that factor, and a bone with
88
- * the default scale and no shear framed as `lb = -sin`, `ld = cos` rather than
89
- * `cos`/`sin` of `rot + 90°`. One bit can move a float32 spelling in the file, so
90
- * this is a parameter and not a rewrite: measured with the runtime's arithmetic
91
- * instead, 2 of the 19 public recipes moved by at most 4e-5. Whether the compiler
92
- * should bind with the runtime's constant is a question of its own, not settled
93
- * here.
94
- */
95
- const COMPILER_ARITHMETIC: WorldArithmetic = {
96
- radiansPerDegree: DEG,
97
- degreesOf: (radians) => radians / DEG,
98
- rotationOnlyFrame: true,
99
- };
100
-
101
106
  /**
102
107
  * Crop pixels (y down, origin top-left) -> Spine world (y up, origin at the
103
108
  * bottom-left of the crop).
@@ -113,6 +118,20 @@ export function cropToSpineY(cropY: number, cropHeight: number): number {
113
118
  return cropHeight - cropY;
114
119
  }
115
120
 
121
+ /**
122
+ * The textbook's arithmetic — `Math.PI`, a bone with the default scale and no
123
+ * shear framed as `[cos, −sin, sin, cos]`, radians to degrees by dividing by
124
+ * the degree factor — in which an unrotated bone's frame is the identity
125
+ * exactly. Every point the compiler binds goes through the runtime's instead
126
+ * (the header's ⚠️); this is what `computeExactFrameTransforms` evaluates
127
+ * under, and nothing else.
128
+ */
129
+ const EXACT_FRAME_ARITHMETIC: WorldArithmetic = {
130
+ radiansPerDegree: Math.PI / 180,
131
+ degreesOf: (radians) => radians / (Math.PI / 180),
132
+ rotationOnlyFrame: true,
133
+ };
134
+
116
135
  /**
117
136
  * World transform of every bone, in declaration order.
118
137
  *
@@ -120,14 +139,44 @@ export function cropToSpineY(cropY: number, cropHeight: number): number {
120
139
  * requires (it resolves `parent` by name against the bones already read), so a
121
140
  * violation here is a violation there.
122
141
  *
123
- * The matrices and origins are the core's (`worldTransforms`, under
124
- * `COMPILER_ARITHMETIC`). What is decided here is what the core does not say:
142
+ * The matrices and origins are the core's (`worldTransforms`, under the
143
+ * runtime's arithmetic — the header's ⚠️). What is decided here is what the core does not say:
125
144
  * an undeclared parent and an `inherit` no mode answers to are refused by name
126
145
  * as `TransformError`, a bone whose `parent` is empty is a root as it always was
127
146
  * here, and `worldRotation` is read off the matrix — a root with the default
128
- * scale and no shear keeps its stated rotation, unwrapped.
147
+ * scale and no shear keeps its stated rotation, unwrapped. The angle is turned
148
+ * into degrees as the runtime turns one (`RUNTIME_DEG`, by multiplying), so
149
+ * the rotation a region writes to cancel it is read back by the runtime as
150
+ * that angle.
129
151
  */
130
152
  export function computeWorldTransforms(bones: readonly PosableBone[]): Map<string, BoneTransform> {
153
+ return evaluate(bones, RUNTIME_ARITHMETIC);
154
+ }
155
+
156
+ /**
157
+ * The same bones under `EXACT_FRAME_ARITHMETIC`: the frame the compiler
158
+ * MEASURES the authored rig in, and binds nothing through (issue #1021) — a
159
+ * mesh's depth turn ceiling (`sampleMeshDepth` in `compile.ts`), a ring's
160
+ * control angles (`ringControlAngles`, which orders the split and refuses a
161
+ * tie by printing the angle), and a `segments` mesh's segments, the distances
162
+ * its falloff and `minWeight` read and its shared-origin refusal. It differs from
163
+ * `computeWorldTransforms` only in the last bits, and that is exactly why it is
164
+ * kept (issue #1021): the ceiling is a statement about the authored mesh, and
165
+ * its reader treats an axis whose area term is exactly zero as one that cannot
166
+ * fold. The runtime frames an unrotated bone with `b = −2.3e-8`, so in its
167
+ * bind space a sheet whose depth rises linearly in x — which cannot fold a
168
+ * pitch at any angle — reads a pitch ceiling of 89.99997°, and `gallery/look`'s
169
+ * two hair locks gained four such ceilings with their counts (`TC03`, `TC06`
170
+ * went red on it). A control angle read through the runtime's frame printed
171
+ * an authored 90 as 89.99999734089101 in its tie refusal (`RF46`). On the 19
172
+ * recipes the only bytes this keeps from moving are look's ceilings; no
173
+ * emitted position goes through it.
174
+ */
175
+ export function computeExactFrameTransforms(bones: readonly PosableBone[]): Map<string, BoneTransform> {
176
+ return evaluate(bones, EXACT_FRAME_ARITHMETIC);
177
+ }
178
+
179
+ function evaluate(bones: readonly PosableBone[], arithmetic: WorldArithmetic): Map<string, BoneTransform> {
131
180
  const model: ModelBone[] = [];
132
181
  const declared = new Set<string>();
133
182
  for (const bone of bones) {
@@ -149,12 +198,12 @@ export function computeWorldTransforms(bones: readonly PosableBone[]): Map<strin
149
198
  });
150
199
  declared.add(bone.name);
151
200
  }
152
- const worlds = worldTransforms(model, null, modeMatrix, COMPILER_ARITHMETIC);
201
+ const worlds = worldTransforms(model, null, modeMatrix, arithmetic);
153
202
  const out = new Map<string, BoneTransform>();
154
203
  for (const bone of model) {
155
204
  const w = worlds.get(bone.name) as CoreWorld;
156
205
  const plain = (bone.scaleX ?? 1) === 1 && (bone.scaleY ?? 1) === 1 && (bone.shearX ?? 0) === 0 && (bone.shearY ?? 0) === 0;
157
- const worldRotation = bone.parent === undefined && plain ? (bone.rotation ?? 0) : (Math.atan2(w.c, w.a) / DEG + 360) % 360;
206
+ const worldRotation = bone.parent === undefined && plain ? (bone.rotation ?? 0) : (arithmetic.degreesOf(Math.atan2(w.c, w.a)) + 360) % 360;
158
207
  out.set(bone.name, { a: w.a, b: w.b, c: w.c, d: w.d, worldX: w.worldX, worldY: w.worldY, worldRotation });
159
208
  }
160
209
  return out;