Plugins

A Premation plugin is a native plugin: a compiled library, with a small manifest beside it, that runs inside the engine process on your own computer. It is built against the native plugin SDK, which is modelled on the After Effects plugin API — effects with parameters, smart render, sequence data, layer checkouts and a GPU path, plus menu commands, footage importers and output modules — so an After Effects plugin author will find their way around.

What a plugin can add

An effect can read the composition’s camera and lights, other layers’ transforms, its own parameters at other times (for trails and its own motion blur), the composition’s scene depth (so a model passes behind the comp’s 3D layers), and images and files beside a model it loads. It can draw beyond its layer’s bounds, or over the whole composition frame. The model3d sample in the SDK shows all of it together — a glTF model drawn through the comp camera and lights, with motion blur and occlusion — the class of plugin After Effects users know as Element 3D.

Parameters are declared by the plugin and evaluated by the engine, so a plugin parameter is an ordinary effect property: it keyframes, takes expressions, copies and pastes, saves with the project and undoes like a built-in one.

Commands and panels change the project only through the engine’s own API, as ordinary edits: one run of a command is one undo entry, and a command that fails or crashes leaves the project as it was. There are no custom layer types.

The plugin store

In the installers, the store is on the dashboard: Dashboard ▸ Plugins, with three sections — Store, Installed and Publish.

• Store. Search, or filter by Free / Premation Cloud. A plugin’s page shows its icon and screenshots, About, what it adds (effects, commands, import and export formats, panels), the platforms it runs on, the SDK it was built for, its licence, and every version with its release notes. A Verified badge marks a publisher the store has verified.
• Install. The app downloads the package, checks its size, its SHA-256 and the publisher’s signature, and remembers that publisher’s key for this plugin — a later version signed with a different key is refused unless the store reports an authorised key change. The engine then rescans, and the plugin’s effects are in Effects & Presets without a restart.
• Updates. An installed plugin with a newer version shows Update to version, with “What’s new” from the publisher’s release notes. A plugin that is already running is replaced when the engine next starts; on Windows the row says Restart to finish until then.
• A plugin with no build for your computer says Not for this computer rather than offering an install.

The local edition, built from source, makes no requests to our servers, so it has no store and no dashboard. Install from a file or a folder there, below.

Installing from a file or a folder

A .pplugin file. Double-click it, or use Dashboard ▸ Plugins ▸ Installed ▸ Install from file…. Premation checks the package and shows who signed it, what it adds and what it can access before anything is installed:

A package whose signature does not verify, that is signed with a different key than the one this machine remembers, that has no build for this computer, or that has been revoked is refused outright.

A bundle folder. A bundle is a folder holding a premation-plugin.json and the binary it names. Copy it into the plugins folder and press Rescan on the Installed page — it loads without a restart.

The engine also reads a machine-wide folder that a vendor’s own installer can write to — %ProgramData%\Premation\Plug-ins on Windows, /Library/Application Support/Premation/Plug-ins on macOS — and any folders named in the PREMATION_PLUGIN_PATH environment variable (;-separated), which is the route for a plugin author testing a build in place.

Managing installed plugins

The Installed page and the editor’s Plugins panel (Window ▸ Panels ▸ Plugins, or Plugins ▸ Manage Plugins…) list every plugin the engine found, whether or not it loaded, with its name, version and vendor. Each row has a switch to turn the plugin on or off, Update when a newer version is in the store, and Uninstall for a plugin installed from the store or a file. An uninstalled plugin is removed when the engine next starts (“Removed on restart”). A plugin copied in by hand is removed by taking its folder out.

A malformed manifest, a missing binary for your platform, or an SDK version the engine does not accept leaves the plugin Failed with that reason — and none of its code has run, because the manifest is read and checked before the binary is loaded. A plugin that is not loaded adds nothing: its commands leave the Plugins menu, its formats the import picker and the Render Queue, its panels the dock.

The Plugins menu

The Plugins menu sits before Window and appears once a loaded plugin offers a command or a panel. Each plugin’s commands are in a submenu, its panels under Panels, and Manage Plugins… opens the Plugins panel. A command works on the selected layers in the active composition, and its result is reported in a notification.

Premation Cloud plugins

Premation’s own plugins — starting with a 3D model renderer in the Element 3D class — are included with Premation Cloud; every third-party plugin stays free. In the store they carry a Premation Cloud badge, and on a Free account the install button is Get Premation Cloud.

On an account without the plan, such a plugin is listed as Requires Premation Cloud and is not loaded. Nothing in the project is lost: its effects pass through — the layer renders as if the effect were off — the effect card and the viewer say why, an export passes it through the same way, and every value stays in the file. After upgrading, Check plan on the plugin’s row confirms the plan, and the plugin loads the next time Premation starts.

Projects, exports and missing plugins

• An effect from a plugin that is not installed, not loaded or switched off is kept in the project file and passes through, and the effect card says why, so it is all still there when the plugin comes back.
• Exports render plugin effects — the export starts its own plugin host over the same folders, so the file matches the viewer. Footage read by a plugin importer, and its sound, export too.
• Server renders do not run plugins. A project that uses plugin effects is refused before it is sent, naming the plugins; export it on your computer instead.
• Collect Files carries a model or other file a plugin effect uses, and the files beside it that the plugin lists (a glTF’s .bin and textures).

What the host guarantees

A plugin is native code running in the engine, so the engine is built to contain it rather than trust it:

A crash of the engine process restarts the engine, not the app — see When the engine stops.

A GPU effect gets the same treatment on its GPU path: the work runs inside an error scope, a GPU error drops that frame’s commands unsubmitted, and the effect renders on its CPU path for that frame instead.

What the host does not do is sandbox a plugin’s access to your machine. It is native code loaded into the engine, with the operating-system permissions the engine has, and the install dialog says so. A plugin’s panel is different: it is a page shown in a sandbox with no network, no storage and no access to the computer, talking to the editor only through messages. Install plugins from people you trust, as you would in any other native creative application.

What happened to the old plugin system

The JavaScript/WGSL plugin system — plugin.json packages with an entry module in a Worker, WGSL effect kernels, panels, custom layer types, and the registry behind them — was removed in 0.9.0. There is no version of it in the new engine, and the store lists native plugins only.

A project that used it still opens, and nothing is deleted. Since 1.0 the effects and layers that came from the old system are kept in the project, exactly like effects from a native plugin that is not installed: an effect passes through (its layer renders as if it were off), the reason is recorded on the layer’s error list, a layer from an old plugin layer type draws nothing and is marked in the Layers panel, and saving writes all of it back unchanged. After the project opens, one notice names the missing plugins and says how many effects and layers are kept. (In 0.9 this content was removed in one undoable step when the project opened.)

On the dashboard, people who used the old registry see a one-time notice that the store is back for native plugins and that JavaScript plugins no longer run.

Related

• Writing a native plugin
• Publishing a plugin
• The effect stack