Resource Manager: Config Editor – Arma Reforger

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "<syntaxhighlight lang="C#">" to "<enforce>")
m (Fix)
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{TOC|side||4}}
{{TOC|side||4}}
{{Wiki|TODO|add images}}
{{Feature|informative|See {{Link|Arma Reforger:Scripting: Config Object}} and {{Link|Arma Reforger:Create a Config Class}} to see how to create and configure a config class.}}
 
 
== Main Interface ==
== Main Interface ==


Line 28: Line 30:
See uiwidget for all possible interfaces and how to interact with them.
See uiwidget for all possible interfaces and how to interact with them.


=== Array Interface ===
=== Array ===
 
a +/- interface displaying the amount of elements between parentheses.
 
Press + to add an element, - to remove the highlighted one.
 
To edit the array in a more advanced way, right-click on an item's name to use contextual menu's additional options:
 
 
== Config Base Container Class ==
 
A Base Container is a class that serves as a blueprint for the Config Editor.
 
=== BaseContainerProps ===
 
The usage of a {{hl|BaseContainerProps}} class decoration is required for the class to be visible and editable in the Config Editor - see Examples below.
 
The minimum required attribute usage is <enforce>[BaseContainerProps(configRoot: true)]</syntaxhighlight> for the base object Config to be visible in the Config creation process.
 
A class inheriting a decorated one must be decorated as well in order to be usable.
 
It accepts the following parameters:
<enforce>
BaseContainerProps(string category = "", string description = "", string color = "255 0 0 255", bool visible = true, bool insertable = true, bool configRoot = false, string icon = "", NamingConvention namingConvention = NamingConvention.NC_MUST_HAVE_GUID)
</syntaxhighlight>
A class name display is defined as follow:
 
* if the class uses a name instead of a GUID (see NC_MUST_HAVE_NAME), the name is displayed - otherwise, the classname is
* the class can use an  custom name with the usage of an additional decorator such as {{hl|BaseContainerCustomTitle}} or one of its children
 
==== category ====
Type: string
 
Default: ""
 
The class' category - only useful in World Editor plugins definition.
 
==== description ====
Type: string
 
Default: ""
 
The class' description - only useful in World Editor plugins definition.
 
==== color ====
Type: string
 
Default: "255 0 0 255"
 
The class' colour in RGBA format (Red Green Blue Alpha) in a 0..255 range - only useful in World Editor plugins definition.
 
==== visible ====
Type: bool
 
Default: true


The class' visibility - only useful in World Editor plugins definition.
a "+/-" interface displaying the current amount of elements between parentheses.


==== insertable ====
Press "+" to add an element, "-" to remove the highlighted one - if none is selected, the last array element is removed.
Type: bool


Default: true
To edit the array in a more advanced way, right-click on an item's name to use contextual menu's additional options.


==== configRoot ====
=== Slider ===
Type: bool


Default: false
Click and drag to set the value. It is still possible to click on the slider and manually enter the desired value.


Define if the class is selectable when creating a new Config.


==== icon ====
== Advanced Usage ==
Type: string


Default: ""
=== Config Prefab from Config ===
 
The class' icon - only useful in World Editor plugins definition.
 
==== namingConvention ====
Type: enum
 
Default: NamingConvention.NC_MUST_HAVE_GUID
 
See the NamingConvention enum class.
 
===== NC_CAN_HAVE_NAME =====
Internal use.
 
===== NC_MUST_HAVE_NAME =====
Force providing a name on object creation (whether a class or an array of them) instead of having an automatically generated GUID. The displayed object name is then the entered name.
 
===== NC_MUST_HAVE_GUID =====
The default value: the Workbench generates a GUID for this config entry. The displayed object name is then the classname.
 
=== Attribute ===
 
The usage of an {{hl|Attribute}} member variable decoration is required for the value to be visible and editable in the Config Editor - see Examples below.
 
The minimum required Attribute usage is <syntaxhighlight lang="c#" inline>[Attribute()]</syntaxhighlight>.
 
A variable's display name is deduced as follows:
 
{{hl|m_iMyVariable}} is split by removing {{hl|m_}} (conventional name prefix for a member variable), {{hl|i}} (optional, additional prefix for variable type) and splitting the remaining part using the capital letters: here {{hl|My Variable}}.
 
It accepts the following parameters:
<enforce>
Attribute(string defvalue = "", string uiwidget = "auto", string desc = "", string params = "", ParamEnumArray enums = null, string category = "", int precision = 3)
</syntaxhighlight>
 
