This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Rendering
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
VR Development
Double Precision Coordinates
API
Animations-Related Classes
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Extending Editor Functionality

Warning
This feature is an experimental one and is not recommended for production use.

UNIGINE enables you to extend the core UnigineEditor functionality, e.g., add new menus, windows, tool bar commands, sub-modes, define how properties are displayed, and even create your custom Editor. This is made possible by UnigineEditor's Plugin System via adding custom user plugins.

UnigineEditor is an application written entirely in C++ relying a lot on the Qt5 framework infrastructure. So, in order to extend its functionality not only C++ programming skills are required, but you should also be familiar with the Qt5 framework, CMake build system.

Notice
Qt Framework version 5.12.3 is required to develop plugins for UnigineEditor. It is not included in UNIGINE SDK, so you'll have to download and install it.

See Also#

Editor Plugin System#

Plugins are collections of code and data that developers can easily enable or disable within UnigineEditor on a per-project basis. Each plugin is compiled into a dynamic library that is shipped separately, it is detected and loaded at run time by UnigineEditor.

Basically the structure of the Plugin System is as follows:

Plugin System

Plugin System

Here is a brief description of the main components:

  • QPluginLoader is responsible for plugin loading and providing meta data.
  • Editor::PluginInfo — plugin meta data parsing and storage, interaction with plugin interface, it also contains the current plugin state and information on a possible plugin initialization error.
  • Editor::PluginManager — a manager class responsible for locating plugins, building plugin loading queue, as well as loading and removing plugins.
  • Editor::Plugin — the basic class all Editor plugins inherit from, it has the following declaration:

    Editor::Plugin Class Declaration

    Source code (C++)
    namespace Editor
    {
     
    class EDITOR_API Plugin
    {
    public:
        Plugin();
        virtual ~Plugin();
        // Plugin's life cycle.
        virtual bool init()     = 0;
        virtual void shutdown() = 0;
    };
     
    } // namespace Editor
     
    // Associates the given Identifier (a string literal) to the interface class called Editor::Plugin.
    Q_DECLARE_INTERFACE(Editor::Plugin, "com.unigine.EditorPlugin")

    It has two abstract methods defining the plugin's life cycle, you should override them for your custom plugin:

    • init() — plugin initialization (returns initialization result)
    • shutdown() — plugin shutdown
    Notice
    The Q_DECLARE_INTERFACE macro adds the interface to Qt's metasystem.

Locating Plugins#

Plugins having their libraries located in the directory given below, are automatically loaded and added to the list of available UnigineEditor plugins, no specific code is required:

  • %project%/bin/plugins/ — for Debug and Release builds and any SDK build.
Notice
All UNIGINE plugins, both for the Engine and UnigineEditor, should meet requirements to their location (paths) and comply with naming convention.

To see the list of all currently loaded plugins in UnigineEditor, choose Windows -> Editor Plugin Manager.

Plugins List

You can view any plugin's description by selecting it in the list and clicking Details.

Plugin Details

Plugin Meta Data#

Each plugin must have additional information required by the plugin manager to find your plugin and resolve its dependencies before actually loading your plugin's library file. This information is stored in a meta file in JSON format (myplugin.json file automatically generated when adding an Editor plugin template to your project) and can be obtained at run time from an instance of the Editor::PluginInfo class. This meta file may look as follows:

Source code
{
    "Name" : "MyPlugin",
    "Vendor" : "Unigine",
    "Description" : "The plugin's description text." ,
    "Version" : "@PLUGIN_VERSION@",
    "CompatVersion" : "@PLUGIN_COMPAT_VERSION@"
    "Dependencies" : [
      {
        "Name": "RequiredPlugin",
        "Type": "required",
        "Version" : "2.9.0.0"
      },
      {
        "Name": "OptionalPlugin",
        "Type": "optional",
        "Version" : "2.8.0"
      }

    ]
}

Here is a brief overview of the basic elements:

  • Name — plugin name displayed in UnigineEditor's Plugins List, and used as reference when describing other plugins dependencies.
  • Vendor, Description — additional information (optional).
  • Version — current plugin version.
  • CompatVersion — last binary compatible plugin version, defines which version of this plugin the current version is binary backward compatible with and is used to resolve dependencies on this plugin.
  • Dependencies — list of objects describing dependencies on other plugins.
  • Name — name of the plugin, on which this plugin relies.
  • Type — dependency type, can be either required or optional.
  • Version — version with which the plugin must be compatible to fill the dependency, in the form x.y.z. Can be empty if the version does not matter.

