When a package names a `repo` that isn't a GitHub repository URL (`https://github.com/<owner>/<repo>`, a trailing `/` or `.git` allowed, or a folder in one, `.../tree/<ref>/<path>`), Install, Update and Preview now refuse its release URLs with an error naming the package. Before, such a `repo` skipped the repository check and any GitHub release asset was downloaded. A package without a `repo` keeps any repository's release asset. The example catalog's schema now holds `repo` and release `url` to the same forms, and `scripts/validate.sh` checks that every release is an asset of the package's `repo` before it downloads anything.
18 KiB
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
.wasmfile) 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 RGBAf32pixels, 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:
Cargo.toml: changename(the.wasmfile is named after it, with-turned into_),description,versionandlicense. Keepcrate-type = ["cdylib"]and the release profile (panic = "abort"keeps the module small and import-free).- The manifest (the
MANIFESTstring insrc/lib.rs):id: your own, reverse-domain (io.github.yourname.glow-rings): letters, digits,.,_,-. It must be unique among all plug-ins, andec.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 areslider,angle,checkbox,popup,pointandcolor; the fields and limits are in The manifest.
ec_render: the parameters arrive asf64s 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, return0. Checknparamsbefore 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.
- Commit everything, including
Cargo.lock. - Tag the version (
git tag v1.0.0) and push the tag. - Create a GitHub release for the tag and attach the
.wasmas 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, as https://github.com/<owner>/<repo> (a trailing / or .git is allowed), or a folder in it, https://github.com/<owner>/<repo>/tree/<ref>/<path>. The details' "Open on GitHub" opens it. When repo is given in any other form, Install and Preview refuse every release of the package. |
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: https://github.com/<owner>/<repo>/releases/download/<tag>/<file>. When the package has a repo, the asset must be in that repository. Install and Preview refuse any other https:// URL. |
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 onhttps://; 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,
minApporsha256, or nourl. The rest of the catalog still works. - EffectCraft installs the newest release whose
apiit implements and whoseminAppit meets. When the newest release needs a newer EffectCraft,library.listsays so (needsNewerApp). - The download must match
sha256(andsize, 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.refreshreads 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.listshows your package as users will see it (latest,effects,needsNewerApp).library.previewdownloads the module, checks it againstsizeandsha256, 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) andanimated(the frames differ over time).library.installinstalls 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
- Fork
storytold/effectcraft-plugins. - Add your package to
packagesinindex.json. Keep the file's formatting. - 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.
licenseis an open-source licence and the repository has its text. - Public source.
repois 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.installfrom a local catalog shows it. - Ids. The package id and effect ids are your own, follow the rules, don't start with
ec., andeffectsmatches the manifest'sid. - 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
- Change the code, raise the version in
Cargo.tomland in the manifest, build, and publish a new GitHub release (a new tag; never re-use an old one). - Add a new object to
versionswith the newversion,url,sha256,sizeandeffects. Keep the old entries: they may stay, and users of an older EffectCraft still get a release they can run (setminAppon the new one if it needs a newer app). - Test it with a local catalog as in step 8 (
library.updateupdates 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.missinglists 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.