Writing a plugin

Write a plugin with a .mplugin manifest, runtime and editor C++ modules, content and shaders, enable it per project, and register through the engine's seams.

Last updated Oct 27, 2026Edit this pageVersion 1.0.0

A plugin is a folder with a .mplugin manifest and, usually, C++ modules and a Content/ folder. When a project enables it, its content mounts into the virtual filesystem, its modules load and register their types, and its editor module (if it has one) extends the editor. The engine ships 7 plugins in Engine/Plugins/, all off by default, and lists its feature modules beside them.

Layout

Text
MyPlugin/
  MyPlugin.mplugin            JSON manifest
  MyPlugin.Build.cs           the runtime module's rules
  Public/MyPlugin/            reflected headers
  Private/                    sources
  Content/                    assets, mounted at Plugins/MyPlugin
  Shaders/                    HLSL, optional

A plugin lives either in Engine/Plugins/<Name>/ (shared by every project on the machine, loaded at engine start-up, read-only in the editor) or in <Project>/Plugins/<Name>/ (committed with the project, loaded when the project opens).

The manifest

MyPlugin.mplugin
{
  "name": "MyPlugin",
  "friendlyName": "My Plugin",
  "version": "1.0.0",
  "description": "What the plugin adds, in one or two sentences.",
  "author": "Studio",
  "category": "Gameplay",
  "icon": "swords",
  "enabledByDefault": false,
  "content": true,
  "engineVersion": "0.3",
  "dependencies": [],
  "modules": [
    { "name": "MyPlugin", "type": "Runtime", "loadingPhase": "Default" },
    { "name": "MyPluginEditor", "type": "Editor" }
  ]
}
KeyMeaning
nameThe plugin's identity; one plugin per name
contenttrue mounts the plugin's Content/ folder
enabledByDefaultUsed when the project's Config/Plugins.ini says nothing
engineVersionThe engine major.minor the plugin targets; another version blocks the plugin
dependenciesNames of plugins that must be enabled and loadable first
modulesThe C++ modules to load: a name, or an object with name, type and loadingPhase
requiresOnline, server, dlc, beta, marketplaceUrlFlags the Plugins window and packaging read

A module's type decides which hosts load it. "Runtime" (the default) loads everywhere; "Editor" loads only in the editor, and the game, the server and packaging skip it.

Enabling a plugin

Each project decides in Config/Plugins.ini:

Config/Plugins.ini
[enabled]
Combat=True
ScanHierarchy=True

The file wins over enabledByDefault. The editor's Plugins window writes it; see Editor. Content mounts and unmounts immediately. Enabling a code plugin loads its modules at once; disabling one that is already loaded takes effect after a restart, because unloading it would remove classes that live objects use.

Cooking, packaging and the monolithic link read the same file, so a disabled plugin ships neither its content nor its binaries.

Dependencies and versions

An enabled plugin does not load (no content, no modules) when a dependency is missing, disabled or blocked itself, when the dependencies form a cycle, or when its engineVersion names another engine major.minor. The plugin stays enabled, and its blocked reason appears in the log and the Plugins window:

Text
Plugin 'Survival' does not load: it requires plugin 'Combat', which is disabled

Modules load in dependency order: a plugin's modules load only after those of every plugin it depends on.

Runtime modules

A plugin module is an ordinary module with its own .Build.cs, built by mbt like a game module:

MyPlugin.Build.cs
public class MyPlugin : ModuleRules
{
	public MyPlugin(ReadOnlyTargetRules Target) : base(Target)
	{
		PublicDependencyModuleNames.Add("EngineLoop");

		PrivateIncludePaths.Add(EngineLoopIncludeDirectory);
		CompilerFlags.Add("/FIstdafx.h");

		bUseHeaderTool = true;
		HeaderToolDirectories.Add("Public/MyPlugin");
	}
}

The loader looks for the module binary in the engine's binaries folder first, then in the plugin's own Binaries/<platform>/ and Binaries/ folders (<platform> is the platform id, such as win-x64), so a plugin can ship prebuilt. A module whose binary has not been built is skipped with a log line, and the project still opens.

Build plugins in the same configuration as the engine that loads them: the loader refuses a module built against another C++ runtime (a debug plugin in a dev editor, for example).

Extending the engine

Reflected types (MCLASS, MOWO_REFLECTED components) register themselves when the module loads; nothing else is needed for them to save, appear in the editor and show up in Visual Scripting.

Everything else goes through FEngineModularRegistry from the module's InitializeModule: FEngineModularRegistry

