Skip to main content

Plugin Management

This page explains operational plugin workflows: importing, refreshing, opening plugin/data folders, deleting, and resetting.

Version

All workflows on this page are supported since 3.0.0-dev.4.

Quick Mental Model​

  • Source package: what you author (manifest + Lua or native library + optional assets/data)
  • Installed plugin: runtime-managed installed copy
  • Plugin data: runtime state/config/cache generated by plugin usage

Core manages installation and runtime storage. You should treat runtime paths as managed internals and avoid assumptions about directory names.

Import Queues​

There are two import queues with different behavior:

QueueTypical useSource after successful import
import/plugin/One-shot install/updateRemoved automatically
import/plugin-dev/Development iterationKept for future refreshes

Development Workflow​

  1. Put plugin source under import/plugin-dev/<type>.<id>/
  2. Click Refresh Plugins
  3. Test in UI
  4. Repeat

This gives a tight iteration loop without manual re-copying.

One-Time Install / Update Workflow​

  1. Put package under import/plugin/<type>.<id>/
  2. Click Refresh Plugins
  3. Verify plugin appears and works

Use this for manual distribution installs and scripted deployments.

Refresh Behavior​

When you refresh plugins:

  • Pending imports are processed
  • Plugin registries are reloaded
  • Device/plugin runtime is refreshed so updates are applied promptly
  • UI receives plugin-change notification
  • Native-c entries are loaded through a shadow copy cache, so an update can replace the original DLL/shared library without being blocked by the running process

If a plugin update changes runtime behavior (effects/controllers/extensions), refresh is the expected way to apply it.

Plugin Metadata You Can Rely On​

get_plugins returns additional operational metadata:

  • pluginDir: resolved plugin runtime directory
  • dataDir: plugin data directory (if present)
  • bundled: whether plugin is bundled
  • installSource: one of bundled | import | import-dev | package | manual

Use this metadata in tools and support workflows instead of guessing installation origin.

Bundled vs User-Installed Plugins​

Bundled Plugins​

  • Bundled with the app
  • Should be reset, not deleted
  • Can be overridden by user-installed versions and then restored via reset

User-Installed Plugins​

  • Can be deleted
  • Optional plugin data cleanup is supported during delete

Delete vs Reset​

Delete​

Use when you want to remove an installed user plugin.

  • Removes installed plugin copy
  • Optionally removes plugin data
  • For import-dev sources, deleting installed copy does not remove source package; it can be imported again on next refresh/startup

Reset​

Use when you want to discard user override and return to default/bundled behavior.

  • Removes installed override copy
  • Optionally removes plugin data
  • Bundled version is used again if available

Open Folder Operations​

From plugin management operations/API, you can open:

  • Plugin directory (global plugin root or specific plugin)
  • Plugin data directory (for a specific plugin)

Use these for diagnostics and migration, but avoid writing ad-hoc tooling that depends on runtime folder naming.

.skyignore for Import Packaging​

Plugin import supports .skyignore syntax compatible with .gitignore style patterns.

Typical use cases:

  • Exclude temporary build files
  • Exclude local debug artifacts
  • Keep package lean and predictable

Example:

*.tmp
*.log
build/
node_modules/
!important.log

For native-c source packages, exclude build directories such as target/, bin/, obj/, and keep the compiled artifact under the entry path declared in manifest.json.

Troubleshooting​

Plugin not visible after refresh​

  • Confirm folder name is <type>.<id>
  • Confirm manifest.json is valid
  • Confirm package is placed in the expected import queue
  • Check Core logs for manifest/runtime errors

Plugin keeps reappearing after delete​

Likely imported from import/plugin-dev/. Deleting installed copy does not remove development source package.

Plugin data not cleared​

Delete/reset only removes data when the corresponding deleteData/resetData option is enabled.

Wrong plugin version active​

Refresh plugins and check installSource + plugin metadata in get_plugins result to verify which copy is active.