PLUGIN SDK

C# plugin SDK

Kroys.Plugins: commands, panels, settings pages, importers, exporters, asset types, viewport tools, background tasks and undoable scene edits for editor plugins written in C#.

NamespaceKroys.Plugins

AssemblyKroysPlugins.Sdk.dll

SDK2.2.0

Types37

START

A plugin

Derive one class from EditorPlugin and register what the plugin adds in OnLoad through Host. Save the file and the running editor rebuilds and reloads the plugin. Start with Your first C# plugin.

Plugin.cs

public sealed class LevelToolsPlugin : EditorPlugin
{
    private int clicks;

    public override void OnLoad()
    {
        Host.AddPanel(new PanelOptions("Main", "Level Tools") { Icon = "plug" }, DrawPanel);
    }

    private void DrawPanel(Ui ui)
    {
        ui.Heading("Level Tools");
        if (ui.Button("Count", ButtonStyle.Primary)) clicks++;
        ui.SameLine();
        ui.Text($"Clicks: {clicks}");
    }
}

RULES

Rules the editor relies on

Every callback runs on the editor's main thread, except importers, exporters and the run part of RunTask (worker threads). Log and Post are thread-safe.
What a plugin uses is declared in its manifest: capability lines (commands, panels, settings, importers, exporters, asset-types, viewport-tools, tasks, services, automation, components) and permission lines (scene.read, scene.write, assets.write). A call outside them throws KroysException naming the missing line.
An exception that escapes a callback is caught by the editor: the Console shows it with file and line, the plugin turns Faulted until it is reloaded, and the editor keeps running.
A hot reload removes every registration, calls OnUnload, unloads the old assembly and calls OnLoad on a new instance. Fields start fresh; GetSetting / SetSetting values stay.
Edits of the document scene are undoable; wrap several in using (Host.Transaction("Label")) to make them one undo step.

Plugin and host

EditorPluginBase class of a C# editor plugin.KroysExceptionA host function failed (the message is the host's error text).PluginHostThe editor seen from a C# plugin: registrations (commands, panels, settings pages, services, importers, exporters, asset types, viewport to…RegistrationA registration (command, panel, service ...).SeveritySeverity of a log line or notification.

Registration options

AssetLoadResultResult of an asset type's Load hook.AssetTypeHandlersAsset type hooks (all optional).AssetTypeOptionsA plugin asset type (Content Browser create / open / save hooks).CommandOptionsA command (command palette, Tools > Plugins menu, optional toolbar button and shortcut).ComponentFieldA field of a plugin component type.ComponentTypeOptionsA plugin component type (capability "components").ExporterOptionsAn exporter (File > Export with Plugin) running on a worker thread.ImporterOptionsAn importer (File > Import, content drops) running on a worker thread.PanelCategoryWhere a panel appears in the Window menu.PanelOptionsA dockable panel drawn with Ui.PanelSlotWhere a panel docks when it first opens.SettingsPageOptionsA page of the Settings window (group PLUGINS).ViewportToolHandlersViewport tool hooks (all optional).ViewportToolOptionsA viewport tool (plugin toolbar of the viewport).

UI

ButtonStyleButton styles (Ui.Button).DrawArgsSize and timing of a draw callback.InputFlagsText input options.TableFlagsTable options.ThemeColorSemantic theme colours of the editor.ThemeMetricTheme metrics (spacing, radius, scale).TreeFlagsTree node options.UiThe editor's immediate-mode UI for plugin panels and settings pages, drawn with the editor theme (no Dear ImGui dependency).Ui.ScopeEnds a Disabled or Id block when disposed.

Scene

ComponentTypeA component type (engine or plugin).EntityAn entity of a world (0: none).TransformPosition, rotation (Euler degrees) and scale.WorldA scene: the editor document (PluginHost.Document).

Viewport

ViewportViewport drawing and camera for viewport tools (valid inside a tool's Draw).ViewportInputMouse state over the viewport.

Jobs and tasks

AutomationJobAn automation step's context (capture scripts: plugin-step <name>).FileJobAn import or export job (worker thread).TaskProgressA running editor task (worker thread).

C ABI

Native plugins

Native editor and runtime plugins use the C ABI and the header-only C++ layer: see the C/C++ plugin SDK. For anything the managed API does not wrap, Host.Raw and Host.Context give C# the same C tables (Kroys.Plugins.Native, generated from kroys_plugin.h).

Generated from the XML documentation of Managed/PluginSdk/Api by Tools/BuildDocsSite.py. Every public member is documented (CS1591 is an error in the SDK project).