animl 0.0.0-stage → 0.1.0

package/modules/machine/core/index.js

@@ -0,0 +1,324 @@
+import { installRandom } from "../../../packages/core/src/random.js";
+import { ptr } from "../../../packages/core/src/diag.js";
+import { VERBOSE as V } from "../../../packages/core/src/flags.js";
+import { inputExpression } from "../../../packages/core/src/load.js";
+import { BindError, expression, evaluate } from "../../bind/core/expression.js";
+import { after } from "../manifest.js";
+import { entries } from "./registry.js";
+import { MachinePolicy, install } from "./runtime.js";
+import {
+  states,
+  anyEdges,
+  compiledActions,
+  transitions
+} from "./types.js";
+const list = (x) => x === void 0 ? [] : typeof x === "string" ? [x] : x;
+const err = (d, code, p, message, hint = "check the machine field and its referenced input, state or timeline") => d.err(code, p, V && message, V && hint);
+let compileValue = inputExpression;
+const machine = {
+  name: "machine",
+  after,
+  entries,
+  init(_modules, shared) {
+    installRandom(shared.Player);
+    install(shared.sampleTrack, shared.mixValues);
+    compileValue = shared.inputExpression;
+    return { ...machine, init: void 0 };
+  },
+  load(model, raw, d) {
+    if (!raw.requires?.includes("machine")) return;
+    const used = /* @__PURE__ */ new Set();
+    const input = (name, type, p) => {
+      const i = model.inputs.get(name);
+      if (!i) err(d, "unknown-input", p, V && `unknown machine input ${name}`);
+      else if (i.type !== type) err(d, "input-type", p, V && `expected ${type} input`);
+      used.add(name);
+      return i;
+    };
+    const actions = (a, p) => {
+      if (!a) return;
+      const set = [];
+      for (const name of list(a?.fire)) input(name, "trigger", p + "/fire");
+      for (const name of list(a?.toggle)) input(name, "bool", p + "/toggle");
+      for (const [name, val] of Object.entries(a?.set ?? {})) {
+        if (name === "$comment") continue;
+        const pointer = ptr(p + "/set", name);
+        if (typeof val === "string") {
+          const i = model.inputs.get(name);
+          input(name, i && i.type !== "trigger" ? i.type : "number", pointer);
+          if (i && i.type !== "trigger") {
+            const evaluate2 = compileValue(model, val, i.type, pointer, d, (n) => used.add(n));
+            if (evaluate2) set.push([name, evaluate2]);
+          }
+        } else {
+          input(name, typeof val === "boolean" ? "bool" : "number", pointer);
+          set.push([name, val]);
+        }
+      }
+      compiledActions.set(a, { fire: list(a.fire), toggle: list(a.toggle), set, emit: a.emit });
+    };
+    const number = (src, p) => {
+      if (src === void 0 || typeof src === "number") return () => src ?? 1;
+      if (typeof src === "string") {
+        input(src, "number", p);
+        return (p2) => Number(p2.get(src));
+      }
+      if (!raw.requires.includes("bind"))
+        err(
+          d,
+          "undeclared-feature",
+          p,
+          V && "machine data sources use bind until P4e",
+          V && 'add "bind" to requires'
+        );
+      try {
+        const e = expression(src.bind, new Map([...model.inputs].map(([n, i]) => [n, i.type])));
+        if (e.type !== "number")
+          throw new BindError("bind-type", 0, "expected a numeric blend expression");
+        for (const name of e.inputs) used.add(name);
+        return (p2) => Number(evaluate(e, new Map([...e.inputs].map((n) => [n, p2.get(n)]))));
+      } catch (e) {
+        if (!(e instanceof BindError)) throw e;
+        err(d, e.code, p + "/bind", e.message, V && "use a numeric input expression");
+        return () => 0;
+      }
+    };
+    const timeline = (name, p) => {
+      const index = model.timelines.findIndex((t) => t.name === name);
+      if (index < 0) err(d, "unknown-timeline", p, V && `unknown blend timeline ${name}`);
+      return index;
+    };
+    for (const layer of model.layers) {
+      const rawStates = raw.machine.layers[layer.name].states;
+      const any = [];
+      for (const state of layer.states) {
+        const r = rawStates[state.name];
+        const p = ptr(ptr("/machine/layers", layer.name) + "/states", state.name);
+        const info = {
+          ...r,
+          axis: r.mix?.axis === void 0 ? void 0 : number(r.mix.axis, p + "/mix/axis")
+        };
+        states.set(state, info);
+        if (r.reset === false)
+          err(
+            d,
+            "machine-state",
+            p + "/reset",
+            V && "reset false is not a supported suspension policy",
+            V && "omit reset or use reset: true"
+          );
+        actions(r.enterActions, p + "/enterActions");
+        actions(r.exitActions, p + "/exitActions");
+        if (r.kind && (state.play !== void 0 || state.pose?.size || r.mix))
+          err(
+            d,
+            "machine-state",
+            p + "/kind",
+            V && "special states require an empty pose",
+            V && "use pose: {} and omit play/mix"
+          );
+        if (r.kind === "any") {
+          any.push(state);
+          if (layer.states[layer.initial] === state)
+            err(d, "machine-state", p + "/kind", V && "any state cannot be initial");
+        }
+        if (r.kind === "exit" && state.on.length)
+          err(
+            d,
+            "machine-state",
+            p + "/on",
+            V && "terminal state has no outgoing transitions",
+            V && "remove its on list"
+          );
+        const clock = rawStates[state.name];
+        if (r.mix && (clock.hold || clock.time !== void 0))
+          err(
+            d,
+            "machine-clock",
+            p + "/mix",
+            V && "blend children need autonomous clocks",
+            V && "omit hold/time on a blend state"
+          );
+        if (r.kind === "random" && !Number.isFinite(state.on.reduce((sum, _t, i) => sum + (clock.on[i].weight ?? 1), 0)))
+          err(
+            d,
+            "machine-state",
+            p + "/on",
+            V && "random weight sum must be finite",
+            V && "reduce the random weights"
+          );
+        if (r.mix) {
+          if (state.play === void 0)
+            err(
+              d,
+              "machine-blend",
+              p + "/mix",
+              V && "a blend needs play as its exit clock",
+              V && "set play to the selected child animation"
+            );
+          const children = r.mix.children.map((c, i) => ({
+            timeline: timeline(c.play, `${p}/mix/children/${i}/play`),
+            at: c.at ?? 0,
+            weight: number(c.weight, `${p}/mix/children/${i}/weight`)
+          }));
+          Object.assign(info, { children });
+          if (r.mix.mode === "1d" && (r.mix.axis === void 0 || r.mix.children.some(
+            (c, i, a) => c.at === void 0 || i > 0 && c.at <= a[i - 1].at
+          )))
+            err(
+              d,
+              "machine-blend",
+              p + "/mix",
+              V && "1d needs an axis and strictly increasing thresholds",
+              V && "supply axis and a unique increasing at for every child"
+            );
+          if (r.mix.exit !== void 0 && (r.mix.exit >= children.length || children[r.mix.exit]?.timeline !== state.play))
+            err(
+              d,
+              "machine-blend",
+              p + "/mix/exit",
+              V && "exit child must exist and match play",
+              V && "choose the index whose play matches the state play"
+            );
+          if (!children.some((c) => c.timeline === state.play))
+            err(d, "machine-blend", p + "/play", V && "exit clock must be a blend child");
+          for (const c of children)
+            for (const tr of model.timelines[c.timeline]?.tracks ?? [])
+              if (!state.writes.includes(tr.addr)) state.writes.push(tr.addr);
+        }
+        for (const [i, t] of state.on.entries()) {
+          const tr = rawStates[state.name].on[i];
+          const tp = p + "/on/" + i;
+          transitions.set(t, tr);
+          const synced = tr.continue && Object.values(rawStates).some(
+            (s) => s.on?.some(
+              (edge) => edge.to === state.name && edge.sync
+            )
+          );
+          if (tr.continue && (clock.hold || clock.time !== void 0 || synced))
+            err(
+              d,
+              "machine-clock",
+              tp + "/continue",
+              V && "continued outgoing playback needs an autonomous, unsynchronized source",
+              V && "omit continue or hold/time/sync"
+            );
+          if (tr.sync && rawStates[layer.states[t.to].name].mix)
+            err(
+              d,
+              "machine-clock",
+              tp + "/sync",
+              V && "blend child clocks cannot inherit a synchronized primary clock",
+              V && "omit sync when entering a blend"
+            );
+          if (((tr.exitRatio ?? 0) > 0 || (tr.blendRatio ?? 0) > 0) && state.play !== void 0 && state.speed * (raw.timelines[model.timelines[state.play].name].speed ?? 1) === 0)
+            err(
+              d,
+              "machine-clock",
+              tp,
+              V && "a positive relative time needs nonzero playback speed",
+              V && "use an explicit duration or a nonzero speed"
+            );
+          actions(tr.actions, tp + "/actions");
+          t.actions = void 0;
+          actions(tr.endActions, tp + "/endActions");
+          if (rawStates[layer.states[t.to].name].kind === "any")
+            err(d, "machine-state", tp + "/to", V && "any state is not a transition destination");
+          if (tr.change)
+            input(
+              tr.change.input,
+              tr.change.mode === "changed" ? model.inputs.get(tr.change.input)?.type === "bool" ? "bool" : "number" : "number",
+              tp + "/change/input"
+            );
+          for (const [key, operand] of Object.entries(tr.guard ?? {}))
+            if (typeof operand === "object" && operand !== null) {
+              if (Object.keys(operand).filter((x) => x !== "$comment").length !== 1)
+                err(
+                  d,
+                  "machine-guard",
+                  tp + "/guard/" + key,
+                  V && "choose exactly one operand source"
+                );
+              if ("component" in operand) {
+                const n = String(operand.component), inp = model.inputs.get(n);
+                if (!n.includes(".") || !inp || inp.type === "trigger")
+                  err(
+                    d,
+                    "machine-guard",
+                    tp + "/guard/" + key + "/component",
+                    V && "expected a numeric or boolean component input"
+                  );
+                used.add(n);
+              }
+              if ("focus" in operand && !model.ids.has(String(operand.focus)))
+                err(
+                  d,
+                  "unknown-target",
+                  tp + "/guard/" + key + "/focus",
+                  V && "unknown focus node"
+                );
+            }
+          if (tr.guard) {
+            const type = (o) => typeof o !== "object" ? typeof o : o.focus !== void 0 ? "boolean" : o.component !== void 0 ? model.inputs.get(o.component)?.type === "bool" ? "boolean" : "number" : "number";
+            if (type(tr.guard.left) !== type(tr.guard.right) || type(tr.guard.left) === "boolean" && !["==", "!="].includes(tr.guard.op))
+              err(
+                d,
+                "machine-guard",
+                tp + "/guard",
+                V && "guard operand types or operator do not match"
+              );
+          }
+          if ((tr.exitRatio !== void 0 || tr.blendRatio !== void 0) && state.play === void 0)
+            err(d, "machine-clock", tp, V && "relative times need a play state");
+          if (tr.blendRatio !== void 0 && tr.blend !== void 0)
+            err(d, "machine-clock", tp + "/blendRatio", V && "blend and blendRatio are exclusive");
+        }
+      }
+      for (const s of any) for (const t of s.on) anyEdges.add(t);
+      for (const state of layer.states)
+        if (states.get(state)?.kind !== "any" && states.get(state)?.kind !== "exit")
+          state.on = [
+            ...any.flatMap(
+              (s) => s.on.filter(
+                (t) => layer.states[t.to] !== state || t.triggers.length > 0 || !!transitions.get(t)?.change
+              )
+            ),
+            ...state.on
+          ];
+    }
+    for (const layer of model.layers) {
+      const seen = /* @__PURE__ */ new Set([layer.initial]);
+      const pending = [layer.initial];
+      while (pending.length)
+        for (const t of layer.states[pending.pop()].on)
+          if (!seen.has(t.to)) {
+            seen.add(t.to);
+            pending.push(t.to);
+          }
+      for (let i = d.list.length - 1; i >= 0; i--)
+        if (d.list[i].code === "unreachable-state" && layer.states.some(
+          (s, j) => (seen.has(j) || states.get(s)?.kind === "any") && d.list[i].pointer === ptr(ptr("/machine/layers", layer.name) + "/states", s.name)
+        ))
+          d.list.splice(i, 1);
+    }
+    for (const n of used)
+      if (n.includes(".")) {
+        const [id, inputName] = n.split(".");
+        const node = model.nodes[model.ids.get(id)];
+        if (node?.raw.component) {
+          const pointer = ptr(ptr("/components", node.raw.component) + "/inputs", inputName);
+          for (let i = d.list.length - 1; i >= 0; i--)
+            if (d.list[i].code === "unused-input" && d.list[i].pointer === pointer)
+              d.list.splice(i, 1);
+        }
+      }
+    for (let i = d.list.length - 1; i >= 0; i--)
+      if (d.list[i].code === "unused-input" && [...used].some((n) => d.list[i].pointer === ptr("/inputs", n)))
+        d.list.splice(i, 1);
+    const previous = model.playback;
+    model.playback = (p) => new MachinePolicy(p, previous?.(p));
+  }
+};
+export {
+  machine
+};

