> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin System Overview

> Extend Mudstack with custom plugins: thumbnailers, context menu commands, automation, and integrations. Learn how the plugin system works and where to start.

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](https://github.com/mudstack/mudstack-plugins)** – 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)](https://www.npmjs.com/package/@mudstack/plugins)** – 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

* [Create your first plugin](/developer/creating-a-plugin) – Step-by-step from template to a running plugin.
* [How the plugin system works](/developer/plugin-system-architecture) – Discovery, process isolation, and messaging.
* [Plugin lifecycle](/developer/plugin-lifecycle) – States, activate/deactivate, and cleanup.
* [Plugin API reference](/developer/plugin-api) – Events, db, config, execute, and inter-plugin calls.
* [Plugin ideas](/developer/plugin-ideas) – A long list of concrete plugins you can build.