@px-petals/roku.motion-web 0.0.0-stage → 1.0.0

package/mixer/mixer.stage.js

@@ -0,0 +1,431 @@
+/**
+ * The stage: what is playing, per layer, as poses for the mixer. It knows no
+ * state machine, only what the machine tells it: a layer enters a state,
+ * with a cross-fade or without. It keeps each state's clock and says, for a
+ * set of input values, which animations show at what time and weight.
+ *
+ * - A layer holds a list of runs, oldest first. A run is a state being
+ * played. Entering a state with a cross-fade adds a run whose weight rises
+ * from 0 to 1 over the fade, while the outgoing run plays on; entering one
+ * without replaces them. A run that reaches full weight drops the runs
+ * before it, and a run entered during a fade stacks on the last, so a
+ * cross-fade interrupted by another continues from where it was.
+ * - A blend state is a run with several animations: a 1D blend weights the
+ * two animations either side of its input's value, a direct blend weights
+ * each by its own input (0 to 100).
+ * - A state's `speed` scales its clock, and its `mode` plays its timelines
+ * backwards (`Reverse`, `ReverseBounce`). A ping-pong timeline is already
+ * written out there and back, so `Bounce` plays it forward.
+ * - Layers apply in order, so a later layer overrides what it keys.
+ */
+
+import { convertValue } from '../motion/motion.convert.js'
+
+/** @import { Pose } from './mixer.js' */
+
+/** Runs one layer keeps: an endless chain of interrupted fades is cut here */
+const MAX_RUNS = 4
+
+/**
+ * One state being played.
+ * @typedef {object} Run
+ * @property {any}             state
+ * @property {number}          time     seconds since it was entered, unwrapped
+ * @property {number}          ramp     its weight, 0 to 1
+ * @property {number[] | null} ease     the curve the ramp follows from `fade`'s share of `fadeFor`: a cubic's `[x1, y1, x2, y2]`; null for linear
+ * @property {number}          fade     seconds the ramp has taken
+ * @property {number}          fadeFor  seconds the ramp takes
+ * @property {boolean}         finished a state that does not loop has reached its end
+ * @property {number}          from     where the last step began, in seconds of the state's clock; -1 before the first, so frame 0 sounds
+ */
+
+/**
+ * @param {Record<string, { frames: number, fps: number }>} animations a bundle's animations
+ */
+export function createStage(animations) {
+  /** @type {{ runs: Run[] }[]} */
+  let layers = []
+  let loopsAll = false
+  let frames = 0
+
+  /**
+   * An animation's length in seconds.
+   * @param {string} id
+   */
+  function lengthOf(id) {
+    const entry = animations[id]
+    return entry && entry.fps > 0 ? entry.frames / entry.fps : 0
+  }
+
+  /**
+   * A state's timeline: its animation's, or a blend's longest.
+   * @param {any} state
+   */
+  function stateLength(state) {
+    if (!state.blend) return lengthOf(state.animation)
+    let longest = 0
+    for (let n = 0; n < state.blend.animations.length; n++) longest = Math.max(longest, lengthOf(state.blend.animations[n].animation))
+    return longest
+  }
+
+  /**
+   * A state loops when it says so, or the host asked for every state to.
+   * @param {any} state
+   */
+  function loops(state) {
+    return loopsAll || state.loop === true
+  }
+
+  /**
+   * @param {number}   layer
+   * @param {any}      state  a machine state: an animation, or a blend of several
+   * @param {number}   fadeMs how long the layer's current state fades into it
+   * @param {number[]} [ease] the fade's cubic curve; linear without
+   */
+  function enter(layer, state, fadeMs, ease) {
+    if (!layers[layer]) layers[layer] = { runs: [] }
+    const target = layers[layer]
+
+    /** @type {Run} */
+    const run = { state, time: 0, ramp: 1, ease: ease && ease.length === 4 ? ease : null, fade: 0, fadeFor: 0, finished: false, from: -1 }
+    if (fadeMs > 0 && target.runs.length) {
+      run.ramp = 0
+      run.fadeFor = fadeMs / 1000
+      target.runs.push(run)
+      if (target.runs.length > MAX_RUNS) target.runs.shift()
+    } else {
+      target.runs = [ run ]
+    }
+  }
+
+  /**
+   * Plays time forward.
+   *
+   * @param   {number}   seconds
+   * @returns {number[]}         the layers whose state, which does not loop, reached its end
+   */
+  function advance(seconds) {
+    frames += 1
+    /** @type {number[]} */
+    const done = []
+    for (let n = 0; n < layers.length; n++) {
+      const layer = layers[n]
+      if (!layer) continue
+
+      for (let r = 0; r < layer.runs.length; r++) {
+        const run = layer.runs[r]
+        run.from = run.time === 0 && run.from === -1 ? -1 : run.time
+        run.time += seconds * speedOf(run.state)
+        if (run.ramp < 1) {
+          run.fade += seconds
+          run.ramp = run.fadeFor > 0 ? eased(Math.min(1, run.fade / run.fadeFor), run.ease) : 1
+        }
+      }
+
+      // the newest run at full weight is all that shows: the ones before it go
+      for (let r = layer.runs.length - 1; r > 0; r--) {
+        if (layer.runs[r].ramp >= 1) {
+          layer.runs = layer.runs.slice(r)
+          break
+        }
+      }
+
+      const newest = layer.runs[layer.runs.length - 1]
+      if (!newest.finished && !loops(newest.state) && newest.time >= stateLength(newest.state)) {
+        newest.finished = true
+        done.push(n)
+      }
+    }
+    return done
+  }
+
+  /**
+   * How fast a state plays its timeline, as its `speed` says (1 without).
+   * @param {any} state
+   */
+  function speedOf(state) {
+    return typeof state.speed === 'number' && state.speed > 0 ? state.speed : 1
+  }
+
+  /**
+   * An animation's time at a run's time: wrapped if it loops, held a frame
+   * before its end if it doesn't (the last frame, as the plain player holds it).
+   *
+   * @param   {number}  time
+   * @param   {string}  id
+   * @param   {boolean} isLooping
+   * @param   {string}  [mode]    the state's `Reverse` or `ReverseBounce`; forward without
+   * @returns {number}
+   */
+  function timeIn(time, id, isLooping, mode) {
+    const length = lengthOf(id)
+    if (length <= 0) return 0
+    // a ping-pong timeline is written out forward then back, so bouncing is playing it through, and bouncing in reverse is playing it backwards
+    if (mode === 'Reverse' || mode === 'ReverseBounce') return isLooping ? length - (time % length) : Math.max(0, length - time)
+    if (isLooping) return time % length
+    const entry = animations[id]
+    return time < length ? time : Math.max(0, length - 1 / entry.fps)
+  }
+
+  /**
+   * What shows now, in the order the mixer applies it.
+   *
+   * @param   {Record<string, any>} values the machine's inputs, which blends read
+   * @returns {Pose[]}
+   */
+  function poses(values) {
+    /** @type {Pose[]} */
+    const result = []
+    for (let n = 0; n < layers.length; n++) {
+      const layer = layers[n]
+      if (!layer) continue
+      for (let r = 0; r < layer.runs.length; r++) {
+        const run = layer.runs[r]
+        if (run.state.blend) addBlend(result, run, values)
+        else result.push({ animation: run.state.animation, time: timeIn(run.time, run.state.animation, loops(run.state), run.state.mode), weight: run.ramp })
+      }
+    }
+    return result
+  }
+
+  /**
+   * @param {Pose[]}              result
+   * @param {Run}                 run
+   * @param {Record<string, any>} values
+   */
+  function addBlend(result, run, values) {
+    const blend = run.state.blend
+    const weights = blend.type === 'Direct' ? directWeights(blend, values) : oneDimensionWeights(blend, values)
+    for (let n = 0; n < weights.length; n++) {
+      const entry = blend.animations[weights[n].index]
+      const weight = weights[n].weight * run.ramp
+      if (weight <= 0) continue
+      result.push({ animation: entry.animation, time: timeIn(run.time, entry.animation, loopsAll || entry.loop === true, run.state.mode), weight })
+    }
+  }
+
+  /**
+   * The stretch of each playing animation's own timeline the last step passed
+   * over, in seconds, for its audio cues: more than one where it looped, and
+   * where a state plays backwards, the stretch of the timeline as it is laid out.
+   *
+   * @param   {Record<string, any>}                               values
+   * @returns {{ animation: string, from: number, to: number }[]}
+   */
+  function sweeps(values) {
+    /** @type {{ animation: string, from: number, to: number }[]} */
+    const result = []
+    for (let n = 0; n < layers.length; n++) {
+      const layer = layers[n]
+      if (!layer) continue
+      for (let r = 0; r < layer.runs.length; r++) {
+        const run = layer.runs[r]
+        const state = run.state
+        /** @type {{ id: string, isLooping: boolean }[]} */
+        const shown = []
+        if (!state.blend) shown.push({ id: state.animation, isLooping: loops(state) })
+        else {
+          const weights = state.blend.type === 'Direct' ? directWeights(state.blend, values) : oneDimensionWeights(state.blend, values)
+          for (let w = 0; w < weights.length; w++) {
+            const entry = state.blend.animations[weights[w].index]
+            if (weights[w].weight * run.ramp > 0) shown.push({ id: entry.animation, isLooping: loopsAll || entry.loop === true })
+          }
+        }
+        for (let s = 0; s < shown.length; s++) {
+          const length = lengthOf(shown[s].id)
+          const parts = segments(run.from, run.time, length, shown[s].isLooping)
+          for (let p = 0; p < parts.length; p++) {
+            const isReversed = state.mode === 'Reverse' || state.mode === 'ReverseBounce'
+            result.push(isReversed ? { animation: shown[s].id, from: length - parts[p][1], to: length - parts[p][0] } : { animation: shown[s].id, from: parts[p][0], to: parts[p][1] })
+          }
+        }
+      }
+    }
+    return result
+  }
+
+  /** The newest run of the first layer: what text overlays follow. */
+  function lead() {
+    const layer = layers[0]
+    if (!layer || !layer.runs.length) return null
+    const run = layer.runs[layer.runs.length - 1]
+    if (!run.state.blend) return { animation: run.state.animation, time: timeIn(run.time, run.state.animation, loops(run.state), run.state.mode) }
+    const first = run.state.blend.animations[0]
+    return first ? { animation: first.animation, time: timeIn(run.time, first.animation, loopsAll || first.loop === true, run.state.mode) } : null
+  }
+
+  return {
+    enter,
+    advance,
+    poses,
+    lead,
+    sweeps,
+
+    /** @returns {number} how many times time has moved on: the mixer's frame */
+    get frame() {
+      return frames
+    },
+
+    /**
+     * @param   {number} layer
+     * @returns {number}       ms the layer's current state has played, unwrapped
+     */
+    elapsedMs(layer) {
+      const target = layers[layer]
+      return target && target.runs.length ? target.runs[target.runs.length - 1].time * 1000 : 0
+    },
+
+    /** Whether nothing moves: every state has run out, and no fade is left. */
+    isIdle() {
+      for (let n = 0; n < layers.length; n++) {
+        const layer = layers[n]
+        if (!layer) continue
+        const newest = layer.runs[layer.runs.length - 1]
+        if (layer.runs.length > 1 || !newest.finished) return false
+      }
+      return true
+    },
+
+    /** Starts every layer's current state over, fades done. */
+    rewind() {
+      for (let n = 0; n < layers.length; n++) {
+        const layer = layers[n]
+        if (!layer || !layer.runs.length) continue
+        const newest = layer.runs[layer.runs.length - 1]
+        layer.runs = [ { state: newest.state, time: 0, ramp: 1, ease: null, fade: 0, fadeFor: 0, finished: false, from: -1 } ]
+      }
+    },
+
+    /** @param {boolean} on every state loops, as the `loop` control asks */
+    setLoops(on) {
+      loopsAll = on
+    },
+
+    /** Forgets every layer. */
+    clear() {
+      layers = []
+    },
+  }
+}
+
+/**
+ * The stretches of a timeline that a step from `from` to `to` (a state's
+ * unwrapped clock) passes over: one, or one per time it wrapped, each after
+ * the first from before frame 0 so that frame sounds again. A timeline that
+ * does not loop stops at its end.
+ *
+ * @param   {number}             from
+ * @param   {number}             to
+ * @param   {number}             length    the timeline's, in seconds
+ * @param   {boolean}            isLooping
+ * @returns {[number, number][]}
+ */
+export function segments(from, to, length, isLooping) {
+  if (length <= 0 || to <= from) return []
+  if (!isLooping) return from < length ? [ [ from, Math.min(to, length) ] ] : []
+
+  /** @type {[number, number][]} */
+  const parts = []
+  const first = Math.floor(Math.max(from, 0) / length)
+  let start = from
+  for (let wrap = first; wrap < first + 8; wrap++) {
+    const base = wrap * length
+    parts.push([ start < 0 ? start : start - base, Math.min(to, base + length) - base ])
+    if (to <= base + length) break
+    start = -1
+  }
+  return parts
+}
+
+/**
+ * How far a cross-fade is along its curve: a cubic Bezier from (0, 0) to
+ * (1, 1) with control points (x1, y1) and (x2, y2), read at time `t`, as
+ * Rive's cubic interpolator reads it. Without a curve, `t` itself.
+ *
+ * @param   {number}        t     0 to 1, how much of the fade's time has passed
+ * @param   {number[]|null} curve [x1, y1, x2, y2]
+ * @returns {number}
+ */
+export function eased(t, curve) {
+  if (!curve || t <= 0 || t >= 1) return t
+  const x1 = curve[0]
+  const x2 = curve[2]
+  // solve x(s) = t for the curve's parameter s, by bisection: x is rising for the control points a designer can draw
+  let low = 0
+  let high = 1
+  let s = t
+  for (let n = 0; n < 24; n++) {
+    s = (low + high) / 2
+    const x = bezier(s, x1, x2)
+    if (x < t) low = s
+    else high = s
+  }
+  return bezier(s, curve[1], curve[3])
+}
+
+/**
+ * One axis of a cubic Bezier from 0 to 1.
+ *
+ * @param {number} s
+ * @param {number} p1
+ * @param {number} p2
+ */
+function bezier(s, p1, p2) {
+  const u = 1 - s
+  return 3 * u * u * s * p1 + 3 * u * s * s * p2 + s * s * s
+}
+
+/**
+ * A 1D blend: the animation at the input's value, or the two either side of
+ * it, weighted by how far along it is (the first by what is left, as Rive
+ * applies them; they lerp onto what the property held, so the pair settles
+ * a little off a plain average). A value outside the range
+ * plays the animation at that end.
+ *
+ * @param   {any}                                 blend
+ * @param   {Record<string, any>}                 values
+ * @returns {{ index: number, weight: number }[]}
+ */
+export function oneDimensionWeights(blend, values) {
+  const raw = Number(convertValue(blend.convert, values[blend.input]))
+  const x = raw === raw ? raw : 0
+
+  // by value, as the animations were authored: the order may not be sorted
+  const order = []
+  for (let n = 0; n < blend.animations.length; n++) order.push(n)
+  order.sort((a, b) => blend.animations[a].value - blend.animations[b].value)
+  if (!order.length) return []
+
+  const first = order[0]
+  const last = order[order.length - 1]
+  if (x <= blend.animations[first].value) return [ { index: first, weight: 1 } ]
+  if (x >= blend.animations[last].value) return [ { index: last, weight: 1 } ]
+
+  for (let n = 0; n < order.length - 1; n++) {
+    const from = blend.animations[order[n]]
+    const to = blend.animations[order[n + 1]]
+    if (x > to.value) continue
+    const span = to.value - from.value
+    return [ { index: order[n], weight: 1 - (span > 0 ? (x - from.value) / span : 1) }, { index: order[n + 1], weight: span > 0 ? (x - from.value) / span : 1 } ]
+  }
+  return [ { index: last, weight: 1 } ]
+}
+
+/**
+ * A direct blend: each animation weighted by its own input, 0 to 100, or by
+ * the fixed mix the file gives it.
+ *
+ * @param   {any}                                 blend
+ * @param   {Record<string, any>}                 values
+ * @returns {{ index: number, weight: number }[]}
+ */
+export function directWeights(blend, values) {
+  const weights = []
+  for (let n = 0; n < blend.animations.length; n++) {
+    const entry = blend.animations[n]
+    const raw = typeof entry.input === 'string' ? Number(convertValue(entry.convert, values[entry.input])) : entry.mix === undefined ? 100 : entry.mix
+    const percent = raw === raw ? raw : 0
+    weights.push({ index: n, weight: Math.min(1, Math.max(0, percent / 100)) })
+  }
+  return weights
+}