Extending Editor Functionality

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.

See Also#

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:

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.

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.

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

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

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:

{
    "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#

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

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

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.

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:

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);