@px-petals/roku.motion-web 1.0.0 → 1.1.0

package/script/rive/host/host.js

@@ -0,0 +1,533 @@
+/**
+ * The Rive scripting host: runs one compiled script on the Luau VM the way
+ * Rive's runtime does, and gives the player what the script does (view-model
+ * writes through the adapter, drawings, a path effect's output).
+ *
+ * A compiled script's main chunk returns a factory function. The host calls
+ * it to make the script's table (`self`), sets the script's inputs on it, then
+ * drives it with `self` as the first argument:
+ *
+ * - `init(self, context)` once, returning false to refuse;
+ * - `advance(self, seconds)` each frame while it keeps returning true (a false
+ *   stops them until a view-model change or an input wakes it);
+ * - `update(self)` when an input changed or `context:markNeedsUpdate()` asked
+ *   (a request made from inside `update` is ignored, as in Rive);
+ * - `draw(self, renderer)` each frame, which the host records;
+ * - for a path effect, `update(self, path, node)` returns the new path;
+ * - for a converter, `convert(self, value)` and `reverseConvert(self, value)`;
+ * - for a listener action, `perform(self, pointerEvent)`;
+ * - for a transition condition, `evaluate(self)`;
+ * - for a layout, `measure(self)` and `resize(self, size)`.
+ */
+
+import { createLuau } from '../../luau/luau.js'
+import { LuaClosure, LuaTable, NativeFunction, Vector } from '../../luau/vm/vm.value.js'
+import { LuauError, encodeUtf8 } from '../../luau/luau.convert.js'
+import { Context } from '../context/context.js'
+import { viewModelAt } from '../context/context.viewmodel.js'
+import { commandsToContours } from '../api/draw/draw.contours.js'
+import { Path, pathFromContours } from '../api/draw/draw.path.js'
+import { Recorder, Renderer } from '../api/draw/draw.renderer.js'
+import { dataValue, readDataValue } from '../api/data/data.value.js'
+import { installGlobals } from './host.globals.js'
+import { NodeReadData } from './host.node.js'
+import { createAssets } from '../api/assets/assets.js'
+import { PointerEvent, pointerData } from '../api/pointer/pointer.event.js'
+
+/** @import { Contour } from '../api/draw/draw.contours.js' */
+/** @import { Drawing } from '../api/draw/draw.renderer.js' */
+/** @import { Scope, ViewModelAdapter } from '../context/context.viewmodel.js' */
+/** @import { NodeInfo } from './host.node.js' */
+
+/** a pointer event at the listener's origin, shared since a Vector is never mutated */
+const ORIGIN = new Vector(0, 0, 0)
+
+/**
+ * @typedef {object} HostOptions
+ * @property {import('../../luau/luau.js').Luau} [luau]  a VM to run in; default a new one
+ * @property {Uint8Array} [bytes]  the script's bytecode (see `load`)
+ * @property {ViewModelAdapter | null} [viewModel]  the view model bound to the script's node, `context:viewModel()`; null for none
+ * @property {ViewModelAdapter | null} [rootViewModel]  `context:rootViewModel()`; default the same as `viewModel`
+ * @property {ViewModelAdapter | null} [parentViewModel]  the enclosing data context's, `dataContext():parent():viewModel()`
+ * @property {Record<string, ViewModelAdapter>} [globalViewModels]  `context:globalViewModel(name)`
+ * @property {Record<string, any>} [inputs]  the script's inputs by name: numbers, booleans, strings, ARGB colour numbers, or a view-model adapter for a view-model input
+ * @property {(message: string) => void} [log]  where `print` and `context.log` write
+ * @property {(error: Error) => void} [onError]  where an error a script raises goes; default logs it
+ * @property {boolean} [strict]  rethrow a script's errors instead of reporting them
+ * @property {(drawings: Drawing[]) => void} [onDraw]  called with each frame's drawings
+ * @property {import('../api/assets/assets.js').AssetSource} [assets]  the images, fonts, audio and artboards the player has, by name; without it every name is accepted (an image of unknown size, the fallback font)
+ */
+
+/**
+ * A script's bytecode without Rive's wrapper: a script asset stores one byte
+ * (0) before the Luau version byte, and valid bytecode never starts with 0.
+ *
+ * @param   {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+export function stripWrapper(bytes) {
+  return bytes.length > 1 && bytes[0] === 0 ? bytes.subarray(1) : bytes
+}
+
+/** One script, instantiated */
+export class ScriptHost {
+  /** @param {HostOptions} [options] */
+  constructor(options) {
+    const o = options || {}
+    this.options = o
+    /** @type {string[]} */
+    this.logged = []
+    /** @type {Error[]} errors the script raised, in order */
+    this.errors = []
+    this.luau = o.luau || createLuau({ print: (text) => this.log(text) })
+    /** @type {import('../api/media/media.audio.js').AudioEvent[]} */
+    this.audioEvents = []
+    this.assets = createAssets(o.assets)
+    installGlobals(this.luau, { audio: this.audioEvents, fallback: this.assets.fallback })
+    this.recorder = new Recorder()
+    /** @type {Record<number, Vector>} where each pointer was last */
+    this.pointers = {}
+    /** @type {LuaTable | null} the script's own table */
+    this.self = null
+    /** @type {{ adapter: ViewModelAdapter, scope: Scope }[]} */
+    this.scopes = []
+    /** `update` is owed */
+    this.needsUpdate = false
+    /** `advance` is still wanted */
+    this.advancing = true
+    /** `update` is running, when `markNeedsUpdate` does nothing */
+    this.updating = false
+    this.initialized = false
+    /** false once `init` returned false or raised */
+    this.running = true
+    this.context = Context.wrap(this.contextEnv())
+    /** the DataValue and the PointerEvent reused for each protocol call, so a call allocates none of its own @type {{ in: any, event: any, eventData: any }} */
+    this.scratch = { in: null, event: null, eventData: null }
+    if (o.bytes) this.load(o.bytes)
+  }
+
+  /**
+   * @param {string} message
+   */
+  log(message) {
+    this.logged.push(message)
+    if (this.options.log) this.options.log(message)
+  }
+
+  /**
+   * What the Context stands on.
+   *
+   * @returns {import('../context/context.js').ContextEnv}
+   */
+  contextEnv() {
+    const o = this.options
+    const viewModel = o.viewModel || null
+    return {
+      scopeFor: (adapter) => this.scopeFor(adapter),
+      immediate: viewModel,
+      root: o.rootViewModel === undefined ? viewModel : o.rootViewModel,
+      parent: o.parentViewModel || null,
+      globals: o.globalViewModels || {},
+      assets: this.assets,
+      markNeedsUpdate: () => {
+        if (!this.updating) this.needsUpdate = true
+      },
+      log: (message) => this.log(message),
+    }
+  }
+
+  /**
+   * @param   {ViewModelAdapter} adapter
+   * @returns {Scope}
+   */
+  scopeFor(adapter) {
+    for (let n = 0; n < this.scopes.length; n++) if (this.scopes[n].adapter === adapter) return this.scopes[n].scope
+    /** @type {Scope} */
+    const scope = {
+      adapter,
+      props: {},
+      scopeFor: (a) => this.scopeFor(a),
+      asset: (kind, name) => (kind === 'image' ? this.assets.image(name) : kind === 'font' ? this.assets.font(name) : undefined),
+      call: (fn, args) => {
+        this.guard(() => this.luau.callRaw(fn, args))
+      },
+      wake: () => {
+        this.advancing = true
+      },
+    }
+    this.scopes.push({ adapter, scope })
+    return scope
+  }
+
+  /**
+   * Runs host work that calls into Lua, keeping a script's error out of the player.
+   *
+   * @template T
+   * @param   {() => T} work
+   * @returns {T | undefined}
+   */
+  guard(work) {
+    try {
+      return work()
+    } catch (e) {
+      if (!(e instanceof LuauError) || this.options.strict) throw e
+      this.errors.push(e)
+      if (this.options.onError) this.options.onError(e)
+      else this.log('error: ' + e.message)
+      return undefined
+    }
+  }
+
+  // Loading
+  // ■■■■■■■
+
+  /**
+   * Loads the script and makes its table. The bytes may still carry Rive's
+   * wrapper byte (see `stripWrapper`).
+   *
+   * @param   {Uint8Array} bytes
+   * @returns {this}
+   */
+  load(bytes) {
+    const module = this.luau.load(stripWrapper(bytes))
+    const returned = this.luau.callRaw(this.luau.vm.instantiate(module), [])
+    const factory = returned[0]
+    if (!(factory instanceof NativeFunction) && !(factory instanceof LuaClosure)) throw new Error("a script's main chunk must return a factory function")
+    const made = this.luau.callRaw(factory, [])[0]
+    if (!(made instanceof LuaTable)) throw new Error("a script's factory must return a table")
+    this.self = made
+    const inputs = this.options.inputs
+    if (inputs) for (const name in inputs) this.setValue(name, inputs[name])
+    return this
+  }
+
+  /**
+   * @param {string} name
+   * @param {any}    value
+   */
+  setValue(name, value) {
+    if (!this.self) throw new Error('no script is loaded')
+    this.self.set(encodeUtf8(name), this.inputValue(value))
+  }
+
+  /**
+   * @param   {any} value
+   * @returns {any}
+   */
+  inputValue(value) {
+    if (typeof value === 'string') return encodeUtf8(value)
+    if (value && typeof value === 'object' && typeof value.kind === 'string' && typeof value.name === 'string') return this.assets.input(value)
+    if (value && typeof value === 'object' && typeof value.subscribe === 'function') return viewModelAt(this.scopeFor(value), '')
+    return value === null ? undefined : value
+  }
+
+  /**
+   * Sets a script input, as the player does when it changes (an animated or
+   * data-bound input); `update` runs next.
+   *
+   * @param {string} name
+   * @param {any}    value
+   */
+  setInput(name, value) {
+    this.setValue(name, value)
+    this.needsUpdate = true
+    this.advancing = true
+  }
+
+  /**
+   * @param   {string} name
+   * @returns {any}    the method, or undefined when the script has none
+   */
+  method(name) {
+    const fn = this.self ? this.self.getStr(name) : undefined
+    return fn === undefined ? undefined : fn
+  }
+
+  /**
+   * @param   {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this.method(name) !== undefined
+  }
+
+  /**
+   * Calls a method with `self` first.
+   *
+   * @param   {string} name
+   * @param   {any[]}  args
+   * @returns {{ ok: boolean, result: any }}
+   */
+  invoke(name, args) {
+    const fn = this.method(name)
+    if (fn === undefined) return { ok: true, result: undefined }
+    let ok = false
+    /** @type {any} */
+    let result
+    this.guard(() => {
+      result = this.luau.callRaw(fn, [ this.self ].concat(args))[0]
+      ok = true
+    })
+    return { ok, result }
+  }
+
+  // Protocols
+  // ■■■■■■■■■
+
+  /**
+   * Converter scripts: `convert(self, input)` turns a view-model value into
+   * the target's. A number, string or boolean goes in by its type; a colour
+   * (an ARGB number) by `kind`.
+   *
+   * @param   {any}    value
+   * @param   {string} [kind]  `color` for a colour
+   * @returns {{ kind: string, value: any } | undefined}  what the script returned (a colour is its ARGB number); undefined when the script has no such method, failed, or returned something but a DataValue
+   */
+  convert(value, kind) {
+    return this.dataCall('convert', value, kind)
+  }
+
+  /**
+   * The same for `reverseConvert(self, input)`, which a two-way bind uses to
+   * turn the target's value back into the source's.
+   *
+   * @param   {any}    value
+   * @param   {string} [kind]
+   * @returns {{ kind: string, value: any } | undefined}
+   */
+  reverseConvert(value, kind) {
+    return this.dataCall('reverseConvert', value, kind)
+  }
+
+  /**
+   * @param   {string} name
+   * @param   {any}    value
+   * @param   {string} [kind]
+   * @returns {{ kind: string, value: any } | undefined}
+   */
+  dataCall(name, value, kind) {
+    if (!this.initialized) this.init()
+    if (!this.running || !this.has(name)) return undefined
+    this.scratch.in = dataValue(this.scratch.in, value, kind)
+    const r = this.invoke(name, [ this.scratch.in ])
+    const out = r.ok ? readDataValue(r.result) : undefined
+    return out ? { kind: out.kind, value: out.value } : undefined
+  }
+
+  /**
+   * Listener action scripts: `perform(self, pointerEvent)`.
+   *
+   * @param   {{ id?: number, x?: number, y?: number, previousX?: number, previousY?: number, type?: string, timeStamp?: number }} [event]  the pointer event, in the listener's local coordinates; none is a pointer at the origin
+   * @returns {{ ok: boolean, hit: string }}  `hit` is what the script did with the event: "" nothing, "opaque" or "translucent"
+   */
+  perform(event) {
+    if (!this.initialized) this.init()
+    if (!this.running || !this.has('perform')) return { ok: false, hit: '' }
+    const e = event || {}
+    const s = this.scratch
+    if (!s.event) {
+      s.eventData = pointerData(0, ORIGIN, ORIGIN, 'move', 0)
+      s.event = PointerEvent.wrap(s.eventData)
+    }
+    const d = s.eventData
+    d.id = e.id || 0
+    d.position = e.x || e.y ? new Vector(e.x || 0, e.y || 0, 0) : ORIGIN
+    d.previous = e.previousX === undefined ? d.position : new Vector(e.previousX, e.previousY || 0, 0)
+    d.type = e.type || 'move'
+    d.time = e.timeStamp || 0
+    d.hit = false
+    d.translucent = false
+    const r = this.invoke('perform', [ s.event ])
+    return { ok: r.ok, hit: d.hit ? (d.translucent ? 'translucent' : 'opaque') : '' }
+  }
+
+  /**
+   * Transition condition scripts: `evaluate(self)`; true lets the transition pass.
+   *
+   * @returns {boolean}  false when the script has no `evaluate` or fails
+   */
+  evaluate() {
+    if (!this.initialized) this.init()
+    if (!this.running || !this.has('evaluate')) return false
+    const r = this.invoke('evaluate', [])
+    return r.ok && r.result === true
+  }
+
+  /**
+   * Layout scripts: `measure(self)` proposes an ideal size.
+   *
+   * @returns {{ width: number, height: number } | null}  null when the script has no `measure` or returns no vector
+   */
+  measure() {
+    if (!this.initialized) this.init()
+    if (!this.running || !this.has('measure')) return null
+    const r = this.invoke('measure', [])
+    const v = r.result
+    return r.ok && v instanceof Vector ? { width: v.x, height: v.y } : null
+  }
+
+  /**
+   * Layout scripts: `resize(self, size)`, called when the layout gets its size.
+   *
+   * @param   {number}  width
+   * @param   {number}  height
+   * @returns {boolean} whether the script ran
+   */
+  resize(width, height) {
+    if (!this.initialized) this.init()
+    if (!this.running || !this.has('resize')) return false
+    return this.invoke('resize', [ new Vector(width, height, 0) ]).ok
+  }
+
+  // Lifecycle
+  // ■■■■■■■■■
+
+  /**
+   * Calls `init`. Whatever it returns but false counts as success; an error
+   * or false stops the script.
+   *
+   * @returns {boolean}
+   */
+  init() {
+    if (this.initialized) return this.running
+    this.initialized = true
+    const r = this.invoke('init', [ this.context ])
+    this.running = r.ok && r.result !== false
+    this.needsUpdate = true
+    return this.running
+  }
+
+  /**
+   * Calls `advance` while the script wants it.
+   *
+   * @param   {number} seconds
+   * @returns {boolean} whether the script wants more advances
+   */
+  advance(seconds) {
+    if (!this.running || !this.advancing || !this.has('advance')) return false
+    const r = this.invoke('advance', [ seconds ])
+    if (!r.ok) {
+      this.running = false
+      return false
+    }
+    this.advancing = r.result !== false
+    return this.advancing
+  }
+
+  /**
+   * Calls `update` if an input changed or an update was asked for.
+   *
+   * @returns {boolean} whether it ran
+   */
+  update() {
+    if (!this.running || !this.needsUpdate) return false
+    this.needsUpdate = false
+    if (!this.has('update')) return false
+    this.updating = true
+    try {
+      this.invoke('update', [])
+    } finally {
+      this.updating = false
+    }
+    return true
+  }
+
+  /**
+   * One frame: `advance`, then `update` when owed.
+   *
+   * @param   {number} seconds
+   * @returns {{ advanced: boolean, updated: boolean }}
+   */
+  frame(seconds) {
+    const advanced = this.advance(seconds)
+    return { advanced, updated: this.update() }
+  }
+
+  /**
+   * Calls `draw` and returns what it drew.
+   *
+   * @param   {Drawing[]} [into]  a list to fill (emptied first) instead of a new one, so a player that draws every frame allocates no list
+   * @returns {Drawing[]}
+   */
+  draw(into) {
+    const rec = this.recorder
+    rec.reset(into)
+    if (this.running && this.has('draw')) this.invoke('draw', [ Renderer.wrap(rec) ])
+    if (this.options.onDraw) this.options.onDraw(rec.drawings)
+    return rec.drawings
+  }
+
+  /**
+   * The audio the script started, stopped or seeked since the last call.
+   *
+   * @returns {import('../api/media/media.audio.js').AudioEvent[]}
+   */
+  audio() {
+    return this.audioEvents.splice(0, this.audioEvents.length)
+  }
+
+  /**
+   * A pointer event for the scripted node, at a point in the node's own space:
+   * calls `pointerDown`, `pointerMove`, `pointerUp` or `pointerExit` if the
+   * script has it.
+   *
+   * @param   {'down' | 'move' | 'up' | 'exit'} type
+   * @param   {number} x
+   * @param   {number} y
+   * @param   {number} [id]
+   * @param   {number} [seconds]  the event's time stamp
+   * @returns {{ hit: boolean, translucent: boolean }}  whether the script claimed it (`event:hit()`), and let it through
+   */
+  pointer(type, x, y, id, seconds) {
+    const key = id || 0
+    const at = new Vector(x, y, 0)
+    const name = 'pointer' + type.charAt(0).toUpperCase() + type.slice(1)
+    const data = pointerData(key, at, this.pointers[key] || at, name, seconds || 0)
+    if (type === 'exit') delete this.pointers[key]
+    else this.pointers[key] = at
+    if (this.running && this.has(name)) this.invoke(name, [ PointerEvent.wrap(data) ])
+    return { hit: data.hit, translucent: data.translucent }
+  }
+
+  /**
+   * Runs a path effect: `update(self, path, node)` on a path given as Lottie
+   * vertex arrays. A script without `update`, or one that fails, leaves the
+   * path as it was.
+   *
+   * @param   {Contour[]} contours
+   * @param   {NodeInfo}  [node]
+   * @returns {Contour[]}
+   */
+  effect(contours, node) {
+    if (!this.running || !this.has('update')) return contours
+    const path = pathFromContours(contours)
+    const data = NodeReadData.wrap({ info: node || {}, path })
+    this.updating = true
+    this.needsUpdate = false
+    let out
+    try {
+      out = this.invoke('update', [ path, data ])
+    } finally {
+      this.updating = false
+    }
+    const made = out.ok ? Path.unwrap(out.result) : undefined
+    return made ? commandsToContours(made.cmds) : contours
+  }
+}
+
+/**
+ * Makes a host for a script.
+ *
+ * ```js
+ * const host = createScriptHost({ bytes, viewModel: createMemoryViewModel({ score: 0 }), inputs: { speed: 2 } })
+ * host.init()
+ * host.frame(1 / 60)
+ * const drawings = host.draw()
+ * ```
+ *
+ * @param   {HostOptions} [options]
+ * @returns {ScriptHost}
+ */
+export function createScriptHost(options) {
+  return new ScriptHost(options)
+}

