@rig-c/play 1.16.0 → 1.17.0

package/README.md

@@ -643,6 +643,63 @@ physics state) and nothing when no physics hangs under a re-posed bone. Three li
 - A later `seek` replays from the start with the sets then active, as it
   always has, so it does not reproduce a carried switch.
 
+**Easing a drawn set in and out** (#174). A drawn set snaps its bones to the
+drawn angles in one frame. `ease` turns them there over a duration instead,
+and swaps the attachments halfway, the way an alternate drawing takes over
+at a middle angle:
+
+```ts
+player.setSets(['wave_r'], { ease: 0.5 });   // also setSet, addSet, removeSet
+player.setSets([], { ease: 0.5 });           // and back
+```
+
+- **The curve.** Each bone whose drawn rotation the call adds, removes or
+  changes turns from what it shows to its new local rotation along the
+  shorter way: `start + shortestΔ(start, end) · smoothstep(u)`, with
+  `u = elapsed / ease`. Going on, the start is the clip's value at the time
+  (it moves with the clip) and the end the drawn local; going off, the start
+  is the drawn local and the end the clip's value. So the progress from start
+  to end never leaves `[0, 1]` and never turns back, while the clip plays
+  underneath. On `@rig-c/parts`' public wind example with its gesture set
+  (`wave_r`, 0.5 s), it is 0 to 1 and non-decreasing on every frame, on and
+  off; on a clip that holds the arm still, the sleeve's world angle goes
+  −119.32° → −110° and back with no overshoot.
+- **The swap.** The held pose draws the attachments it showed until the frame
+  whose `u` is nearest ½, then the set's (a tie goes to the later frame; the
+  next step is predicted from the current one, so a constant `dt` lands on
+  the nearest frame). On the wind example at `frame(1/60)`, 0.5 s swaps on
+  frame 15 and 0.25 s on frame 8. `activeSets`, `set` and `slotIdentity().sets`
+  name the call's sets from the call on; `slotIdentity().slots` reports what
+  the pose draws, so before the swap it shows the previous attachments.
+- **The end.** On the frame the elapsed time reaches `ease`, the player is in
+  exactly the instant switch's state: from then on every bone matches an
+  instant switch made at the same frame (0° measured) and the slot identity
+  too.
+- **Time.** The elapsed time is the player's step (`dt × timeScale`): a
+  paused player, or a step of 0, holds the ease where it is. Before `play`
+  there is nothing to step and the switch is instant; so is a call that
+  re-poses no bone. A `seek` or a skin change lands an ease in flight at
+  once.
+- **A call during an ease** starts a new one from the angles shown (no jump:
+  reversing a 0.5 s ease at 0.3 makes no frame-to-frame step larger than the
+  ease's own), and the attachment swap starts again from what is drawn. A
+  call without `ease` during an ease lands it at once.
+- `ease: 0`, or no `ease`, is the instant switch, frame for frame. Anything
+  but a finite number at or above 0 is refused by name before anything
+  changes.
+
+With physics: `ease` and `physics: 'carry'` carry the chains under the eased
+bones on every eased frame — before each step, the turn the frame's blend
+makes is read as #173's switch is (a trial pose at the previous time) and
+the chains are moved by it — so the ease's own turn is not read as motion.
+`physics: 'reset'` with `ease` restarts them once, at the call. On `drape`
+(0.5 s raise, sleeve tips in the arm's frame): the ease alone moves the
+sleeve up to 30 units a frame relative to the arm (the chain reads the turn
+as motion), ease + carry at most 3.9 on the `idle` clip (its idle ranges are
+1.5 hanging and 4.2 raised) and 2.3 on `shift` (0.85 and 0.07), where
+gravity re-settles the chain in the turning arm's frame (with gravity at 0,
+0.83 against 0.84).
+
 `sets.json` keys are read strictly. Besides `slots`, `hides` and `drawn`, a
 set may carry `drawnLength`, `registration` and `threshold`, which parts
 writes and which place nothing under `check --set`: play reads past them by

package/dist/index.js

@@ -8962,6 +8962,20 @@ function frameOf(source, pose, color = [1, 1, 1, 1], draws = () => true) {
   return { order };
 }
 const DEFAULT_ENVIRONMENT = Object.freeze({ wind: Object.freeze([1, 0]), gravity: Object.freeze([0, 1]) });
+function setEaseOption(call, options) {
+  const ease = options?.ease;
+  if (ease === void 0) return 0;
+  if (typeof ease !== "number" || !Number.isFinite(ease) || ease < 0) {
+    throw new Error(`${call}: options.ease must be a finite number of seconds at or above 0, got ${typeof ease === "number" ? String(ease) : JSON.stringify(ease)}`);
+  }
+  return ease;
+}
+function easeProgress(ease) {
+  return Math.min(Math.max(ease.elapsed / ease.duration, 0), 1);
+}
+function smoothstep(u) {
+  return u * u * (3 - 2 * u);
+}
 function setPhysicsOption(call, options) {
   if (options === void 0) return void 0;
   if (options === null || typeof options !== "object") {
@@ -9285,6 +9299,12 @@ class RigPlayer {
   drawnPose = null;
   /** Test-only (#173's planted control): `carry` maps every state through the identity instead of the anchor's turn. Not API. */
   carryPlant = false;
+  /** An eased set switch in flight (#174), or null. */
+  easing = null;
+  /** The last positive step `advance` took: what predicts the next one when an ease starts. */
+  lastStep = 0;
+  /** Test-only (#174's planted controls): swap the attachments at u = 0, or ease by w = 1.2u (1 at u = 1). Not API. */
+  easePlant = null;
   adjustFn = null;
   /** Current preview patches, reapplied through the public core API on replay; no edit history. */
   physicsPatches = /* @__PURE__ */ new Map();
@@ -9295,7 +9315,8 @@ class RigPlayer {
   draws = () => true;
   /** Handed to every track the player opens; reads the current `adjust` so setting it later needs no reopen. */
   adjustHook = (locals, ctx) => {
-    if (this.drawnPose !== null) for (const [bone2, rotation] of this.drawnPose) locals.bone(bone2).rotation = rotation;
+    if (this.easing !== null) this.applyEase(this.easing, locals);
+    else if (this.drawnPose !== null) for (const [bone2, rotation] of this.drawnPose) locals.bone(bone2).rotation = rotation;
     if (this.adjustFn !== null) this.adjustFn(locals, ctx);
   };
   listeners = {
@@ -9504,11 +9525,12 @@ class RigPlayer {
     if (time > 0) this.stepTo(time);
     return tracks;
   }
-  /** Stores `raw` and applies `activeSet` when one is active. Zero work when `activeSet === null`. */
+  /** Stores `raw` and applies the shown set (`activeSet`, or before an ease's swap the composition it eases from). Zero work when none. */
   setRawPose(raw) {
     this.rawPose = raw;
     this.heldParameters = null;
-    this.pose = this.activeSet === null ? raw : applySetToPose(this.view, raw, this.activeSet);
+    const set = this.shownSet();
+    this.pose = set === null ? raw : applySetToPose(this.view, raw, set);
     this.poseGeneration++;
     this.cachedIdentity = null;
   }
@@ -9626,6 +9648,7 @@ class RigPlayer {
     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.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.easing = null;
     const cache = this.ensureSeekCache();
     const stepper = this.tracks ?? this.track;
     const exactHit = cache.exact.get(time);
@@ -9781,6 +9804,8 @@ class RigPlayer {
     if (this.pose === null) return;
     const step = dt * this.timeScale;
     if (this.paused || !(step > 0)) return;
+    this.lastStep = step;
+    if (this.easing !== null) this.advanceEase(this.easing, step);
     const tracks = this.tracks;
     if (tracks !== null) {
       const before2 = [];
@@ -9823,6 +9848,7 @@ class RigPlayer {
     this.source = frameSource(view, this.read.parsed);
     this.skinName = name;
     this.setup = null;
+    this.easing = null;
     this.clearSeekCache();
     if (this.animation !== null && (this.track !== null || this.tracks !== null)) {
       const time = this.time;
@@ -9881,7 +9907,8 @@ class RigPlayer {
       throw new Error(`cannot setSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
     const physics = setPhysicsOption("setSet", options);
-    this.activate(name === null ? [] : [this.namedSet(name)], physics);
+    const ease = setEaseOption("setSet", options);
+    this.activate(name === null ? [] : [this.namedSet(name)], physics, ease);
   }
   /**
    * Makes exactly `names` the active attachment sets (#168), together: each
@@ -9903,19 +9930,42 @@ class RigPlayer {
    * under a re-posed bone. A later `seek` replays from the start with the sets
    * then active and does not reproduce a carried switch. `setSet`, `addSet`
    * and `removeSet` take the same option.
+   *
+   * `options.ease` (#174, seconds, a finite number at or above 0) eases the
+   * bones the call re-poses instead of snapping them. Each bone whose drawn
+   * rotation the call adds, removes or changes turns from what it shows to
+   * its new local rotation along the shorter way, as
+   * `start + shortestΔ(start, end) · smoothstep(elapsed / ease)`: going on,
+   * from the clip's value at the time to the drawn local; going off, from the
+   * drawn local to the clip's value. The attachments the pose draws stay the
+   * previous ones until the frame whose `elapsed / ease` is nearest ½ (the
+   * next step predicted from the current one; a tie goes to the later frame),
+   * then become the call's; `activeSets` and `slotIdentity().sets` name the
+   * call's sets at once, while `slotIdentity().slots` follows what is drawn.
+   * On the frame the elapsed time reaches `ease` the player is in exactly the
+   * instant switch's state. The elapsed time is the player's step
+   * (`dt × timeScale`), so a paused player or a zero step holds the ease;
+   * before `play`, or when no bone's rotation changes, the switch is instant.
+   * A call during an ease eases again from the angles shown (a call without
+   * `ease` lands it at once), and `seek` or a skin change lands it at once.
+   * With `physics: 'carry'` the chains under the eased bones are carried on
+   * every eased frame, by the turn that frame's blend makes; with `'reset'`
+   * they restart once, at the call. `0` or absent is the instant switch on
+   * the same code path; anything else throws by name before anything changes.
    */
   setSets(names, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot setSets(${JSON.stringify(names)}): this model has no sets.json`);
     }
     const physics = setPhysicsOption("setSets", options);
+    const ease = setEaseOption("setSets", options);
     const sets = names.map((name) => this.namedSet(name));
     for (let i = 0; i < sets.length; i++) {
       for (let j = 0; j < i; j++) {
         if (sets[i] === sets[j]) throw new Error(`set ${JSON.stringify(sets[i].name)} is named twice in setSets`);
       }
     }
-    this.activate(sets, physics);
+    this.activate(sets, physics, ease);
   }
   /**
    * Activates `name` beside the sets already active (#168): a set already
@@ -9927,9 +9977,10 @@ class RigPlayer {
       throw new Error(`cannot addSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
     const physics = setPhysicsOption("addSet", options);
+    const ease = setEaseOption("addSet", options);
     const found = this.namedSet(name);
     if (this.activeList.includes(found)) return;
-    this.activate([...this.activeList, found], physics);
+    this.activate([...this.activeList, found], physics, ease);
   }
   /**
    * Deactivates `name`, keeping every other active set (#168). An unknown name
@@ -9940,9 +9991,10 @@ class RigPlayer {
       throw new Error(`cannot removeSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
     const physics = setPhysicsOption("removeSet", options);
+    const ease = setEaseOption("removeSet", options);
     const found = this.namedSet(name);
     if (!this.activeList.includes(found)) return;
-    this.activate(this.activeList.filter((s) => s !== found), physics);
+    this.activate(this.activeList.filter((s) => s !== found), physics, ease);
   }
   /** The declared set named `name`, or a throw naming it and the available sets. */
   namedSet(name) {
@@ -9990,16 +10042,16 @@ class RigPlayer {
   }
   /**
    * The physics under the bones a set switch re-poses (#173), before the
-   * repose step: the drawn rotations went from `before` to `after` (already
-   * `drawnPose`), and every physics constraint whose bone is one of the
+   * repose step: the `changed` bones' rotations went from what the held pose
+   * shows to what the player now applies (`drawnPose`, or an ease's next
+   * blend, #174), and every physics constraint whose bone is one of the
    * changed bones or a descendant of one is carried or reset. Nothing to do
    * before `play` (the setup pose carries no physics state) or when no
    * constraint hangs under a changed bone.
    */
-  handOverPhysics(before, after, mode) {
+  handOverPhysics(changed, mode) {
     const stepper = this.tracks ?? this.track;
     if (stepper === null || this.pose === null || this.rawPose === null) return;
-    const changed = drawnChanged(before, after);
     if (changed.size === 0) return;
     const parentOf = new Map(this.view.bones.map((b) => [b.name, b.parent]));
     const anchorOf = (bone2) => {
@@ -10079,11 +10131,112 @@ class RigPlayer {
       s.ty = c * tx + d * s.ty;
     }
   }
+  /**
+   * The composition the held pose draws: `activeSet`, except before an ease's
+   * swap (#174), when it is the composition the ease started from.
+   */
+  shownSet() {
+    const easing = this.easing;
+    return easing === null || easing.swapped ? this.activeSet : easing.fromSet;
+  }
+  /** The local an eased bone shows at the ease's current progress, given the clip's local `clip`. */
+  easedLocal(easing, from, to, clip) {
+    const start = from ?? clip;
+    const end = to ?? clip;
+    const u = easeProgress(easing);
+    const w = this.easePlant === "overshoot" ? u < 1 ? 1.2 * u : 1 : smoothstep(u);
+    return start + normaliseDegrees(end - start) * w;
+  }
+  /**
+   * The ease's part of `adjustHook` (#174): every drawn bone the ease does not
+   * turn takes its drawn local, as without an ease; every eased bone reads
+   * the clip's local (what the timelines left) and then takes its blend.
+   */
+  applyEase(easing, locals) {
+    for (const bone2 of easing.bones.keys()) easing.clip.set(bone2, locals.bone(bone2).rotation);
+    if (this.drawnPose !== null) {
+      for (const [bone2, rotation] of this.drawnPose) if (!easing.bones.has(bone2)) locals.bone(bone2).rotation = rotation;
+    }
+    for (const [bone2, { from, to }] of easing.bones) {
+      locals.bone(bone2).rotation = this.easedLocal(easing, from, to, easing.clip.get(bone2));
+    }
+  }
+  /**
+   * Starts an eased switch (#174) to the sets already made active, from what
+   * the held pose shows: an eased bone's start is the local it shows (fixed),
+   * or the clip's value for a bone that showed the clip's; its end is the new
+   * drawn local, or the clip's value for a bone whose set went. Returns false,
+   * changing nothing, when there is nothing to ease — before `play` (no step
+   * to ease over) or when no bone's rotation changes — and the call is then
+   * an instant one.
+   */
+  startEase(duration, shownBefore, drawn, physics) {
+    const stepper = this.tracks ?? this.track;
+    if (stepper === null || this.pose === null) return false;
+    const before = this.drawnPose;
+    const after = drawn === void 0 ? null : drawnLocals(this.view, drawn);
+    const previous = this.easing;
+    const candidates = drawnChanged(before, after);
+    if (previous !== null) for (const bone2 of previous.bones.keys()) candidates.add(bone2);
+    const bones = /* @__PURE__ */ new Map();
+    for (const bone2 of candidates) {
+      const to = after?.get(bone2) ?? null;
+      let from;
+      const eased = previous?.bones.get(bone2);
+      if (previous !== null && eased !== void 0) {
+        from = previous.elapsed > 0 ? this.easedLocal(previous, eased.from, eased.to, previous.clip.get(bone2)) : eased.from;
+      } else {
+        from = before?.get(bone2) ?? null;
+      }
+      if (from === to) continue;
+      bones.set(bone2, { from, to });
+    }
+    if (bones.size === 0) return false;
+    const easing = {
+      duration,
+      elapsed: 0,
+      bones,
+      clip: /* @__PURE__ */ new Map(),
+      fromSet: shownBefore,
+      swapped: false,
+      physics
+    };
+    if (this.easePlant === "swap-at-0" || this.swapsNow(0, this.lastStep / duration)) easing.swapped = true;
+    this.easing = easing;
+    this.drawnPose = after;
+    if (physics === "reset") this.handOverPhysics(new Set(bones.keys()), "reset");
+    this.reposeDrawn();
+    return true;
+  }
+  /**
+   * Whether the frame at progress `u` is the one nearest ½, the next frame
+   * being at `next`: it is when `u` reached ½ or the next one would be
+   * farther from it; a tie (within 1e-9) goes to the later frame.
+   */
+  swapsNow(u, next) {
+    if (u >= 0.5) return true;
+    return next > u && 0.5 - u < next - 0.5 - 1e-9;
+  }
+  /**
+   * One step of an eased switch (#174), before the track steps: the elapsed
+   * time advances by the step, the attachments swap when this is the frame
+   * nearest ½ (`swapsNow`, the next step predicted by this one), and the
+   * ease ends — the instant switch's state, `drawnPose` alone — on the frame
+   * it reaches its duration. With `physics: 'carry'`, the chains under the
+   * eased bones are carried by the turn this frame's blend makes, read by a
+   * trial `step(0)` at the previous time (`handOverPhysics`).
+   */
+  advanceEase(easing, step) {
+    easing.elapsed += step;
+    if (easing.elapsed >= easing.duration) this.easing = null;
+    else if (!easing.swapped && this.swapsNow(easing.elapsed / easing.duration, (easing.elapsed + step) / easing.duration)) easing.swapped = true;
+    if (easing.physics === "carry") this.handOverPhysics(new Set(easing.bones.keys()), "carry");
+  }
   /**
    * Makes `sets` (distinct) the active sets: refuses any two touching one slot
    * before changing anything, then applies their composition to the held pose.
    */
-  activate(sets, physics) {
+  activate(sets, physics, ease = 0) {
     for (let i = 0; i < sets.length; i++) {
       for (let j = 0; j < i; j++) {
         const other = this.touched(sets[j]);
@@ -10105,14 +10258,27 @@ class RigPlayer {
       }
     }
     const drawnBefore = this.activeSet?.drawn;
+    const shownBefore = this.shownSet();
     this.activeList = this.setList.filter((s) => sets.includes(s));
     this.activeSet = composeSets(this.activeList);
     this.clearSeekCache();
     const drawn = this.activeSet?.drawn;
+    if (ease > 0 && this.startEase(ease, shownBefore, drawn, physics)) return;
+    const easing = this.easing;
+    if (easing !== null) {
+      this.easing = null;
+      const posedBefore = this.drawnPose;
+      this.drawnPose = drawn === void 0 ? null : drawnLocals(this.view, drawn);
+      const changed = drawnChanged(posedBefore, this.drawnPose);
+      for (const bone2 of easing.bones.keys()) changed.add(bone2);
+      if (physics !== void 0) this.handOverPhysics(changed, physics);
+      this.reposeDrawn();
+      return;
+    }
     if (drawn !== drawnBefore && !(drawn === void 0 && drawnBefore === void 0)) {
       const posedBefore = this.drawnPose;
       this.drawnPose = drawn === void 0 ? null : drawnLocals(this.view, drawn);
-      if (physics !== void 0) this.handOverPhysics(posedBefore, this.drawnPose, physics);
+      if (physics !== void 0) this.handOverPhysics(drawnChanged(posedBefore, this.drawnPose), physics);
       this.reposeDrawn();
       return;
     }
@@ -10304,9 +10470,10 @@ class RigPlayer {
     const setupShownSlots = new Set(setupPose.shown.map((s) => s.slot));
     const rawRowBySlot = new Map(raw.slots.map((r) => [r[0], r]));
     const slots = [];
+    const shownSet = this.shownSet();
     for (let z = 0; z < pose.drawOrder.length; z++) {
       const slotName = pose.drawOrder[z];
-      if (this.activeSet !== null && hiddenBySet(slotName, this.activeSet)) {
+      if (shownSet !== null && hiddenBySet(slotName, shownSet)) {
         slots.push(Object.freeze({
           slot: slotName,
           z,
@@ -10341,7 +10508,7 @@ class RigPlayer {
         continue;
       }
       const rawRow = rawRowBySlot.get(slotName);
-      const overriddenBySet = this.activeSet !== null && slotName in this.activeSet.slots;
+      const overriddenBySet = shownSet !== null && slotName in shownSet.slots;
       const setupHadAttachment = setupShownSlots.has(slotName);
       const isTimelineNull = !overriddenBySet && (setupHadAttachment && rawRow?.[1] === null || this.isSlotKeyedNullByTimeline(slotName, raw.animationTime));
       slots.push(Object.freeze({
@@ -10406,6 +10573,7 @@ class RigPlayer {
     this.renderer.dispose();
     this.clearSeekCache();
     this.cachedIdentity = null;
+    this.easing = null;
     this.tracks = null;
     this.track = null;
     this.pose = null;