Workbench Plugin – Arma Reforger
Workbench Plugins are script files that can be triggered from within any editor (Resource Browser, World Editor, Script Editor, etc).
Existing plugins are listed in scripts > WorkbenchGame and are sorted by directories.
Editor | Directory |
---|---|
Common Plugins | Editor |
Resource Manager | ResourceManager |
String Editor | LocalizationEditor |
Script Editor | ScriptEditor |
World Editor | WorldEditor |
A Plugin must be named ClassnamePlugin, and its file too.
A Tool must be named ClassnameTool, and its file too.
Anatomy
Type
Plugin
A plugin inherits from WorkbenchPlugin and is decorated with a WorkbenchPluginAttribute attribute which signature is as follow:
WorkbenchPluginAttribute(string name, string description = "", string shortcut = "", string icon = "", array<string> wbModules = null, string category = "", int awesomeFontCode = 0)
- name is mandatory: it is the plugin's display name
- description
- shortcut: none (empty string) can be defined, the plugin will then need to be triggered from the Plugin top menu
- icon
- wbModules: to which editors does this plugin apply (e.g wbModules = { "ScriptEditor" })
- category: the plugins menu entry in which this plugin will find itself (e.g Plugins > Text > TutorialPlugin)
- awesomeFontCode: the FontAwesome icon associated with the plugin (see FontAwesome's Cheatsheet)
A plugin must also override either or both Run or RunCommandLine methods in order to have an impact. It can also, but is not mandatory, override the Configure method to display a settings entry.
Tool
A tool is a system that allows for direct manipulation with a config panel available on the side.
A tool inherits from the editor-related class (e.g World Editor: WorldEditorTool) in order to be found in said editor's Tools menu.
It is decorated with a WorkbenchToolAttribute attribute which signature is identical to WorkbenchPluginAttribute (see above).
Scripting
A plugin has access to the currently loaded game/project resources, but in order to be as adaptable as possible it should also be generic.
Each Workbench module (editor) API can be accessed through the following script:
ModuleType moduleType = Workbench.GetModule(ModuleType);
Where ModuleType can be one of the following classes, all children of the WBModuleDef class):
Editor | Class |
---|---|
Resource Manager | ResourceManager |
String Editor | LocalizationEditor |
Script Editor | ScriptEditor |
World Editor | WorldEditor |
Each module has obviously a different API. This tutorial will work with the Script Editor.
Create a Plugin
Run Method
The following is a very basic plugin that does nothing but print "It works!" in the debug console on trigger. It is linked to the Ctrl + ⇧ Shift + H keyboard shortcut, and applies only to "ScriptEditor" Workbench module (a.k.a Script Editor).
[WorkbenchPluginAttribute(name: "Tutorial Plugin", description: "This tutorial plugin does something.", shortcut: "Ctrl+Shift+H", wbModules: { "ScriptEditor" }, awesomeFontCode: 0xF188)]
class TutorialPlugin : WorkbenchPlugin
{
override void Run()
{
Print("It works!");
}
}
In the below code, the GetCurrentLine method is used to get the cursor location's line number. The GetLineText/SetLineText methods is used to obtain and change the line's value by adding an inline comment indicating the current line number ("hardcoded" into the comment).
[WorkbenchPluginAttribute(name: "Tutorial Plugin", description: "This tutorial plugin does something.", shortcut: "Ctrl+Shift+H", wbModules: { "ScriptEditor" }, awesomeFontCode: 0xF188)]
class TutorialPlugin : WorkbenchPlugin
{
override void Run()
{
ScriptEditor scriptEditor = Workbench.GetModule(ScriptEditor);
int lineNumber = scriptEditor.GetCurrentLine();
string lineContent;
scriptEditor.GetLineText(lineContent);
lineContent += " // current line is " + (lineNumber + 1);
scriptEditor.SetLineText(lineContent);
}
}
Configure Method
The Configure method is the one called when clicking Plugins > Settings > Plugin Name. If this method is not overriden with a non-empty code, the option does not appear in this menu.
Dialog
Setup
The Workbench.ScriptDialog methods allows for displaying UI dialogs for the user to confirm an action or set values. It can be used in any method (e.g not only Configure).
Displayed parameters are declared values decorated with an Attribute; a full setup is done as follow:
[WorkbenchPluginAttribute(name: "Tutorial Plugin", description: "This tutorial plugin does something.", shortcut: "Ctrl+Shift+H", wbModules: { "ScriptEditor" }, awesomeFontCode: 0xF188)]
class TutorialPlugin : WorkbenchPlugin
{
[Attribute(desc: "Only display the line number without any other text")]
protected bool m_bOnlyLineNumber;
override void Run()
{
ScriptEditor scriptEditor = Workbench.GetModule(ScriptEditor);
int lineNumber = scriptEditor.GetCurrentLine();
string lineContent;
scriptEditor.GetLineText(lineContent);
string lineNumberText = "";
if (!m_bOnlyLineNumber)
{
lineNumberText = "current line is ";
}
lineNumberText += (lineNumber + 1).ToString();
lineContent += " // " + lineNumberText;
scriptEditor.SetLineText(lineContent);
}
override void Configure()
{
Workbench.ScriptDialog("Tutorial Plugin Configuration", "Usage:\nTick the checkbox or not, depending on if the line number should be hardcoded or not", this);
}
}
Buttons
A button method is decorated with a ButtonAttribute attribute which signature is as follow:
ButtonAttribute(string label = "ScriptButton", bool focused = false)
A button method's return type can be anything, but the value will be treated as a boolean int (1 = true, 0 = false). A void method will return 0. An empty string result will convert as a 1.
[ButtonAttribute("OK")]
int ButtonOK()
{
return 42; // Workbench.ScriptDialog will return 1/true
}
The Workbench.ScriptDialog's return value can then be used to know if the user confirmed or cancelled an interface.