Files
AniCraft/docs/plugins.md
T

16 KiB
Raw Blame History

Plug-ins: the WebAssembly plug-in API (ABI v1)

AniCraft plug-ins are WebAssembly modules run in a sandbox, the same host model as the other Craft apps (PhotoCraft's filter plug-ins). One .wasm file works on Windows, macOS, Linux and, later, the web build. A plug-in adds a command: it reads the open document and changes it through AniCraft's own command registry, so everything it does is checked like any other edit and can be undone in one step. The decision and the alternatives are in ADR 0017.

This page is the contract for plug-in authors and the reference for the host (crates/plugins, the plugin.* commands in crates/engine/src/cmds_plugin.rs).

Using plug-ins

In the app: Commands › Plug-ins lists the installed plug-ins. One with settings opens a dialog generated from its parameters, with a live preview on the stage; OK (Enter) keeps the result as one undo step named after the plug-in, Cancel (Esc) leaves the document as it was. Commands › Install Plug-in… picks a .wasm file, Manage Plug-ins… shows what is installed (with Run, Remove, the plug-ins folder and Reload), and Reload Plug-ins re-reads the folder. The command palette (Ctrl+K) finds plug-ins by name too. A plug-in that works on the selection is greyed out until something is selected.

Command Params What it does
plugin.install {"path": "x.wasm", "confirm"?: true} Validates the module and installs it. With a plug-ins folder, the module is copied there as <id>.wasm (atomically). Replacing an installed plug-in's file is irreversible, so it needs "confirm": true (ADR 0004).
plugin.list {} {"plugins": [{id, name, version, author, description, kind, entries, selection, params, notation, size, source, in_folder}], "folder", "abi"}. In the app: the Plug-ins window.
plugin.run {"id": "…", "params"?: {…}} Runs a plug-in. Missing params take their defaults; numbers are clamped to their range; a wrong type is an error. One undo step; on any failure the document is left exactly as it was. Returns the run's log, request count and instructions used.
plugin.remove {"id": "…", "confirm"?: true} Uninstalls. When its file is in the plug-ins folder it is deleted, which needs "confirm": true.
plugin.reload {"folder"?: "…"} Re-reads every *.wasm in the plug-ins folder (first making folder the plug-ins folder when given). A bad module is reported and skipped.

Where plug-ins live. The app uses a plugins folder in its settings folder: %APPDATA%\AniCraft\plugins on Windows, ~/Library/Application Support/AniCraft/plugins on macOS, $XDG_CONFIG_HOME/anicraft/plugins (default ~/.config/anicraft/plugins) on Linux. Every *.wasm in it loads at start. The ANICRAFT_PLUGINS environment variable points somewhere else instead (handy while writing a plug-in). Plug-ins belong to the session, not the document: they stay installed across New and Open, and documents never contain plug-ins.

Headless. anicraft-cli loads plug-ins only when asked, so scripted runs are repeatable: --plugins <folder> (or ANICRAFT_PLUGINS) on any subcommand, or plugin.reload with a folder. Over MCP the same commands are available through anicraft_run.

anicraft-cli exec --sample plugin.run '{"id":"org.anicraft.star-field","params":{"count":200}}' \
    --plugins examples/plugins/dist --save stars.anicraft

The sandbox

The host is wasmi, a pure-Rust WebAssembly interpreter (MIT OR Apache-2.0), built with full validation, its strict module limits and the portable dispatcher (the default tail-call dispatcher can overflow the host stack on a long-running module, which would abort the process). Limits (anicraft_plugins::Limits, defaults):

Limit Default On violation
Host imports only anicraft.call and anicraft.response (no WASI, files, clock, randomness or network) module rejected at install
Module size 16 MiB rejected
Linear memory 256 MiB per instance memory.grow returns −1; an oversized initial memory fails to load
Instructions (fuel) 1,000,000,000 per run (a tenth for loading) the run stops: "exceeded its instruction budget"
Wall clock 5 s per run, host calls included (native builds; checked every 10 M instructions and at every request) "exceeded its time budget"
Requests 100,000 per run "exceeded its host-call budget"
Request / response size 1 MiB / 8 MiB an oversized request traps; an oversized response becomes an error answer
All requests of a run 64 MiB "exceeded its request budget" (bounds what one run can add to a document)
Params handed to ac_run 64 KiB error
Log 200 lines of ≤ 500 characters (more are counted, not kept) dropped
Call depth 1,024 frames trap

Every run gets a fresh instance, so nothing survives from one run to the next. Traps, exhausted budgets, malformed modules, bad manifests, out-of-range pointers and non-zero return codes all become errors, and the document goes back to how it was before the run. The CPU interpreter runs about 470 M simple instructions per second on the development machine, so the default fuel is roughly two seconds of computing.

What a plug-in may do. Requests reach the same commands the menus, the CLI and MCP use, with the same parameter checks, except:

  • file.*: no opening, saving, importing or exporting files;
  • plugin.*: no installing, running or removing plug-ins;
  • edit.undo, edit.redo: the whole run is one undo step;
  • cut, copy and paste (artwork and frames): your clipboard is yours.

Commands in a namespace the host doesn't know are refused, and a test fails when a new namespace appears without a decision. Commands that would need an irreversible confirmation are refused too.

ABI v1

A plug-in is a core WebAssembly module (MVP plus the usual post-MVP features: bulk memory, sign extension, multi-value, saturating conversions; no SIMD, no memory64). All integers are i32 unless noted; pointers are offsets into the module's memory.

Exports

Export Signature Meaning
memory memory The module's linear memory.
ac_abi_version () -> i32 Must return 1.
ac_manifest () -> i64 (len << 32) | ptr of the UTF-8 manifest JSON (≤ 64 KiB).
ac_alloc (size) -> ptr A block of size bytes the host may write, or 0 on failure. Never freed: each run gets a fresh instance.
ac_run (params_ptr, params_len) -> i32 Runs the command with the validated parameters (UTF-8 JSON object). 0 = success; anything else fails the run (and undoes it), with the last log line as the message.

Imports (module anicraft, both optional)

Import Signature Meaning
call (req_ptr, req_len) -> i32 Sends one JSON request; returns the length of the response.
response (dst_ptr, dst_cap) -> i32 Copies up to dst_cap bytes of the last response to dst_ptr; returns the bytes copied.

Every response is JSON: {"ok":true,"result":…} or {"ok":false,"error":"…"} (ok always first). A refused or failed request is an answer, not a trap: the plug-in decides what to do.

Requests

Request Result
{"op":"command","id":"draw.star","params":{…}} The command's result (see anicraft-cli commands for ids and params).
{"op":"document"} {abi, stage: {width, height, fps, background}, scene, scenes, frame, frames, layer, layers: [{id, name, kind, visible, locked, parent}], selection: [ids]} (the selection on every layer, ADR 0044)
{"op":"elements","selected"?:bool,"paths"?:bool} The elements on the active layer at the playhead (tweens applied): {layer, frame, elements: [{id, kind: shape|symbol|text, name, selected, transform: [a,b,c,d,e,f], bounds: [x,y,w,h] (stage), alpha, fill, stroke, path (SVG path data, local space, with "paths")}]} (at most 10,000).
{"op":"log","message":"…"} null; the line goes into the run's report, and the last one explains a failure.

Unknown ops answer {"ok":false,"error":"unknown op '…'"}, so a plug-in can feature-detect. New ops and plug-in kinds are added without changing version 1; the version changes only when an existing contract changes.

Reserved for later kinds: exporters (kind: "exporter", frames in, bytes out); easing presets. Frame scripts are below.

Frame scripts (kind: "frame-script")

A frame script runs while the movie plays (Test Movie, control.test_movie), when the playhead enters a keyframe that names one of its entry points, and steers playback with the same timeline actions the Actions panel edits (ADR 0024). It never changes the document, so the stage and every export stay as authored.

{"id": "org.example.menu", "name": "Menu Logic", "kind": "frame-script", "entries": ["main", "intro"]}
  • entries: 1-32 entry points ([A-Za-z0-9_]{1,32}), ["main"] when left out. A keyframe picks one: Window › Actions › Frame › Runs: Frame script, or actions.set {"layer": …, "frame": …, "plugin": "org.example.menu", "entry": "intro"}.
  • Frame scripts are not commands: they are not in Commands › Plug-ins and plugin.run refuses them.
  • Each run is a fresh instance; ac_run gets {"entry", "frame", "label", "timeline"} (the keyframe's frame, 0-based, the label there, and the dot path of the timeline it is on, "" for the main timeline).
Request Result
{"op":"player"} The player state: {scene, scene_name, scenes, frame, frames, playing, clips: [{path, name, frame, frames, playing}], pointer: {x, y, down} | null, hover, tick, timeline: {path, frame, frames, label, playing}} (timeline is the script's own).
{"op":"action","action":{…}} Queues one action: {"queued": 1}. A malformed action is an error answer.
{"op":"actions","actions":[…]} Queues several (at most 256 per run).
{"op":"log","message":"…"} A line in the Output panel.
command, document, elements Refused: a frame script can't read or change the document.

Actions are JSON objects with an op (the same as actions.set takes; frames are 0-based):

Action Fields
{"op":"stop"}, {"op":"play"} target?
{"op":"goto_and_play"}, {"op":"goto_and_stop"} frame: a number or a label; scene? (main timeline); target?
{"op":"next_frame"}, {"op":"prev_frame"} target?
{"op":"next_scene"}, {"op":"prev_scene"} —
{"op":"trace","message":"…"} —
{"op":"set_property","property":"x|y|alpha|visible|rotation|scale_x|scale_y","value":n} target?

target is a dot path of instance names from the script's timeline: "" (itself), hero, hero.arm, parent, root. The queued actions run after the script returns, in order; if the script fails (a trap, a non-zero return, a budget), none of them run.

Limits (Limits::frame_script): 20,000,000 instructions per frame, shared by all the frame scripts of that frame; 100 ms wall clock per run; 1,000 requests; 64 KiB per request, 1 MiB per response, 1 MiB in all; 50 log lines. A script that runs out writes one Output line (“exceeded its instruction budget”), the rest of the frame's scripts don't run, and the movie plays on. A script that reads the player and sends an action takes about 50 µs (debug build).

// The guest SDK's request helper sends one JSON request and returns the answer.
fn run(p: &Value) -> Result<(), String> {
    let st = ac::request(&json!({"op": "player"}))?;
    if st["frame"].as_u64() == Some(0) && st["pointer"].is_null() {
        ac::request(&json!({"op": "action", "action": {"op": "stop"}}))?;
        ac::request(&json!({"op": "log", "message": format!("waiting on {}", p["entry"])}))?;
    }
    Ok(())
}

Manifest

{
  "id": "org.example.stars",
  "name": "Star Field",
  "version": "1.0.0",
  "kind": "command",
  "author": "Example",
  "description": "What it does, one sentence.",
  "selection": "optional",
  "params": {
    "count":  {"type": "int", "min": 1, "max": 1000, "default": 120, "label": "Stars"},
    "size":   {"type": "number", "min": 1, "max": 50, "default": 4},
    "twinkle":{"type": "bool", "default": true},
    "shape":  {"type": "choice", "options": ["star", "dot"], "default": "star"},
    "color":  {"type": "color", "default": "#fff4c2"}
  }
}
  • id: 1–64 characters from A-Z a-z 0-9 . _ - (reverse-DNS recommended). Installing a module with the same id replaces the old one.
  • name: the menu label, 1–64 printable characters (control characters and invisible format characters such as bidi overrides are rejected). The app adds "…" when there are parameters.
  • kind: "command", or "frame-script" (see Frame scripts above, with its entries).
  • selection: "optional" (default; generators) or "required" (selection transforms: the menu item is disabled without a selection and plugin.run refuses).
  • params: in dialog order, at most 32. Names are [A-Za-z0-9_], 1–32 characters, not starting with _, not id. label (optional) is the dialog label; by default the name with underscores as spaces. Types: number and int (min, max, default; a slider), bool (a checkbox), choice (options, default; a dropdown), color ("#rrggbb"; a swatch).

Writing a plug-in in Rust

examples/plugins has a small guest SDK and two complete plug-ins:

  • Star Field (star-field/): a generator. Scatters stars of varied size, angle and brightness over the stage on a new layer (layer.new, draw.star, element.set_transform, element.set_alpha).
  • Jitter Selection (jitter/): a selection transform. Moves, turns and scales each selected element about its own centre (elements, element.select, modify.transform).
use anicraft_plugin_sdk::{self as ac, Rng};
use serde_json::{Value, json};

const MANIFEST: &str = r#"{"id":"org.example.dots","name":"Dots","kind":"command",
  "params":{"count":{"type":"int","min":1,"max":100,"default":10}}}"#;

ac::plugin!(MANIFEST, run);

fn run(p: &Value) -> Result<(), String> {
    let stage = &ac::document()?["stage"];
    let (w, h) = (stage["width"].as_f64().unwrap_or(550.0), stage["height"].as_f64().unwrap_or(400.0));
    let mut rng = Rng::new(1);
    for _ in 0..p["count"].as_u64().unwrap_or(10) {
        let (x, y) = (rng.unit() * w, rng.unit() * h);
        ac::command("draw.ellipse", json!({"x": x, "y": y, "w": 8, "h": 8, "stroke": null}))?;
    }
    Ok(())
}

Build them with examples/plugins/build.sh (needs rustup target add wasm32-unknown-unknown); the modules land in examples/plugins/dist/. std and serde_json are fine as long as nothing touches WASI. Plug-ins get no randomness: use a seed parameter (the SDK's Rng), which also makes every preview match the result. The only unsafe code a Rust plug-in needs is the two imports and the exports' raw pointers, all inside the SDK. Any language that compiles to core WebAssembly works (C, Zig, AssemblyScript, hand-written WAT; the host's tests are written in WAT).

Performance

Measured on the development machine (Windows, debug build of AniCraft with optimised dependencies, anicraft-cli run --sample … --plugins examples/plugins/dist):

Load both sample modules (72 KB and 80 KB) under 5 ms of the CLI's ~45 ms start-up
Star Field, 120 stars (361 requests, 60 M instructions for 200) ~27 ms, fast enough for the live preview
Star Field, 1,000 stars (3,001 requests) ~230 ms
Jitter Selection on one element ~1 ms (0.8 M instructions)
A busy loop in the interpreter ~470 M instructions/s (20 M in 43 ms)

A request costs about 75 µs here: most of it is the command itself plus the plug-in parsing and writing JSON. Generators that create thousands of elements should expect a fraction of a second per run.

Not in v1

  • Exporters and easing plug-ins (reserved above), panels and other UI plug-ins.
  • State that survives between frame-script runs (each run is a fresh instance).
  • Runs on a background thread with progress and cancel: a run blocks the app for at most its time budget (5 s).
  • A compact binary view of large documents (v1 answers JSON only), and requests that edit a path's points directly by data (today: path.* commands, or redraw with draw.path).
  • Signing, a plug-in catalogue, and per-plug-in permissions beyond the fixed policy above.