mirror of
https://github.com/storytold/AniCraft.git
synced 2026-11-19 09:01:29 +01:00
209 lines
11 KiB
Markdown
209 lines
11 KiB
Markdown
# Plug-ins
|
||
|
||
Plug-ins add to AniCraft: generators that draw for you, effects that change the selection,
|
||
scripts that steer a movie while it plays, export formats and eases. This chapter shows how to
|
||
install, run and manage them, and what a plug-in is and isn't allowed to do.
|
||
|
||
On macOS, press ⌘ where this guide says Ctrl, and ⌥ where it says Alt.
|
||
|
||
## What a plug-in is
|
||
|
||
A plug-in is a single `.wasm` file (a WebAssembly module). The same file works on Windows, macOS
|
||
and Linux. There are four kinds:
|
||
|
||
* **Command plug-ins** appear in **Commands › Plug-ins**. A generator, such as a star field
|
||
scattered over the stage, works on its own. A selection effect, such as one that jitters the
|
||
selected shapes, needs something selected first.
|
||
* **Frame-script plug-ins** don't appear in the Commands menu. You pick one for a keyframe in the
|
||
Actions panel, and it runs while the movie plays in Test Movie. See
|
||
[Interactivity](interactivity.md) for keyframe actions.
|
||
* **Export-format plug-ins** appear in **File › Export**, below the built-in formats. See
|
||
[Exporting with a plug-in](#exporting-with-a-plug-in).
|
||
* **Ease plug-ins** add eases to every ease menu, under **Plug-in eases**. See
|
||
[Plug-in eases](#plug-in-eases).
|
||
|
||
A plug-in changes your document only through AniCraft's own commands, the same ones the menus
|
||
use. So everything it does is checked like any other edit, and the whole run is a single step
|
||
you can undo.
|
||
|
||
Plug-ins belong to AniCraft on your computer, not to a document. They stay installed when you
|
||
open or create documents, and a document never contains a plug-in.
|
||
|
||
## Installing a plug-in
|
||
|
||
1. Choose **Commands › Install Plug-in…**.
|
||
2. Pick the `.wasm` file.
|
||
3. AniCraft checks the file and copies it into its plug-ins folder. The status bar says
|
||
"Installed Star Field 1.0.0 — find it in Commands › Plug-ins" (with the plug-in's own name and
|
||
version).
|
||
|
||
If a plug-in with the same id is already installed, installing replaces it, and AniCraft asks
|
||
first because the old file is overwritten. The status bar then says "Updated".
|
||
|
||
You can also copy `.wasm` files into the plug-ins folder yourself and choose **Commands › Reload
|
||
Plug-ins**. Every `.wasm` in the folder loads when AniCraft starts. The folder is called
|
||
`plugins` and sits in AniCraft's settings folder:
|
||
|
||
| System | Plug-ins folder |
|
||
|---|---|
|
||
| Windows | `%APPDATA%\AniCraft\plugins` |
|
||
| macOS | `~/Library/Application Support/AniCraft/plugins` |
|
||
| Linux | `~/.config/anicraft/plugins` (or `$XDG_CONFIG_HOME/anicraft/plugins`) |
|
||
|
||
If a file can't be loaded, AniCraft starts anyway, skips it and names it in the status bar.
|
||
|
||
Only install plug-ins from people you trust, as you would with any download. The sandbox below
|
||
keeps them away from your files, but a plug-in can still change the open document in ways you
|
||
didn't expect. Undo puts it back.
|
||
|
||
## Running a plug-in
|
||
|
||
1. If the plug-in works on a selection, select some artwork first. Until you do, its menu item
|
||
is greyed out, and the tooltip says "Select some artwork first".
|
||
2. Choose it in **Commands › Plug-ins**, or press **Ctrl+K** and type its name: the command
|
||
palette finds plug-ins too.
|
||
3. A plug-in without settings runs straight away. One with settings (its name ends in "…") opens
|
||
a dialog first.
|
||
|
||
### The settings dialog
|
||
|
||
The dialog is built from the plug-in's own settings: sliders for numbers, checkboxes, menus for
|
||
choices and colour swatches.
|
||
|
||
* **Preview on the stage** is on, so every change you make shows on the stage at once.
|
||
* **OK** (or **Enter**) keeps the result.
|
||
* **Cancel** (or **Esc**) leaves the document exactly as it was.
|
||
|
||
Whatever you tried in the preview, OK records one undo step named after the plug-in. The status
|
||
bar says how to undo it, for example "Star Field — Ctrl+Z to undo".
|
||
|
||
Most plug-ins give the same result every time for the same settings. Plug-ins that scatter or
|
||
jitter usually have a **seed** setting: change it for a different arrangement.
|
||
|
||
## Managing plug-ins
|
||
|
||
Choose **Commands › Manage Plug-ins…** to open the Plug-ins window. It lists every installed
|
||
plug-in with its name, version, author, id and size, and its description.
|
||
|
||
* **Run** (or **Run…** for plug-ins with settings) runs it, as the menu does.
|
||
* **Remove…** uninstalls it. Because this deletes the plug-in's file from the plug-ins folder,
|
||
AniCraft asks first, and it can't be undone. Keep a copy of the `.wasm` if you might want it
|
||
again.
|
||
* **Folder** shows where the plug-ins folder is. **Show Folder** opens it on your computer.
|
||
* **Install Plug-in…** and **Reload** do the same as the Commands menu items.
|
||
|
||
When nothing is installed yet, the window says so: "No plug-ins installed yet".
|
||
|
||
## Exporting with a plug-in
|
||
|
||
1. Choose **File › Export** and the plug-in's format, for example **Plain Text Frames…**. Its
|
||
name is the plug-in's own; hover over it for its description.
|
||
2. The **Export** window shows the plug-in's options (as a settings dialog does), the
|
||
**Frames** to export (**All** sets the whole movie), and the **File**. **Browse…** picks the
|
||
file with your system's dialog.
|
||
3. Choose **Export** (or press **Enter**). A progress bar counts the frames while the plug-in
|
||
works, and you can keep editing. **Cancel** stops it, and nothing is written.
|
||
|
||
If the file is already there, the window asks before replacing it ("A file with this name is
|
||
already there. Replace it? This can't be undone."), and the button becomes **Replace**. When the
|
||
export is done, the window closes and the status bar says where the file went and how big it
|
||
is.
|
||
|
||
An export-format plug-in never sees your document. AniCraft hands it each frame as the stage
|
||
draws it (shapes, positions, colours) and writes the file it makes. In the Plug-ins window, such
|
||
a plug-in has an **Export…** button instead of Run.
|
||
|
||
## Plug-in eases
|
||
|
||
An ease plug-in adds its eases to the ease menu of the timeline, of **Properties › Frame** and of
|
||
the Motion Editor, under **Plug-in eases**, as small curves under the plug-in's name. Click one to
|
||
ease the tween with it; the menu then shows its name, for example **Stepped 4**.
|
||
|
||
The tween keeps the curve itself, not a link to the plug-in. So your document plays the same on
|
||
a computer without the plug-in, and installing a newer version of the plug-in doesn't change
|
||
tweens you already eased (choose the ease again to take the new curve). In **Edit Ease…** a
|
||
plug-in's ease shows as its curve; adding or moving a point turns it into a custom ease drawn
|
||
like it.
|
||
|
||
## The sandbox: what plug-ins may do
|
||
|
||
Plug-ins run sandboxed. In the words of the Plug-ins window: they can change the open document
|
||
through AniCraft's commands, never your files.
|
||
|
||
A plug-in **can**:
|
||
|
||
* read the stage size, frame rate, scenes, layers and the current selection;
|
||
* read the elements on the active layer at the playhead;
|
||
* run AniCraft's editing commands: draw shapes, add layers, move, transform and recolour artwork,
|
||
add keyframes and so on, with the same checks as the menus;
|
||
* write lines to its own log, which AniCraft shows when the run fails.
|
||
|
||
A plug-in **cannot**:
|
||
|
||
* open, save, import or export files, or touch anything else on your disk;
|
||
* reach the network, the clock or other programs;
|
||
* install, run or remove plug-ins;
|
||
* undo or redo (the whole run is one undo step);
|
||
* cut, copy or paste: your clipboard stays yours;
|
||
* run anything that would need a "this cannot be undone" confirmation.
|
||
|
||
Each run starts fresh, so nothing a plug-in did last time carries over. A run also has limits on
|
||
how long it may take (5 seconds), how much memory it may use and how much it may add to the
|
||
document. If a plug-in goes over a limit, fails or crashes, the run stops, the document goes back
|
||
to how it was before the run, and the status bar says why.
|
||
|
||
While a command plug-in runs, AniCraft waits for it, at most for its time limit. Frame-script
|
||
plug-ins have much tighter limits per frame, and if one runs out the movie keeps playing. An
|
||
export runs in the background with more time (up to 10 minutes) and a limit on the size of
|
||
the file (64 MB). An ease plug-in's eases are worked out once, when it loads; one that gives
|
||
something that isn't a number, or doesn't start at 0 and end at 1, doesn't load, and the status
|
||
bar says which ease and why.
|
||
|
||
## Frame-script plug-ins
|
||
|
||
A frame-script plug-in reads where the movie is (frame, scene, pointer, which movie clips are
|
||
playing) and sends timeline actions back: stop, play, go to a frame or label, next or previous
|
||
frame or scene, trace a message, or set an instance's position, alpha, visibility, rotation or
|
||
scale. It never changes the document, so the stage and every export stay as you made them.
|
||
|
||
To use one:
|
||
|
||
1. Install it as above.
|
||
2. Select a keyframe and open the Actions panel (**Window › Actions**, **F9**).
|
||
3. Set **Type** to **Plug-in**, choose the plug-in, and pick its **Entry** point if it has
|
||
several.
|
||
4. Test the movie with **Control › Test Movie** (**Ctrl+Enter**). Messages from the script appear
|
||
in the Output panel.
|
||
|
||
The keyframe remembers which plug-in it runs, but the plug-in itself stays on your computer. If
|
||
you send the document to someone who doesn't have it installed, the Actions panel says so, and
|
||
Test Movie notes it and plays on without it.
|
||
|
||
## Plug-ins in other places
|
||
|
||
* **The web version** can't install, remove or reload plug-ins, because they live in a folder on
|
||
your computer. Use the desktop app.
|
||
* **On the command line**, plug-ins load only when you ask, so scripted runs are repeatable. See
|
||
[Working headless](working-headless.md). `anicraft-cli export --format <id>` exports with a
|
||
plug-in's format (or a built-in one), and `anicraft-cli formats` lists them.
|
||
|
||
## What isn't there yet
|
||
|
||
* Plug-ins that add panels or other parts of the interface.
|
||
* Plug-in formats in **File › Publish Settings**, and ease plug-ins with settings.
|
||
* Running a long command plug-in in the background with a progress bar and Cancel (exports
|
||
already do).
|
||
* A plug-in catalogue, signed plug-ins and per-plug-in permissions beyond the fixed rules above.
|
||
|
||
## For plug-in authors
|
||
|
||
Plug-ins can be written in any language that compiles to WebAssembly. The AniCraft repository
|
||
has a small Rust kit and four complete sample plug-ins: Star Field (a generator), Jitter
|
||
Selection (a selection effect), Plain Text Frames (an export format) and Stepped Eases (eases). The plug-in interface, the manifest that describes a plug-in's
|
||
settings, the exact limits and the frame-script requests are documented in
|
||
[the plug-in API on GitHub](https://github.com/storytold/AniCraft/blob/main/docs/plugins.md).
|
||
|
||
You can test a plug-in without installing it: point AniCraft at a folder of `.wasm` files with
|
||
the `ANICRAFT_PLUGINS` environment variable, then use **Commands › Reload Plug-ins** after each
|
||
build. Every command a plug-in can run is listed in [the command reference](reference/commands.md).
|