Workbench Plugin – Arma Reforger
Lou Montana (talk | contribs) m (Text replacement - "lang="cpp">" to "lang="C#">") |
Lou Montana (talk | contribs) (Add configure infobox) |
||
(11 intermediate revisions by the same user not shown) | |||
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| | 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 | ||
| | | {{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}} | |||
|- | |- | ||
| | | Animation Editor | ||
| | | {{n/a}} | ||
| {{n/a}} | |||
|- | |- | ||
| Script Editor | | Script Editor | ||
| ScriptEditor | | {{hl|Data\Scripts\WorkbenchGame\ScriptEditor}} | ||
| {{Link/Enfusion|armaR|ScriptEditor}} | |||
|- | |- | ||
| | | Audio Editor | ||
| | | {{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 28: | Line 55: | ||
== | == 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: | ||
< | <enforce> | ||
WorkbenchPluginAttribute(string name, string description = "", string shortcut = "", string icon = "", array<string> wbModules = null, string category = "", int awesomeFontCode = 0) | WorkbenchPluginAttribute(string name, string description = "", string shortcut = "", string icon = "", array<string> wbModules = null, string category = "", int awesomeFontCode = 0) | ||
</ | </enforce> | ||
* name is mandatory: it is the plugin's display name | * name is mandatory: it is the plugin's display name | ||
* description | * description: optional, it is the on hover description text | ||
* shortcut: none (empty string) can be defined, the plugin will then need to be triggered from the Plugin top menu | * shortcut: in format e.g {{hl|"Ctrl+Shift+I"}} for {{Controls|Ctrl|shift|I}} - none (empty string) can be defined, the plugin will then need to be triggered from the Plugin top menu | ||
* 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 > | * category: the plugins menu entry in which this plugin will find itself (e.g Plugins > Text > ''Plugin Name''){{Feature|informative|{{hl|category}} accepts forward slash {{hl|/}} to create sub-categories.}} | ||
* awesomeFontCode: the FontAwesome icon associated with the plugin (see | * awesomeFontCode: the FontAwesome icon associated with the plugin (see {{Link|https://fontawesome.com/FontAwesome}}'s {{Link|https://fontawesome.com/v5/search?o{{=}}r&m{{=}}free|Free Icons Cheatsheet}}) | ||
A plugin must also override either or both {{hl|Run}} or {{hl|RunCommandLine}} methods in order to have an impact. | A plugin must also override either or both {{hl|Run}} or {{hl|RunCommandLine}} methods in order to have an impact. | ||
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 == | |||
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 59: | Line 85: | ||
It is decorated with a {{hl|WorkbenchToolAttribute}} attribute which signature is identical to {{hl|WorkbenchPluginAttribute}} (see above). | It is decorated with a {{hl|WorkbenchToolAttribute}} attribute which signature is identical to {{hl|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. | 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: | Each Workbench module (editor) API can be accessed through the following script: | ||
< | <enforce> | ||
ModuleType moduleType = Workbench.GetModule(ModuleType); | ModuleType moduleType = Workbench.GetModule(ModuleType); | ||
</ | </enforce> | ||
Where {{hl|ModuleType}} can be one of the | 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). | ||
Each module has obviously a different API | Each module has obviously a different API - see their classes for more information. | ||
=== Plugins === | |||
Other plugins can be accessed through <enforce inline>aWorkbenchModule.GetPlugin(TAG_ClassNamePlugin);</enforce>. | |||
=== | === Common Methods === | ||
See {{Link/Enfusion|armaR|WorkbenchPlugin}}. | |||
==== Run ==== | |||
The {{hl|Run}} method is called when clicking Plugins > ''Plugin Name'' or using its shortcut if any. If this method is not overridden with a non-empty code, the plugin does not appear in this menu. | |||
{{Feature|informative|There is no way to distinguish between clicking the plugin in the menu or using the shortcut.}} | |||
==== RunCommandline ==== | |||
The {{hl|RunCommandline}} method is called when calling the script from {{Link|Arma Reforger:Startup Parameters}}'s {{Link|Arma Reforger:Startup Parameters#plugin|plugin}} option, e.g: | |||
ArmaReforgerWorkbenchSteam.exe -wbModule=ScriptEditor -plugin=TAG_MyPlugin pluginArguments | |||
{{ | ==== Configure ==== | ||
The {{hl|Configure}} method is called when clicking Plugins > Settings > ''Plugin Name''. If this method is not overridden with a non-empty code, the entry does not appear in this menu. | |||
{{Feature|informative| | |||
Think of the plugin's behaviour: should the end user encounter a configuration popup: | |||
* on each plugin usage (e.g from the <enforce inline>Run</enforce> method) | |||
* only when reaching for the plugin settings | |||
* and/or should only ''some'' settings be offered on every usage? | |||
}} | |||
The | ==== OnResourceContextMenu ==== | ||
The {{hl|OnResourceContextMenu}} method is called when clicking {{Link|Arma Reforger:Resource Manager}} Resource Browser Context Menu's Plugins > ''Plugin Name''. | |||
{{Feature|important|For the plugin to appear, {{hl|WorkbenchPluginAttribute}}'s {{hl|resourceTypes}} parameter must be defined (e.g <enforce inline>resourceTypes: { "fbx", "xob", "et" }</enforce>) | |||
=== | === Generic Modal === | ||
The <enforce inline>Workbench.Dialog()</enforce> method can be used to create a modal addressed to the user. It takes a caption (modal title) a text (in-modal description text), and a detailed text if needed. | |||
The | |||
The end result is a modal with an OK button and a "Show Details" button if a detailed text has been provided. | |||
=== Scripted Modal === | |||
The <enforce inline>Workbench.ScriptDialog()</enforce> method can be used to create a modal addressed to the user to confirm an action or set values. It can be used in any method (e.g not only {{hl|Configure}}). | |||
It takes a caption (modal title) a text (in-modal description text), and a class instance - usually <enforce inline>this</enforce>. | |||
The class instance can be anything but {{hl|null}}, but it is much more interesting to offer options to the user, at least an OK/Cancel button choice. | |||
{{Feature|informative|If no buttons are defined, the modal can still be closed through the close button (« × ») or using {{Controls|Alt|F4}}.}} | |||
} | |||
{{ | ==== Attributes ==== | ||
Same as a {{Link|Arma Reforger:Scripting: Config Object|Config Object}} declaration, the <enforce inline>[Attribute()]</enforce> decorator is required. | |||
<enforce> | |||
[Attribute(defvalue: "1", desc: "Does something, otherwise does nothing")] | |||
protected m_bDoSomething; | |||
</enforce> | |||
==== Buttons ==== | ==== Buttons ==== | ||
A button method is decorated with a | A button method is decorated with a <enforce inline>[Button()]</enforce> decorator which signature is as follow: | ||
< | <enforce> | ||
ButtonAttribute(string label = "ScriptButton", bool focused = false) | 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. | 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. | ||
< | {{Feature|important|Beware, as an empty string result will convert as a 1.}} | ||
[ButtonAttribute("OK")] | |||
<enforce> | |||
[ButtonAttribute("OK", true)] // focused by default | |||
int ButtonOK() | int ButtonOK() | ||
{ | { | ||
return 42; // Workbench.ScriptDialog will return 1/true | return 42; // Workbench.ScriptDialog will return 1/true | ||
} | } | ||
</ | |||
[ButtonAttribute("Cancel")] | |||
int ButtonCancel() | |||
{ | |||
return 0; // Workbench.ScriptDialog will return 0/false | |||
} | |||
</enforce> | |||
The {{hl|Workbench.ScriptDialog}}'s return value can then be used to know if the user confirmed or cancelled an interface. | 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.}} | {{Feature|informative|By default, a scripted dialog does not have any buttons and clicking on the close button (« × ») or using {{Controls|Alt|F4}} will make the {{hl|Workbench.ScriptDialog}} method return 0.}} | ||
== Tutorials == | |||
See {{GameCategory|armaR|Modding|Tutorials|Scripting|Workbench|text= Plugin/Tool tutorials}}. | |||
{{GameCategory|armaR|Modding| | {{GameCategory|armaR|Modding|Guidelines|Scripting}} |
Latest revision as of 23:51, 28 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:
- name is mandatory: it is the plugin's display name
- description: optional, it is the on hover description text
- shortcut: in format e.g "Ctrl+Shift+I" for Ctrl + ⇧ Shift + I - 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 > Plugin Name)
- awesomeFontCode: the FontAwesome icon associated with the plugin (see https://fontawesome.com/FontAwesome's Free Icons 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
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:
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);.
Common Methods
See WorkbenchPlugin.
Run
The Run method is called when clicking Plugins > Plugin Name or using its shortcut if any. If this method is not overridden with a non-empty code, the plugin does not appear in this menu.
RunCommandline
The RunCommandline method is called when calling the script from Startup Parameters's plugin option, e.g:
ArmaReforgerWorkbenchSteam.exe -wbModule=ScriptEditor -plugin=TAG_MyPlugin pluginArguments
Configure
The Configure method is called when clicking Plugins > Settings > Plugin Name. If this method is not overridden with a non-empty code, the entry does not appear in this menu.
OnResourceContextMenu
The OnResourceContextMenu method is called when clicking Resource Manager Resource Browser Context Menu's Plugins > Plugin Name. {{Feature|important|For the plugin to appear, WorkbenchPluginAttribute's resourceTypes parameter must be defined (e.g resourceTypes: { "fbx", "xob", "et" })
Generic Modal
The Workbench.Dialog() method can be used to create a modal addressed to the user. It takes a caption (modal title) a text (in-modal description text), and a detailed text if needed.
The end result is a modal with an OK button and a "Show Details" button if a detailed text has been provided.
Scripted Modal
The Workbench.ScriptDialog() method can be used to create a modal addressed to the user to confirm an action or set values. It can be used in any method (e.g not only Configure). It takes a caption (modal title) a text (in-modal description text), and a class instance - usually this.
The class instance can be anything but null, but it is much more interesting to offer options to the user, at least an OK/Cancel button choice.
Attributes
Same as a Config Object declaration, the [Attribute()] decorator is required.
Buttons
A button method is decorated with a [Button()] decorator which signature is as follow:
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.
The Workbench.ScriptDialog's return value can then be used to know if the user confirmed or cancelled an interface.