EN Editor Plugins

Editor Plugin API v2 and the plugin catalog

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Native plugins can add palette components, graph node types, actions and docks. The plugin API version is 2 and the interface IID is dev.jsonapiforge.EditorPlugin/2.0. This system is separate from project Python hooks and SDK adapters.

Package layout and manifest

Place NAME.forgeplugin.json alongside the native library. Both can reside at the ZIP root or inside a single portable top-level directory. Replace the placeholder hash below with the final binary's real SHA-256:

{
  "id": "vendor.plugin-name", "name": "Plugin Name", "version": "1.0.0",
  "apiVersion": 2, "library": "PluginName.so",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "permissions": ["workspace.read", "graph.nodes.register"]
}

Use .dll on Windows and .dylib on macOS. The digest must be lowercase. The library must remain within the manifest directory and must not be a symlink. IDs/permissions are lowercase dotted identifiers; the permission list is limited to 32 entries.

Import and activation

1. Review publisher, source, platform and ABI compatibility.
2. Select Plugins → Import plugin from ZIP….
3. Import does not enable the plugin.
4. In Plugins → Manage plugins…, review ID, version, hash and permissions, then enable it separately.
5. Use Reload approved plugins if needed.

The ZIP importer allows at most 256 entries, a 64 MiB archive, 64 MiB per file and 128 MiB expanded data. It checks compression ratios, CRC, paths, duplicates/case collisions, manifest and library digest/API. Traversal, absolute paths and symlinks are rejected.

Native development contract

ForgeEditor::IEditorPlugin requires pluginId, displayName, apiVersion, initialize(EditorHost*, QString*) and shutdown. QObject metadata/interface declarations must match the actual IID. Host usage includes:

host->addPaletteComponent("Queue", "Resources", queueFragment);
host->addGraphNodeType("Queue Publish", "vendor.queue.publish", defaultProperties);
host->addToolAction(action);
host->addDockWidget(Qt::RightDockWidgetArea, dock);
host->showStatusMessage("Queue tools ready");

This is an API excerpt, not a complete plugin project. Match Qt version, compiler ABI, operating system, CPU and plugin API. A matching API number does not make MinGW/MSVC or Linux/macOS binaries interchangeable.

Native plugins run with the desktop user's privileges. Manifest permissions are not an OS sandbox. SHA-256 establishes integrity, not publisher identity. Use a trusted signed distribution channel and review native code.

Forge-backed catalog

The catalog is an ordinary GET /api/<project>/v1/<resource>?limit=100&offset=0 resource. Records contain plugin_id, name, version, publisher, HTTPS download_url, sha256, permissions and enabled. The UI reads at most 100 records/2 MiB and validates URL, digest and identity fields.

Selecting a catalog entry copies its URL. It does not automatically download, install or enable native code; the explicit ZIP-import flow remains necessary. EditorPluginRegistry provides the metadata backend. Binary hosting and publisher signatures are separate concerns.

Custom graph nodes can remain on the canvas without acquiring compilation support. The current compiler rejects them as design-only. A reviewed export action can emit ordinary Forge fragments for the standard validation flow.

Alongside your plugin's own license, check rights to redistribute protected Editor code/branding. Third-party dependencies retain their respective terms.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• Editor/editor/plugins/README.md
• Editor/editor/include/forgeeditor/IEditorPlugin.hpp
• Editor/editor/src/PluginManager.cpp
• Editor/editor/src/SafeZipReader.cpp
• Editor/editor/src/PluginCatalogClient.cpp

---

English home · All English pages · Version maintenance