Plugin API

A plugin is a single .sshowplugin file: a renamed zip file that holds the manifest (plugin.json) and one UI document. An icon is optional. The editor uses only these files. The 13 plugins use the same format.

When you click a plugin in the list, the editor opens a separate floating panel next to the list and loads the UI document in a sandboxed frame inside it. The SSHOWPlugin SDK and the editor’s theme styles go in before the document’s scripts, so your script can call SSHOWPlugin.connect() from the start.

A plugin reaches the editor only through the functions in the tables below. Every function returns a Promise, and applyActions is the only way to change the document. The AI Assistant and AI apps (Connect an AI app (MCP)) change the document with the same actions.

All you need is a text editor and a zip tool. You build a Hello plugin that adds one text object to the canvas when you click a button.

Five fields are required, and three are optional. Unknown fields are ignored, so a manifest with newly added fields still opens in older editors.

In the title row of a running plugin’s panel, click the Plugin info button (an i in a circle) to see the version, author, ID, and description.

Every read function returns a copy as of that moment. Changing the copy doesn’t change the document. To make a change, send it with applyActions.

For images, video, and audio, data.src comes as an asset:// URL for a project asset, and you read the bytes with assets.get. A long src that isn’t an asset (such as a data: URL) comes as a placeholder that records only its length (src len=… kind=…), so don’t send it back. Web requests in interactions come with the values in their URLs and their header values masked.

document.applyActions(actions, label) is the only way to change the document. It applies the actions in the array in the order written, and the whole call becomes one undo step (one ⌘Z). label is that step’s name, and if you leave it empty, the plugin’s name is used.

It returns { applied, skipped, ids }. applied is the number of actions applied. skipped holds { index, op, id, code, reason } for each skipped action. Even if some actions are invalid, the rest are still applied.

In a create action, config.id is an alias for this call only. Later actions in the same array can refer to that object by the alias. The engine sets the real id, which comes back paired with the alias in ids.objects, ids.scenes, or ids.variables. From the next call on, use the real id. Name aliases like 'bar'. If you use the engine’s id pattern, like o1 or s2, and the engine happens to create that same id, the alias is left out of ids.

Writes take the same path as edits you make by hand in the editor. In Animation mode, when Auto-keyframe is on, values such as position, size, and opacity are recorded as keyframes at the playhead. To edit keyframes, see Work with keyframes.

If set contains even one unknown key, the whole action is skipped, and the reason goes into skipped. For any action without sceneId, the target is the scene that’s current when you call. After create_scene or duplicate_scene, the current scene switches to the new one, so give sceneId to write to the original scene in the next call.

This example puts an action that creates an object and an action that edits it in one call. 'bar' is an alias for this call only, and after the call, ids.objects.bar is the real id.

As in Hello’s Script 2, write the code below inside an async function, where the api you got from connect() is available. Writing await at the top level, outside a function, causes a syntax error.

transform.x and y are the position of the object’s anchor point, and a shape’s anchor point is at its center by default (anchorX and anchorY 0.5). So this bar spans from (340, 180) to (460, 420).

You read the bytes of images, video, and audio by their asset:// URLs, and you register new bytes to get a URL. A plugin that edits the selected image first reads the image’s data.src with getSelection. It gets the bytes with assets.get, edits them, registers the result with assets.register, and then changes data.src to the new URL with update_object.

Put the URL you get into an action right away. Assets that aren’t used anywhere may be cleaned up.

Closing the panel also discards the plugin’s document, so values kept in script variables are gone when you open it again. Keep values that must last, like options, in storage. localStorage isn’t available inside the frame, so the editor keeps one record per plugin id on its behalf.

The record lives in the app, not in the document. Every project you open in this app sees the same record, and it isn’t saved in .sshow files. Web, desktop, and tablet keep separate records, and importing the same id again doesn’t erase the record. Put anything that must stay with the document into objects with applyActions.

Listen with events.on(type, callback), and stop with events.off(type, callback). The callback receives no value. It’s a signal to read again, so when it arrives, read again with the read functions. Types other than the three below are rejected, and all subscriptions end when the plugin stops.

Request a UI size with ui.resize(size). A single number is the height, and { width, height } sets whichever sides you include. The panel starts 340px wide and 52% of the window height, and it resizes only between 280 × 240px and 90% of the window. A requested size stays, as if the user had resized the panel.

The UI document gets the editor’s design values as the CSS variables below, and they follow the same light or dark setting as the editor. Use them like var(--sshow-primary), and the panel changes along with the theme with no extra code. Scrollbars are the same 6px bars as in the editor, and if you write your own ::-webkit-scrollbar rules, yours take priority.

ui.getTheme() returns { mode, colors, borderRadius, fontSize }. mode is 'light' or 'dark'. Use it only when your script needs color values, such as when drawing on a canvas element.

Editor shortcuts keep working even when the plugin UI has focus. Keys the plugin doesn’t handle go on to the editor: ⌘Z undoes, Tab switches the edit mode, and Space pans the view (a short press plays the timeline in Animation mode). So inside the UI, Tab can’t move focus and Space can’t press buttons.

To use a key in your plugin, stop it before it reaches window. For keys your script handles itself, call preventDefault(). For keys that should keep a browser default, like moving focus or pressing a button, call stopPropagation() in both keydown and keyup. preventDefault() stops that default too. The SDK forwards keys from window, so attach your listeners to document or an element, not to window. While an input, a textarea, or a contenteditable element has focus, no keys are forwarded.

A plugin runs in a sandboxed frame, separate from the editor. The limits below protect the documents and accounts of the people who use plugins.

There are two ways to check a plugin in the editor again after you change it. You can import the file again anywhere, and in the Windows desktop app you can also have the app watch a folder.

A published plugin goes into the plugin list in Studio, where anyone can install it. A person reviews every version before it’s published.