effectcraft/docs/plugins.md

Plug-ins and extensions

EffectCraft's core aims at After Effects parity. What After Effects users get from third parties (effect plug-ins, scripts, ScriptUI panels) is an extension in EffectCraft too, and EffectCraft offers the same kinds of extension points as After Effects so that anyone can write their own.

Extension points compared with After Effects

From After Effects' public documentation (the user guide's scripting pages and the Scripting Guide):

After Effects	EffectCraft
Effect plug-ins (C/C++ SDK, .aex / .plugin)	Effect plug-ins: WebAssembly modules (plug-in API v1) or Rust; the Plug-ins folder next to the settings loads at start-up	Different ABI: After Effects SDK plug-ins can't run (G8)
Scripts folder: its scripts are listed in File ▸ Scripts	Scripts/ in the settings folder (File ▸ Scripts ▸ Install Script File… copies a script there), listed in File ▸ Scripts with the bundled samples; a subfolder (one level) is a submenu named after it	Same
File ▸ Scripts ▸ Run Script File… (.jsx, .jsxbin)	.jsx / .js	Gap: .jsxbin (an undocumented binary encoding)
File ▸ Scripts ▸ Recent Script Files: the 10 most recently run scripts; Cmd+Option+Shift+D (Ctrl+Alt+Shift+D on Windows) reruns one	File ▸ Scripts ▸ Recent Script Files lists the 10 scripts run last (script files and File ▸ Scripts entries, newest first, kept in the settings); Cmd+Alt+Shift+D runs the most recent one again (file.runScript {"recent": 0}, a key that can be changed in Edit ▸ Keyboard Shortcuts)	Same
ExtendScript preprocessor directives (#include, #target, #targetengine)	#include / //@include / #includepath inline files relative to the script (once each, depth-limited, file gate applies); #target, #targetengine, #strict are ignored	Same
Scripts/Startup and Scripts/Shutdown: run in alphabetical order when the app starts and quits	Scripts/Startup/ and Scripts/Shutdown/ in the settings folder, in alphabetical order (case ignored): the Startup scripts run at launch before a project opens, and the Shutdown scripts run as the desktop app quits, after the project is closed. A Startup script that fails is reported in a toast and in the log, a Shutdown script that fails is reported in the log, and the next script still runs	Partial: each script runs in its own global scope, so variables and functions a Startup script defines are not available to later scripts; a Startup script's modal dialog stays open while the next scripts run and the app starts; a Shutdown script's modal dialogs close as if canceled; the web app runs no Shutdown scripts
Scripts/ScriptUI Panels: listed at the bottom of the Window menu, dockable like the app's own panels, this is the panel	Scripts/ScriptUI Panels/ in the settings folder (File ▸ Scripts ▸ Install ScriptUI Panel… copies one there), listed at the bottom of the Window menu (a subfolder, one level, is a submenu named after it), docked like any panel, this is the panel; the panels open when the app quits open again at the next launch	Same. Where a panel was docked isn't kept: workspace layouts aren't saved between launches
Keyboard shortcuts for scripts (the Keyboard Shortcuts editor lists the scripts of the Scripts folder)	Edit ▸ Keyboard Shortcuts lists the scripts of File ▸ Scripts under File ▸ Scripts (file.runScript {"name": "<file name>"}); a key given to one is saved with the preset, File ▸ Scripts shows it, and pressing it runs the script as its menu entry does	Same. After Effects binds a key to a script's place in the alphabetical list (ExecuteScriptMenuItem01…), and EffectCraft binds it to the script's file name. The Window menu entries of ScriptUI panels aren't offered
Running a script from the command line (afterfx -r script.jsx)	effectcraft-cli script, the control channel's and MCP's script.run	Same purpose, other entry points
app.settings (kept in the preferences between sessions)	Kept in script_settings.json in the settings folder (script.settings.get / script.settings.save)	Same
Allow Scripts to Write Files and Access Network	Settings ▸ Scripting & Expressions	Same

The settings folder is ~/Library/Application Support/EffectCraft on macOS, %APPDATA%\EffectCraft on Windows and $XDG_CONFIG_HOME/effectcraft (or ~/.config/effectcraft) on Linux (preferences.md); the web app keeps it in browser storage.

Scripts

Scripts use After Effects' scripting object model (app, app.project, CompItem, layers, Property with keyframes and eases, app.beginUndoGroup…), so most scripts written for After Effects' documented API run unchanged. Every edit a script makes is an engine command: undoable, journaled and the same as the UI's action. The effectcraft-script crate's docs (crates/script/src/lib.rs) list the object model.

• Run one: File ▸ Scripts ▸ Run Script File…, the Script Console panel, effectcraft-cli script file.jsx, or script.run {code, name} over the control channel and MCP.
• Install one: File ▸ Scripts ▸ Install Script File… (or copy it into Scripts/ in the settings folder). It is listed in File ▸ Scripts at once (After Effects asks for a restart).
• Run one at every launch or quit: copy it into Scripts/Startup/ or Scripts/Shutdown/ in the settings folder. These scripts are not listed in File ▸ Scripts. file.runStartupScripts and file.runShutdownScripts run them and return {ran, waiting, failed}; the desktop app calls them at launch and quit, and the web app calls file.runStartupScripts at launch.
• file.scripts.list lists installed and bundled scripts and panels; file.runScript {name} runs one; file.uninstallScript {name} removes an installed one.
• A subfolder of Scripts/ is a submenu of File ▸ Scripts named after the folder, and its scripts are named Folder/File.jsx in file.scripts.list and file.runScript. One level of folders is listed; deeper folders are not. file.uninstallScript removes only scripts at the top of the Scripts folders: delete a script in a subfolder yourself. A subfolder may be a link to another folder (an extension's own), and uninstall never deletes a file through it.

ScriptUI panels

A ScriptUI panel is a script that builds its user interface into the panel it is given as this. Put it in Scripts/ScriptUI Panels/ in the settings folder (or use File ▸ Scripts ▸ Install ScriptUI Panel…) and it is listed at the bottom of the Window menu under its file name; choosing it runs the script and docks its panel as a tab, which you can move, float, maximize and close like any other panel. Closing the tab closes the panel (its onClose runs). Panels open when EffectCraft quits open again at the next launch (window.restoreScriptPanels, which the desktop and web apps run at start-up; the list is scriptui_panels.json in the settings folder).

To group panels, for example the several panels of one extension, make a subfolder of Scripts/ScriptUI Panels/ and put them in it: Scripts/ScriptUI Panels/My Tools/Animate.jsx is listed as Window ▸ My Tools ▸ Animate.jsx, its tab is titled Animate, and commands name it My Tools/Animate.jsx (window.scriptPanel {name}). One level of folders is listed. Install ScriptUI Panel… copies a panel to the top of the folder; make the subfolder and move panels into it yourself, and delete them from it yourself too.

Run from File ▸ Scripts instead, the same script gets no panel, so it should make a floating palette itself. A minimal panel:

// Nudge.jsx: moves the selected layers 10 px right, as a dockable panel.
(function (thisObj) {
  var ui = thisObj instanceof Panel ? thisObj : new Window("palette", "Nudge", undefined, { resizeable: true });
  ui.orientation = "column";
  ui.alignChildren = ["fill", "top"];
  var go = ui.add("button", undefined, "Nudge Right", { name: "nudge" });
  var status = ui.add("statictext", undefined, "Select layers, then click.");
  go.onClick = function () {
    var comp = app.project.activeItem;
    if (!(comp instanceof CompItem)) return;
    var layers = comp.selectedLayers;
    app.beginUndoGroup("Nudge Right");
    for (var i = 0; i < layers.length; i++) {
      var p = layers[i].transform.position;
      var v = p.value;
      if (p.numKeys === 0) p.setValue([v[0] + 10, v[1]]);
    }
    app.endUndoGroup();
    status.text = "Moved " + layers.length + " layer(s).";
  };
  if (ui instanceof Window) ui.show(); else ui.layout.layout(true);
})(this);

Supported controls: panel, group, button, iconbutton, statictext, edittext, checkbox, radiobutton, slider, scrollbar, progressbar, dropdownlist, listbox, tabbedpanel / tab and image, with ScriptUI's automatic layout (orientation, alignChildren, alignment, margins, spacing, preferredSize), resource strings, event handlers (onClick, onChange, onChanging, onClose, addEventListener) and onDraw with ScriptUIGraphics. Mouse events (addEventListener("mousedown" | "mouseup" | "mousemove" | "mouseover" | "mouseout" | "click", handler, capture?)) reach the control under the pointer and its containers (capture, target, bubble; stopPropagation()), with a MouseEvent carrying clientX/clientY relative to the target, button, detail (click count) and the modifier keys. Agents use a panel like a user: scriptui.list, scriptui.get (its controls), scriptui.click, scriptui.set, scriptui.mouse and scriptui.close; every control has the automation id scriptui.<window>.<control id or name>. The bundled sample Layer Tools.jsx (crates/engine/scripts/ScriptUI Panels/) and the Ease Presets extension below are longer examples.

Bundled extensions

Optional tools that ship with EffectCraft but are not part of its core: they are scripts on the public scripting API, like the third-party scripts After Effects users install, and are listed with the bundled samples (file.scripts.list reports them as extension). A script of the same name in your Scripts folders takes their place.

Ease Presets (extensions/scriptui-panels/Ease Presets.jsx)

Window ▸ Ease Presets.jsx: easing curves kept by name and applied to the sides of selected keyframes (#254; it was a core panel in v0.6.0). A curve is the out side of a segment's first key and the in side of its second, in the Keyframe Velocity dialog's terms: influence in percent, and speed relative to the segment's average speed (1 = as fast as a straight line, 0 = at rest), so one curve fits any duration and change of value.

• Click a preset to apply it to the selected keyframes of each selected property, in one undo step. Ease chooses the sides (#1329): In eases each key's incoming side with the curve's in side, Out its outgoing side with the curve's out side, In-Out (the default) both. A side is eased when it has a neighbouring keyframe, selected or not (the neighbour doesn't change), with its speeds scaled to the segment on that side: per dimension, and along the motion path for spatial properties. So a single keyframe works, a selected pair gets the whole curve, and the first and last keys ease the side that has a segment. The side not eased keeps playing as it did (a Hold stays a Hold). Roving keyframes are skipped, and the status says how many: they pass speed straight through, so an ease on one wouldn't play (turn off Roving to ease it). The keys stay selected, so you can try another.
• The drawing shows the working curve; type its numbers (Out % and Speed, In % and Speed) and click Apply, or click From Keys to read the curve between the first selected pair of neighbouring keys.
• Save keeps the working curve under the typed name (replacing a preset of that name); Rename and Delete act on the selected preset of your own. The twelve built-in presets can't change.
• User presets are kept with app.settings (section Ease Presets, key userPresets, in script_settings.json in the settings folder). Presets saved by the v0.6.0 core panel (ease_presets.json) move there the first time a later version loads its settings; the old file is left as it was.

It uses only After Effects' documented scripting API (comp.selectedProperties, Property.selectedKeys, keyInTemporalEase / keyOutTemporalEase, setTemporalEaseAtKey with KeyframeEase, setInterpolationTypeAtKey, app.settings, ScriptUI), so it is also a worked example of a keyframe tool.

Effect plug-ins

EffectCraft loads third-party effects through a small, versioned plug-in API (API version 2; WebAssembly ABI 1). A plug-in effect behaves exactly like a built-in one: it is listed in Effects & Presets (and the Effect menu) under its category, applied by id (effect.apply {"effect": "org.example.posterize"}) or display name, its parameters are ordinary properties (keyframes, expressions, Effect Controls, prop.set), and it is saved in projects by id.

There are two ways to write one:

	WebAssembly plug-in	Rust plug-in
What	a .wasm (or .wat) module	a type implementing effectcraft_effects::plugin::EffectPlugin
Loaded by	Effect ▸ Install Effect Plug-in… (copied into the Plug-ins folder next to the settings and loaded on every start-up), Effect ▸ Load Effect Plug-in… / effect.plugins.load {path | folder} (loads in this session only), the Plug-ins folder next to the settings at start-up, or effect.plugins.install {path | folder}	register_plugin(Arc::new(MyEffect)) in an app that links EffectCraft's crates
Sandbox	yes: no imports (no files, clock or network), fuel-limited, at most 1 GiB of memory, deterministic floats	none (it is your code)
Platforms	desktop and CLI (the wasmi interpreter, crate feature effectcraft-plugin/wasm); not the web build	everywhere

effect.plugins.list lists what is loaded: {api, wasm, plugins: [{id, name, category, version, author, source, params}]}.

The contract

• Pixels are premultiplied RGBA f32 (0–1; values may exceed 1 in 32 bpc projects), row major, processed in place. The buffer is the layer's (after masks and the effects above), possibly at preview resolution (scale = buffer pixels per layer pixel) and padded.
• Parameters arrive flattened to f64s in the order they are declared: slider, angle, checkbox (0 / 1) and popup (0-based index) take one value, point two (already in buffer pixels), colour four (RGBA 0–1).
• Time is layer time in seconds.
• Rendering must be deterministic and may run on several threads at once (a WebAssembly plug-in gets one instance per thread).
• A failed render (an error code, a trap, running out of fuel) leaves the frame unchanged.

The manifest

Every plug-in describes itself with a JSON manifest:

{
  "api": 1,
  "id": "org.effectcraft.example.posterize-bands",
  "name": "Posterize Bands",
  "category": "Stylize",
  "version": "1.0.0",
  "author": "EffectCraft contributors",
  "description": "Quantizes luminance into tinted bands.",
  "params": [
    {"id": "levels", "name": "Levels", "type": "slider", "default": 4, "min": 2, "max": 64, "sliderMax": 16, "decimals": 0},
    {"id": "mix", "name": "Tint Amount", "type": "slider", "default": 50, "min": 0, "max": 100},
    {"id": "tint", "name": "Tint", "type": "color", "default": [1.0, 0.55, 0.2, 1.0]},
    {"id": "invert", "name": "Invert Bands", "type": "checkbox", "default": false}
  ]
}

• id: stable, reverse-domain; letters, digits, ., _, -. ec. is reserved for built-ins. Ids must be unique (a second plug-in with a taken id is refused).
• category: one of the Effects & Presets categories (Blur & Sharpen, Stylize, …) or a new one, which appears after the built-in categories.
• Parameter types: slider (default, min, max, optional sliderMin, sliderMax, decimals), angle (default degrees), checkbox (default bool), popup (options, default index), point (default as fractions of the layer size, [0.5, 0.5] = centre), color (default RGBA 0–1). Parameter ids are letters, digits and _, unique; at most 256 parameters; a slider needs min ≤ default ≤ max (and sliderMin ≤ sliderMax); the manifest is at most 1 MiB.

WebAssembly ABI (v1)

A module with no imports that exports:

export	signature
memory	memory	linear memory shared with the host
ec_api_version	() -> i32	must return 1
ec_manifest_ptr, ec_manifest_len	() -> i32	the UTF-8 JSON manifest in memory
ec_alloc	(bytes: i32) -> i32	a buffer of at least bytes bytes, 8-byte aligned; it may reuse the previous one
ec_render	(pixels: i32, width: i32, height: i32, params: i32, nparams: i32, time: f64, scale: f64) -> i32	process the pixels in place; return 0 on success

For each frame the host calls ec_alloc once for a buffer holding the parameters (nparams little-endian f64s) followed by the pixels (width × height × 4 little-endian f32s), fills it, calls ec_render, and reads the pixels back. Each call gets a fuel budget proportional to the frame size; a module that loops forever stops with an error instead of hanging the app.

Example

examples/plugins/posterize-bands is a complete plug-in in plain Rust (no dependencies):

cd examples/plugins/posterize-bands
cargo build --release --target wasm32-unknown-unknown
# then, in EffectCraft: Effect ▸ Install Effect Plug-in…
#   → target/wasm32-unknown-unknown/release/posterize_bands.wasm  (copied into Plug-ins, loads on start-up)
# or in-session only: Effect ▸ Load Effect Plug-in…
# or headless:
effectcraft-cli exec effect.plugins.load '{"path": "target/wasm32-unknown-unknown/release/posterize_bands.wasm"}'

Bundles. effect.plugins.install {"folder": ...} installs a whole plug-in folder in one go: every .wasm at its top level is copied into the Plug-ins folder (and loads at once), and every .jsx at its top level is installed as a ScriptUI panel — so a third-party plug-in ships as one folder the user installs once. A .wasm that does not load is not copied (the install rolls it back), and per-file problems in a folder install come back in errors instead of failing the whole bundle.

What an install does and does not do. It is a security boundary: it copies code into a folder the app runs at every start, so:

• Only .wasm (path / a bundle's .wasm) and .jsx (a bundle's panel) are installed; other files in a bundle (readmes, manifests, sources) are skipped. Files are named by their own entry name, so a bundle cannot carry a path, a .. component or a name that escapes the destination folder.
• Nothing is overwritten. An existing plug-in or panel with the same file name makes that file fail with "already installed": delete it from Plug-ins / Scripts/ScriptUI Panels first to update it (versioning the file name is the other option). A bundle is installed file by file, so one collision does not undo the rest.
• Files over 64 MiB are refused before they are read, rather than copied into a startup folder.
• A .wasm is loaded once, in the same sandbox it runs in later (see below), so a module that cannot load is reported instead of failing every start. That load runs the module's start-up code and its metadata exports; ec_render is never called, and a panel's script is not run at install time (it runs when the panel opens, as with any installed panel). The copy made before the load is then removed again — best effort: if removing it fails, the command says so and names the file, and you delete it from Plug-ins yourself.
• A .wasm is uninstalled by deleting it from Plug-ins (the next start no longer loads it): there is no effect.plugins.uninstall. A panel installed here is an installed script, so file.uninstallScript {name} removes it. Replacing either means removing it first.
• Hidden files (names starting with ., such as macOS ._x.wasm copies) are skipped in a bundle and refused as a single install. A panel name that differs from an installed panel's only in letter case counts as the same name.
• Installed plug-ins share the Plug-ins folder with the Plug-in Library (which keeps its packages in Plug-ins/Library). An effect id can be registered only once: a plug-in whose id is already loaded, from either kind of install, is refused. At start-up the files installed here load before the library's packages, so if both carry the same id (for example after files were copied by hand), the file here wins and the library package reports the duplicate.

The sandbox. A plug-in runs in the wasmi interpreter with no imports (no file, network or clock access), deterministic floats, a fuel budget per frame and a 1 GiB memory cap, so a plug-in cannot escape the sandbox, hang the app or render differently on another machine. A ScriptUI panel is different: it is a script with the app's scripting object model, so it can read and write project data through commands; file and network access for scripts follow Settings ▸ Scripting & Expressions, exactly as for a script installed with File ▸ Scripts ▸ Install ScriptUI Panel….

Any language that compiles to WebAssembly works (C, Zig, AssemblyScript…) as long as the module has no imports. crates/plugin/src/tests.rs has a plug-in written directly in WebAssembly text.

Rust plug-ins

use std::sync::Arc;
use effectcraft_effects::plugin::*;

struct Swap(PluginManifest);

impl EffectPlugin for Swap {
    fn manifest(&self) -> &PluginManifest { &self.0 }
    fn render(&self, frame: &mut PluginFrame, params: &PluginParams, _time: f64) -> Result<(), String> {
        if params.b("on") {
            for p in frame.pixels.iter_mut() { p.swap(0, 2); }
        }
        Ok(())
    }
}

register_plugin(Arc::new(Swap(manifest)))?; // before the UI builds its menus

PluginParams reads values by parameter id (f, b, point, color, and in API 2 point3, layer, text). At most 1024 plug-in effects can be registered per process.

Plug-in API 2 (native plug-ins)

API 2 is for Rust plug-ins and for hosts that bring effects from elsewhere (such as external effect helpers); the WebAssembly ABI stays at 1. Manifests with "api": 1 or 2 are accepted, effect.plugins.list reports api: 2, and up to 1024 plug-in effects can be registered.

• New parameter types: point3 (default [x, y, z]; x, y arrive in buffer pixels, z as is), layer (another layer of the composition; flattens to its id, -1 for none, read with PluginParams::layer), text (a string field) and hidden (a string that is not shown, for opaque plug-in data). text / hidden take no slot in flat; their strings are in PluginParams::texts, one per such parameter in declaration order, read with PluginParams::text(id). slider gains "integer": true (shown with 0 decimals) and every parameter an optional "group" path ("Advanced/Edges"; informational). WebAssembly modules can't use point3, layer, text or hidden.
• PluginFrame also carries origin (buffer pixels of layer pixel (0, 0); padding shifts it) and layer_size (layer pixels).
• EffectPlugin::padding(params, time, scale, layer_size, instance_key) -> u32 asks for that many transparent buffer pixels on every side before rendering (glows, regions of definition larger than the input); at most 4096. layer_size is the layer's size in layer pixels (so sizes relative to the frame can be measured) and instance_key identifies the applied effect instance (see PluginHost::instance_key).
• EffectPlugin::render_v2(frame, params, time, host) (default: calls render) gets a PluginHost with input_at(layer_time) (the effect's input at another time, in its own extent; the effects above this one are applied), layer_input(param_id, layer_time) (a layer parameter's layer, effects and masks applied, resampled into the frame's grid), params_at(layer_time), frame_rate(), time(), instance_key() (a stable id of the applied effect instance: the same on every frame, different per layer and per application; plug-ins that keep state between frames pool their native instances by it) and frame_range() (the layer's source time range in layer-time seconds, None when it has none). Images are PluginImage { width, height, pixels, origin, scale }. It may run on several threads at once.

Compatibility

The API version is checked when a plug-in loads: a manifest or module for another version is refused with a message. Within a version the contract above does not change; additions (new parameter types, new optional exports) bump the version.

Plug-in Library

Settings ▸ Plug-in Library (also Effect ▸ Plug-in Library…) lists WebAssembly effect plug-ins published by the community, and installs, updates and removes them without bundling them into the app. Only WebAssembly effects are listed: they run in the same sandbox as any plug-in, so a package can't read files, open the network or crash the app.

• One reviewed catalog. The list comes from one index.json in the storytold/effectcraft-plugins repository; packages are added by pull request and reviewed there. The app has no field for another catalog; library.refresh {catalog} (for plug-in authors testing an entry) takes an index.json on GitHub or a local file, and the page then says it shows a test catalog until Refresh.
• Nothing is downloaded until you ask. Fetch Catalog (library.refresh) reads the catalog; Install (library.install) downloads the package's .wasm, checks its SHA-256 (and its size, when the catalog gives one) against the catalog and loads it. Downloads use the system's curl, https:// only and starting on GitHub's hosts (redirects stay on https://; the SHA-256 check is what guarantees the file).
• Where it goes. <Plug-ins>/Library/<id>/<version>/<id>.wasm (the Plug-ins folder next to the settings), listed in Library/installed.json. Installed packages load at start-up, each checked against the SHA-256 it was installed with. The catalog last fetched is kept as Library/catalog.json, so the list works offline.
• Restart after removing or updating. Registered effects can't be unloaded: removing or updating a package whose effects are loaded takes effect at the next start, and the list says "Restart EffectCraft to finish".
• Preview before installing. Preview (library.preview) downloads the package's module (checked against the catalog's size and SHA-256) without installing it, and renders its effect in the sandbox on a built-in sample frame with default parameters: 2 seconds at 12 fps, with a Before/After split. The details show it playing, the effects with their parameter names, "Open on GitHub" (the package's repo) and, when the package has a preview.video link (an https:// YouTube, Vimeo or GitHub URL), "Watch video".
• Missing effects. library.missing lists the effects a project uses that aren't installed, and the catalog packages that provide them.

Commands (UI, CLI, control channel and MCP): library.list {query?, tag?, installed?}, library.refresh {catalog?, wait?}, library.preview {id, version?, wait?}, library.install {id, version?, wait?}, library.update {id?, wait?}, library.uninstall {id}, library.missing, library.loadInstalled. Downloads run in the background; wait: true runs them to the end (scripts and tests).

Publishing a plug-in

publishing-plugins.md walks through it from an empty folder to a listed package: build, test, release on GitHub, the catalog entry and its fields, testing the entry with a local file:// catalog, the pull request and its review, updates and removal.