rig-play 1.6.0 → 1.8.0

package/README.md

@@ -300,15 +300,37 @@ 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
-the tracks, carrying the single track over by replay (its animation set, pose 0
-taken, stepped to its time); from then on `seek` and `skin` are refused by name,
-since the player cannot replay a composition to a time — step it forward instead.
+the tracks, carrying the single track over by **replay** (its animation set, pose 0
+taken, stepped to its time in `seekStep` increments — one pose per step played, so
+on a stage that idled a while that is one long frame; the core offers no hand-over
+of a live track's state). To never pay it, stand the player on the tracks from the
+start: `new RigPlayer(root, assets, { tracks: true })`. Pick the single track for a
+rig whose animations key what the tracks do not mix (below); pick the tracks for
+layering. Either way, after the first `mix`, `track` above 0, `queue` or `clear`,
+`seek` and `skin` are refused by name, since the player cannot replay a composition
+to a time — step it forward instead.
 Every entry mixes from the setup pose each step, so `adjust` writes still last one
 pose. **What the tracks do not mix**, in rig-c's words at `play`/`queue`: an
 animation keying a constraint (ik, transform, path, physics, slider), a sequence,
@@ -653,7 +675,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. |

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");
@@ -8342,6 +8424,10 @@ class RigPlayer {
   loop = true;
   /** One past the highest track touched — how many `current(track)` reads a step takes. */
   trackCount = 0;
+  /** `RigPlayerOptions.tracks`: every play opens the live tracks, never the single track. */
+  trackMode;
+  /** Set once anything beyond a plain play on track 0 happened: a mix, another track, a queue, a clear. `seek` and `skin` then cannot replay and refuse. */
+  beyondBase = false;
   paused = false;
   pose = null;
   setup = null;
@@ -8364,6 +8450,7 @@ class RigPlayer {
     this.view = options.skin === void 0 ? underNoSkin(read.doc) : underSkin(read.doc, options.skin);
     this.source = frameSource(this.view, read.parsed);
     this.seekStep = options.seekStep ?? 1 / 60;
+    this.trackMode = options.tracks === true;
     if (!(this.seekStep > 0)) throw new Error(`seekStep must be a positive number of seconds, got ${String(options.seekStep)}`);
     this.root = root;
     this.assets = assets;
@@ -8433,8 +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 (this.tracks === null && track === 0 && mix === 0) {
+    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 });
@@ -8442,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;
@@ -8458,8 +8549,9 @@ class RigPlayer {
    */
   queue(name, options = {}) {
     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);
   }
@@ -8469,6 +8561,7 @@ class RigPlayer {
    * setup pose. The pose the player holds is re-posed at once.
    */
   clear(track = 0, options = {}) {
+    this.beyondBase = true;
     const tracks = this.compose();
     tracks.setEmptyAnimation(track, options.mix ?? 0);
     this.trackCount = Math.max(this.trackCount, track + 1);
@@ -8481,31 +8574,48 @@ class RigPlayer {
    * its last `mix` seconds.
    */
   queueClear(track = 0, options = {}) {
+    this.beyondBase = true;
     const tracks = this.compose();
     tracks.addEmptyAnimation(track, options.mix ?? 0, options.delay ?? 0);
     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() {
     return this.tracks !== null;
   }
   /**
-   * The live tracks, opened by the first composing call. A single track in
-   * play is carried over by replay: track 0 set to its animation, pose 0 taken
-   * by `start()` (the player's — nothing steps before it) and the tracks
-   * stepped to the single track's time in `seekStep` increments, so a physics
-   * rig's history restarts there and nothing is fired on the way.
+   * The live tracks, opened by the first composing call (or by the first
+   * `play` under `tracks: true`). A single track in play is carried over by
+   * replay: track 0 set to its animation, pose 0 taken by `start()` (the
+   * player's — nothing steps before it) and the tracks stepped to the single
+   * track's time in `seekStep` increments, so a physics rig's history
+   * restarts there and nothing is fired on the way. The core offers no
+   * hand-over of a live track's state, so that replay costs one pose per
+   * `seekStep` of time played — which `tracks: true` avoids entirely.
    */
   compose() {
     if (this.tracks !== null) return this.tracks;
@@ -8542,12 +8652,20 @@ class RigPlayer {
   seek(time) {
     if (this.animation === null) throw new Error("seek before play: no animation is open");
     if (!(time >= 0) || !Number.isFinite(time)) throw new Error(`seek time must be a finite time at or above 0, got ${String(time)}`);
-    if (this.tracks !== null) throw new Error("seek is defined for a single animation on track 0; after a mix, another track, a queue or a clear the player cannot replay to a time — step it forward with frame/advance instead");
+    if (this.beyondBase) throw new Error("seek is defined for a single animation on track 0; after a mix, another track, a queue or a clear the player cannot replay to a time — step it forward with frame/advance instead");
     this.reopen();
     this.stepTo(time);
   }
-  /** The single track opened again with track 0's animation as `play` last set it, at pose 0. */
+  /** Whatever is open, opened again with track 0's animation as `play` last set it, at pose 0: the single track, or the tracks under `tracks: true`. */
   reopen() {
+    if (this.tracks !== null) {
+      const tracks = openTracks(this.view, { reset: "animation", adjust: this.adjustHook });
+      tracks.setAnimation(0, this.animation, { loop: this.loop, mixDuration: 0 });
+      this.trackCount = 1;
+      this.tracks = tracks;
+      this.pose = tracks.start();
+      return;
+    }
     this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook });
     this.pose = this.track.first;
   }
@@ -8616,14 +8734,14 @@ class RigPlayer {
   }
   set skin(name) {
     if (name === this.skinName) return;
-    if (this.tracks !== null) throw new Error("skin cannot change after a mix, another track, a queue or a clear: the player cannot replay those to the current time — set it before composing, or play again");
+    if (this.beyondBase) throw new Error("skin cannot change after a mix, another track, a queue or a clear: the player cannot replay those to the current time — set it before composing, or play again");
     const view = name === void 0 ? underNoSkin(this.read.doc) : underSkin(this.read.doc, name);
     this.view = view;
     this.source = frameSource(view, this.read.parsed);
     this.skinName = name;
     this.setup = null;
-    if (this.animation !== null && this.track !== null) {
-      const time = this.track.trackTime;
+    if (this.animation !== null && (this.track !== null || this.tracks !== null)) {
+      const time = this.time;
       this.reopen();
       this.stepTo(time);
     }