Build a native plugin

A plugin is a shared library — a .dll on Windows, a .dylib on macOS — plus a small JSON manifest. The engine, the C++ process that draws every Premation frame, loads it and calls it. The API is modelled on After Effects' effect API, so if you have written an After Effects effect the selectors, the parameter types and the smart-render checkouts will be familiar.

1. What is in the SDK

The samples cover deliberately different parts of the API.

2. Build and run the samples

You need the repository and the native toolchain described in native/README.md: clang (clang-cl on Windows), CMake, Ninja and vcpkg. The samples build with the engine, from the native directory.

# Windows
cmake --preset windows-clang-cl-engine
cmake --build --preset windows-clang-cl-engine

# macOS
cmake --preset macos-clang-engine
cmake --build --preset macos-clang-engine

1. 1

   Look in the build tree for a plugins folder.

   What happens Each sample is laid out as an installable bundle: plugins/<name>/ holding premation-plugin.json and the binary it names. The grade sample and the GPU half of checkout need Dawn's headers, so they appear only in the engine build.

2. 2

   Run premation-plugins --plugins <that folder> list.

   What happens Every plugin the engine finds is listed as loaded, disabled, failed (with the reason) or quarantined.

3. 3

   Run premation-plugins --plugins <that folder> --bits 32 render com.premation.samples.ripple.

   What happens Renders the effect at 32-bit float without an editor. Use --bits 8 or 16 for the other depths.

3. The manifest

{
  "manifestVersion": 1,
  "id": "com.example.glow",
  "name": "Example Glow",
  "version": "1.2.0",
  "vendor": "Example",
  "sdk": { "major": 1, "minor": 0 },
  "binary": { "windows": "glow.dll", "macos": "libglow.dylib", "linux": "libglow.so" },
  "effects": [ { "matchName": "com.example.glow", "name": "Glow", "category": "Example" } ]
}

4. The entry point

A module exports one symbol, PremationPluginInfo, which lists its effects. Each effect has its own entry function, which receives a selector and dispatches on it. This is ripple's, trimmed to its shape; the prs:: helpers are the samples' own convenience layer in samples/common, not part of the SDK.

#include <premation_sdk/premation_sdk.h>

PrErr PR_CALL ripple_main(PrCmd cmd, const PrInData* in, PrOutData* out,
                          PrParamDef* const* params, PrWorld*, void*) {
  switch (cmd) {
    case PR_CMD_ABOUT:
      prs::message(out, "Ripple 1.0 — Premation SDK sample (CPU effect, 8/16/32 bpc).");
      return PR_ERR_NONE;
    case PR_CMD_GLOBAL_SETUP:
      out->my_version = PR_VERSION(1, 0, 0);
      out->out_flags = PR_OUT_FLAG_DEEP_COLOR_AWARE | PR_OUT_FLAG_FLOAT_COLOR_AWARE |
                       PR_OUT_FLAG_SMART_RENDER | PR_OUT_FLAG_THREADED_RENDER;
      return PR_ERR_NONE;
    case PR_CMD_PARAMS_SETUP:      return params_setup(in);
    case PR_CMD_SMART_PRE_RENDER:  return in->host->checkout_layer(in->host_ref, 0, 0, in->current_time, nullptr);
    case PR_CMD_SMART_RENDER:      return smart_render(in, out, params);
    default:                       return PR_ERR_NONE;
  }
}

const PrEffectEntry kEffects[] = {{"com.premation.samples.ripple", &ripple_main}};
const PrPluginInfo kInfo = {sizeof(PrPluginInfo), PR_SDK_VERSION,
                            "com.premation.samples.ripple", 1, kEffects};

extern "C" PR_EXPORT const PrPluginInfo* PR_CALL PremationPluginInfo(void) { return &kInfo; }

The plugin id and the match names in that table must equal the manifest's. The selectors map one to one onto After Effects':

Out flags declare what the effect can do: DEEP_COLOR_AWARE (16-bit), FLOAT_COLOR_AWARE (32-bit float), SMART_RENDER, GPU_RENDER, SEQUENCE_DATA, GENERATOR, WIDE_TIME_INPUT, NON_PARAM_VARY, SEND_UPDATE_PARAMS_UI and THREADED_RENDER.

