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 (Text replacement - "<syntaxhighlight lang="c#" inline>" to "<enforce inline>")
Line 125: Line 125:
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 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>.
The minimum required Attribute usage is <enforce inline>[Attribute()]</syntaxhighlight>.


A variable's display name is deduced as follows:
A variable's display name is deduced as follows:
Line 312: Line 312:


===== Callback =====
===== 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>.}}
{{Feature|informative|A callback method must be decorated with <enforce inline>[CallbackMethod()]</syntaxhighlight> and have the following signature: <enforce inline>void MethodName(Managed eventParams)</syntaxhighlight>.}}


Data type:
Data type:

Revision as of 19:18, 30 July 2022

🚧
TODO: add images

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 Interface

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

insertable

Type: bool

Default: true

configRoot

Type: bool

Default: false

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

icon

Type: string

Default: ""

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 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 <enforce inline>[Attribute()]</syntaxhighlight>.

A variable's display name is deduced as follows:

m_iMyVariable is split by removing m_ (conventional name prefix for a member variable), i (optional, additional prefix for variable type) and splitting the remaining part using the capital letters: here 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.

In the case of an array, the value will define the UI for the items, not the array itself.
Auto
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 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
A callback method must be decorated with <enforce inline>[CallbackMethod()]</syntaxhighlight> and have the following signature: <enforce 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 "0 100 5" for a 0..100 range with steps of 5)
  • Vector: "minValue, maxValue, step, purpose, space" (e.g "0 100 5" for a 0..100 range with steps of 5) for each vector value. purpose and space are optional; using them makes step optional and allows to set the vector value in World Editor using the transformation gizmo.
    • purpose possible values:
      • purposeCoords - the vector property represents coordinates
      • purposeAngles - the vector property represents rotations
    • space possible values:
      • spaceEntity - the vector represents a value in the entity's local space (relative coordinates)
      • spaceWorld   - the vector is an absolute world position
      • spaceCustom   - any custom space; if it is defined then World Editor asks the entity for a matrix of the space calling virtual function   WB_GetKeySpaceMatrixWorld - this function is used for entity slots which do have custom orientation given by model pivots.
    • examples:
      • inf inf purposeCoords spaceEntity
      • -90 +90 5 purposeAngles spaceWorld
  • ResourcePicker: "extension1;extension2" (e.g "dds;edds;imageset;png" for an Image Resource Picker)
  • Note that setting a step for an integer does not prevent the user to type in the value manually.
  • It is possible to use inf (for "infinity") to specify a non-restricted range - e.g "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 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.

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.


Examples

The following ConfigExample.conf is created from the below 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>