Actually, the author creates a .json.in file, which is then used by CMake to generate the actual plugin .json meta data file, replacing variables like EDITOR_VERSION with their actual values.

Plugin Dependencies#

A plugin can rely on other plugins. Such dependencies are specified in the plugin meta data, to ensure that these other plugins are loaded before this one.

Dependencies are declared with the key Dependency that contains an array of JSON objects with required keys Name and Version, and the optional key Type.

The following formulas illustrate how the dependency information is matched. In the formulas the name of the required plugin (as defined in Name of the dependency object) is denoted as DependencyName and the required version of the plugin is denoted as DependencyVersion. A plugin with given Name, Version, and CompatVersion as defined in the plugin meta data matches the dependency if the following conditions are met:

  • Its Name matches DependencyName.
  • CompatVersion <= DependencyVersion <= Version

For example, a dependency

Source code
{
    "Name" : "SomeOtherPlugin",
    "Version" : "2.4.1"
}

would be matched by a plugin with

Source code
{
    "Name" : "SomeOtherPlugin",
    "Version" : "3.1.0",
    "CompatVersion" : "2.2.0",
    ...
}

since the name matches, and the version 2.4.1 given in the dependency tag lies between 2.2.0 and 3.1.0.

Plugin Life Cycle#

To be able to write Editor plugins, you must understand the steps that the plugin manager takes when you start or shut down UnigineEditor.

When you start UnigineEditor, the plugin manager does the following:

  • Looks in its search paths for all dynamic libraries, and reads their meta data. All libraries without meta data and the ones without the com.unigine.EditorPlugin IID are ignored. The initial state of all plugins is INVALID as this is the first point where loading a plugin can fail in the worst case of malformed meta data.
  • Creates an instance of the Editor::PluginInfo class for each plugin. Being a container for the plugin meta data, this class also tracks the current plugin state. You can get the Editor::PluginInfo instances via the Editor::PluginManager::plugins() function.
  • Sets the plugins to the READ state.
  • Verifies that the dependencies of each plugin exist and are compatible.
  • Sets the plugins to the RESOLVED state.
  • Sorts all plugins into a list called the "loading queue", where the dependencies of a plugin are positioned after the plugin (but not necessarily directly after it). It ensures that plugins are loaded and initialized in proper order.
  • Loads the plugins' libraries, and creates their Editor::Plugin instances in the order of the loading queue. At this point the plugin constructors are called. Plugins that other plugins depend on are created first.
  • Sets the plugins to the LOADED state.
  • Calls the init() functions of all plugins in accordance with the loading queue. In the init() function, a plugin should make sure that all exported interfaces are set up and available to other plugins. As each plugin assumes that plugins it depends on have set up their exported interfaces.

    Notice
    The plugin init() function is a good place for:
    • Creating new objects
    • Loading settings
    • Adding new menus, and new actions to them
    • Connecting to other plugin's signals
  • Sets the plugins to the RUNNING state.

On UnigineEditor shutdown the plugin manager starts its shutdown sequence:

  • Calls the shutdown() functions of all plugins in the order of the loading queue. Plugins should perform measures for speeding up the actual shutdown here, like disconnecting signals that would otherwise needlessly be called.
  • Destroys all plugins by deleting their Editor::Plugin instances in reverse order of the loading queue. At this point the plugin destructors are called. Plugins should clean up after themselves by freeing memory and other resources.

Hot Reload#

Editor plugins support hot reloading, which can be useful in cases, when you need to perform actions like:

  • Unload a plugin.
  • Do something.
  • Reload the plugin.

You can unload and Load your plugin again when necessary via the corresponding button in the HotReload column (accessible via the Editor Plugin Manager window: Windows -> Editor Plugin Manager).

You can also do the same via code:

Source code (C++)
Unigine::Vector<Editor::PluginInfo *> plugin_infos = Editor::PluginManager::plugins();

// choose your `PluginInfo*`:
Editor::PluginInfo *required_plugin_info = ..;

// Unload a plugin:
bool unloaded = Editor::PluginManager::unloadPlugin(required_plugin_info);

// Do something
// ...

// Reload the plugin
bool loaded = Editor::PluginManager::loadPlugin(required_plugin_info);
Last update: 2023-12-19
Build: ()