Plugins

This page describes the development and management of Plugins for use with the Unreal Engine tools and runtime.

Many Unreal Engine subsystems are designed to be extensible, enabling you to add entire new features and to modify built-in functionality without modifying Engine code directly. You can create new file types, add new menu items and tool bar commands to the Editor, or even create entire new features and Editor sub-modes!

If you want to jump right in and create a Plugin now, please see the Plugin Examples section.

Plugin UI in the Editor

You can see which Plugins are currently installed by opening the Plugin editing interface from the Edit menu.

PluginsEditor.png

The Plugin Editor is accessible from the main 'Window' menu. This interface displays all of the Plugins that are currently installed and can enable or disable Plugins individually.

You can browse categories of Plugins using the tree interface on the left. Selecting a category will show all Plugins in that category as well as Plugins in any sub-category. As you navigate through categories, a bread crumb trail displayed at the top of the UI will enable you to jump quickly to higher-level categories. The number displayed next to a category indicates how many Plugins are available in that category.

PluginCategories.png

Plugins are displayed in the main list, along with each Plugin's name, icon, current version, text description, author (and optional web hyperlink), as well as whether or not the plugin is currently enabled.

The search control at the top will enable you to search Plugins displayed in the list by name.

SearchingPlugins.png

You can enable or disable a Plugin for use with your active project by toggling the Enabled check box under the Plugin's description. You may need to restart the Editor for the change to take effect.

Anatomy of a Plugin

Plugins with code will have a Source folder. This folder will contain one or more directories with module source code for the Plugin. Note that, although Plugins often contain code, this is not actually a requirement. See the Code in Pluginssection for more information.

Plugins with code will have a Binaries folder that contains compiled code for that Plugin, and temporary build product files will be stored in a separate Intermediate folder under the Plugin's directory.

Plugins can have their own Content folder that contains Asset files specific to that Plugin. See the Content in Plugins section for more information. Plugin configuration files should be placed using the same convention as other configuration files:

  • Engine plugins: [PluginName]/Config/Base[PluginName].ini
  • Game plugins: [PluginName]/Config/Default[PluginName].ini

Plugins do not yet support their own Derived Data Cache distribution. We plan to add support for this at a later date.

Plugin Folders

In order for Plugins to be found, they must be located in one of the search paths for Plugins, either in your project, or in the Engine itself.

Plugin Type

Search Path

Engine

/[UE4 Root]/Engine/Plugins/[Plugin Name]/

Game

/[Project Root]/Plugins/[Plugin Name]/

You can also organize Plugins into subdirectories under the base Plugins folder. The engine will scan all of your sub-folders under the base Plugins folder for Plugins to load, but it will never scan subdirectories beneath a Plugin that has already been found.

Unreal Engine finds your Plugin by searching for .uplugin files on disk. We call these files Plugin Descriptors. They are text files that provide basic information about your Plugin. Plugin Descriptors are discovered and loaded automatically by the Engine, Editor, and the Unreal Build Tool (UBT), whenever those programs are run. See the section on Plugin Descriptors to learn about creating and customizing these files.

Code in Plugins

When generating project files for Visual Studio or Xcode, any Plugins that have Source folders (containing .Build.cs files) will be added to your project files to make it easier to navigate to their source code. These Plugins will automatically be compiled by Unreal Build Tool when compiling your game project.

Plugins are allowed to have any number of Module source directories. Most Plugins will only have one Module, but it is possible to create multiple, for example, if a Plugin contains some Editor-only functionality, and other code that is intended to run during the game.

For the most part, Plugin source file layout is the same as any other C++ Module in the Engine.

Plugins are able to declare new reflected types (UCLASSUSTRUCT, etc.) in header files within a Classes subdirectory in their Module code folders. The Engine's build system will detect these files and generate code as needed to support the new types. You will need to follow the normal rules for using UObjects within C++ modules, such as including the generated header file and the Module's generated.inl file in one of your Module's source files.

Most Plugin Modules will not export public APIs in header files via the Public source folder, because Plugin Modules cannot be direct dependencies of (or statically linked by) the Engine or game code. However, there are a few exceptions to this rule:

  • If your Plugin contains multiple C++ Modules, code in a Public folder can be shared between Modules within your Plugin.
  • If you are creating a game Plugin (not an Engine Plugin), and you want the game to statically link against one of your Plugin Modules. This is an unusual practice, but can be useful for Plugins that want to declare new types that game classes can inherit or use directly. The Engine itself will never have direct dependencies on a Plugin, but the game project code and content may.
  • If you want to distribute public interface headers with your Plugin, to enable game code or other Plugins to access types implemented in that Plugin's Modules. This is generally discouraged, as we do not currently support (or have plans to support) Plugins that are directly dependent on other Plugins.

