Workbench Plugin – Arma Reforger

From Bohemia Interactive Community
Jump to navigation Jump to search
(Change category)
(Remove tutorial part, Change category to Guidelines)
Line 2: Line 2:
'''Workbench Plugins''' are script files that can be triggered from within any editor (Resource Browser, World Editor, Script Editor, etc).
'''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 {{hl|scripts > WorkbenchGame}} and are sorted by directories.
Existing plugins are listed in {{hl|Data\Scripts\WorkbenchGame}} and are sorted by directories.
 
{| class="wikitable"
{| class="wikitable"
! Editor
! Editor
! Directory
! Directory
! API Class<br>(Module Type)
|-
|-
| Common Plugins
| Common Plugins
| Editor
| {{hl|Data\Scripts\WorkbenchGame}}
| {{n/a}}
|-
|-
| Resource Manager
| Resource Manager
| ResourceManager
| {{hl|Data\Scripts\WorkbenchGame\ResourceManager}}
| {{Link/Enfusion|armaR|ResourceManager}}
|-
| World Editor (Tools and Plugins)
| {{hl|Data\Scripts\WorkbenchGame\WorldEditor}}
| {{Link/Enfusion|armaR|WorldEditor}}
|-
| Particle Editor
| {{n/a}}
| {{n/a}}
|-
|-
| String Editor
| Animation Editor
| LocalizationEditor
| {{n/a}}
| {{n/a}}
|-
|-
| Script Editor
| Script Editor
| ScriptEditor
| {{hl|Data\Scripts\WorkbenchGame\ScriptEditor}}
| {{Link/Enfusion|armaR|ScriptEditor}}
|-
|-
| World Editor
| Audio Editor
| WorldEditor
| {{n/a}}
| {{n/a}}
|-
| Behavior Editor
| {{n/a}}
| {{n/a}}
|-
| String Editor
| {{hl|Data\Scripts\WorkbenchGame\LocalizationEditor}}
| {{Link/Enfusion|armaR|LocalizationEditor}}
|-
| Procedural Animation Editor
| {{n/a}}
| {{n/a}}
|}
|}


Line 27: Line 54:
A '''Tool''' must be named {{hl|Classname'''Tool'''}}, and its file too.
A '''Tool''' must be named {{hl|Classname'''Tool'''}}, and its file too.


=== Plugin ===


== Anatomy ==
=== Type ===
==== Plugin ====
A plugin inherits from {{hl|WorkbenchPlugin}} and is decorated with a {{hl|WorkbenchPluginAttribute}} attribute which signature is as follow:
A plugin inherits from {{hl|WorkbenchPlugin}} and is decorated with a {{hl|WorkbenchPluginAttribute}} attribute which signature is as follow:


Line 44: Line 67:
* icon
* icon
* wbModules: to which editors does this plugin apply (e.g {{hl|wbModules {{=}} { "ScriptEditor" }<nowiki/>}})
* wbModules: to which editors does this plugin apply (e.g {{hl|wbModules {{=}} { "ScriptEditor" }<nowiki/>}})
* category: the plugins menu entry in which this plugin will find itself (e.g Plugins > Text > TutorialPlugin)
* category: the plugins menu entry in which this plugin will find itself (e.g Plugins > Text > TutorialPlugin){{Feature|informative|{{hl|category}} accepts forward slash {{hl|/}} to create sub-categories.}}
* awesomeFontCode: the FontAwesome icon associated with the plugin (see [https://fontawesome.com/v5/cheatsheet FontAwesome's Cheatsheet])
* awesomeFontCode: the FontAwesome icon associated with the plugin (see [https://fontawesome.com/v5/cheatsheet FontAwesome's Cheatsheet])


Line 50: Line 73:
It can also, but is not mandatory, override the {{hl|Configure}} method to display a settings entry.
It can also, but is not mandatory, override the {{hl|Configure}} method to display a settings entry.


==== Tool ====
=== Tool ===
 
A tool is a system that allows for direct manipulation with a config panel available on the side.
A tool is a system that allows for direct manipulation with a config panel available on the side.


Line 61: Line 85:
=== Scripting ===
=== Scripting ===


==== Modules ====
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.
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.


Line 68: Line 93:
</enforce>
</enforce>


Where {{hl|ModuleType}} can be one of the following classes, all children of the {{hl|WBModuleDef}} class):
Where {{hl|ModuleType}} can be one of the classes listed {{Link|#mw-content-text|at the beginning of this document}}, all children of the {{hl|WBModuleDef}} class).
{| class="wikitable"
! 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 ===
Each module has obviously a different API - see their classes for more information.
 
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 {{Controls|Ctrl|Shift|H}} keyboard shortcut, and applies only to "ScriptEditor" Workbench module (a.k.a Script Editor).
 
<enforce>
[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!");
}
}
</enforce>
 
In the below code, the {{hl|GetCurrentLine}} method is used to get the cursor location's line number. The {{hl|GetLineText}}/{{hl|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).
 
<enforce>
[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);
}
}
</enforce>
 
{{Feature|important|Every operation goes into one {{Controls|Ctrl|Z}} '''each''', making reverting a multi-line text operation successive Ctrl+Zs.}}
 
=== Configure Method ===
 
The Configure method is the one called when clicking Plugins > Settings > ''Plugin'' ''Name''. If this method is not overridden with a non-empty code, the option does not appear in this menu.
 
=== Dialog ===
 
==== Setup ====
The {{hl|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 {{hl|Configure}}).
 
Displayed parameters are declared values decorated with an {{hl|Attribute}}; a full setup is done as follow:
 
<enforce>
[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);
}
}
</enforce>
 
{{Feature|informative|
Think of the plugin's behaviour: should the end user encounter a configuration popup on each tool usage
(e.g from the {{hl|Run}} method) or can it be configured once, or should ''some'' settings be offered on every usage?
}}
 
==== Buttons ====
A button method is decorated with a {{hl|ButtonAttribute}} attribute which signature is as follow:
<enforce>
ButtonAttribute(string label = "ScriptButton", bool focused = false)
</enforce>
 
A button method's return type can be anything, but the value will be treated as a boolean int (1 = true, 0 = false). A {{hl|void}} method will return 0. An empty string result will convert as a 1.
<enforce>
[ButtonAttribute("OK")]
int ButtonOK()
{
return 42; // Workbench.ScriptDialog will return 1/true
}
</enforce>
The {{hl|Workbench.ScriptDialog}}'s return value can then be used to know if the user confirmed or cancelled an interface.


{{Feature|informative|By default, a scripted dialog does not have any buttons and clicking on the close button (« × ») will make the {{hl|Workbench.ScriptDialog}} method return 0.}}
==== Plugins ====
Other plugins can be accessed through <enforce inline>aWorkbenchModule.GetPlugin(TAG_ClassNamePlugin);</enforce>.




{{GameCategory|armaR|Modding|Tutorials|Scripting|Workbench}}
{{GameCategory|armaR|Modding|Guidelines|Scripting}}

Revision as of 16:14, 26 April 2024

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 Data\Scripts\WorkbenchGame and are sorted by directories.

Editor Directory API Class
(Module Type)
Common Plugins Data\Scripts\WorkbenchGame N/A
Resource Manager Data\Scripts\WorkbenchGame\ResourceManager ResourceManager
World Editor (Tools and Plugins) Data\Scripts\WorkbenchGame\WorldEditor WorldEditor
Particle Editor N/A N/A
Animation Editor N/A N/A
Script Editor Data\Scripts\WorkbenchGame\ScriptEditor ScriptEditor
Audio Editor N/A N/A
Behavior Editor N/A N/A
String Editor Data\Scripts\WorkbenchGame\LocalizationEditor LocalizationEditor
Procedural Animation Editor N/A N/A

A Plugin must be named ClassnamePlugin, and its file too.

A Tool must be named ClassnameTool, and its file too.

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)
    ⓘ
    category accepts forward slash / to create sub-categories.
  • 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.

ⓘ
For now, Tools are only available for the World Editor, and inherit from the WorldEditorTool class.

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

Modules

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 classes listed at the beginning of this document, all children of the WBModuleDef class).

Each module has obviously a different API - see their classes for more information.

Plugins

Other plugins can be accessed through aWorkbenchModule.GetPlugin(TAG_ClassNamePlugin);.

Retrieved from "https://community.bistudio.com/wiki?title=Arma_Reforger:Workbench_Plugin&oldid=363916"