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

package/script/rive/api/assets/assets.js

@@ -0,0 +1,72 @@
+/**
+ * The assets a script reaches by name (`context:image`, `font`, `audio`, an
+ * image or font view-model property, an artboard input). The player says what
+ * it has through `HostOptions.assets`; without that option every name is
+ * accepted, as an asset of unknown size and the fallback font, so a script
+ * still runs and the drawings still name what it used. With it, a name the
+ * player does not know is nil, as in Rive.
+ */
+
+import { artboardHandle } from '../artboard/artboard.js'
+import { AudioSource } from '../media/media.audio.js'
+import { Image } from '../media/media.image.js'
+import { Font, completeFont } from '../text/text.font.js'
+
+/**
+ * @typedef {object} AssetSource
+ * @property {(name: string) => ({ width: number, height: number } | undefined)} [image]
+ * @property {(name: string) => (import('../text/text.font.js').FontInfo | undefined)} [font]
+ * @property {(name: string) => ({ duration: number } | undefined)} [audio]
+ * @property {(name: string) => ({ width: number, height: number } | undefined)} [artboard]
+ */
+
+/**
+ * @param   {AssetSource | undefined} source
+ * @returns {{ image: (name: string) => any, font: (name: string) => any, audio: (name: string) => any, artboard: (name: string) => any, fallback: () => any, input: (value: any) => any }}
+ */
+export function createAssets(source) {
+  /** @type {Record<string, any>} */
+  const made = {}
+  /**
+   * @param {string} kind
+   * @param {string} name
+   * @param {() => any} make
+   */
+  const once = (kind, name, make) => {
+    const key = kind + ':' + name
+    if (!(key in made)) made[key] = make()
+    return made[key]
+  }
+  const fallbackFont = completeFont({ name: '' })
+  /** @type {any} */
+  const api = {
+    image: (/** @type {string} */ name) => once('image', name, () => {
+      const info = source ? (source.image ? source.image(name) : undefined) : { width: 0, height: 0 }
+      return info ? Image.wrap({ name, width: info.width, height: info.height }) : undefined
+    }),
+    font: (/** @type {string} */ name) => once('font', name, () => {
+      const info = source ? (source.font ? source.font(name) : undefined) : completeFont({ name })
+      return info ? Font.wrap(completeFont(info)) : undefined
+    }),
+    audio: (/** @type {string} */ name) => once('audio', name, () => {
+      const info = source ? (source.audio ? source.audio(name) : undefined) : { duration: 0 }
+      return info ? AudioSource.wrap({ name, duration: info.duration }) : undefined
+    }),
+    artboard: (/** @type {string} */ name) => once('artboard', name, () => {
+      const info = source ? (source.artboard ? source.artboard(name) : undefined) : { width: 0, height: 0 }
+      return info ? artboardHandle(name, info.width, info.height) : undefined
+    }),
+    fallback: () => fallbackFont,
+    /**
+     * An input value that names an asset, `{ kind: 'image' | 'font' | 'audio' | 'artboard', name }`, as the Lua value the script gets.
+     *
+     * @param {any} v
+     */
+    input(v) {
+      if (!v || typeof v !== 'object' || typeof v.kind !== 'string' || typeof v.name !== 'string') return v
+      return v.kind === 'image' ? api.image(v.name) : v.kind === 'font' ? api.font(v.name) : v.kind === 'audio' ? api.audio(v.name) : v.kind === 'artboard' ? api.artboard(v.name) : v
+    },
+  }
+  return api
+}
+

package/script/rive/api/data/data.value.js