Content in Plugins

Unreal Engine supports plugins that contain game content as well as binary code. In order to use Content in a Plugin, the "CanContainContent" setting within the Plugin's descriptor must be set to "true".

Plugins in Projects

Plugins reside under the Plugins subfolder within your project's directory, and will be detected and loaded at Engine or Editor start-up time.

If the Plugin contains modules that have Source folders (and .Build.cs files), Plugin code will automatically be added to generated C++ project files, so that you can work on developing the Plugin alongside your project. Whenever you compile your project, any Plugins that have source available will also be compiled as a dependency of your game.

Plugins that do not have a Source folder are ignored by the project generator and will not appear in your C++ project files, but they will still be loaded at start-up as long as binary files exist.

At present, Plugin configuration files are not packaged with projects. This may be supported in the future, but currently requires manually copying the files to the project's Config folder.

Engine Plugins

Unreal Engine 4 has some built-in Plugins included under the Engine directory. Engine Plugins are just like project Plugins, except that they are available for all projects. Typically, these plugins are created by engine and tools programmers to provide baseline functionality that can be used in multiple projects while being maintained in a single place. This can enable the user to add or override engine features without modifying engine code.

By default, engine Plugins are loaded before any of the project's Plugins or Modules are loaded.

Engine Plugins have a special requirement: Engine Modules must never statically link against Plugin Module libraries. That is, Engine Plugins must remain compartmentalized from the Engine itself; Plugin Modules must never be "dependency modules" for Engine Modules. This is a philosophical choice that allows the Engine to function even when the Plugins are not available to be loaded.

