Publishing a plugin
A native plugin reaches other people in one of three forms:
| Form | How people install it |
|---|---|
| The plugin store | Dashboard ▸ Plugins ▸ Store ▸ Install — downloaded, checked and loaded without a restart |
A signed .pplugin file | Double-click it, or Install from file…. The file carries its own signature, so the install dialog can say who made it |
| A bundle folder | Copied into the plugins folder, then Rescan |
Plugins describes each from the installing side. Third-party plugins in the store are free; there is no price, licence key or payout anywhere in it.
Build against the released SDK
Each Premation release attaches the plugin SDK for every platform a plugin may
target — premation-sdk-windows-x64.zip, premation-sdk-macos-arm64.zip,
premation-sdk-macos-x64.zip and premation-sdk-linux-x64.zip — on
GitHub Releases . Each holds
the headers, a CMake package (find_package(PremationSdk) with
premation_add_plugin(), which lays the bundle out for you), the
premation-plugins test tool, the samples, and the pack and sign scripts.
Writing a native plugin covers the API.
Ship a binary for every platform you support. The manifest’s binary entry
names one library per platform key, and the engine takes the most specific key
for the machine it runs on:
| Machine | Keys tried, in order |
|---|---|
| Windows x64 | windows-x64, windows |
| macOS, Apple silicon | macos-arm64, macos-universal, macos |
| macOS, Intel | macos-x64, macos-universal, macos |
| Linux x64 | linux-x64, linux |
On a machine with no matching key the plugin is listed as Failed (“no usable binary for platform”), with none of its code run, and the store shows it as Not for this computer. Premation itself is released for Windows and macOS.
examples/plugin-ci/ in the editor repository is a complete plugin repository:
an example effect and a GitHub Actions workflow that builds the three platforms
against the SDK, merges them, packs, signs and publishes on a tag.
Pack and sign
Make a signing key, once
node sign-plugin.mjs keygen --out plugin-key.jsonKeep this file, and keep it private. It is the only thing that can ship an update: Premation remembers a plugin’s key when it is first installed and refuses a later package signed with another.
Pack the bundle
node pack-plugin.mjs <bundle-folder> --key plugin-key.jsonThe packer checks the manifest the way the engine will, refuses unsafe or
unexpected files, records the SHA-256 of every file in the manifest, and zips the
bundle deterministically — the same folder always packs to the same bytes. It
writes <id>-<version>.pplugin, signed inside, and a detached
<id>-<version>.pplugin.sig for the store. --only-present packs a build from
one operating system, dropping the platform keys whose binary is not there.
A package may hold up to 2,000 files, 128 MB per file and 256 MB in all. An installer refuses a package whose files do not match the hashes in its manifest exactly — a file missing, extra or changed.
Publish to the store
Publishing needs a Premation account. In Dashboard ▸ Plugins ▸ Publish:
- Choose the package (
.pplugin) and its signature (.sig). The signing key itself never enters the app. - Choose Private or Public. A private plugin is visible to, and installs for, its publisher only — useful for testing the store install on your own machines. Making a plugin public needs a verified publisher; the store refuses otherwise, and you can switch visibility later from Your plugins.
- Optionally write release notes for this version, in Markdown. They are shown as “What’s new” on the plugin’s page and with the update offer to everyone on an older version.
- Publish. The version number comes from the package and must be higher than the one already published.
sign-plugin.mjs publish <x.pplugin> --token <access token> does the same from a
script or CI, with --visibility private|public.
The listing
Open a plugin under Your plugins to edit what people read before they install it. The listing lives outside the signed package, so it can change without a new version:
| Item | Rules |
|---|---|
| Icon | Square PNG, JPEG or WebP, at least 256 × 256, up to 2 MB |
| Screenshots | Up to three images, up to 2 MB each |
| About | Markdown — what it does, how to use it, what it is good for |
| Release notes | Per version, editable after publishing |
Before you hand one over
Everything below is checkable on your own machine, without an editor, using
the premation-plugins
tool.
| Check | Why |
|---|---|
list shows the plugin loaded | Proves the manifest parses, the id and match names are valid and agree with what the module reports, and the SDK version is accepted |
render at --bits 8, 16 and 32 | An effect is handed a different pixel depth in projects of different bit depths, depending on the flags it set |
crash-check with each fault | Shows that a fault in your render code disables one instance rather than the engine — and tells you honestly what a hang or an abort() costs |
Run it once with the GPU path off (--plugin-gpu 0 on premation-render) if you ship a GPU effect | The CPU fallback is what renders whenever the GPU path errors, so it has to give the same picture |
Install the .pplugin itself, through Install from file… or a private store listing | Proves the package, its signature and every platform key are what you think they are |
Naming and versions
- The plugin
idis permanent. Match names are the id or<id>.<name>, and a project stores an effect by its match name. If you rename it, projects made with the old name keep the effect in the file but can no longer find its plugin. versionis yours;sdkis the contract. Build against one SDK major and setsdk.majorandsdk.minorto what you built with. The host loads a plugin whose major equals its own and whose minor is no greater than its own. The SDK in this release is 1.2; 1.0 and 1.1 plugins keep loading.- Do not change parameter ids between versions. Each parameter is stored in the document under its id.
Signing on macOS
The macOS engine is packaged with library validation switched off, which is what
lets it load a native plugin signed by its author rather than by Premation.
Sign your own binary with your own Developer ID, as you would for any macOS
library. A plugin installed from the store or from a .pplugin has the macOS
quarantine flag removed from its files, since you chose to install it. This page
does not document what macOS does with an unsigned library on a given machine,
because that is a property of the operating system rather than of Premation —
and note that Premation’s own macOS builds are currently unsigned (see
Updates & macOS setup).