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

package/script/luau/vm/vm.value.js

@@ -0,0 +1,406 @@
+/**
+ * Lua values. They are plain JS values wherever one fits:
+ *
+ * | Lua      | JS                                           |
+ * | -------- | -------------------------------------------- |
+ * | nil      | `undefined`                                  |
+ * | boolean  | `true`, `false`                              |
+ * | number   | a double                                     |
+ * | string   | a byte string: one char per byte, 0 to 255   |
+ * | vector   | `Vector` (immutable, three components)       |
+ * | table    | `LuaTable`                                   |
+ * | function | `LuaClosure` (bytecode) or `NativeFunction`  |
+ *
+ * A JS array is never a Lua value, so a native function can return one to
+ * mean several results.
+ */
+
+// Values
+// ■■■■■■
+
+/** Where the next object id comes from; ids key tables by identity and name them in `tostring` */
+let lastId = 0
+
+/** @returns {number} */
+export function newId() {
+  return ++lastId
+}
+
+const f32 = new Float32Array(1)
+
+/**
+ * A number rounded to single precision, which is what a vector component holds.
+ * (`Math.fround` is newer than the oldest browsers this runs in.)
+ *
+ * @param   {number} x
+ * @returns {number}
+ */
+export function fround(x) {
+  f32[0] = x
+  return f32[0]
+}
+
+/** A three-component vector value, single precision per component; it compares and keys by components */
+export class Vector {
+  /**
+   * @param {number} x
+   * @param {number} y
+   * @param {number} z
+   */
+  constructor(x, y, z) {
+    this.x = fround(x)
+    this.y = fround(y)
+    this.z = fround(z)
+  }
+}
+
+/** The results of a function that returns nothing. Never mutate it. */
+export const EMPTY = /** @type {any[]} */ ([])
+
+/**
+ * A host function. It gets the VM and its arguments as an array and returns
+ * an array of results, or any other value for exactly one result.
+ *
+ * @typedef {(vm: any, args: any[]) => any} NativeCall
+ */
+
+export class NativeFunction {
+  /**
+   * @param {string}     name
+   * @param {NativeCall} fn
+   */
+  constructor(name, fn) {
+    this.name = name
+    this.fn = fn
+    this.id = 0
+  }
+}
+
+/** A variable a closure captured: on the VM's stack while its function runs, in `v` once that returns */
+export class Upvalue {
+  /**
+   * @param {any[]} stack
+   * @param {number} index
+   */
+  constructor(stack, index) {
+    /** @type {any[] | null} */
+    this.s = stack
+    this.i = index
+    this.v = undefined
+  }
+}
+
+/** A function made from a proto and the upvalues it captured */
+export class LuaClosure {
+  /**
+   * @param {import('../load/load.js').Proto} proto
+   * @param {Upvalue[]}  upvals
+   * @param {LuaTable}   env      the globals
+   */
+  constructor(proto, upvals, env) {
+    this.proto = proto
+    this.upvals = upvals
+    this.env = env
+    this.id = 0
+  }
+}
+
+/** A thrown Lua error: the error value, and how many Lua frames up its position is taken from (0: none) */
+export class LuaThrow {
+  /**
+   * @param {any}    value
+   * @param {number} [level]
+   */
+  constructor(value, level) {
+    this.value = value
+    this.level = level === undefined ? 0 : level
+    /** The source line the error was raised at, 0 when unknown */
+    this.line = 0
+    /** The chunk that line is in */
+    this.chunk = ''
+  }
+}
+
+/**
+ * An error to throw from a native function or the VM: a string error gets the
+ * position of the Lua code that was running, `level` frames up.
+ *
+ * @param   {any}    value
+ * @param   {number} [level]
+ * @returns {LuaThrow}
+ */
+export function fail(value, level) {
+  return new LuaThrow(value, level === undefined ? 1 : level)
+}
+
+/**
+ * @param   {any} v
+ * @returns {string} Lua's `type` of v
+ */
+export function typeName(v) {
+  switch (typeof v) {
+    case 'undefined': return 'nil'
+    case 'boolean': return 'boolean'
+    case 'number': return 'number'
+    case 'string': return 'string'
+    default: break
+  }
+  if (v instanceof LuaTable) return 'table'
+  if (v instanceof Vector) return 'vector'
+  return 'function'
+}
+
+// Tables
+// ■■■■■■
+
+/**
+ * A Lua table. Keys 1..n are the `arr` array (kept free of trailing nils, so
+ * `arr.length` is a border); every other key is in one of three dictionaries
+ * (strings, numbers, everything else) that map a key to a slot in the `hk`
+ * and `hv` arrays. Slots keep their insertion order, which is the traversal
+ * order, and a removed key keeps its slot with a nil value until the next
+ * rebuild, so assigning nil during a traversal is safe.
+ */
+export class LuaTable {
+  constructor() {
+    /** @type {any[]} */
+    this.arr = []
+    /** @type {Record<string, number> | null} */
+    this.hs = null
+    /** @type {Record<string, number> | null} */
+    this.hn = null
+    /** @type {Record<string, number> | null} */
+    this.ho = null
+    /** @type {any[]} */
+    this.hk = []
+    /** @type {any[]} */
+    this.hv = []
+    this.dead = 0
+    /** the key and value `advance` found */
+    this.ck = undefined
+    this.cv = undefined
+    /** @type {LuaTable | undefined} */
+    this.meta = undefined
+    this.frozen = false
+    this.id = 0
+  }
+
+  /**
+   * @param   {string} key
+   * @returns {any}
+   */
+  getStr(key) {
+    const hs = this.hs
+    if (hs === null) return undefined
+    const slot = hs[key]
+    return slot === undefined ? undefined : this.hv[slot]
+  }
+
+  /**
+   * @param   {any} key
+   * @returns {any}
+   */
+  get(key) {
+    if (typeof key === 'string') return this.getStr(key)
+    if (typeof key === 'number') {
+      const arr = this.arr
+      if (key >= 1 && key <= arr.length && Math.floor(key) === key) return arr[key - 1]
+      const hn = this.hn
+      if (hn === null) return undefined
+      const slot = hn[key]
+      return slot === undefined ? undefined : this.hv[slot]
+    }
+    const slot = this.slotOf(key)
+    return slot === undefined ? undefined : this.hv[slot]
+  }
+
+  /**
+   * The slot a key holds in the hash part, or undefined
+   *
+   * @param   {any} key
+   * @returns {number | undefined}
+   */
+  slotOf(key) {
+    if (typeof key === 'string') return this.hs === null ? undefined : this.hs[key]
+    if (typeof key === 'number') return this.hn === null ? undefined : this.hn[key]
+    return this.ho === null ? undefined : this.ho[objectKey(key)]
+  }
+
+  /**
+   * Sets a key without looking at the metatable. The key must not be nil or NaN.
+   *
+   * @param {any} key
+   * @param {any} value
+   */
+  set(key, value) {
+    if (typeof key === 'number') {
+      const arr = this.arr
+      const n = arr.length
+      if (key >= 1 && key <= n + 1 && Math.floor(key) === key) {
+        if (key <= n) {
+          arr[key - 1] = value
+          if (value === undefined && key === n) {
+            let m = n - 1
+            while (m > 0 && arr[m - 1] === undefined) m--
+            arr.length = m
+          }
+        } else if (value !== undefined) {
+          arr.push(value)
+          if (this.hn !== null) this.migrate()
+        }
+        return
+      }
+    }
+    let slot = this.slotOf(key)
+    if (slot !== undefined) {
+      const old = this.hv[slot]
+      this.hv[slot] = value
+      if (value === undefined && old !== undefined) this.dead++
+      else if (old === undefined && value !== undefined) this.dead--
+      return
+    }
+    if (value === undefined) return
+    if (this.dead > 16 && this.dead * 2 > this.hk.length) this.rebuild()
+    slot = this.hk.length
+    this.hk.push(key)
+    this.hv.push(value)
+    if (typeof key === 'string') {
+      const hs = this.hs === null ? (this.hs = Object.create(null)) : this.hs
+      hs[key] = slot
+    } else if (typeof key === 'number') {
+      const hn = this.hn === null ? (this.hn = Object.create(null)) : this.hn
+      hn[key] = slot
+    } else {
+      const ho = this.ho === null ? (this.ho = Object.create(null)) : this.ho
+      ho[objectKey(key)] = slot
+    }
+  }
+
+  /** After the array part grew, moves the keys that now continue it out of the hash part */
+  migrate() {
+    const hn = /** @type {Record<string, number>} */ (this.hn)
+    for (;;) {
+      const slot = hn[this.arr.length + 1]
+      if (slot === undefined || this.hv[slot] === undefined) return
+      this.arr.push(this.hv[slot])
+      this.hv[slot] = undefined
+      this.dead++
+    }
+  }
+
+  /** Drops the slots whose values are nil */
+  rebuild() {
+    const keys = this.hk
+    const values = this.hv
+    this.hk = []
+    this.hv = []
+    this.hs = null
+    this.hn = null
+    this.ho = null
+    this.dead = 0
+    for (let i = 0; i < keys.length; i++) if (values[i] !== undefined) this.set(keys[i], values[i])
+  }
+
+  /** @returns {number} a border: the length `#` gives */
+  length() {
+    return this.arr.length
+  }
+
+  /**
+   * One step of a traversal. A position is an array index (0 and up), or -1
+   * and down for hash slot 0 and up; it survives assigning nil to entries.
+   * Finds the entry at or after `pos`, leaves its key and value in `ck` and
+   * `cv`, and returns the position after it; null when there are no more.
+   *
+   * @param   {number} pos  where to start: 0 for the beginning
+   * @returns {number | null}
+   */
+  advance(pos) {
+    const arr = this.arr
+    let i = pos
+    if (i >= 0) {
+      for (; i < arr.length; i++) {
+        if (arr[i] !== undefined) {
+          this.ck = i + 1
+          this.cv = arr[i]
+          return i + 1
+        }
+      }
+      i = -1
+    }
+    const hv = this.hv
+    for (let s = -i - 1; s < hv.length; s++) {
+      if (hv[s] !== undefined) {
+        this.ck = this.hk[s]
+        this.cv = hv[s]
+        return -s - 2
+      }
+    }
+    return null
+  }
+
+  /**
+   * Stores values at keys `start`, `start + 1`, ... in the array part, nils
+   * included, as a table constructor does (so `{ nil, nil, 3 }` has length 3).
+   *
+   * @param {number} start  the first key, 1 or more
+   * @param {any[]}  source
+   * @param {number} from   the first index in source
+   * @param {number} count
+   */
+  setRange(start, source, from, count) {
+    const arr = this.arr
+    while (arr.length < start - 1) arr.push(undefined)
+    for (let i = 0; i < count; i++) {
+      const v = source[from + i]
+      if (start - 1 + i < arr.length) arr[start - 1 + i] = v
+      else arr.push(v)
+      if (this.hn !== null) {
+        const slot = this.hn[start + i]
+        if (slot !== undefined && this.hv[slot] !== undefined) {
+          this.hv[slot] = undefined
+          this.dead++
+        }
+      }
+    }
+    let m = arr.length
+    while (m > 0 && arr[m - 1] === undefined) m--
+    arr.length = m
+    if (this.hn !== null) this.migrate()
+  }
+
+  /**
+   * The position after a key, for `next`; undefined when the key is not in the table.
+   *
+   * @param   {any} key
+   * @returns {number | undefined}
+   */
+  after(key) {
+    if (key === undefined) return 0
+    if (typeof key === 'number' && key >= 1 && key <= this.arr.length && Math.floor(key) === key) return key
+    const slot = this.slotOf(key)
+    return slot === undefined ? undefined : -slot - 2
+  }
+
+  /** @returns {LuaTable} a copy without the metatable's identity: same entries, same metatable */
+  clone() {
+    const t = new LuaTable()
+    t.arr = this.arr.slice()
+    for (let s = 0; s < this.hk.length; s++) if (this.hv[s] !== undefined) t.set(this.hk[s], this.hv[s])
+    t.meta = this.meta
+    return t
+  }
+}
+
+/**
+ * The dictionary key for a key that is neither a string nor a number.
+ *
+ * @param   {any} key
+ * @returns {string}
+ */
+function objectKey(key) {
+  if (typeof key === 'boolean') return key ? 'b1' : 'b0'
+  if (key instanceof Vector) return 'v' + key.x + ',' + key.y + ',' + key.z
+  if (key.id === 0) key.id = newId()
+  return 'o' + key.id
+}

