effectcraft/docs/publishing-plugins.md

Publishing an effect plug-in

This guide takes you from an empty folder to an effect listed in EffectCraft's Plug-in Library (Settings ▸ Plug-in Library, also Effect ▸ Plug-in Library…). The reference for the plug-in API is plugins.md; this page is the walk-through.

If you only want to use plug-ins, skip to For users.

What a plug-in is

• A plug-in is one WebAssembly module (a .wasm file) that adds one effect. It is listed in Effects & Presets under its category, its parameters are ordinary properties (keyframes, expressions, Effect Controls), and projects save it by its id.
• It runs in a sandbox. The module may not import anything: no files, no clock, no network, no random numbers. Each render gets a fuel budget, and memory is capped at 1 GiB. A plug-in that loops forever or traps stops with an error; it can't crash the app.
• It implements plug-in API version 1: a JSON manifest and five exports (memory, ec_api_version, ec_manifest_ptr / ec_manifest_len, ec_alloc, ec_render). The ABI and the contract (premultiplied RGBA f32 pixels, processed in place, deterministic) are in plugins.md.
• Any language that compiles to WebAssembly without imports works. This guide uses Rust, because the example is in Rust.
• The Plug-in Library is in the desktop app and the CLI. The web build has no plug-ins.

1. Start from the example

examples/plugins/posterize-bands is a complete plug-in in plain Rust with no dependencies. Copy it into a new folder (and a new Git repository):

cp -r effectcraft/examples/plugins/posterize-bands my-effect
cd my-effect
rm -rf target
git init

The folder has its own [workspace], so it builds on its own, outside the EffectCraft repository.

Then make it yours:

1. Cargo.toml: change name (the .wasm file is named after it, with - turned into _), description, version and license. Keep crate-type = ["cdylib"] and the release profile (panic = "abort" keeps the module small and import-free).
2. The manifest (the MANIFEST string in src/lib.rs):
   • id: your own, reverse-domain (io.github.yourname.glow-rings): letters, digits, ., _, -. It must be unique among all plug-ins, and ec. is reserved for built-in effects. Never change it after release: projects find the effect by this id.
   • name: the name shown in Effects & Presets.
   • category: an existing Effects & Presets category (Stylize, Blur & Sharpen, …) or a new one.
   • version: the same version as the release (1.0.0).
   • author, description.
   • params: one entry per control. Types are slider, angle, checkbox, popup, point and color; the fields and limits are in The manifest.
3. ec_render: the parameters arrive as f64s in the order they are declared (a point takes two values, a colour four), then the pixels. Read them by position, change the pixels in place, return 0. Check nparams before you read, as the example does, and return non-zero if something is wrong: the frame is then left unchanged.

Keep ec_api_version, ec_manifest_ptr, ec_manifest_len and ec_alloc as they are.