==== defvalue ====
Type: string
 
Default: ""
 
The default value. It is always a string, even in the case of a boolean ("0", "1", '''not''' "false"/"true") or a number ("5678", "12.34").
 
==== uiwidget ====
Type: string
 
Default: "auto"
 
The Widget type to be used. It can be forced to whatever wanted. Note that not all widgets fit all variable types. See the UIWidgets class.
 
{{Feature|informative|In the case of an array, the value will define the UI for the items, not the array itself.}}
 
===== Auto =====
{| class="wikitable"
! Data Type
! UI Widget
|-
| bool
| Checkbox
|-
| int
| SpinBox
|-
| float
| EditBox (numerical version)
|-
| string
| EditBox (text version)
|-
| vector
| Coords
|-
| array
| Array Widget and item type Widget
|-
| Color
| ColorPicker
|}
 
===== Hidden =====
Does not display the field.
 
===== None =====
Identical to Hidden.
 
===== ColorPicker =====
a colour modification UI. Clicking the colour rectangle will display the colour picker, allowing to set values in many ways:
 
===== ResourceNamePicker =====
Allows referring to a resource of any kind.
 
===== ResourcePickerThumbnail =====
Allows previewing images and textures - to be combined with edds and/or imageset {{hl|params}} Attribute parameter.
 
===== FileNamePicker =====
Internal use.
 
===== ResourceAssignArray =====
Internal use.
 
===== Date =====
Range 01/01/2000 00:00 → 31/12/2063 23:59 '''UTC Time''' (e.g 01/01/2000 '''01:00''' in Western Europe)
 
Data types:
 
* int
 
===== Graph =====
Internal use.
 
===== Font =====
Internal use.
 
===== FileEditBox =====
Internal use.
 
===== SpinBox =====
a numerical, editable up-down field.
 
Data types:
 
* int
* float
 
===== ComboBox =====
A combo box that opens and allows to pick one value among a selection.
 
Data type:
 
* int
* float
* string
 
===== EditComboBox =====
Data type:
 
* int
* float
* string
 
===== SearchComboBox =====
Data type:
 
* int
* float
* string
 
===== LocaleEditBox =====
Internal use.
 
===== EditBox =====
Data type:
 
* int
* float
* string
 
===== CheckBox =====
Checked for true, unchecked for false.
 
Data types:
 
* bool
 
===== Slider =====
A click and drag allows to set the value on the slider; a click on the slider itself allows to type in the wanted value.
 
Data types:
 
* int
* float
 
===== Flags =====
Offers checkboxes for each enums provided. Power of two values are recommended, e.g:
<enforce>
enums: { ParamEnum("First flag", "1"), ParamEnum("Second flag", "2"), ParamEnum("Third flag", "2"), ParamEnum("Fourth flag", "8") } // etc
</syntaxhighlight>
 
Data types:
 
* int
 
===== Button =====
Internal use.
 
===== Script =====
Internal use.
 
===== EditBoxWithButton =====
Internal use.
 
===== LODFactorsEdit =====
Internal use.
 
===== Object =====
Clicking the "set class" button creates an instance allowing to set its values (if any).
 
Data types:
 
* object (all classes)
 
===== Coords =====
Clicking an axis letter and dragging left or right changes the value.
 
Data type:
 
* vector
 
===== Range =====
Internal only.
 
===== Callback =====
{{Feature|informative|A callback method must be decorated with <syntaxhighlight lang="c#" inline>[CallbackMethod()]</syntaxhighlight> and have the following signature: <syntaxhighlight lang="c#" inline>void MethodName(Managed eventParams)</syntaxhighlight>.}}
 
Data type:
 
* Event
 
===== TopLevelObject =====
Internal use.
 
===== GraphDialog =====
a graph modification UI. Double-clicking on the graph creates a new point, click/dragging on a point moves it (no further than its surrounding ones on the X-axis), clicking on a point focuses it, and pressing  removes that point.
 
Data types:
 
* Curve
 
===== BoundingVolume =====
Internal use.
 
===== Editor =====
Internal use.
 
==== desc ====
Type: string
 
Default: ""
 
The variable description; this provides a '''tooltip''' when hovering the variable name and does not replace it.
 
==== params ====
Type: string
 
Default: ""
 
Used to define UI-specific settings, e.g a numerical range.
 