package/script/play/play.js

@@ -0,0 +1,199 @@
+/**
+ * The scripts a bundle ships, run while it plays: scripted converters on a
+ * slot's source, transition conditions on a machine's guards, and listener
+ * actions on its interactions.
+ *
+ * This file imports the Luau VM and Rive host, so the player's main bundle
+ * does not: the page gives `script/script.js` (which exports `createScripts`)
+ * to `loadScripts` (bundle/bundle.js), and only for a bundle that lists scripts
+ * (`manifest.scripts`). A bundle without them downloads and parses none of it,
+ * and the legacy build's main file holds none of it either (the host is a file
+ * of its own there).
+ *
+ * Scripted nodes, drawables and path effects (`objects`) run every frame beside
+ * these, from `play.objects.js`.
+ *
+ * The scripts see the player's live values as their view model: a property is
+ * a key of the values by its dotted path, and a write changes the value (a
+ * trigger sets the event). A converter script that reads none of it is run
+ * once per distinct input; one that reads it is run on each use.
+ */
+
+import { createScriptHost } from '../rive/rive.js'
+import { createObjects } from './play.objects.js'
+
+/** Tells the runtimes of several Motions apart, which may share a manifest's objects */
+let nextRuntime = 1
+
+/** The interactions a pointer event is made of, by the name a script sees */
+const POINTER_TYPES = /** @type {Record<string, string>} */ ({
+  Click: 'click',
+  PointerDown: 'down',
+  PointerUp: 'up',
+  PointerEnter: 'enter',
+  PointerExit: 'exit',
+  PointerMove: 'move',
+})
+
+/**
+ * @typedef {object} Scripts
+ * @property {(descriptor: any, value: any, isReverse?: boolean, kind?: string, values?: Record<string, any>) => any} convert a converter script's result for a value; the value itself when the script gives none
+ * @property {(guard: any, values: Record<string, any>) => boolean}                                          evaluate whether a transition condition script lets its transition pass
+ * @property {(action: any, type: string, values: Record<string, any>, events: Record<string, boolean>) => boolean} perform   runs a listener action script; whether it changed a value or fired a trigger
+ * @property {(values: Record<string, any>) => void}                                                         changed  the values changed: scripts listening to a property hear of it
+ * @property {(entries: import('./play.objects.js').ObjectEntry[], env: import('./play.objects.js').ObjectsEnv) => import('./play.objects.js').Objects} objects  starts the bundle's scripted nodes, drawables and path effects, which run each frame (`play.objects.js`)
+ * @property {number}                                                                                        count    the scripts started so far
+ */
+
+/**
+ * @param   {any}                        manifest
+ * @param   {Record<string, Uint8Array>} bytes    each script's bytecode, by the entry a descriptor names it by
+ * @param   {(message: string) => void}  report
+ * @param   {Function}                   [make]   makes a script host; default the Rive host (a test passes one that counts)
+ * @returns {Scripts}
+ */
+export function createScripts(manifest, bytes, report, make = createScriptHost) {
+  const runtime = nextRuntime++
+  /** @type {Array<{ host: any, pure: boolean, hasIn: boolean, lastIn: any, lastOut: any }>} */
+  const entries = []
+  /** @type {Array<{ path: string, fn: (value: any) => void, last: any }>} */
+  const subscriptions = []
+  /** @type {Record<string, any>} */
+  let values = {}
+  /** @type {Record<string, boolean>} */
+  let events = {}
+  let dirty = false
+  /** values a script read, to tell whether a result may be reused */
+  let reads = 0
+  /** @type {Record<string, string>} */
+  const kinds = {}
+  const properties = (manifest.data && manifest.data.properties) || []
+  for (let n = 0; n < properties.length; n++) kinds[properties[n].name] = properties[n].type
+  /** the pointer event of the latest listener action, reused */
+  const pointer = { type: 'click' }
+
+  /** The player's values, as the view model a script reaches */
+  const adapter = {
+    get: (/** @type {string} */ path) => {
+      reads++
+      return values[path]
+    },
+    kind: (/** @type {string} */ path) => {
+      const kind = kinds[path]
+      if (kind) return kind
+      const value = values[path]
+      return typeof value === 'number' ? 'number' : typeof value === 'string' ? 'string' : typeof value === 'boolean' ? 'boolean' : undefined
+    },
+    set: (/** @type {string} */ path, /** @type {any} */ value) => {
+      if (values[path] === value) return
+      values[path] = value
+      dirty = true
+    },
+    fire: (/** @type {string} */ path) => {
+      events[path] = true
+      dirty = true
+    },
+    subscribe: (/** @type {string} */ path, /** @type {(value: any) => void} */ fn) => {
+      const subscription = { path, fn, last: values[path] }
+      subscriptions.push(subscription)
+      return () => {
+        const at = subscriptions.indexOf(subscription)
+        if (at >= 0) subscriptions.splice(at, 1)
+      }
+    },
+  }
+
+  /**
+   * The host a descriptor, guard or action runs, made when it is first used.
+   *
+   * @param   {any} ref  carries `script`, and `inputs` when the object sets any
+   * @returns {typeof entries[number] | null}
+   */
+  function entryOf(ref) {
+    if (ref._runtime === runtime) return ref._host < 0 ? null : entries[ref._host]
+    ref._runtime = runtime
+    const data = bytes[ref.script]
+    if (!data) {
+      report("script '" + ref.script + "' is not in the bundle")
+      ref._host = -1
+      return null
+    }
+    const host = make({
+      bytes: data,
+      inputs: ref.inputs,
+      viewModel: adapter,
+      log: () => {},
+      onError: (/** @type {Error} */ error) => report("script '" + ref.script + "': " + error.message),
+    })
+    host.init()
+    entries.push({ host, pure: true, hasIn: false, lastIn: undefined, lastOut: undefined })
+    ref._host = entries.length - 1
+    return entries[ref._host]
+  }
+
+  /**
+   * @param {Record<string, any>}     v
+   * @param {Record<string, boolean>} [e]
+   */
+  function bind(v, e) {
+    values = v
+    if (e) events = e
+  }
+
+  return {
+    convert(descriptor, value, isReverse, kind, current) {
+      if (current) bind(current)
+      const entry = entryOf(descriptor)
+      if (!entry) return value
+      // a script that read nothing gives the same result for the same input
+      if (!isReverse && entry.pure && entry.hasIn && entry.lastIn === value) return entry.lastOut
+
+      const before = reads
+      const out = isReverse ? entry.host.reverseConvert(value, kind) : entry.host.convert(value, kind)
+      if (reads !== before) entry.pure = false
+      if (!out) return value
+      if (!isReverse) {
+        entry.hasIn = true
+        entry.lastIn = value
+        entry.lastOut = out.value
+      }
+      return out.value
+    },
+
+    evaluate(guard, current) {
+      bind(current)
+      const entry = entryOf(guard)
+      return !!entry && entry.host.evaluate()
+    },
+
+    perform(action, type, current, pending) {
+      bind(current, pending)
+      const entry = entryOf(action)
+      if (!entry) return false
+      dirty = false
+      pointer.type = POINTER_TYPES[type] || 'click'
+      entry.host.perform(pointer)
+      return dirty
+    },
+
+    changed(current) {
+      if (!subscriptions.length) return
+      bind(current)
+      const heard = subscriptions.slice()
+      for (let n = 0; n < heard.length; n++) {
+        const value = values[heard[n].path]
+        if (value === heard[n].last) continue
+        heard[n].last = value
+        heard[n].fn(value)
+      }
+    },
+
+    objects(list, env) {
+      return createObjects(list, bytes, env, report, make)
+    },
+
+    get count() {
+      return entries.length
+    },
+  }
+}