@@ -0,0 +1,99 @@
+/**
+ * The values the protocols beyond nodes pass to a script: `DataValue` (what a
+ * converter script converts), `PointerEvent` (what a listener action script
+ * performs on) and `Vec2D` (what a layout script measures and is resized to,
+ * the same value as `Vector`).
+ */
+
+import { LuaTable, NativeFunction } from '../../../luau/vm/vm.value.js'
+import { encodeUtf8 } from '../../../luau/luau.convert.js'
+import { badArg, defineType, num, text } from '../api.type.js'
+
+/** The kinds of DataValue, by the constructor that makes them */
+export const KINDS = [ 'number', 'string', 'boolean', 'color' ]
+
+/** What each kind holds before a script sets it */
+const EMPTY_VALUES = /** @type {Record<string, any>} */ ({ number: 0, string: '', boolean: false, color: 0 })
+
+/**
+ * @typedef {object} DataValueData
+ * @property {'number' | 'string' | 'boolean' | 'color'} kind
+ * @property {any} value  JS text for a string; a colour is its ARGB number
+ */
+
+export const DataValue = defineType('DataValue', {
+  fields: {
+    value: {
+      get: (d) => (d.kind === 'string' ? encodeUtf8(d.value) : d.value),
+      set: (d, v) => {
+        if (d.kind === 'number' || d.kind === 'color') d.value = num([ v ], 0, 'value')
+        else if (d.kind === 'string') d.value = text([ v ], 0, 'value')
+        else if (typeof v === 'boolean') d.value = v
+        else throw badArg(0, 'value', 'boolean', [ v ])
+      },
+    },
+  },
+  methods: {
+    isNumber: (d) => d.kind === 'number',
+    isString: (d) => d.kind === 'string',
+    isBoolean: (d) => d.kind === 'boolean',
+    isColor: (d) => d.kind === 'color',
+  },
+})
+
+/**
+ * The DataValue kind a JS value is, when the player does not say.
+ *
+ * @param   {any} value
+ * @returns {DataValueData['kind']}
+ */
+export function kindOf(value) {
+  if (typeof value === 'string') return 'string'
+  if (typeof value === 'boolean') return 'boolean'
+  return 'number'
+}
+
+/**
+ * Fills a DataValue wrapper (or makes one) with a JS value.
+ *
+ * @param   {any}    wrapper  an earlier wrapper to reuse, or undefined
+ * @param   {any}    value
+ * @param   {string} [kind]   `color` for an ARGB number; default by the value's type
+ * @returns {any}
+ */
+export function dataValue(wrapper, value, kind) {
+  const k = kind || kindOf(value)
+  if (wrapper) {
+    wrapper.host.kind = k
+    wrapper.host.value = value
+    return wrapper
+  }
+  return DataValue.wrap({ kind: k, value })
+}
+
+/**
+ * @param   {any} lua  a value a script returned
+ * @returns {DataValueData | undefined}  undefined when it is not a DataValue
+ */
+export function readDataValue(lua) {
+  return DataValue.unwrap(lua)
+}
+
+/**
+ * Installs `DataValue` and `Vec2D`; `PointerEvent` is the pointer cluster's.
+ *
+ * @param {import('../../../luau/vm/vm.js').VM} vm
+ */
+export function installData(vm) {
+  const values = new LuaTable()
+  for (const kind of KINDS) {
+    values.set(kind, new NativeFunction('DataValue.' + kind, function () {
+      return DataValue.wrap({ kind, value: EMPTY_VALUES[kind] })
+    }))
+  }
+  vm.globals.set('DataValue', values)
+
+
+  // a Vec2D is the Vector a script already has
+  vm.globals.set('Vec2D', vm.globals.get('Vector'))
+}

package/script/rive/api/draw/draw.contours.js