CallWhat it adds
RegisterSceneSystem(FModularSceneSystem)An ECS scene system with its tick order and the play modes it runs in
RegisterAssetSerializer(factory)An asset type; each host applies the registered serializers after its built-in ones
RegisterStateFragment(...)World state a plugin system owns that save games and level travel carry
RegisterCharacterExtension(...)Input bindings and an aim feed for a plugin-owned character mode

These add to the engine's built-in tables and never replace them. Descriptors cross the DLL boundary as plain function pointers, never std::function.

Online platform plugins register an IOnlineService the same way; see Multiplayer.

Editor modules

The editor is an executable with no public headers, so a plugin cannot link into it. It links EditorFramework instead, the library that holds the editor's extension points. A module of type "Editor" that depends on it:

MyPluginEditor.Build.cs
public class MyPluginEditor : ModuleRules
{
	public MyPluginEditor(ReadOnlyTargetRules Target) : base(Target)
	{
		PrivateDependencyModuleNames.Add("Core");
		PrivateDependencyModuleNames.Add("Arc");
		PrivateDependencyModuleNames.Add("EditorFramework");
	}
}

Two registries are available:

  • FEditorDockPanelRegistry registers dock panels. A panel appears under Window > Plugins and restores with the layout like a built-in one. FEditorDockPanelRegistry
  • FEditorExtensionRegistry adds menu entries (File, Edit, Tools, Window, Build, Help), toolbar buttons beside the play controls, Details customizations keyed by component type, and viewport modes. FEditorExtensionRegistry
MyPluginEditor.cpp
#include <Arc/Framework/ArcDeclarativeSyntax.h>
#include <Arc/Widgets/ATextBlock.h>
#include <Core/FModuleManager.h>
#include <EditorFramework/EditorExtensionRegistry.h>
#include <EditorFramework/EditorPanelRegistry.h>

#include <utility>

MOWO_IMPLEMENT_MODULE_API_VERSION()

extern "C" MOWO_MODULE_EXPORT void InitializeModule() {
	Mowo::FEditorDockPanelDesc panel;
	panel.Kind = "MyTool";
	panel.Title = "My Tool";
	panel.Create = [](int32_t) {
		Mowo::FEditorDockPanelInstance instance;
		instance.Surface = ArcNew(Arcf::ATextBlock).Text(Arcf::CText::FromString("Hello from MyPlugin"));

		return instance;
	};
	Mowo::FEditorDockPanelRegistry::Get().Register(std::move(panel));

	Mowo::FEditorMenuExtension entry;
	entry.Id = "MyPlugin.Run";
	entry.Menu = Mowo::EEditorMenu::Tools;
	entry.Label = "Run My Tool";
	entry.Execute = []() {
	};
	Mowo::FEditorExtensionRegistry::Get().AddMenuEntry(std::move(entry));
}

extern "C" MOWO_MODULE_EXPORT void ShutdownModule() {
	Mowo::FEditorExtensionRegistry::Get().RemoveMenuEntry("MyPlugin.Run");
	Mowo::FEditorDockPanelRegistry::Get().Unregister("MyTool");
}
Warning

Remove in ShutdownModule everything you added in InitializeModule. A panel factory, a menu callback and every widget they built are code inside your DLL; an entry left behind is called or destroyed after that code is gone.

The module ABI check

Every module binary exports its ABI version with MOWO_IMPLEMENT_MODULE_API_VERSION() from Core/FModuleManager.h. Right after loading a library, FModuleManager compares it with the engine's MOWO_MODULE_API_VERSION and the C++ runtime the module was built against. A binary that exports another number, or none, is refused: the log names the module and says to rebuild it against this engine, its static registrations are removed, and the library is freed. FModuleManager::LoadModule

The check exists because descriptors such as FModularSceneSystem are copied with the engine's layout; a plugin built against an older layout would hand over a shorter struct. When you change such a boundary type in the engine, bump MOWO_MODULE_API_VERSION.

Unloading

When a project closes, its plugin modules unload. The world is torn down first, then each module's reflected classes are unregistered, a garbage collection frees objects whose code lives in the module, ShutdownModule runs, and the library is freed.

Before the library is freed, the engine sweeps every registry that might still point into it: scene systems, reflection, the modular registry, console commands, property-type handlers, EventBus subscriptions, timers and others. Most registrations record the module they came from automatically, so plugin code needs no extra step. FModuleManager::AddUnloadHandler lets your own registries join the sweep.

Shaders

A plugin keeps HLSL in Shaders/ and maps it to a virtual root in its .Build.cs:

