23 KiB
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
Saved commands share the rule
A saved command (ADR 0097, History › Save As Command) may call exactly the commands a plug-in
may (plugin_may_call), and no macro.* command. Plug-ins may not call any macro.* command
either, so the two can never call each other.
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|camera|group, name, selected, transform: [a,b,c,d,e,f], bounds: [x,y,w,h]|null (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. |
bounds is null for cameras and for any element whose evaluated bounds are empty.
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.
Two more kinds are below: frame scripts, and exporters and eases (ADR 0088).
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, oractions.set {"layer": …, "frame": …, "plugin": "org.example.menu", "entry": "intro"}.- Frame scripts are not commands: they are not in Commands › Plug-ins and
plugin.runrefuses them. - Each run is a fresh instance;
ac_rungets{"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(())
}
Exporters (kind: "exporter")
An exporter adds an export format. File › Export lists it below the built-in formats; it opens
an Export window with the plug-in's options, the frames and the file, then shows a progress bar
and Cancel while the export runs (on a worker thread, with a snapshot of the document).
Headless: file.export_plugin and anicraft-cli export --format <id>.
{"id": "org.example.text", "name": "Plain Text Frames", "kind": "exporter",
"format": {"name": "Plain Text Frames", "extension": "txt"},
"params": {"detail": {"type": "choice", "options": ["Summary", "Shapes"], "default": "Shapes"}}}
format:name(1-64 printable characters; the menu item and the window's title) andextension(1-16 characters from a-z 0-9, without the dot; the file dialog's filter).paramsare the export's options, declared and checked exactly as a command's parameters.- Exports:
memory,ac_abi_version,ac_manifest,ac_allocandac_export(options_ptr, options_len) -> i64:(len << 32) | ptrof the file's bytes in the module's memory, or a negative number when it fails (the last log line says why). AniCraft writes the file; an exporter never touches files. - An exporter never sees the document, only evaluated frames:
| Request | Result |
|---|---|
{"op":"movie"} |
{abi, name (the file's stem), width, height, fps, background: "#rrggbbaa", from, to (movie frames, 0-based), frames (in the export), total_frames, scenes: [{name, start, frames}]} |
{"op":"frame","index":i} |
Frame from + i, evaluated as the stage shows it at that frame (guides left out): {index, frame, scene, scene_frame, items, clips, groups} |
{"op":"log","message":"…"} |
null |
command, document, elements |
Refused |
Each item of a frame is one filled or stroked path, in drawing order:
{layer, element, path (SVG path data, local space), transform: [a,b,c,d,e,f] (local → stage), fill, stroke, fill_rule: "nonzero"|"evenodd", alpha, color?: {mul: [r,g,b,a], add: [r,g,b,a]} (the colour effect, when there is one), clip?, masks?, group?}.
fill is null or {"type": "solid", "color": "#rrggbbaa"}, {"type": "linear", start, end, stops: [[offset, colour]], spread, linear_rgb}, {"type": "radial", center, radius, focal, matrix, stops, spread, linear_rgb} or {"type": "bitmap", bitmap (library id), repeat, matrix}; stroke is null or {color, width, cap, join, miter_limit, dash?, variable_width?}.
An item with masks: n is mask artwork that forms clip n (it isn't drawn); an item with
clip: n is drawn only inside clip n; clips[n] is the clip it is intersected with.
groups[n] ({parent, alpha, blend, clip, filters}) fades its items as one. Text arrives as
outlines.
Limits (Limits::exporter): 50,000,000,000 instructions (about 100 s of computing), 10
minutes, 1,000,000 requests, 32 MiB per answer, 64 MiB of output (checked before a byte is
copied). Progress is the frames read (each counted once); Cancel stops the export at its next
request or within one slice of fuel, and nothing is written.
Eases (kind: "ease")
An ease plug-in adds eases to every ease menu (the timeline's, Properties › Frame, the Motion Editor), under Plug-in eases.
{"id": "org.example.steps", "name": "Stepped Eases", "kind": "ease",
"eases": [{"id": "steps4", "name": "Stepped 4"}, {"id": "smooth4", "name": "Smooth Steps 4"}]}
eases: 1-32 of{id ([A-Za-z0-9_-]{1,32}), name (1-48 printable characters)}. Noparams.- Exports:
memory,ac_abi_version,ac_manifestandac_ease(index: i32, t: f64) -> f64: ease numberindex's eased progress at timet. - AniCraft calls it once, when the plug-in loads, at 257 times (
t = i / 256), with no host calls allowed, and keeps the table. The values must be finite, within −10..10, 0 at t = 0 and 1 at t = 1 (within 0.001); otherwise the plug-in doesn't load and the message names the ease, the time and the value. - A tween given one keeps the table (
Easing::Sampled, read with linear interpolation), so the document opens and plays the same without the plug-in, and a newer version of it never changes a finished movie. Pick the ease again to take a newer curve. Editing its points in the Custom Ease window makes it a custom ease through 48 of its samples. - Easing params take
{"plugin": "org.example.steps", "ease": "steps4"}(its id or name) and{"sampled": {…}}(whatease.inforeturns; works without the plug-in).ease.listlists the installed plug-ins' eases.
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 fromA-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","frame-script"(see Frame scripts above, with itsentries),"exporter"(with itsformat) or"ease"(with itseases); see above.selection:"optional"(default; generators) or"required"(selection transforms: the menu item is disabled without a selection andplugin.runrefuses).params: in dialog order, at most 32. Names are[A-Za-z0-9_], 1–32 characters, not starting with_, notid.label(optional) is the dialog label; by default the name with underscores as spaces. Types:numberandint(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). - Plain Text Frames (
text-export/): an exporter. The movie as readable text, one block per frame, each shape with its position and paint (exporter!,movie,frame). - Stepped Eases (
stepped-ease/): an ease plug-in. Stepped 2, 4 and 8, and Smooth Steps 4 (ease!).
// An exporter: options in, the file's bytes out.
ac::exporter!(MANIFEST, export);
fn export(options: &Value) -> Result<Vec<u8>, String> {
let movie = ac::movie()?;
let mut out = String::new();
for i in 0..movie["frames"].as_u64().unwrap_or(0) {
let f = ac::frame(i)?;
out += &format!("frame {}: {} shapes\n", f["frame"], f["items"].as_array().map_or(0, Vec::len));
}
Ok(out.into_bytes())
}
// An ease plug-in: eased progress of ease `index` at time `t`.
ac::ease!(MANIFEST, ease);
fn ease(index: usize, t: f64) -> f64 {
let n = [2.0, 4.0][index.min(1)];
if t >= 1.0 { 1.0 } else { (t * n).floor() / n }
}
Built for anything but WebAssembly, the SDK's host imports are stand-ins that answer every
request with an error, so cargo test runs a plug-in's pure parts natively (the samples do).
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) |
| Plain Text Frames, the 48-frame demo with paths (70 KB of text) | ~77 ms (92 M instructions) |
| Stepped Eases: load and sample four eases (1,028 calls) | ~1.8 ms |
| 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
- Panels and other UI plug-ins; exporter plug-ins in Publish Settings; bitmaps' pixels and sounds handed to exporters; ease plug-ins with parameters.
- State that survives between frame-script runs (each run is a fresh instance).
- Command plug-ins on a background thread with progress and cancel: a run blocks the app for at most its time budget (5 s). (Exports already run on one.)
- 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 withdraw.path). - Signing, a plug-in catalogue, and per-plug-in permissions beyond the fixed policy above.