Anatomy of plugin

From UE4: Community Wiki
Jump to: navigation, search


This article is a preliminary version, it is subject to change.


Assumed Knowledge[edit]

You are an experienced programmer that has experience with object-oriented programming languages, such as C++ and Java. You have moderate experience or have mastered basic programming concepts, such as variables, functions, classes, reflection, modules, compiling, debugging, etc; and you can write and compile your own programs.

Plugins[edit]

A Plugin is similar to a Module except it may include Content (assets) as well as code.

Project and Engine Plugins[edit]

Project Plugins will reside in the Plugins folder, which is in the Project's root directory (where the .uproject resides).

Engine Plugins will initially be created as a Project Plugin where they will be programmed and debugged, but when distributed, they will reside in the Engine's installation directory. For example, Marketplace Plugins are installed to the folder:

.../UE_<VERSION>/Engine/Plugins/Marketplace/


An Engine Plugin may be moved into a Project's Plugin folder to recompile and debug


Engine Plugins may be moved into a Project's Plugin folder and used as a Project Plugin


Plugin Descriptor File[edit]

A .uplugin file, which is a plain-text file that stores Plugin Descriptors in a JSON object. It will exist at the root directory of the Plugin.


Fill this out


Plugin File Structure[edit]

Fill this out


Modules[edit]

Plugins may contain one or more Modules, which are implemented by creating a class that inherits from IModuleInterface and overriding the StartupModule and ShutdownModule methods, etc. Each Module will exist in its own subfolder under the Plugin's "Source" folder. A Module may also act as a controller (in an MVC architecture) in which methods are implemented to perform actions. When a new Plugin is created, a Module will automatically be generated in the Plugin's "Source" folder and its generated folder and module will be given the same name as the Plugin, e.g.

The Module's path: /MyPluginTitle/Source/MyPluginTitle

The Module's header file: /MyPluginTitle/Source/MyPluginTitle/Public/MyPluginTitle.h

The Module's type name: FMyPluginTitleModule

Listing 1 below shows the module header generated for a plugin from the Editor Toolbar Button template with the name MyEditorToolbarButton. Note that it does not contain a reflection header, i.e. *.generated.h

Listing 1: Generated Module from Editor Toolbar Button Template

// MyEditorToolbarButton.h
// Copyright 1998-2018 Epic Games, Inc. All Rights Reserved.

#pragma once

#include "CoreMinimal.h"
#include "Modules/ModuleManager.h"

class FToolBarBuilder;
class FMenuBuilder;

class FMyEditorToolbarButtonModule : public IModuleInterface
{
public:

	/** IModuleInterface implementation */
	virtual void StartupModule() override;
	virtual void ShutdownModule() override;
	
	/** This function will be bound to Command. */
	void PluginButtonClicked();
	
private:

	void AddToolbarExtension(FToolBarBuilder& Builder);
	void AddMenuExtension(FMenuBuilder& Builder);

private:
	TSharedPtr<class FUICommandList> PluginCommands;
};

A Module may also contain Commands, which contains metadata that may be mapped to UI elements. And those Commands may have methods or Actions or mapped to them using the MapAction method. For example, the generated Module above contains the variable "PluginCommands", which stores a list of Commands.

A Module may also have style data that can be applied to UI elements, which may be stored in a Style class.

Module Descriptors[edit]

Module's also have Descriptors that will be defined in the Plugin's Descriptor file and they consist of the properties Name, Type, and LoadingPhase. Please read the official documentation for further details.

https://docs.unrealengine.com/en-US/Programming/Plugins/index.html#moduledescriptors

New Reflected Types[edit]

Fill this out


Warnings and Tips[edit]

The UE4 EULA prohibits inclusion of Editor Modules in Shipping games and apps.


The Developer Module Type was deprecated in 4.24


An Engine Module will only ever contain code


Commands[edit]

Commands are instances of the FUICommandInfo class, which contains metadata about the appearance and functionality of a command that may be mapped to a UI element, such as ActiveChords, Label, Description, Icon, UIStyle, CommandName, UserInterfaceType (See UICommandInfo.h).

Command Registration[edit]

When a new plugin is created, it may have automatically generated a subclass of TCommands and overridden the method RegisterCommands(). Within this method, the Commands will be instantiated using the UI_COMMAND macro.

void FMyToolbarButtonCommands::RegisterCommands()
{
	UI_COMMAND(PluginAction, "MyToolbarButton", "Execute MyToolbarButton action", EUserInterfaceActionType::Button, FInputGesture());
}

The RegisterCommands() method is invoked during the Module's StartupModule() method.

void FMyToolbarButtonModule::StartupModule()
{
	...

	FMyToolbarButtonCommands::Register();
	...

Mapping Actions to Commands[edit]

After a Command has been instantiated, it may be mapped to a method or an Action.

	PluginCommands = MakeShareable(new FUICommandList);

	PluginCommands->MapAction(
		FMyToolbarButtonCommands::Get().PluginAction,
		FExecuteAction::CreateRaw(this, &FMyToolbarButtonModule::PluginButtonClicked),
		FCanExecuteAction());

Editor Keyboard Shortcuts[edit]

Commands may be assigned keyboard shortcuts in the Editor Preferences:

Editor Preferences > Keyboard Shortcuts > General - Keyboard Shortcuts

Actions[edit]

Actions are instances of the struct FUIAction and contains FExecuteAction*** delegates (see UIAction.h). An Action may also be mapped to a Command using the MapAction method.

Style[edit]

A Style class is a base class that contains Slate appearance data, such as images and fonts, that may be mapped to a Plugin's Slate UI elements. A "Style" class will automatically be generated with some Plugin Templates as the file ***Style.h within a Module's Source folder.

Style Set Name[edit]

The Style Set Name is a string of the type FName and is similar to a package name. In automatically generated ***Style.h classes, the method GetStyleSetName() will be implemented and return a string such as, "[MyModuleTitle]Style" or "[MyPluginTitle]Style".

Slate Style Set[edit]

The class FSlateStyleSet is a subclass of ISlateStyle, and encapsulates Slate appearance properties. A variable of the type FSlateStyleSet will automatically be created with some Plugin Templates in the ***Style.h class, e.g:

static TSharedPtr< class FSlateStyleSet > StyleInstance;

The variable StyleInstance is instantiated in the Style class's Create() method for automatically generated Style classes. Within this method, the root directory of the style's content is assigned to the Plugin's folder "Resources". This method is also used to create the mapping of property names to appearance data, such as fonts and images, etc using the method FSlateStyleSet::Set, e.g:

Style->Set("MyModule.PropertyName", new IMAGE_BRUSH(TEXT("Filename"), Icon40x40));

Property Names[edit]

Property Names are strings of the type FName and are typically assigned in the format "MyModule.PropertyName". They are mapped to appearance data using the Set method and they may be referenced when creating instances of Slate objects, e.g:

FSlateIcon(FMyModuleStyle::GetStyleSetName(), "MyModule.PropertyName")

Style Lifecycle Methods[edit]

In automatically generated ***Style.h classes, the lifecycle methods Initialize and Shutdown and ReloadTextures will be implemented. The Initialize and ReloadTexture methods will be invoked during a Module's StartupModule method and the Shutdown method will be invoked during the Module's ShutdownModule method.

Extenders and UI Extension Points[edit]

TODO

Slate UI Framework[edit]

Fill this out


Plugin Editor Settings[edit]

Fill this out


Automation Scripts[edit]

Fill this out


Tools[edit]

Fill this out


Custom Editor Mode[edit]

Fill this out


Tips[edit]

Recompile a plugin from the menu: Windows > Developer Tools > Modules