* Number: "minValue, maxValue, step" (e.g {{hl|"0 100 5"}} for a 0..100 range with steps of 5)
* Vector: "minValue, maxValue, step, purpose, space" (e.g {{hl|"0 100 5"}} for a 0..100 range with steps of 5) for each vector value. {{hl|purpose}} and {{hl|space}} are optional; using them makes {{hl|step}} optional and allows to set the vector value in World Editor using the transformation gizmo.
** {{hl|purpose}} possible values:
*** {{hl|purposeCoords}} - the vector property represents coordinates
*** {{hl|purposeAngles}} - the vector property represents rotations
** {{hl|space}} possible values:
*** {{hl|spaceEntity}} - the vector represents a value in the entity's local space (relative coordinates)
*** {{hl|spaceWorld}}   - the vector is an absolute world position
*** {{hl|spaceCustom}}   - any custom space; if it is defined then World Editor asks the entity for a matrix of the space calling virtual function   {{hl|WB_GetKeySpaceMatrixWorld}} - this function is used for entity slots which do have custom orientation given by model pivots.
** examples:
*** {{hl|inf inf purposeCoords spaceEntity}}
*** {{hl|-90 +90 5 purposeAngles spaceWorld}}
* ResourcePicker: "extension1;extension2" (e.g {{hl|"dds;edds;imageset;png"}} for an Image Resource Picker)
 
{{Feature|informative|
* Note that setting a step for an integer does not prevent the user to type in the value manually.
* It is possible to use {{hl|inf}} (for "infinity") to specify a non-restricted range - e.g {{hl|"inf inf 0"}}.
}}
 
==== enums ====
Type: ParamsEnumArray
 
Default: null
 
An array of ParamEnum. Used to define ComboBox's items. It can be defined as follows:
<enforce>{ ParamEnum("Text 1", "Value 1", "Description"), ParamEnum("Text 2", "Value 2") }</syntaxhighlight>
 
The description is optional and is to fill a combobox's entry tooltip. As many as needed {{hl|ParamEnum}} entries can exist.
 
==== category ====
Type: string
 
Default: ""
 
The variable's category - only useful in World Editor plugins to categorise properties.
 
==== precision ====
Type: int
 
Default: 3
 
The wanted floating point precision. Restricts a floating point field to a certain amount of decimals.
 
 
== Config File ==
 
In the Resource Browser, browse to the directory in which to create the config file; then click on the '''Create''' button and select the '''Config File''' option:
 
Enter the new file's name in the appearing dialog:
 
Look for the BaseContainer class in the next one:
 
After clicking the classname once, the file is created from this model in the selected directory.
 
Double-click on it to open it and edit it.
 
 
== Config Prefab from Config ==


Creating a Prefab Config from a config object is doable by drag and dropping the object into the Resource Browser window.
Creating a Prefab Config from a config object is doable by drag and dropping the object into the Resource Browser window.
Line 411: Line 51:
This will display the dialog to name the new file; once filled the file is created in the selected directory.
This will display the dialog to name the new file; once filled the file is created in the selected directory.


 
=== Inherited Config File ===
== Inherited Config File ==


An inherited config file is a config that will use another config file as its default values model, and obviously uses the same config class.
An inherited config file is a config that will use another config file as its default values model, and obviously uses the same config class.
Line 420: Line 59:
The created file will now have the (default) values of the model.
The created file will now have the (default) values of the model.


=== Filling by Config ===


== Filling by Config ==
If a Config already exists and is compatible with the target entry, dragging and dropping the config on the field/entry will fill it with Config's values.
 
This is shown with the blue circle as well as the .conf button present in the value name, as shown below:
If a Config already exists and is compatible with the target entry, dragging and dropping the config on the field/entry will fill it with Config's values. This is shown with the blue circle as well as the .conf button present in the value name, as shown below:


Editing from the current Config will only change and override the sub-Config values in the current Config.
Editing from the current Config will only change and override the sub-Config values in the current Config.
Line 431: Line 70:
Changes made in one tab are immediately broadcast to other tabs if such sub-Config is used.
Changes made in one tab are immediately broadcast to other tabs if such sub-Config is used.


