rig-play 1.7.0 → 1.8.1

package/NOTICE.md

@@ -3,8 +3,8 @@
 ## Spine Runtimes
 
 **The published package links nothing from Esoteric Software.** An install of
-`rig-play` (or of `spine-html`, the same files under the name the package first
-shipped as) carries one JavaScript module, `dist/index.js`, plus type
+`@rig-c/play` (or of `rig-play` or `spine-html`, the same files under the names the
+package shipped as before) carries one JavaScript module, `dist/index.js`, plus type
 declarations, and that module bundles two things: the renderer, and
 `rig-c/core` (MIT), rigc's own posing core, which poses the compiled model
 document `rigc build` writes. No part of the
@@ -28,7 +28,7 @@ it, and it is neither committed nor published.
 
 ### What that means, as a chain of facts
 
-rig-play's own code is MIT (see `LICENSE`). The following is a restatement of
+@rig-c/play's own code is MIT (see `LICENSE`). The following is a restatement of
 Esoteric Software's terms, not a licence term of this project:
 
 1. rigc writes two things side by side: the model document this package plays,
@@ -46,7 +46,7 @@ Esoteric Software's terms, not a licence term of this project:
    because the package links none.
 
 > **What a consumer does with rigc's Spine-format output is governed by
-> Esoteric Software's terms**, not by this package — rig-play neither adds those
+> Esoteric Software's terms**, not by this package — @rig-c/play neither adds those
 > terms nor removes them.
 
 ## Example assets

package/README.md

@@ -1,18 +1,21 @@
 <p align="center">
-  <img src="assets/banner.svg" alt="rig-play - plays rigc's compiled model as DOM elements or one canvas" width="100%" />
+  <img src="assets/banner.svg" alt="@rig-c/play - plays rigc's compiled model as DOM elements or one canvas" width="100%" />
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/rig-play"><img src="https://img.shields.io/npm/v/rig-play.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/rig-play"><img src="https://img.shields.io/npm/dm/rig-play.svg?style=flat-square&color=EC4899" alt="npm downloads" /></a>
+  <a href="https://www.npmjs.com/package/@rig-c/play"><img src="https://img.shields.io/npm/v/@rig-c/play.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@rig-c/play"><img src="https://img.shields.io/npm/dm/@rig-c/play.svg?style=flat-square&color=EC4899" alt="npm downloads" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="license" /></a>
 </p>
 
