v1.2.1

Mac & Linux: re-download every update

Skip to Content
Customising & extendingPublishing a plugin

Publishing a plugin

A native plugin reaches other people in one of three forms:

FormHow people install it
The plugin storeDashboard ▸ Plugins ▸ Store ▸ Install — downloaded, checked and loaded without a restart
A signed .pplugin fileDouble-click it, or Install from file…. The file carries its own signature, so the install dialog can say who made it
A bundle folderCopied 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:

MachineKeys tried, in order
Windows x64windows-x64, windows
macOS, Apple siliconmacos-arm64, macos-universal, macos
macOS, Intelmacos-x64, macos-universal, macos
Linux x64linux-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.json

Keep 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.json

The 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:

  1. Choose the package (.pplugin) and its signature (.sig). The signing key itself never enters the app.
  2. 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.
  3. 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.
  4. 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:

ItemRules
IconSquare PNG, JPEG or WebP, at least 256 × 256, up to 2 MB
ScreenshotsUp to three images, up to 2 MB each
AboutMarkdown — what it does, how to use it, what it is good for
Release notesPer 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.

CheckWhy
list shows the plugin loadedProves 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 32An effect is handed a different pixel depth in projects of different bit depths, depending on the flags it set
crash-check with each faultShows 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 effectThe 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 listingProves the package, its signature and every platform key are what you think they are

Naming and versions

  • The plugin id is 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.
  • version is yours; sdk is the contract. Build against one SDK major and set sdk.major and sdk.minor to 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).

Last updated on