@@ -0,0 +1,163 @@
+/**
+ * Paths as drawing commands and as Lottie vertex arrays. A command is
+ * `{ t, p }`: `t` one of `moveTo`, `lineTo`, `quadTo`, `cubicTo`, `close` and
+ * `p` its points flattened (`[x, y]`, `[cx, cy, x, y]`, `[c1x, c1y, c2x, c2y, x, y]`).
+ * A contour is Lottie's shape value: `v` vertices, `i` and `o` the in and out
+ * handles *relative to their vertex*, and `c` whether it closes.
+ */
+
+/**
+ * @typedef {object} Command
+ * @property {'moveTo' | 'lineTo' | 'quadTo' | 'cubicTo' | 'close'} t
+ * @property {number[]} p
+ */
+
+/**
+ * @typedef {object} Contour
+ * @property {number[][]} v
+ * @property {number[][]} i
+ * @property {number[][]} o
+ * @property {boolean}    c
+ */
+
+/** How many numbers each command carries */
+export const POINTS = { moveTo: 2, lineTo: 2, quadTo: 4, cubicTo: 6, close: 0 }
+
+/** A closing vertex this close to the first is the same vertex */
+const SAME = 1e-9
+
+/**
+ * @param   {Command[]}  cmds
+ * @param   {number[]}   [m]  a matrix to apply, [xx, xy, yx, yy, tx, ty]
+ * @returns {Contour[]}
+ */
+export function commandsToContours(cmds, m) {
+  /** @type {Contour[]} */
+  const out = []
+  /** @type {{ cur: Contour | null }} the contour being built */
+  const st = { cur: null }
+  let lx = 0
+  let ly = 0
+  let sx = 0
+  let sy = 0
+
+  /** @returns {Contour} */
+  const begin = () => {
+    const c = { v: [ [ lx, ly ] ], i: [ [ 0, 0 ] ], o: [ [ 0, 0 ] ], c: false }
+    st.cur = c
+    return c
+  }
+  const finish = () => {
+    if (st.cur && st.cur.v.length > 1) out.push(st.cur)
+    st.cur = null
+  }
+  /**
+   * @param {number} c1x
+   * @param {number} c1y
+   * @param {number} c2x
+   * @param {number} c2y
+   * @param {number} x
+   * @param {number} y
+   */
+  const curve = (c1x, c1y, c2x, c2y, x, y) => {
+    const c = st.cur || begin()
+    const last = c.v.length - 1
+    c.o[last] = [ c1x - c.v[last][0], c1y - c.v[last][1] ]
+    c.v.push([ x, y ])
+    c.i.push([ c2x - x, c2y - y ])
+    c.o.push([ 0, 0 ])
+    lx = x
+    ly = y
+  }
+
+  for (let n = 0; n < cmds.length; n++) {
+    const p = cmds[n].p
+    switch (cmds[n].t) {
+      case 'moveTo':
+        finish()
+        lx = sx = p[0]
+        ly = sy = p[1]
+        begin()
+        break
+      case 'lineTo': {
+        const c = st.cur || begin()
+        c.v.push([ p[0], p[1] ])
+        c.i.push([ 0, 0 ])
+        c.o.push([ 0, 0 ])
+        lx = p[0]
+        ly = p[1]
+        break
+      }
+      case 'quadTo':
+        curve(lx + (2 / 3) * (p[0] - lx), ly + (2 / 3) * (p[1] - ly), p[2] + (2 / 3) * (p[0] - p[2]), p[3] + (2 / 3) * (p[1] - p[3]), p[2], p[3])
+        break
+      case 'cubicTo':
+        curve(p[0], p[1], p[2], p[3], p[4], p[5])
+        break
+      default: {
+        // close
+        const c = st.cur
+        if (c) {
+          c.c = true
+          const last = c.v.length - 1
+          if (last > 0 && Math.abs(c.v[last][0] - c.v[0][0]) < SAME && Math.abs(c.v[last][1] - c.v[0][1]) < SAME) {
+            c.i[0] = c.i[last]
+            c.v.pop()
+            c.i.pop()
+            c.o.pop()
+          }
+          finish()
+        }
+        lx = sx
+        ly = sy
+        break
+      }
+    }
+  }
+  finish()
+  return m ? transformContours(out, m) : out
+}
+
+/**
+ * @param   {Contour[]} contours
+ * @param   {number[]}  m
+ * @returns {Contour[]} the contours under the matrix; handles are vectors, so the translation does not touch them
+ */
+export function transformContours(contours, m) {
+  return contours.map(function (c) {
+    return {
+      v: c.v.map((pt) => [ m[0] * pt[0] + m[2] * pt[1] + m[4], m[1] * pt[0] + m[3] * pt[1] + m[5] ]),
+      i: c.i.map((pt) => [ m[0] * pt[0] + m[2] * pt[1], m[1] * pt[0] + m[3] * pt[1] ]),
+      o: c.o.map((pt) => [ m[0] * pt[0] + m[2] * pt[1], m[1] * pt[0] + m[3] * pt[1] ]),
+      c: c.c,
+    }
+  })
+}
+
+/**
+ * @param   {Contour[]} contours
+ * @returns {Command[]}
+ */
+export function contoursToCommands(contours) {
+  /** @type {Command[]} */
+  const cmds = []
+  for (let n = 0; n < contours.length; n++) {
+    const c = contours[n]
+    if (c.v.length === 0) continue
+    cmds.push({ t: 'moveTo', p: [ c.v[0][0], c.v[0][1] ] })
+    const count = c.c ? c.v.length : c.v.length - 1
+    for (let k = 0; k < count; k++) {
+      const a = k
+      const b = (k + 1) % c.v.length
+      const o = c.o[a] || [ 0, 0 ]
+      const i = c.i[b] || [ 0, 0 ]
+      if (o[0] === 0 && o[1] === 0 && i[0] === 0 && i[1] === 0) {
+        if (b !== 0) cmds.push({ t: 'lineTo', p: [ c.v[b][0], c.v[b][1] ] })
+      } else {
+        cmds.push({ t: 'cubicTo', p: [ c.v[a][0] + o[0], c.v[a][1] + o[1], c.v[b][0] + i[0], c.v[b][1] + i[1], c.v[b][0], c.v[b][1] ] })
+      }
+    }
+    if (c.c) cmds.push({ t: 'close', p: [] })
+  }
+  return cmds
+}