package/script/rive/host/host.node.js

@@ -0,0 +1,45 @@
+/**
+ * `NodeReadData`: the node a path effect belongs to, as the effect's `update`
+ * sees it (its transform, and the paint of the stroke or fill the effect is
+ * on). The player describes the node in plain numbers.
+ */
+
+import { Vector } from '../../luau/vm/vm.value.js'
+import { defineType } from '../api/api.type.js'
+import { Mat2D } from '../api/math/math.mat2d.js'
+import { Paint, defaultPaint } from '../api/draw/draw.paint.js'
+
+/**
+ * @typedef {object} NodeInfo
+ * @property {number}   [x]
+ * @property {number}   [y]
+ * @property {number}   [rotation]  radians
+ * @property {number}   [scaleX]
+ * @property {number}   [scaleY]
+ * @property {number[]} [worldTransform]  [xx, xy, yx, yy, tx, ty]
+ * @property {import('../api/draw/draw.paint.js').PaintData} [paint]  the stroke or fill the effect is on
+ */
+
+/**
+ * @typedef {object} NodeData
+ * @property {NodeInfo} info
+ * @property {any}      path  the PathData wrapper the effect is given
+ */
+
+export const NodeReadData = defineType('NodeReadData', {
+  fields: {
+    x: { get: (n) => n.info.x || 0 },
+    y: { get: (n) => n.info.y || 0 },
+    rotation: { get: (n) => n.info.rotation || 0 },
+    scaleX: { get: (n) => (n.info.scaleX === undefined ? 1 : n.info.scaleX) },
+    scaleY: { get: (n) => (n.info.scaleY === undefined ? 1 : n.info.scaleY) },
+    position: { get: (n) => new Vector(n.info.x || 0, n.info.y || 0, 0) },
+    scale: { get: (n) => new Vector(n.info.scaleX === undefined ? 1 : n.info.scaleX, n.info.scaleY === undefined ? 1 : n.info.scaleY, 0) },
+    worldTransform: { get: (n) => Mat2D.wrap(n.info.worldTransform ? n.info.worldTransform.slice() : [ 1, 0, 0, 1, 0, 0 ]) },
+    paint: { get: (n) => Paint.wrap(n.info.paint || defaultPaint()) },
+  },
+  methods: {
+    asPath: (n) => n.path,
+    asPaint: (n) => Paint.wrap(n.info.paint || defaultPaint()),
+  },
+})