5. Parameters

Parameters are declared, and the engine keyframes and evaluates them. At every render the plugin receives each parameter's value at that frame's time; it never interpolates anything itself. In the project each parameter is an ordinary effect property, so undo, keyframes, expressions, copy and paste, save and open, and change events work as they do for a built-in effect.

Parameter flags include CANNOT_ANIMATE, SUPERVISE, HIDDEN, START_COLLAPSED and DISABLED.

6. Pixels and time

Checkouts at another time are resolved from the frame itself, so a frame stays a pure function of the document: preview, export and a restarted engine render the same pixels.

7. Sequence data and buttons

Per-instance state lives in the project, not only in the process. Adding the effect runs SEQUENCE_SETUP, FLATTEN and SETDOWN and stores the flat bytes with the effect in the same undo entry. A render rebuilds the instance from those bytes whenever they change. A button press produces new bytes and any parameter writes as one undo entry, so undo brings back the old bytes and the old bytes render the old picture. This is how the rings sample keeps its palette: shuffle, undo and redo all render exactly.

8. A GPU effect

An effect with GPU_RENDER records WebGPU commands into the host's command encoder, on the engine's own Dawn device. The input is the effect chain's texture as it is, the output is a texture the host owns, and nothing is copied or read back.

premation-render --plugins <dir> renders a scene that contains plugin effects outside the editor, and --plugin-gpu 0 forces the CPU path so you can compare the two.

9. Plugins that are not effects

Since SDK 1.2 a bundle can list commands, importers, export formats and panels in its manifest, with or without effects. They map onto the After Effects plugin classes that are not effects.

A bundle can also ship presets (listed under its effect in the Effects browser) and draw on-canvas handles that drag its parameters. The distribute, ppmio, ppmseq and statspanel samples show one of each kind.

10. What happens when it crashes

Every selector call runs through a guard and a crash journal. Each sample has a Debug ▸ Fault popup that injects each class of fault, and the host tests use it to prove every row below in a child process.

A quarantined plugin is listed but not loaded. Re-enabling it through the engine API retries it and clears the quarantine. On macOS a stack overflow is reported as an access violation, because both arrive as SIGSEGV.

premation-plugins --plugins <dir> crash-check com.premation.samples.ripple 2   # 2 = access violation

11. Install a bundle

1. 1

   Copy the bundle folder — premation-plugin.json and its binary together — into the plugins folder inside the app's user-data directory. In the installers, Dashboard ▸ Plugins ▸ Installed ▸ Open plugins folder opens it.

   What happens The desktop app passes that folder to the engine as native-plugins. A folder may be a bundle itself or a folder of bundles. Load order is sorted, so it is deterministic.

2. 2

   Or set PREMATION_PLUGIN_PATH to one or more folders, separated by semicolons.

   What happens The engine scans those as well, along with a machine-wide Plug-ins folder that a vendor's installer can write to.

3. 3

   Click Rescan on the Installed page, or restart Premation.

   What happens A new bundle loads without a restart. The engine lists every plugin as loaded, disabled, failed or quarantined; a failed plugin says why and none of its code has run. An update or removal of a plugin that is already loaded applies at the next start.

To hand a plugin to someone else, node scripts/pack-plugin.mjs <bundle> --key <key.json> packs it into a signed .pplugin. They install it with Install from file or a double-click, and the dialog names the publisher, what the plugin adds and how far its signature can be trusted before anything is installed. The Publish section of Dashboard ▸ Plugins lists it in the store, where every third-party plugin is free; a new public plugin needs a verified publisher.

The plugins folder works the same in the installers and in a build made from the repository; the store and publishing need the installers' account. A project that uses a plugin that is missing, disabled or locked keeps the effect's data, passes the layer through and says why, ready for when the plugin comes back.

What is not here

Settled decisions, so you do not plan around them. A plugin cannot add a custom layer type, and there is no scripting language like ExtendScript: automation is a C++ command or a panel that sends engine commands. After Effects, OpenFX and FxPlug plugins do not load. The store only opened with 1.0, so its catalogue is young. The JavaScript plugin permissions model is gone with the system it belonged to, and crash guards are not a security sandbox. If you need any of those today, After Effects has them.

Next guide