package/modules/machine/core/registry.d.ts

@@ -0,0 +1,5 @@
+import type { ModuleEntry } from '../../../packages/core/src/modules.js';
+import type { Shape } from '../../../packages/core/src/registry.js';
+export declare const action: Shape;
+export declare const source: Shape;
+export declare const entries: ModuleEntry[];

package/modules/machine/core/registry.js

@@ -0,0 +1,95 @@
+const str = { k: "str" }, num = { k: "num" }, bool = { k: "bool" };
+const names = { k: "alt", of: [str, { k: "arr", of: str, min: 1 }] };
+const action = {
+  k: "obj",
+  p: {
+    fire: names,
+    set: { k: "map", of: { k: "alt", of: [num, bool, { ...str, feature: "bind" }] } },
+    toggle: names,
+    emit: str
+  }
+};
+const source = {
+  k: "alt",
+  of: [num, str, { k: "obj", p: { bind: str }, req: ["bind"] }]
+};
+const operand = {
+  k: "alt",
+  of: [
+    num,
+    bool,
+    {
+      k: "obj",
+      p: {
+        artboard: { k: "str", of: ["width", "height", "aspect"] },
+        component: str,
+        focus: str
+      }
+    }
+  ]
+};
+const entries = [
+  { target: "document", shapes: { machineSeed: { k: "num", int: true, min: 0, max: 4294967295 } } },
+  {
+    target: "state",
+    shapes: {
+      kind: { k: "str", of: ["entry", "exit", "any", "random"] },
+      reset: bool,
+      enterActions: action,
+      exitActions: action,
+      mix: {
+        k: "obj",
+        p: {
+          mode: { k: "str", of: ["1d", "direct", "additive"] },
+          axis: source,
+          exit: { k: "num", min: 0, int: true },
+          children: {
+            k: "arr",
+            min: 1,
+            of: {
+              k: "obj",
+              p: {
+                play: str,
+                at: num,
+                weight: source
+              },
+              req: ["play"]
+            }
+          }
+        },
+        req: ["mode", "children"]
+      }
+    }
+  },
+  {
+    target: "transition",
+    shapes: {
+      disabled: bool,
+      weight: { k: "num", min: 0 },
+      continue: bool,
+      exitRatio: { k: "num", min: 0, max: 1 },
+      blendRatio: { k: "num", min: 0 },
+      actions: { ...action, feature: "bind|machine" },
+      endActions: action,
+      change: {
+        k: "obj",
+        p: { input: str, mode: { k: "str", of: ["changed", "increased", "decreased"] } },
+        req: ["input", "mode"]
+      },
+      guard: {
+        k: "obj",
+        p: {
+          left: operand,
+          right: operand,
+          op: { k: "str", of: ["==", "!=", "<", "<=", ">", ">="] }
+        },
+        req: ["left", "right", "op"]
+      }
+    }
+  }
+];
+export {
+  action,
+  entries,
+  source
+};