C#
AddShaderSourceDirectoryMapping("/Plugin/MyPlugin", "Shaders");
ShaderDirectories.Add("Shaders/Private");
ShaderArchive = "MyPluginShaders.meaf";

Its shaders include engine headers as /Engine/Public/… and their own as /Plugin/MyPlugin/…, and their compiled keys carry the Plugin/MyPlugin/ prefix, so a plugin cannot replace an engine shader. See Rendering.

Content and packaging

An enabled plugin's Content/ mounts at Plugins/<Name>, so its assets are referenced as Plugins/MyPlugin/Materials/M_Plastic.mat. Cooking and packaging put every enabled plugin's content into the game's content archive under the same prefix, so references resolve unchanged in a packaged game. See Shipping.

Engine plugins and feature modules

Engine systems such as AI and navigation, the Sequencer and destruction are feature modules. They build with the engine, but a project switches each one in Config/Plugins.ini exactly like a plugin, and the Plugins window lists them under Engine Features. A game loads, registers and packages only the ones its project enables; the editor registers all of them, because its asset editors open every asset type, and the switch decides what a standalone run, the packaged game and the server load. Play in the editor keeps every module registered.

Feature moduleDefaultNeeds
AINavigation (AI and Navigation)on
NarrativeonAINavigation
VoiceChatoff
Destruction, GeometryTools, PointCloud, Sequencer, LevelGen, PCG, GpuEcsoff
Scripting (Wolang Scripting)off
Accessibility (Automatic Subtitles, ONNX Runtime)offVoiceChat, Narrative

AI and Navigation and Narrative are on because the templates place navigation agents, schedules, quests and music, and Combat depends on both. A plugin may name a feature module in dependencies (Combat does), and turning that module off blocks the plugin. What stays a plugin is what a game opts into on top: platform SDKs (SteamPlatform, DiscordPlatform, MowoOnlinePlatform), gameplay kits (Combat, Survival), SmartProps and ScanHierarchy. No engine module depends on a plugin. See Architecture.

Config/Plugins.ini
[enabled]
VoiceChat=True
Sequencer=True
AINavigation=False

A module another enabled module links stays loaded by the operating system but does not register: Narrative links VoiceChat, so its library is mapped, yet with VoiceChat off no voice system, input action or setting exists. The package carries Config/Plugins.ini and stages only the enabled modules, so a monolithic game compiles in and registers exactly that set.

What a machine skips

At startup the engine probes the machine once and logs a [Capabilities] block: CPU, audio devices, gamepads, whether the Steam and Discord clients run, the GPU, driver and VRAM, hardware ray tracing, mesh shaders, VRS, bindless, async compute, and each vendor feature with the reason it is missing. Vendor features are decided from the vendor, model and driver: DLSS needs an NVIDIA RTX GPU and driver 520 or newer, DLSS Frame Generation an RTX 40-series, Reflex any NVIDIA GPU, Anti-Lag 2 a Radeon RX, XeSS Frame Generation and XeLL an Intel Arc GPU; FSR and XeSS run on every vendor. No vendor runtime loads to answer, and a runtime this GPU cannot run never loads.

A [Features] block follows: every subsystem that waits for a capability, a project switch or an enabled module, and whether it starts. A skipped one allocates nothing and starts no thread:

Text
[Features] skipped VoiceCapture: no audio input device
[Features] skipped SteamOnline: the Steam client is not running
[Features] skipped DLSS Frame Generation runtime: needs an RTX 40-series or newer

The client check runs once at startup: a Steam or Discord client started after the game is picked up on the next launch.

Engine sources

This page describes behavior implemented in these files of the engine repository, checked against commit 8f1cfbd42.

  • Engine/Source/Runtime/Project/Public/Project/PluginManager.h
  • Engine/Source/Runtime/Core/Public/Core/FModuleManager.h
  • Engine/Source/Runtime/Game/Public/Game/EngineModularRegistry.h
  • Engine/Source/Runtime/ECS/Public/ECS/SceneSystemRegistry.h
  • Engine/Source/Editor/EditorFramework/Public/EditorFramework/EditorPanelRegistry.h
  • Engine/Source/Editor/EditorFramework/Public/EditorFramework/EditorExtensionRegistry.h
  • Engine/Plugins/Combat/Combat.mplugin
  • Samples/SampleProject/Config/Plugins.ini
  • Engine/Source/Runtime/Project/Public/Project/FeatureModules.h
  • Engine/Source/Runtime/Core/Public/Core/EngineCapabilities.h
  • Engine/Source/Runtime/Core/Public/Core/EngineFeatureRequirements.h

Page feedback

Was this page helpful?