Skip to main content
The Mudstack plugin system lets you extend the desktop app with custom behavior: generate thumbnails for asset types, add context menu actions, react to file and plugin events, call external tools, and integrate with your pipeline—all without modifying Mudstack’s core code.

​
Resources

  • mudstack-plugins repo – Template and example plugins. Fork or use as a template to start a new plugin. The repo root is the plugin template; the examples/ folder has reference plugins (e.g. hello-world, context-menu-example).
  • @mudstack/plugins (npm) – Official package that provides the MudstackPlugin base class and TypeScript types for the Plugin API. Use it in your plugin for full IntelliSense and a consistent lifecycle.

​
How it works (high level)

  1. Discovery – Mudstack scans configured plugin directories (e.g. user plugins folder, built-in plugins). Each plugin is a folder containing a manifest (manifest.json or plugin.json) and an entry point (e.g. index.js).
  2. Isolation – Each plugin runs in its own Node.js child process. The main app communicates with plugins over a message bus (IPC). This keeps a buggy or heavy plugin from crashing the app.
  3. Lifecycle – For enabled plugins, the runtime resolves dependencies, spawns the child process, loads your module, instantiates your class with the Plugin API, then calls activate(). On disable or shutdown it calls deactivate() and tears down the process.
  4. API – Your plugin receives a typed api object (this.api): logging, events (subscribe/emit), database access (accounts, workspaces, libraries, tags, assets, versions), config (get/set/validate), dependency checks, inter-plugin requests, and script/command execution (Node, Python, shell, etc.).

​
What you can build

  • Thumbnailers – Register as a thumbnail generator for specific file types (e.g. .fbx, .gltf). When Mudstack needs a thumbnail, your plugin gets the file path and writes an image; the app displays it.
  • Context menu commands – Add menu items when users right-click assets or folders. Declare commands in the manifest; when the user runs one, an event is emitted and your handler runs (e.g. “Export to Unity”, “Run validation”).
  • Event-driven automation – Subscribe to events such as file.created, file.newVersion, plugin.activated. React by updating tags, calling external tools, or sending notifications.
  • Integrations – Use api.db to read/write workspace and asset data, and api.execute* to run scripts or binaries. Build integrations with your engine, DCC tools, or CI/CD.
  • Pipeline plugins – Combine several of the above: e.g. on new version, generate a thumbnail (if you’re the thumbnailer), run a validator, and post to Slack via a script.

​
Next steps