package/script/rive/rive.js

@@ -0,0 +1,23 @@
+/**
+ * The Rive scripting host: runs the Luau scripts a Rive file carries (node,
+ * drawable and path-effect scripts) on the Luau VM beside it, behind an API
+ * a player implements for its view model. See `rive.md`.
+ *
+ * ```js
+ * import { createScriptHost, createMemoryViewModel } from '@px-petals/roku.motion-web/script/rive/rive.js'
+ *
+ * const host = createScriptHost({ bytes, viewModel: createMemoryViewModel({ score: 0 }), inputs: { speed: 2 } })
+ * host.init()
+ * host.frame(1 / 60)
+ * const drawings = host.draw()
+ * ```
+ */
+
+export { ScriptHost, createScriptHost, stripWrapper } from './host/host.js'
+export { createMemoryViewModel } from './context/context.memory.js'
+export { commandsToContours, contoursToCommands, transformContours } from './api/draw/draw.contours.js'
+
+/** @typedef {import('./host/host.js').HostOptions} HostOptions */
+/** @typedef {import('./context/context.viewmodel.js').ViewModelAdapter} ViewModelAdapter */
+/** @typedef {import('./api/draw/draw.renderer.js').Drawing} Drawing */
+/** @typedef {import('./api/draw/draw.contours.js').Contour} Contour */