Things that break the sandbox rule (the module then imports something and won't load): printing (println!), reading the time (std::time), random numbers (getrandom, rand with its default features), and crates that need wasm-bindgen. If you need randomness, derive it from the pixel position, the time and a seed parameter, so the result stays deterministic.

2. Build

rustup target add wasm32-unknown-unknown       # once
cargo build --release --target wasm32-unknown-unknown

The module is target/wasm32-unknown-unknown/release/<name>.wasm.

3. Test it in EffectCraft

Load the module straight from the build folder:

• Desktop: Effect ▸ Load Effect Plug-in… and pick the .wasm. Apply the effect to a layer, move every control, scrub the time, and try a 32 bpc project if your effect can see values above 1.

• CLI:

  effectcraft-cli exec effect.plugins.load '{"path": "target/wasm32-unknown-unknown/release/my_effect.wasm"}'
  

  The reply describes the effect, or says why the module was refused (a missing export, an import, a bad manifest, another plug-in with the same id).

To have it at every start, put the .wasm in the Plug-ins folder of the settings folder.

4. Check the live preview

Every package in the Plug-in Library gets a live preview: you do nothing to get it. EffectCraft downloads the module (without installing it) and renders your effect in the sandbox on a built-in sample frame (320 × 180: a colour gradient, two discs and a band of fine stripes), with the default parameters, for 2 seconds of animation (12 frames per second), with a Before/After split.

So choose defaults that show what the effect does at a glance. An effect whose defaults do nothing (a strength of 0, an "Enable" checkbox that is off) previews as an unchanged frame. If your effect animates over time, the 2 seconds show it. A render that fails in the preview shows as an error.

You can see the preview before you publish, with a catalog on your disk: see step 8.

5. Publish a GitHub release

The source repository must be public on GitHub, with a licence file.

1. Commit everything, including Cargo.lock.
2. Tag the version (git tag v1.0.0) and push the tag.
3. Create a GitHub release for the tag and attach the .wasm as an asset.

The download URL is then https://github.com/<you>/<repo>/releases/download/v1.0.0/my_effect.wasm.

Never replace an asset after it is listed. The catalog pins its SHA-256; a different file fails every install. Fix a mistake with a new version.

Reviewers rebuild the module from the tagged source and compare checksums, so make the build reproducible: commit Cargo.lock, pin the Rust version with a rust-toolchain.toml ([toolchain] channel = "1.95.0", targets = ["wasm32-unknown-unknown"]), and build with cargo build --release --locked --target wasm32-unknown-unknown. Building the release in GitHub Actions from the tag is the easiest way to show the asset comes from the source.

6. Compute the checksum and size

The catalog needs the file's SHA-256 (64 lower-case hex digits) and its size in bytes. Use the file you attached to the release (download it again if in doubt).

System	SHA-256	Size in bytes
Linux	sha256sum my_effect.wasm	stat -c %s my_effect.wasm
macOS	shasum -a 256 my_effect.wasm	stat -f %z my_effect.wasm
Windows (PowerShell)	(Get-FileHash my_effect.wasm -Algorithm SHA256).Hash.ToLower()	(Get-Item my_effect.wasm).Length

7. Write the catalog entry

The catalog is one index.json in the storytold/effectcraft-plugins repository. A starting point for that repository (an example entry, a JSON Schema and the checks run on every pull request) is in examples/plugin-catalog.

Your entry is one object in packages:

{
  "id": "io.github.yourname.glow-rings",
  "name": "Glow Rings",
  "author": "Your Name",
  "description": "Adds soft concentric rings of light around bright areas.",
  "license": "MIT",
  "repo": "https://github.com/yourname/glow-rings",
  "tags": ["stylize", "light"],
  "preview": {"video": "https://www.youtube.com/watch?v=XXXXXXXXXXX"},
  "versions": [
    {
      "version": "1.0.0",
      "api": 1,
      "minApp": "0.17.0",
      "url": "https://github.com/yourname/glow-rings/releases/download/v1.0.0/glow_rings.wasm",
      "sha256": "<64 hex digits>",
      "size": 18342,
      "effects": ["io.github.yourname.glow-rings"]
    }
  ]
}

Package fields:

Field	Required	What it is
id	yes	The package id: 1 to 100 characters, letters, digits, ., - and _; no leading dot and no ... It is also the folder name on users' disks. Unique in the catalog; usually the same as the effect id. Never change it.
name	yes	The name shown in the list. Not empty.
author	no	You, or your group.
description	no, but reviewed	One or two plain sentences that say what the effect does.
license	no, but reviewed	The licence's SPDX id (MIT, Apache-2.0, MIT OR Apache-2.0…).
repo	no, but reviewed	The public source repository. The details' "Open on GitHub" opens it.
tags	no	Lower-case words for the tag filter (blur, stylize, light, distort…). Reuse tags the catalog already has.
preview.video	no	An https:// link to a short demo video on YouTube, Vimeo or GitHub. "Watch video" opens it in the browser. A link that isn't https:// (or is longer than 500 characters) is left out. The live preview doesn't need it.
versions	yes	One entry per release, newest or oldest first.

Release fields (one per entry in versions):

Field	Required	What it is
version	yes	Dotted numbers only, at most 32 characters: 1.0.0, 1.2. No v and no suffixes such as -beta.
api	yes	The plug-in API the module implements: 1.
minApp	no	The oldest EffectCraft version the release needs (0.17.0). Leave it out if any version with this API works.
url	yes	The release asset's https:// URL on GitHub.
sha256	yes	The file's SHA-256, 64 hex digits.
size	no, but reviewed	The file's size in bytes. When it is given, a download of another size is refused.
effects	yes	The effect ids the module registers (its manifest's id). EffectCraft uses them to find the package that provides an effect a project needs.

The rules EffectCraft applies when it reads the catalog:

• Downloads are https:// only, from GitHub's hosts only: github.com, raw.githubusercontent.com, and the hosts release assets redirect to (objects.githubusercontent.com, release-assets.githubusercontent.com). Any other URL is refused. Redirects may lead elsewhere but stay on https://; the SHA-256 check is what guarantees the file.
• The catalog may be at most 4 MB and a module at most 64 MB.
• A package with a bad id, no name, or an id another package already uses is left out; so is a release with a bad version, minApp or sha256, or no url. The rest of the catalog still works.
• EffectCraft installs the newest release whose api it implements and whose minApp it meets. When the newest release needs a newer EffectCraft, library.list says so (needsNewerApp).
• The download must match sha256 (and size, if given) exactly, or it is refused.

8. Test the entry locally

Before you open a pull request, test the entry with a catalog on your own disk. A local catalog (file://) may also name local files, so you can test before you publish the release: point url at your built module, then switch to the GitHub URL.

Make a folder with an index.json that holds only your package:

{"schema": 1, "packages": [ { "id": "io.github.yourname.glow-rings", "…": "your entry" } ]}

File URLs are absolute: file:///home/me/glow-rings/index.json on Linux and macOS, file:///C:/Users/me/glow-rings/index.json on Windows. Write a space as %20.

Use a separate settings folder, so the test doesn't touch your real installation:

export EFFECTCRAFT_CONFIG_DIR="$PWD/ec-test"           # PowerShell: $env:EFFECTCRAFT_CONFIG_DIR = "$PWD\ec-test"
effectcraft-cli exec library.refresh '{"catalog": "file:///home/me/glow-rings/index.json", "wait": true}'
effectcraft-cli exec library.list
effectcraft-cli exec library.preview '{"id": "io.github.yourname.glow-rings", "wait": true}'
effectcraft-cli exec library.install '{"id": "io.github.yourname.glow-rings", "wait": true}'

• library.refresh reads the catalog and keeps a copy, so the next commands (separate runs of the CLI) see it. A malformed entry is left out and logged with the reason.
• library.list shows your package as users will see it (latest, effects, needsNewerApp).
• library.preview downloads the module, checks it against size and sha256, and renders the preview without installing anything. A wrong checksum fails here. The reply has the frame size (320 × 180), the frame count, the effect's manifest, and two checks: changes (the effect changes the sample frame with its defaults) and animated (the frames differ over time).
• library.install installs it into the test settings folder and loads it.

To look at the preview in the app, start the desktop app with the control channel (effectcraft --control 9877, with the same EFFECTCRAFT_CONFIG_DIR if you set one), point it at your catalog, then open Settings ▸ Plug-in Library and press Preview on your package:

effectcraft-cli exec library.refresh '{"catalog": "file:///home/me/glow-rings/index.json", "wait": true}' --bridge 9877

The Refresh button in the app goes back to the community catalog.

9. Open a pull request to the catalog

1. Fork storytold/effectcraft-plugins.
2. Add your package to packages in index.json. Keep the file's formatting.
3. Open a pull request. Say what the effect does and link the release. A screenshot or a short video helps the review.

The repository runs automatic checks on every pull request (see examples/plugin-catalog); a maintainer then reviews it by hand.

Review checklist

Reviewers check, and you can check first:

• Licence. license is an open-source licence and the repository has its text.
• Public source. repo is public and contains the plug-in's source at the release's tag.
• Reproducible. The module builds from that source (the steps are in the repository's README) and the result has the SHA-256 in the entry.
• No imports. The module imports nothing; EffectCraft refuses it otherwise. library.install from a local catalog shows it.
• Ids. The package id and effect ids are your own, follow the rules, don't start with ec., and effects matches the manifest's id.
• Sensible defaults. The effect does something visible with its defaults, so the live preview shows it, and no default makes it slow.
• Description. It says what the effect does, in plain words.
• Behaves. It renders without errors at different sizes and preview resolutions, and the same frame twice gives the same result.

10. Release an update

1. Change the code, raise the version in Cargo.toml and in the manifest, build, and publish a new GitHub release (a new tag; never re-use an old one).
2. Add a new object to versions with the new version, url, sha256, size and effects. Keep the old entries: they may stay, and users of an older EffectCraft still get a release they can run (set minApp on the new one if it needs a newer app).
3. Test it with a local catalog as in step 8 (library.update updates an installed package), and open a pull request.

Users see "Update" on the package. Keep the effect id and the meaning of existing parameters, so projects made with the old version still open the same. Add parameters at the end.

11. Remove a plug-in

Open a pull request that deletes your package from packages (or one release from versions). People who installed it keep their copy: it stays in their list as unlisted until they remove it. If a release is broken or unsafe, say so in the pull request so it is removed quickly.

For users

Settings ▸ Plug-in Library (also Effect ▸ Plug-in Library…):

• Fetch Catalog reads the community catalog. Nothing is downloaded before that. Refresh reads it again; the last one fetched is kept, so the list works offline.
• Preview shows a package's effect live on a sample frame (playing, with a Before/After slider) without installing it. The details list the effects and their parameters, and have "Open on GitHub" and, when the author added one, "Watch video".
• Install downloads the module, checks it against the catalog's size and SHA-256 and loads it: the effect is in Effects & Presets at once.
• Update (or Update All) installs a newer release. Remove deletes a package.
• Restart after updating or removing a package whose effects are loaded: loaded effects can't be unloaded, so the change takes effect at the next start, and the list says "Restart EffectCraft to finish".
• A project that uses an effect you don't have: library.missing lists the missing effects and the catalog packages that provide them.

The same commands work from the CLI, the control channel and MCP: library.list, library.refresh, library.preview, library.install, library.update, library.uninstall, library.missing, library.loadInstalled (plugins.md).

Where files live

Packages are installed in the Plug-ins/Library folder of the settings folder:

System	Settings folder
macOS	~/Library/Application Support/EffectCraft
Windows	%APPDATA%\EffectCraft
Linux	$XDG_CONFIG_HOME/effectcraft or ~/.config/effectcraft
Portable (a portable.txt beside the executable)	EffectCraftData beside the executable

EFFECTCRAFT_CONFIG_DIR overrides it. In Plug-ins/Library:

• <id>/<version>/<id>.wasm: each installed module.
• installed.json: what is installed, with the SHA-256 each module was installed with. At start-up each module is checked against it; a module that changed on disk isn't loaded (install it again).
• catalog.json: the catalog last fetched.