package/modules/machine/core/runtime.d.ts

@@ -0,0 +1,64 @@
+import type { Player, AnimaEvent } from '../../../packages/core/src/player.js';
+import { sampleTrack, mixValues } from '../../../packages/core/src/player.js';
+import type { PlaybackPolicy, StateM, TimelineM, TransitionM, Value } from '../../../packages/core/src/load.js';
+import { type Run, type Operand, type Actions } from './types.js';
+export declare function install(s: typeof sampleTrack, m: typeof mixValues): void;
+interface Data {
+    eligible: (t: TransitionM) => boolean;
+    chosen?: TransitionM | null;
+    consumed: Set<string>;
+    changed: Set<TransitionM>;
+    outgoing?: {
+        writes: Map<number, (t: number) => Value>;
+        state: StateM;
+        time: number;
+        frozen: number;
+        reduced?: boolean;
+        resumed?: number;
+    };
+    reduced?: boolean;
+    /** State time when full motion was restored, for blend children released from freezing. */
+    resumed?: number;
+    pending?: {
+        transition: TransitionM;
+        duration: number;
+        elapsed: number;
+    };
+}
+export declare class MachinePolicy implements PlaybackPolicy {
+    readonly p: Player;
+    readonly base?: PlaybackPolicy;
+    readonly runs: Map<Run, Data>;
+    readonly originalStates: WeakMap<StateM, StateM>;
+    readonly originalTransitions: WeakMap<TransitionM, TransitionM>;
+    readonly previous: Map<string, Value>;
+    readonly slots: Map<string, number>;
+    constructor(p: Player, base?: PlaybackPolicy);
+    random(): number;
+    get busy(): boolean;
+    states: () => Record<string, string>;
+    inspect: () => import("../../../packages/core/src/player.js").LayerInspect[];
+    pivot: (p: Player, n: number) => [number, number];
+    original(s: StateM): StateM;
+    transition(t: TransitionM): TransitionM;
+    operand(o: Operand): import('../../../packages/core/src/load.js').Value;
+    allowed(t: TransitionM, r: Run): boolean;
+    enter(run: object, from: StateM | undefined, to: StateM, t: TransitionM | undefined, carry: number): void;
+    act(a?: Actions): void;
+    prepare(run: object, s: StateM, dt: number, eligible: (t: TransitionM) => boolean): void;
+    duration(t: TimelineM, speed: number, run: object): number;
+    finished(t: TimelineM, elapsed: number, run: object): boolean;
+    local(t: TimelineM, time: number, speed: number, run: object): number;
+    rest(run: object, s: StateM): boolean;
+    gate(t: TransitionM, s: StateM, elapsed: number, run: object): boolean;
+    carry(t: TransitionM, s: StateM, elapsed: number, run: object): number | undefined;
+    resume(run: object, time: number): void;
+    reduce(t: TimelineM, speed: number, end: boolean, layer: string, out: AnimaEvent[]): number;
+    events(t: TimelineM, a: number, b: number, closed: boolean, layer: string, out: AnimaEvent[], speed: number, run: object, source?: [number, string][]): void;
+    /** Restoring full motion resumes looping blend children; reduced `once` children keep their end. */
+    held(t: TimelineM, reduced?: boolean): boolean;
+    childClock(t: TimelineM, elapsed: number, speed: number, reduced?: boolean, resumed?: number): number;
+    blended(r: Run, state: StateM, address: string, elapsed?: number, frozen?: number, reduced?: boolean | undefined, resumed?: number): Value;
+    compose(dt: number, values: Value[], events: AnimaEvent[]): boolean;
+}
+export {};