Distributing a Plugin

  • Click the *Package...* link to package your Plugin into a folder for distribution.
  • Plugin Descriptor Files

    Plugin descriptors are files that end with .uplugin. The first part of the file name is always the name of your Plugin. Plugin descriptor files are always located in your Plugin's directory, where the Engine will discover them at start-up time.

    Plugin descriptors are in the Json (JavaScript Object Notation) file format.

    Descriptor File Example

    This example plugin descriptor is from the UObjectPlugin example.

    {
        "FileVersion" : 3,
        "Version" : 1,
        "VersionName" : "1.0",
        "FriendlyName" : "UObject Example Plugin",
        "Description" : "An example of a plugin which declares its own UObject type.  This can be used as a starting point when creating your own plugin.",
        "Category" : "Examples",
        "CreatedBy" : "Epic Games, Inc.",
        "CreatedByURL" : "http://epicgames.com",
        "DocsURL" : "",
        "MarketplaceURL" : "",
        "SupportURL" : "",
        "EnabledByDefault" : true,
        "CanContainContent" : false,
        "IsBetaVersion" : false,
        "Installed" : false,
        "Modules" :
        [
            {
                "Name" : "UObjectPlugin",
                "Type" : "Developer",
                "LoadingPhase" : "Default"
            }
        ]
    }
    

    Descriptor File Format

    Field name

    Required/Optional

    Description

    FileVersion

    Required

    Version of this Plugin descriptor file. Note that this really is the descriptor file version, not the Plugin version. This is used for backwards compatibility as new features are added to the Plugin system, and should usually set to the highest version that is allowed by the Engine. The latest version is currently 3, and is the version documented here. We do not expect this version to change very frequently. In the source code, you can look up the EProjectDescriptorVersion namespace and read through the enumerated values to check the actual value. If you require maximum compatibility with older versions of the engine, then you can use an older version of the format, but it is not recommended.

    Version

    Optional

    Current version number of this build of your Plugin. This value should always increase with future versions. This version number is not intended to be displayed to end users.

    VersionName

    Optional

    Version of the Plugin displayed in the Editor. This is not the actual version number as far as the Engine and Editor are concerned, and is not used for version checks. This can be in whatever format you prefer, although a simple Major.Minor format is preferred. You should always update the VersionName whenever the Version number has increased.

    FriendlyName

    Optional

    The name of the Plugin that will be displayed in the Editor. If not specified, the name will default to the .uplugin file name.

    Description

    Optional

    The description of the Plugin that will be displayed in the Editor.

    Category

    Optional

    A dot-separated path string that assigns your Plugin to a category in the Editor. For example, "Editor Features.Level Editing.Mesh Painting", where each category is separated by a period character and represents a deeper level in the tree.

    CreatedBy

    Optional

    The name of the individual or company that created this Plugin. This will be displayed in the Editor's Plugin Browser, or other locations in the UI.

    CreatedByURL

    Optional

    A link to the individual or company that created this Plugin. Will be shown on the Editor's Plugin browser if specified.

    DocsURL

    Optional

    A link to the Plugin's documentation. Will be shown on the Editor's Plugin browser if specified.

    MarketplaceURL

    Optional

    A link to the Plugin's Marketplace page. Will be shown on the Editor's Plugin browser if specified.

    SupportURL

    Optional

    A link to the support page for the plugin. Will be shown on the Editor's Plugin browser if specified.

    EnabledByDefault

    Optional

    If set to true, this Plugin will be enabled by default.

    CanContainContent

    Optional

    When specified and set to true, enables content support for this Plugin. The default setting is false. See the section on Content in Plugins for more info.

    IsBetaVersion

    Optional

    Marks the Plugin as a beta version. In the list of Plugins, "Version" will be replaced with "BETA Version" for this Plugin.

    Installed

    Optional

    If set to true, the Plugin will be listed under the "Installed" section in the list of Plugins, instead of the "Project" or "Built-in" sections.

    Modules

    Optional

    For Plugins that contain source code (and binaries), this is the list of modules that should be loaded at start-up.

    Module Descriptors

    For plugins that contain code, the descriptor file will contain at least one module descriptor.
    {
        "Name" : "UObjectPlugin",
        "Type" : "Developer"
        "LoadingPhase" : "Default"
    }
    

    Field Name

    Required/Optional

    Description

    Name

    Required

    Unique name of this Plugin Module that will be loaded with the Plugin. At runtime, the engine will expect appropriate Plugin binaries to exist in the Plugin's Binaries folder with the module name as specified here. For modules that have a Source directory, a matching *.Build.cs file is expected to exist within the module's subfolder tree.

    Type

    Required

    Sets the type of Module. Valid options are Runtime, RuntimeNoCommandlet, Developer, Editor, EditorNoCommandlet, and Program. This type determines which types of applications this Plugin's Module is suitable for loading in. For example, some plugins may include modules that are only designed to be loaded when the editor is running. Runtime modules will be loaded in all cases, even in shipped games. Developer modules will only be loaded in development runtime or editor builds, but never in shipping builds. Editor modules will only be loaded when the editor is starting up. Your Plugin can use a combination of modules of different types.

    LoadingPhase

    Optional

    If specified, controls when the plugin is loaded at start-up. This is an advanced option that should not normally be required. The valid options are Default (which is used when no LoadingPhase is specified), PreDefault, and PostConfigInit. PostConfigInit enables the module to be loaded before the engine has finished starting up key subsystems. PreDefault loads just before the normal phase. Typically, this is only needed if you expect game modules to depend directly on content within your plugin, or types declared within the plugin's code.

    WhitelistPlatforms

    Optional

    If specified, gives a list of platforms which this module will be compiled for. If not specified, the module will be compiled for all platforms.

    BlacklistPlatforms

    Optional

    If specified, gives a list of platforms which this this module will not be compiled for. If not specified, the module will be compiled for all platforms.

    Icons

    Along with the descriptor file, Plugins usually have an icon file that is used when displaying the Plugin in the Editor's Plugin list.

    File name

    Required/Optional

    Format

    Description

    /Resources/Icon128.png

    Required

    128x128 PNG file

    This icon represents this Plugin in the Plugin Browser.

    Example Plugins

    We have created a few example Plugins that do not really do anything, but serve as an empty shell that you can use when starting to create your own Plugin. These are included with the Engine source code.

    Example name

    Info

    BlankPlugin

    This Plugin is an empty shell that shows the bare minimal files needed to setup a new code Plugin Module.

    UObjectPlugin

    A simple empty Plugin that demonstrates how to declare your own UObject class.

    To use these examples as a starting point for your Plugin:

    1. Copy an example Plugin to a new folder and rename the directories, files and code contents to match your new Plugin name. Leaving the existing names will cause collisions with the original Plugin.
    2. Make a Plugins folder under your project directory, then copy your Plugin to any subdirectory under Plugins.ExamplePlugins.png
    3. Rebuild your C++ project files. The Plugin Modules and source code will appear in directories under your project's directory in the project file.
    4. Compile your project. Unreal Build Tool will detect the Plugins and compile them as dependencies to your project.
    5. Launch the Editor. Your Plugin will be disabled initially, but you can enable it in the Plugin Browser.
    6. Open the Plugin Browser within the Editor. Search for your Plugin and enable it by clicking the check box.
    7. Restart the Editor. Your Plugin will be loaded automatically at startup.
    8. You can see that the Plugins have loaded by opening the Modules viewer under the Window > Developer Tools menu. You can also use your code debugger to place a breakpoint in the Plugin's startup code, such as the StartupModule function.