-Plays the rigs [rigc](https://github.com/firejune/rigc) builds — the compiled model
+Plays the rigs [rigc](https://github.com/rig-c/core) builds — the compiled model
 document `rigc build` writes, `skeleton.model.json` — as **plain DOM**: one
 absolutely-positioned `<img>` per rigid slot, posed with a single CSS `matrix()` write
 per frame, deforming meshes on small per-part canvases; or as **one canvas** per player.
-`spine-html` is the same package under the name it first shipped as.
+`rig-play` and `spine-html` are the same package under the names it shipped as before.
+The toolchain lives under one organisation: the compiler [rig-c/core](https://github.com/rig-c/core)
+(npm `rig-c`), the part generator [rig-c/parts](https://github.com/rig-c/parts)
+(npm `@rig-c/parts`), and this player, [rig-c/play](https://github.com/rig-c/play).
 
 ## Why
 
@@ -29,8 +32,9 @@ At 1.0 it stopped being a Spine runtime. It plays the model document `rigc build
 poses it through `rig-c/core` — rigc's own posing core, bundled into the package — and
 links nothing from Esoteric Software; a Spine export is refused by name. It gained a
 second render mode that draws the whole frame into one canvas. And it took the name
-`rig-play`, which says what it is; `spine-html` keeps being published with the same
-files, so links to the old name keep working.
+`rig-play`, which says what it is; after 1.8 it moved with the rest of the toolchain to
+`@rig-c/play`. `rig-play` and `spine-html` keep being published with the same files, so
+links to either earlier name keep working.
 
 ### Measured
 
@@ -159,11 +163,11 @@ default stays `dom`.
 ## Install
 
 ```bash
-npm i rig-play
-npm i -D rig-c    # the build tool: `rigc build` writes the model rig-play loads
+npm i @rig-c/play
+npm i -D rig-c    # the build tool: `rigc build` writes the model the player loads
 ```
 
-The package plays rigs built by [rigc](https://github.com/firejune/rigc):
+The package plays rigs built by [rigc](https://github.com/rig-c/core):
 `rigc build` writes a compiled model document, `skeleton.model.json` (spec
 `rigc-compiled/3`), next to the Spine pair and the atlas pages. That document
 is what the player loads, and it states everything posing and drawing need —
@@ -173,7 +177,7 @@ the skeleton, the animations, and where every region sits on its page — so the
 is nothing else to install.
 
 ```ts
-import { loadModel, RigPlayer } from 'rig-play';
+import { loadModel, RigPlayer } from '@rig-c/play';
 
 const assets = await loadModel({ modelUrl: '/rigs/walk/skeleton.model.json' });
 
@@ -212,7 +216,7 @@ else. A document whose `spec` is not one `rig-c/core` reads is refused with the
 core's own sentence plus "build it with `rigc build`", and so is a
 `rigc-compiled/1` document, which predates the `pages` section.
 
-`rig-play` is a third-party renderer and is not affiliated with or endorsed by
+`@rig-c/play` is a third-party renderer and is not affiliated with or endorsed by
 Esoteric Software.
 
 ### Drawing your own frames
@@ -221,7 +225,7 @@ Esoteric Software.
 record, so anything that can produce one can draw through it:
 
 ```ts
-import { DomRenderer, type PosedFrame } from 'rig-play';
+import { DomRenderer, type PosedFrame } from '@rig-c/play';
 
 const renderer = new DomRenderer(rootElement, assets.regionImages, assets.pageImages);
 renderer.render(frame); // frame: PosedFrame
@@ -300,9 +304,25 @@ player.play('wave', { track: 2, loop: false, mix: 0.1 });   // a one-shot…
 player.queueClear(2, { mix: 0.1 });                         // …mixed back out over its last 0.1 s
 player.queue('idle_b', { track: 0, mix: 0.3 });             // after the current idle cycle completes
 player.clear(1, { mix: 0.2 });                              // the layer gone, the base showing through
-player.entry(2);                                            // { animation, loop, trackTime, animationTime, duration } | null
+player.entry(2);                                            // { animation, loop, trackTime, animationTime, duration, alpha, additive } | null
+player.play('blink', { track: 3, alpha: 0.6 });            // the same clip at a weight…
+player.setAlpha(3, 0.85);                                   // …changed while it plays
+player.play('breath', { track: 4, additive: true });        // adds to what the tracks below posed
 ```
 
+**Weight and additive layers** (rig-c 2.39.0, the runtime's `TrackEntry.alpha` and
+`additive`): `alpha` (0..1, default 1) multiplies every timeline the entry applies;
+`setAlpha(track, alpha)` changes the current entry's weight from the next pose and
+re-poses the held pose. It does not touch events — an entry fires at any alpha, 0
+included, and one mixing out fires none — or attachments: the current entry keeps
+its attachments at any alpha, one mixing out keeps none. `additive: true`, fixed
+when the entry is set or queued, adds the entry's keyed bone and deform values to
+what the tracks below posed instead of replacing them, so a layer keying the same
+bone channels as an idle does not cover its motion; a rotation is added as it
+stands, with no shortest-angle wrap, and an additive entry mixing out fades with its
+alpha and is never held. Colour, attachment and event timelines apply as on a
+replacing entry. A weight below 1 or an additive entry composes, as a mix does.
+
 `play(name)` keeps meaning what it meant: a plain play on track 0 runs on rig-c's
 single live track, which poses everything the core poses. The first call that
 composes — a `mix`, a `track` above 0, a `queue`, a `clear` — moves the player onto
@@ -637,9 +657,9 @@ name, and unloading is still elements first, bitmaps second.
 
 ### 0.8 → 1.0
 
-| 0.8.0 (`spine-html`) | 1.0.0 (`rig-play`) | Note |
+| 0.8.0 (`spine-html`) | 1.x (`@rig-c/play`, formerly `rig-play`) | Note |
 | --- | --- | --- |
-| `npm i spine-html @esotericsoftware/spine-core` | `npm i rig-play`, and `npm i -D rig-c` for the build tool | 0.8 declared spine-core as a peer dependency (`>=4.0.0 <4.4.0`). 1.0.0 declares no dependencies and no peer dependencies. |
+| `npm i spine-html @esotericsoftware/spine-core` | `npm i @rig-c/play`, and `npm i -D rig-c` for the build tool | 0.8 declared spine-core as a peer dependency (`>=4.0.0 <4.4.0`). 1.0.0 declares no dependencies and no peer dependencies. |
 | `loadSkeletonAssets(options)` | `loadModel(options)` | One URL instead of two. The `.atlas` and `skeleton.json` a build writes beside the document are not fetched. |
 | `LoadSkeletonAssetsOptions.atlasUrl`, `skeletonUrl` | `LoadModelOptions.modelUrl` | |
 | `resolvePage(pageName, atlasUrl)` | `resolvePage(pageName, modelUrl)` | The default now resolves a page name against the model URL's directory. |
@@ -659,7 +679,7 @@ name, and unloading is still elements first, bitmaps second.
 | `new Skeleton(assets.data)` and `new AnimationState(new AnimationStateData(assets.data))` | `new RigPlayer(root, assets, options?)` | The player holds the pose and the track. |
 | `state.setAnimation(0, 'walk', true)` | `player.play('walk', { loop: true })` | `loop` defaults to true. `play` opens the animation at its first pose with the physics reset there. `player.current` names what is playing. |
 | `skeleton.findSlot('x').attachment = null` to hide a slot, or a second skeleton with slots emptied | `RigPlayerOptions.slots`, `player.slots`, `player.posedFrame(slots)` | A draw filter since 1.6.0 — the pose is the whole rig's; a clipping slot left out does not clip. See *Drawing some slots only*. |
-| `state.setAnimation(1, 'smile', false)` with a mix, `addAnimation`, `setEmptyAnimation`, `addEmptyAnimation`, `getCurrent(track)` | `player.play(name, { track, loop, mix })`, `player.queue(name, { track, loop, mix, delay })`, `player.clear(track, { mix })`, `player.queueClear(track, { mix, delay })`, `player.entry(track)` | Since 1.5.0, rig-c's live tracks: the runtime's mixing at tolerance 0. Constraint, sequence, draw-order and path-deform timelines are not mixed and are refused on the tracks. See *Several tracks*. |
+| `state.setAnimation(1, 'smile', false)` with a mix, `addAnimation`, `setEmptyAnimation`, `addEmptyAnimation`, `getCurrent(track)`, `entry.alpha`, `entry.additive` | `player.play(name, { track, loop, mix, alpha, additive })`, `player.queue(name, { track, loop, mix, delay, alpha, additive })`, `player.clear(track, { mix })`, `player.queueClear(track, { mix, delay })`, `player.setAlpha(track, alpha)`, `player.entry(track)` | Since 1.5.0, rig-c's live tracks: the runtime's mixing at tolerance 0. Constraint, sequence, draw-order and path-deform timelines are not mixed and are refused on the tracks. See *Several tracks*. |
 | `state.update(delta)`, `state.apply(skeleton)`, `skeleton.update(delta)`, `skeleton.updateWorldTransform(Physics.update)`, `renderer.render(skeleton)` | `player.frame(dt)` | Or `player.advance(dt)` then `player.draw()`, to time the two apart. |
 | time scale (the caller's own, on the spine-core side) | `player.timeScale` | Multiplies every step. 0 holds the pose without re-posing it; a negative value is not stepped. |
 | holding a pose (the caller stopped advancing) | `player.pause()`, `player.resume()` | `frame` keeps drawing the held pose. |
@@ -745,7 +765,7 @@ renderer.dispose(); assets.dispose(); // on unload
 1.0.0:
 
 ```ts
-import { loadModel, RigPlayer } from 'rig-play';
+import { loadModel, RigPlayer } from '@rig-c/play';
 const assets = await loadModel({ modelUrl: '/rigs/walk/skeleton.model.json' });
 const player = new RigPlayer(rootElement, assets);
 player.play('walk', { loop: true });
@@ -918,10 +938,10 @@ perf oracle is the demo's stats line on a real device.
 
 ## License
 
-rig-play's own code is MIT (see [LICENSE](LICENSE)). That says nothing about Spine,
+@rig-c/play's own code is MIT (see [LICENSE](LICENSE)). That says nothing about Spine,
 so here is what is true of this package and this repository, stated plainly:
 
-1. The published package — `rig-play`, and `spine-html`, the same files — **links
+1. The published package — `@rig-c/play`, and `rig-play` and `spine-html`, the same files — **links
    nothing from Esoteric Software**. Its one module bundles the renderer and
    `rig-c/core` (MIT), which poses rigc's model document; no part of the
    [Spine Runtimes](https://github.com/EsotericSoftware/spine-runtimes) is in it or
@@ -940,7 +960,7 @@ so here is what is true of this package and this repository, stated plainly:
    this project.
 
 > **What a consumer does with rigc's Spine-format output is governed by Esoteric
-> Software's terms**, not by this package — rig-play neither adds those terms nor
+> Software's terms**, not by this package — @rig-c/play neither adds those terms nor
 > removes them.
 
 No example assets of Esoteric Software's are fetched or redistributed. See

package/dist/index.js

@@ -379,7 +379,7 @@ function timelineIdentity(slot, shown) {
 const nameOf = (a) => `${a.skin}/${a.slot}/${a.attachment}`;
 function attachmentStates(doc, resolve, placeholders, sample, sliders, plant = {}, mixed) {
   const evalDeform = plant.deform ?? deformAt;
-  const blendOf = plant.deformBlend ?? blendDeform;
+  const blendOf2 = plant.deformBlend ?? blendDeform;
   const evalFrame = plant.sequence ?? sequenceFrameAt;
   const shown = [];
   const why = [];
@@ -410,7 +410,7 @@ function attachmentStates(doc, resolve, placeholders, sample, sliders, plant = {
         if (!seen.includes(now2.identity)) seen.push(now2.identity);
         if (a.deform !== null && now2.vertices !== null) {
           const target = evalDeform(now2.vertices, a.deform, t);
-          if (target !== null) deform = blend === null ? target : blendOf(now2.vertices, deform, target, blend.alpha, blend.additive);
+          if (target !== null) deform = blend === null ? target : blendOf2(now2.vertices, deform, target, blend.alpha, blend.additive);
         }
         if (a.sequence !== null && now2.count !== void 0) {
           const f = evalFrame(a.sequence, now2.count, t);
@@ -5072,6 +5072,9 @@ const FIRST = 2;
 const MODE = 3;
 const HOLD = 4;
 const EMPTY = { name: null, duration: 0, timelines: [], ids: /* @__PURE__ */ new Set() };
+function addable(tl) {
+  return tl.type === "deform" || tl.type === "bone" && tl.kind !== "inherit";
+}
 const BONE_PROPERTIES = {
   rotate: ["rotate"],
   translate: ["x", "y"],
@@ -5141,6 +5144,8 @@ function newEntry(anim, loop) {
     mixTime: 0,
     mixDuration: 0,
     totalAlpha: 0,
+    alpha: 1,
+    additive: false,
     keepHold: false,
     timelineMode: [],
     timelineHoldMix: [],
@@ -5317,6 +5322,19 @@ class Mixer {
     }
     return this.plant.mixReversed === true ? 1 - m : m;
   }
+  /** `TrackEntry.alpha` — inverted or ignored under the plants. */
+  alphaOf(e) {
+    if (this.plant.alphaIgnored === true) return 1;
+    return this.plant.alphaInverted === true ? 1 - e.alpha : e.alpha;
+  }
+  /** `TrackEntry.additive` — never under the plant that applies an additive entry as a replacing one. */
+  additiveOf(e) {
+    return e.additive && this.plant.additiveAsReplace !== true;
+  }
+  /** Whether `computeHold` reads an entry as additive — never under the plant that holds as if none were. */
+  holdsAdditive(e) {
+    return e !== null && this.additiveOf(e) && this.plant.additiveHeld !== true;
+  }
   update(delta) {
     const tracks = this.tracks;
     for (let i = 0, n = tracks.length; i < n; i++) {
@@ -5387,7 +5405,7 @@ class Mixer {
     for (let i = 0, n = tracks.length; i < n; i++) {
       const current = tracks[i];
       if (current === null || current.delay > 0) continue;
-      let alpha = 1;
+      let alpha = this.alphaOf(current);
       if (current.mixingFrom !== null) alpha *= this.applyMixingFrom(current, pose, i);
       else if (current.trackTime >= current.trackEnd && current.next === null) alpha = 0;
       const animationLast = current.animationLast;
@@ -5397,18 +5415,22 @@ class Mixer {
       if (i === 0 && alpha === 1) {
         for (const tl of timelines) {
           if (tl.type === "attachment") this.applyAttachment(pose, tl, animationTime, SETUP, true);
-          else this.applyTimeline(pose, tl, animationLast, animationTime, true, 1, SETUP, false);
+          else this.applyTimeline(pose, tl, animationLast, animationTime, true, 1, SETUP, false, false);
         }
       } else {
         const modes = current.timelineMode;
-        const retain = alpha >= 0;
-        const firstFrame = current.timelinesRotation.length !== count << 1;
+        const retain = this.plant.attachmentsBelowHalfAlpha === true ? alpha >= 0.5 : alpha >= 0;
+        const add = this.additiveOf(current);
+        const shortest = add && this.plant.additiveRotateRemembered !== true;
+        const firstFrame = !shortest && current.timelinesRotation.length !== count << 1;
         if (firstFrame) current.timelinesRotation.length = count << 1;
         timelines.forEach((tl, ii) => {
           const from = this.fromOf(modes[ii] & MODE, i);
-          if (tl.type === "bone" && tl.kind === "rotate") this.applyRotate(pose, tl, animationTime, alpha, from, current.timelinesRotation, ii << 1, firstFrame);
-          else if (tl.type === "attachment") this.applyAttachment(pose, tl, animationTime, from, retain);
-          else this.applyTimeline(pose, tl, animationLast, animationTime, true, alpha, from, false);
+          if (!shortest && tl.type === "bone" && tl.kind === "rotate") this.applyRotate(pose, tl, animationTime, alpha, from, current.timelinesRotation, ii << 1, firstFrame);
+          else if (tl.type === "attachment") {
+            if (add && this.plant.additiveAttachmentsDirect === true) this.applyAttachmentDirect(pose, tl, animationTime, from, false);
+            else this.applyAttachment(pose, tl, animationTime, from, retain);
+          } else this.applyTimeline(pose, tl, animationLast, animationTime, true, alpha, from, false, add);
         });
       }
       if (i === 0) base = animationTime;
@@ -5428,15 +5450,17 @@ class Mixer {
     const from = to.mixingFrom;
     const fromMix = from.mixingFrom !== null ? this.applyMixingFrom(from, pose, track) : 1;
     const mix = this.mixOf(to);
-    const a = 1 * fromMix;
-    const keep = 1 - mix * 1;
+    const a = this.alphaOf(from) * fromMix;
+    const keep = 1 - mix * (this.plant.holdIgnoresEntryAlpha === true ? 1 : this.alphaOf(to));
     const alphaMix = a * (1 - mix);
     const alphaHold = keep > 0 ? alphaMix / keep : a;
     const timelines = from.anim.timelines;
     const count = timelines.length;
     const modes = from.timelineMode;
     const holdMix = from.timelineHoldMix;
-    const firstFrame = from.timelinesRotation.length !== count << 1;
+    const add = this.additiveOf(from);
+    const shortest = add && this.plant.additiveRotateRemembered !== true;
+    const firstFrame = !shortest && from.timelinesRotation.length !== count << 1;
     if (firstFrame) from.timelinesRotation.length = count << 1;
     const animationLast = from.animationLast;
     const animationTime = animationTimeOf(from);
@@ -5451,9 +5475,11 @@ class Mixer {
         alpha = h === null || h === void 0 ? alphaHold : alphaHold * (1 - this.mixOf(h));
       } else alpha = alphaMix;
       from.totalAlpha += alpha;
-      if (tl.type === "bone" && tl.kind === "rotate") this.applyRotate(pose, tl, animationTime, alpha, mixFrom, from.timelinesRotation, i << 1, firstFrame);
-      else if (tl.type === "attachment") this.applyAttachment(pose, tl, animationTime, mixFrom, false);
-      else this.applyTimeline(pose, tl, animationLast, animationTime, fire, alpha, mixFrom, true);
+      if (!shortest && tl.type === "bone" && tl.kind === "rotate") this.applyRotate(pose, tl, animationTime, alpha, mixFrom, from.timelinesRotation, i << 1, firstFrame);
+      else if (tl.type === "attachment") {
+        if (add && this.plant.additiveAttachmentsDirect === true) this.applyAttachmentDirect(pose, tl, animationTime, mixFrom, true);
+        else this.applyAttachment(pose, tl, animationTime, mixFrom, false);
+      } else this.applyTimeline(pose, tl, animationLast, animationTime, fire, alpha, mixFrom, true, add);
     });
     from.nextAnimationLast = animationTime;
     from.nextTrackLast = from.trackTime;
@@ -5480,14 +5506,20 @@ class Mixer {
     const holdMix = entry.timelineHoldMix;
     holdMix.length = 0;
     const to = entry.mixingTo;
+    const add = this.holdsAdditive(entry);
+    const toAdds = this.holdsAdditive(to);
     timelines.forEach((tl, i) => {
       const from = this.propertyFrom(track, tl.ids);
+      if (add && addable(tl)) {
+        modes[i] = from;
+        return;
+      }
       let mode;
-      if (to === null || tl.instant || !hasAny(to.anim, tl.ids)) mode = from;
+      if (to === null || tl.instant || toAdds && addable(tl) || !hasAny(to.anim, tl.ids)) mode = from;
       else {
         mode = from | HOLD;
         for (let next = to.mixingTo; next !== null; next = next.mixingTo) {
-          if (!hasAny(next.anim, tl.ids)) {
+          if (this.holdsAdditive(next) && addable(tl) || !hasAny(next.anim, tl.ids)) {
             if (next.mixDuration > 0) holdMix[i] = next;
             break;
           }
@@ -5523,15 +5555,15 @@ class Mixer {
     const channel2 = this.plant.channel ?? channelAt;
     return keys[index].values.map((_v, c) => channel2(keys, index, c, t));
   }
-  /** `Timeline.apply` for every timeline but an attachment's and a rotation mixed below full weight. */
-  applyTimeline(pose, tl, lastTime, time, fire, alpha, from, out) {
+  /** `Timeline.apply` for every timeline but an attachment's and a rotation mixed below full weight; `add` is the entry's, read only by the timelines the runtime adds (`addable`). */
+  applyTimeline(pose, tl, lastTime, time, fire, alpha, from, out, add) {
     switch (tl.type) {
       case "bone":
-        return this.applyBone(pose, tl, time, alpha, from, out);
+        return this.applyBone(pose, tl, time, alpha, from, out, add);
       case "colour":
         return this.applyColour(pose, tl, time, alpha, from);
       case "deform":
-        return this.applyDeform(pose, tl, time, alpha, from);
+        return this.applyDeform(pose, tl, time, alpha, from, add);
       case "events":
         if (fire) pose.events.push(...eventsFired(tl.keys, lastTime, time, rawNumber, time < lastTime));
         return;
@@ -5539,7 +5571,7 @@ class Mixer {
         return;
     }
   }
-  applyBone(pose, tl, time, alpha, from, out) {
+  applyBone(pose, tl, time, alpha, from, out, add) {
     const bone2 = pose.bone(tl.bone);
     if (bone2 === null) return;
     const setup = this.doc.bones[tl.bone];
@@ -5562,7 +5594,7 @@ class Mixer {
     const relative = (field, i) => {
       const s = setup[field] ?? 0;
       const c = bone2[field] ?? 0;
-      bone2[field] = v === null ? beforeFirstKey(from, alpha, c, s) : from === SETUP ? s + v[i] * alpha : c + (v[i] + s - c) * alpha;
+      bone2[field] = v === null ? beforeFirstKey(from, alpha, c, s) : from === SETUP ? s + v[i] * alpha : c + (add ? v[i] : v[i] + s - c) * alpha;
     };
     const pair = (fx, fy) => {
       const sx = setup[fx] ?? 0;
@@ -5580,6 +5612,9 @@ class Mixer {
       if (from === SETUP) {
         bone2[fx] = sx + v[0] * alpha;
         bone2[fy] = sy + v[1] * alpha;
+      } else if (add) {
+        bone2[fx] = (bone2[fx] ?? 0) + v[0] * alpha;
+        bone2[fy] = (bone2[fy] ?? 0) + v[1] * alpha;
       } else {
         bone2[fx] = (bone2[fx] ?? 0) + (sx + v[0] - (bone2[fx] ?? 0)) * alpha;
         bone2[fy] = (bone2[fy] ?? 0) + (sy + v[1] - (bone2[fy] ?? 0)) * alpha;
@@ -5588,7 +5623,7 @@ class Mixer {
     const scale = (field, i) => {
       const s = setup[field] ?? 1;
       const c = bone2[field] ?? 1;
-      bone2[field] = v === null ? beforeFirstKey(from, alpha, c, s) : scaleValue(v[i] * s, alpha, from, out, c, s);
+      bone2[field] = v === null ? beforeFirstKey(from, alpha, c, s) : scaleValue(v[i] * s, alpha, from, out, add, c, s);
     };
     switch (tl.kind) {
       case "rotate":
@@ -5624,8 +5659,8 @@ class Mixer {
             bone2.scaleY = (bone2.scaleY ?? 1) + (sy - (bone2.scaleY ?? 1)) * alpha;
           }
         } else {
-          bone2.scaleX = scaleValue(v[0] * (setup.scaleX ?? 1), alpha, from, out, bone2.scaleX ?? 1, setup.scaleX ?? 1);
-          bone2.scaleY = scaleValue(v[1] * (setup.scaleY ?? 1), alpha, from, out, bone2.scaleY ?? 1, setup.scaleY ?? 1);
+          bone2.scaleX = scaleValue(v[0] * (setup.scaleX ?? 1), alpha, from, out, add, bone2.scaleX ?? 1, setup.scaleX ?? 1);
+          bone2.scaleY = scaleValue(v[1] * (setup.scaleY ?? 1), alpha, from, out, add, bone2.scaleY ?? 1, setup.scaleY ?? 1);
         }
         break;
       case "scalex":
@@ -5640,7 +5675,7 @@ class Mixer {
   applyRotate(pose, tl, time, alpha, from, rotations, i, firstFrame) {
     if (firstFrame) rotations[i] = 0;
     if (alpha === 1) {
-      this.applyBone(pose, tl, time, 1, from, false);
+      this.applyBone(pose, tl, time, 1, from, false, false);
       return;
     }
     const bone2 = pose.bone(tl.bone);
@@ -5712,6 +5747,14 @@ class Mixer {
     if (retain) s.attachmentState = ATTACH_RETAIN;
     else if (!setup) s.attachmentState = ATTACH_SETUP;
   }
+  /** `AttachmentTimeline.apply` — the plain timeline, writing no attachment state: only `additiveAttachmentsDirect` reaches it, the reading `CO52` rejects. */
+  applyAttachmentDirect(pose, tl, time, from, out) {
+    if (!pose.slotLive(tl.slot)) return;
+    const index = (this.plant.search ?? keyIndexAt)(tl.keys, time);
+    if (out || index < 0) {
+      if (from !== CURRENT) pose.setAttachment(tl.slot, this.doc.slots[tl.slot].setup);
+    } else pose.setAttachment(tl.slot, tl.keys[index].name ?? null);
+  }
   applyColour(pose, tl, time, alpha, from) {
     if (!pose.slotLive(tl.slot)) return;
     const slot = this.doc.slots[tl.slot];
@@ -5807,7 +5850,7 @@ class Mixer {
     }
   }
   /** `DeformTimeline.apply`: every live slot showing the record the timeline keys, its deform array mixed. */
-  applyDeform(pose, tl, time, alpha, from) {
+  applyDeform(pose, tl, time, alpha, from, add) {
     const keys = tl.timeline.deform;
     if (keys === null) return;
     pose.slots.forEach((s, k) => {
@@ -5837,12 +5880,26 @@ class Mixer {
         }
         return;
       }
-      if (alpha === 1) s.deform = [...target];
-      else if (mixFrom === SETUP) {
+      const fromSetup = mixFrom === SETUP;
+      if (alpha === 1) {
+        if (add && !fromSetup) {
+          const current = s.deform;
+          if (!vertices.weighted) {
+            const setup = setupArray(vertices);
+            s.deform = current.map((c, i) => c + (target[i] - setup[i]));
+          } else s.deform = current.map((c, i) => c + target[i]);
+        } else s.deform = [...target];
+      } else if (fromSetup) {
         if (!vertices.weighted) {
           const setup = setupArray(vertices);
           s.deform = target.map((v, i) => setup[i] + (v - setup[i]) * alpha);
         } else s.deform = target.map((v) => v * alpha);
+      } else if (add) {
+        const current = s.deform;
+        if (!vertices.weighted) {
+          const setup = setupArray(vertices);
+          s.deform = current.map((c, i) => c + (target[i] - setup[i]) * alpha);
+        } else s.deform = current.map((c, i) => c + target[i] * alpha);
       } else {
         const current = s.deform;
         s.deform = current.map((c, i) => c + (target[i] - c) * alpha);
@@ -5855,9 +5912,10 @@ function beforeFirstKey(from, alpha, current, setup) {
   if (from === FIRST) return current + (setup - current) * alpha;
   return current;
 }
-function scaleValue(value, alpha, from, out, current, setup) {
-  if (alpha === 1) return value;
+function scaleValue(value, alpha, from, out, add, current, setup) {
+  if (alpha === 1 && !add) return value;
   let base = from === SETUP ? setup : current;
+  if (add) return base + (value - setup) * alpha;
   if (out) return base + (Math.abs(value) * Math.sign(base) - base) * alpha;
   base = Math.abs(base) * Math.sign(value);
   return base + (value - base) * alpha;
@@ -5878,6 +5936,16 @@ function loopOf(options, call) {
   if (typeof options !== "object" || options === null || typeof options.loop !== "boolean") throw new CoreInputError(`the live tracks' ${call} options.loop is ${JSON.stringify(options?.loop)}, not true or false`);
   return options.loop;
 }
+function alphaValue(v, what, call) {
+  if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || v > 1) throw new CoreInputError(`the live tracks' ${call} ${what} is ${typeof v === "number" ? String(v) : JSON.stringify(v)}, not a number from 0 to 1`);
+  return v;
+}
+function blendOf(options, call) {
+  const alpha = options.alpha === void 0 ? 1 : alphaValue(options.alpha, "options.alpha", call);
+  const additive = options.additive;
+  if (additive !== void 0 && typeof additive !== "boolean") throw new CoreInputError(`the live tracks' ${call} options.additive is ${JSON.stringify(additive)}, not true or false — an entry adds or it does not`);
+  return { alpha, additive: additive === true };
+}
 function delayOf(v, call) {
   if (typeof v !== "number" || !Number.isFinite(v)) throw new CoreInputError(`the live tracks' ${call} delay is ${String(v)}, not a finite number`);
   return v;
@@ -5911,8 +5979,11 @@ class Tracks {
     const i = trackIndex(track, "setAnimation");
     const loop = loopOf(options, "setAnimation");
     const mix = finiteAtOrAbove0(options.mixDuration, "mixDuration", "setAnimation");
+    const blend = blendOf(options, "setAnimation");
     const entry = this.mixer.setAnimation(i, this.mixer.animation(animation), loop);
     entry.mixDuration = mix;
+    entry.alpha = blend.alpha;
+    entry.additive = blend.additive;
   }
   setEmptyAnimation(track, mixDuration) {
     this.live("setEmptyAnimation");
@@ -5928,8 +5999,11 @@ class Tracks {
     const loop = loopOf(options, "addAnimation");
     const mix = finiteAtOrAbove0(options.mixDuration, "mixDuration", "addAnimation");
     const delay = delayOf(options.delay, "addAnimation");
+    const blend = blendOf(options, "addAnimation");
     const entry = this.mixer.addAnimation(i, this.mixer.animation(animation), loop, delay);
     this.mixer.setMixDuration(entry, mix, delay);
+    entry.alpha = blend.alpha;
+    entry.additive = blend.additive;
   }
   addEmptyAnimation(track, mixDuration, delay) {
     this.live("addEmptyAnimation");
@@ -5941,10 +6015,18 @@ class Tracks {
     entry.mixDuration = mix;
     entry.trackEnd = mix;
   }
+  setAlpha(track, alpha) {
+    this.live("setAlpha");
+    const i = trackIndex(track, "setAlpha");
+    const a = alphaValue(alpha, "alpha", "setAlpha");
+    const e = this.mixer.tracks[i] ?? null;
+    if (e === null) throw new CoreInputError(`the live tracks' setAlpha names track ${i}, which plays nothing — there is no entry to weigh`);
+    e.alpha = a;
+  }
   current(track) {
     const e = this.mixer.tracks[trackIndex(track, "current")] ?? null;
     if (e === null) return null;
-    return { animation: e.anim.name, loop: e.loop, trackTime: e.trackTime, animationTime: animationTimeOf(e), duration: e.anim.duration };
+    return { animation: e.anim.name, loop: e.loop, trackTime: e.trackTime, animationTime: animationTimeOf(e), duration: e.anim.duration, alpha: e.alpha, additive: e.additive };
   }
   start() {
     this.live("start");
@@ -8438,9 +8520,12 @@ class RigPlayer {
     const track = options.track ?? 0;
     const loop = options.loop ?? true;
     const mix = options.mix ?? 0;
+    const alpha = options.alpha ?? 1;
+    const additive = options.additive ?? false;
     this.paused = false;
-    if (track !== 0 || mix !== 0) this.beyondBase = true;
-    if (this.tracks === null && track === 0 && mix === 0 && !this.trackMode) {
+    const plain = track === 0 && mix === 0 && alpha === 1 && !additive;
+    if (!plain) this.beyondBase = true;
+    if (this.tracks === null && plain && !this.trackMode) {
       this.animation = name;
       this.loop = loop;
       this.track = openTrack(this.view, name, { loop, reset: "animation", adjust: this.adjustHook });
@@ -8448,7 +8533,7 @@ class RigPlayer {
       return;
     }
     const tracks = this.compose();
-    tracks.setAnimation(track, name, { loop, mixDuration: mix });
+    tracks.setAnimation(track, name, { loop, mixDuration: mix, alpha, additive });
     this.trackCount = Math.max(this.trackCount, track + 1);
     if (track === 0) {
       this.animation = name;
@@ -8466,7 +8551,7 @@ class RigPlayer {
     const track = options.track ?? 0;
     this.beyondBase = true;
     const tracks = this.compose();
-    tracks.addAnimation(track, name, { loop: options.loop ?? true, mixDuration: options.mix ?? 0, delay: options.delay ?? 0 });
+    tracks.addAnimation(track, name, { loop: options.loop ?? true, mixDuration: options.mix ?? 0, delay: options.delay ?? 0, alpha: options.alpha ?? 1, additive: options.additive ?? false });
     this.trackCount = Math.max(this.trackCount, track + 1);
     this.pose = tracks.step(0);
   }
@@ -8495,15 +8580,28 @@ class RigPlayer {
     this.trackCount = Math.max(this.trackCount, track + 1);
     this.pose = tracks.step(0);
   }
+  /**
+   * Sets the weight of `track`'s current entry, from 0 to 1, from the next pose
+   * on — the pose the player holds is re-posed at once, so a held player shows
+   * it on its next `draw`. An entry it is mixing from keeps its own weight. A
+   * track playing nothing, or a weight outside 0..1, is refused in the core's
+   * words. On the single track this composes: the player moves onto the tracks.
+   */
+  setAlpha(track, alpha) {
+    this.beyondBase = true;
+    const tracks = this.compose();
+    tracks.setAlpha(track, alpha);
+    this.pose = tracks.step(0);
+  }
   /** `track`'s current entry, or null where it plays nothing (and before `play`). */
   entry(track = 0) {
     if (this.tracks !== null) {
       const view = this.tracks.current(track);
-      return view === null ? null : { animation: view.animation, loop: view.loop, trackTime: view.trackTime, animationTime: view.animationTime, duration: view.duration };
+      return view === null ? null : { animation: view.animation, loop: view.loop, trackTime: view.trackTime, animationTime: view.animationTime, duration: view.duration, alpha: view.alpha, additive: view.additive };
     }
     const single = this.track;
     if (track !== 0 || single === null) return null;
-    return { animation: this.animation, loop: this.loop, trackTime: single.trackTime, animationTime: single.animationTime, duration: single.duration };
+    return { animation: this.animation, loop: this.loop, trackTime: single.trackTime, animationTime: single.animationTime, duration: single.duration, alpha: 1, additive: false };
   }
   /** Whether the player is composed: on the live tracks rather than the single track. */
   get composed() {