== Examples ==
The following {{hl|ConfigExample.conf}} is created from the below {{hl|SCR_ConfigExample}} class:
<enforce>
[BaseContainerProps(configRoot: true)]
class SCR_ConfigExample
{
//----------------------------------------------------------------------------------
// basic
//----------------------------------------------------------------------------------
[Attribute(defvalue: "1", desc: "This is a Bool value")]
bool m_bBoolValue;
[Attribute(defvalue: "-1", desc: "This is an Int value")]
int m_iIntValue;
[Attribute(defvalue: "0.5", desc: "This is a Float value")]
float m_fFloatValue;
[Attribute(defvalue: "-", desc: "This is a String value")]
string m_sStringValue;
[Attribute(defvalue: "0 1 0", desc: "This is a Vector value")]
vector m_vVectorValue;
[Attribute(defvalue: "1", uiwidget: UIWidgets.CheckBox, desc: "This is a Bool Array value")]
ref array<bool> m_aBoolArrayValue;
[Attribute(defvalue: "String default value", desc: "This is a String Array value")]
ref array<string> m_aStringArrayValue;
[Attribute(defvalue: "0.008 0.365 0 1", desc: "This is a Colour value")]
ref Color m_cColourValue;
// does not show up - no Attribute defined
int m_iIntValueNotShown;
// does not show up - no Set UI exists
[Attribute(defvalue: "", desc: "This is a String Set value")]
ref set<string> m_sSetValue;
// does not show up - no Map UI exists
[Attribute(defvalue: "", desc: "This is an Int-String Map value")]
ref map<int, string> m_mMapValue;
//----------------------------------------------------------------------------------
// advanced
//----------------------------------------------------------------------------------
[Attribute(defvalue: "50", desc: "This is an Int value in a 0..100 range with steps of 5", params: "0 100 5")]
int m_iIntValueMinMax;
[Attribute(defvalue: "50", uiwidget: UIWidgets.Slider, desc: "This is an Int value using a 0..100 slider with steps of 5", params: "0 100 5")]
int m_iIntValueSlider;
[Attribute(defvalue: "1", uiwidget: UIWidgets.ComboBox, desc: "This is an Int value using a combobox", enums: { ParamEnum("Zero", "0"), ParamEnum("One", "1"), ParamEnum("Two", "2") })]
int m_iIntValueComboBox;
[Attribute(defvalue: "", uiwidget: UIWidgets.ResourcePickerThumbnail, desc: "This is an Image Resource value", params: "edds;imageset")]
ResourceName m_ImageResourcePickerThumbnail;
}
</syntaxhighlight>


{{GameCategory|armaR|Modding|Official Tools|Resource Manager Viewports}}
{{GameCategory|armaR|Modding|Official Tools|Resource Manager Viewports}}

Latest revision as of 16:46, 24 April 2024

See Scripting: Config Object and Create a Config Class to see how to create and configure a config class.


Main Interface

Search Field

Search through value names (not values themselves).

Class

Remind the used Config class.

Parent

A button leading to the parent Config file, in the case of an inherited Config file.

Values

Below these fields are the values name/UI lines. An entry that is not the default value will be bolded.

An entry can be reset to its default value using the arrow  that appears then to the right of the field.


Value Interface

The value interface is composed of two columns; on the left, the value name (extracted from the property's name) and on the right, the UI to edit it - either deduced by the property's type or forced by the Config designer (see Attribute).

See uiwidget for all possible interfaces and how to interact with them.

Array

a "+/-" interface displaying the current amount of elements between parentheses.

Press "+" to add an element, "-" to remove the highlighted one - if none is selected, the last array element is removed.

To edit the array in a more advanced way, right-click on an item's name to use contextual menu's additional options.

Slider

Click and drag to set the value. It is still possible to click on the slider and manually enter the desired value.


Advanced Usage

Config Prefab from Config

Creating a Prefab Config from a config object is doable by drag and dropping the object into the Resource Browser window.

This will display the dialog to name the new file; once filled the file is created in the selected directory.

Inherited Config File

An inherited config file is a config that will use another config file as its default values model, and obviously uses the same config class.

In order to create one, right-click on the config file wanted as model in Resource Browser, then click "Create Inherited File" - a dialog will ask to type the inherited config file name.

The created file will now have the (default) values of the model.

Filling by Config

If a Config already exists and is compatible with the target entry, dragging and dropping the config on the field/entry will fill it with Config's values. This is shown with the blue circle as well as the .conf button present in the value name, as shown below:

Editing from the current Config will only change and override the sub-Config values in the current Config.

To edit the sub-Config values directly, press the .conf button to open said Config.

Changes made in one tab are immediately broadcast to other tabs if such sub-Config is used.