package/script/rive/api/draw/draw.measure.js

@@ -0,0 +1,196 @@
+/**
+ * Measuring paths: `path:measure()` (all contours as one length) and
+ * `path:contours()` (one `ContourMeasure` per contour, chained by `next`).
+ * Curves are measured as polylines of a fixed number of pieces per curve,
+ * which is exact for lines and within a hair for the curves a script draws.
+ */
+
+import { Vector, fail } from '../../../luau/vm/vm.value.js'
+import { defineType, num } from '../api.type.js'
+
+/** @import { Command, Contour } from './draw.contours.js' */
+
+/** Pieces a cubic segment is measured in */
+const PIECES = 24
+
+/**
+ * @typedef {object} Poly
+ * @property {number[][]} pts   the polyline's points
+ * @property {number[]}   cum   the distance along it to each point
+ * @property {number}     length
+ * @property {boolean}    closed
+ */
+
+/**
+ * @param   {Contour} c
+ * @returns {Poly}
+ */
+export function flatten(c) {
+  /** @type {number[][]} */
+  const pts = [ c.v[0] ]
+  const count = c.c ? c.v.length : c.v.length - 1
+  for (let k = 0; k < count; k++) {
+    const b = (k + 1) % c.v.length
+    const p0 = c.v[k]
+    const p3 = c.v[b]
+    const p1 = [ p0[0] + c.o[k][0], p0[1] + c.o[k][1] ]
+    const p2 = [ p3[0] + c.i[b][0], p3[1] + c.i[b][1] ]
+    const straight = c.o[k][0] === 0 && c.o[k][1] === 0 && c.i[b][0] === 0 && c.i[b][1] === 0
+    if (straight) {
+      pts.push(p3)
+      continue
+    }
+    for (let s = 1; s <= PIECES; s++) {
+      const t = s / PIECES
+      const u = 1 - t
+      pts.push([
+        u * u * u * p0[0] + 3 * u * u * t * p1[0] + 3 * u * t * t * p2[0] + t * t * t * p3[0],
+        u * u * u * p0[1] + 3 * u * u * t * p1[1] + 3 * u * t * t * p2[1] + t * t * t * p3[1],
+      ])
+    }
+  }
+  const cum = [ 0 ]
+  for (let n = 1; n < pts.length; n++) cum.push(cum[n - 1] + Math.sqrt((pts[n][0] - pts[n - 1][0]) * (pts[n][0] - pts[n - 1][0]) + (pts[n][1] - pts[n - 1][1]) * (pts[n][1] - pts[n - 1][1])))
+  return { pts, cum, length: cum[cum.length - 1], closed: c.c }
+}
+
+/**
+ * Where a polyline is at a distance, and which way it heads.
+ *
+ * @param   {Poly}   poly
+ * @param   {number} d      clamped to the polyline
+ * @returns {{ x: number, y: number, tx: number, ty: number }}
+ */
+function sample(poly, d) {
+  const dist = Math.max(0, Math.min(poly.length, d))
+  let n = 1
+  while (n < poly.pts.length - 1 && poly.cum[n] < dist) n++
+  if (poly.pts.length < 2) return { x: poly.pts[0][0], y: poly.pts[0][1], tx: 1, ty: 0 }
+  const a = poly.pts[n - 1]
+  const b = poly.pts[n]
+  const span = poly.cum[n] - poly.cum[n - 1]
+  const t = span === 0 ? 0 : (dist - poly.cum[n - 1]) / span
+  const dx = b[0] - a[0]
+  const dy = b[1] - a[1]
+  const len = Math.sqrt(dx * dx + dy * dy) || 1
+  return { x: a[0] + dx * t, y: a[1] + dy * t, tx: dx / len, ty: dy / len }
+}
+
+/**
+ * @typedef {object} Measure
+ * @property {Poly[]}  polys  the contours measured, in order
+ * @property {number}  first  index of the first contour this measure covers
+ * @property {boolean} single whether it covers that one contour only (a ContourMeasure)
+ * @property {(dest: any, cmds: Command[]) => void} sink  appends commands to the path an `extract` was given
+ */
+
+/**
+ * @param   {Measure} m
+ * @returns {number}
+ */
+function totalLength(m) {
+  let sum = 0
+  const end = m.single ? m.first + 1 : m.polys.length
+  for (let n = m.first; n < end; n++) sum += m.polys[n].length
+  return sum
+}
+
+/**
+ * @param   {Measure} m
+ * @param   {number}  d
+ * @returns {{ x: number, y: number, tx: number, ty: number }}
+ */
+function sampleMeasure(m, d) {
+  const end = m.single ? m.first + 1 : m.polys.length
+  let rest = Math.max(0, Math.min(totalLength(m), d))
+  for (let n = m.first; n < end; n++) {
+    const poly = m.polys[n]
+    if (rest <= poly.length || n === end - 1) return sample(poly, rest)
+    rest -= poly.length
+  }
+  return { x: 0, y: 0, tx: 1, ty: 0 }
+}
+
+/**
+ * The commands for the part of a measure between two distances, as lines.
+ *
+ * @param   {Measure} m
+ * @param   {number}  from
+ * @param   {number}  to
+ * @param   {boolean} startWithMove
+ * @returns {Command[]}
+ */
+function extract(m, from, to, startWithMove) {
+  /** @type {Command[]} */
+  const cmds = []
+  const end = m.single ? m.first + 1 : m.polys.length
+  const total = totalLength(m)
+  const a = Math.max(0, Math.min(total, Math.min(from, to)))
+  const b = Math.max(0, Math.min(total, Math.max(from, to)))
+  let offset = 0
+  let started = !startWithMove
+  for (let n = m.first; n < end; n++) {
+    const poly = m.polys[n]
+    const lo = Math.max(a, offset) - offset
+    const hi = Math.min(b, offset + poly.length) - offset
+    offset += poly.length
+    if (hi < lo || (hi === lo && b !== a)) continue
+    const p = sample(poly, lo)
+    cmds.push({ t: started ? 'lineTo' : 'moveTo', p: [ p.x, p.y ] })
+    started = true
+    for (let k = 1; k < poly.pts.length; k++) {
+      if (poly.cum[k] > lo && poly.cum[k] < hi) cmds.push({ t: 'lineTo', p: [ poly.pts[k][0], poly.pts[k][1] ] })
+    }
+    const q = sample(poly, hi)
+    if (hi > lo) cmds.push({ t: 'lineTo', p: [ q.x, q.y ] })
+    started = false
+  }
+  return cmds
+}
+
+/** @type {Record<string, (h: Measure, args: any[], vm: any) => any>} */
+const SHARED = {
+  positionAndTangent: (h, args) => {
+    const s = sampleMeasure(h, num(args, 1, 'positionAndTangent'))
+    return [ new Vector(s.x, s.y, 0), new Vector(s.tx, s.ty, 0) ]
+  },
+  warp: (h, args) => {
+    const v = args[1]
+    if (!(v instanceof Vector)) throw fail("invalid argument #1 to 'warp' (Vector expected)")
+    const s = sampleMeasure(h, v.x)
+    return new Vector(s.x - s.ty * v.y, s.y + s.tx * v.y, 0)
+  },
+  extract: (h, args) => {
+    const startWithMove = args[4] === undefined || args[4] !== false
+    h.sink(args[3], extract(h, num(args, 1, 'extract'), num(args, 2, 'extract'), startWithMove))
+  },
+}
+
+const PathMeasure = defineType('PathMeasure', {
+  fields: {
+    length: { get: (h) => totalLength(h) },
+    isClosed: { get: (h) => h.polys.length === 1 && h.polys[0].closed },
+  },
+  methods: SHARED,
+})
+
+const ContourMeasure = defineType('ContourMeasure', {
+  fields: {
+    length: { get: (h) => totalLength(h) },
+    isClosed: { get: (h) => h.polys[h.first].closed },
+    next: { get: (h) => (h.first + 1 < h.polys.length ? ContourMeasure.wrap({ polys: h.polys, first: h.first + 1, single: true, sink: h.sink }) : undefined) },
+  },
+  methods: SHARED,
+})
+
+/**
+ * @param   {Contour[]} contours
+ * @param   {boolean}   perContour  a chain of ContourMeasures instead of one PathMeasure
+ * @param   {(dest: any, cmds: Command[]) => void} sink  appends commands to a script's Path
+ * @returns {any}       the Lua value `contours()` or `measure()` returns
+ */
+export function measureOf(contours, perContour, sink) {
+  const polys = contours.filter((c) => c.v.length > 0).map(flatten)
+  if (perContour) return polys.length === 0 ? undefined : ContourMeasure.wrap({ polys, first: 0, single: true, sink })
+  return PathMeasure.wrap({ polys, first: 0, single: false, sink })
+}