Files

209 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).