Property File Format

Version of the .prop file.

Name of the property. Manual properties inherited from a manual property refer to it by name. This name is also used to generate GUID for the manual property at run time. This GUID is used by child user properties to refer to their manual parent.

GUID for the property.

The guid attribute is optional. The GUID for the property will be generated from its name at runtime, if this attribute is not specified. GUID of a manual property is uniquely defined by its name.

GUID of a parent property. This attribute is used by a user property to refer to its parent.

Name of a parent property. The attribute is used in a manual property to refer to a manual parent property.

Flag, indicating if the property is manual: created or edited manually (not via the UnigineEditor).

Available values:

• 0 - not manual (by default)
• 1 - manual

Flag indicating if settings of the property can be modified in the UnigineEditor or via code.

Available values:

• 0 - cannot be edited
• 1 - editable (by default)

Flag indicating if a property is displayed in the Properties Hierarchy window. Sometimes it may be necessary to hide properties from artists in the UnigineEditor (e.g. to store certain information used for debugging purposes), this flag allows you to do so.

Available values:

• 0 - displayed (by default)
• 1 - hidden

For example, to create a manual property named custom_property and make it unchangeable, use the following:

<property version="2.14" name="custom_property" manual="1" editable="0">
...
</property>

Unique name of the structure.

Unique name of the base structure from which this structure inherits.

For example, to create a base structure named "struct1", inherit another structure named "struct2" with an extended set of parameters, and create a parameter named "my_struct_param" of the struct2 type, use the following:

<?xml version="1.0" encoding="utf-8"?>
<property version="2.14" name="custom_prop" manual="1">
	<struct name="struct1">
		<parameter name="param_a" type="int" a="0">1</parameter>
		<parameter name="param_b" type="toggle">0</parameter>
		<parameter name="param_c" type="int" sa="100">1</parameter>
	</struct>
	<struct name="struct2" parent_name="struct1">
		<parameter name="param2_a" type="toggle">0</parameter>
		<parameter name="param2_b" type="toggle">1</parameter>
	</struct>
	<parameter name="my_struct_param" type="struct2"></parameter>
</property>

Index of an array element for which a value is declared. For example, to specify a value of the 10^th element of the array of integer elements, you can use:

<?xml version="1.0" encoding="utf-8"?>
<property version="2.14" name="custom_prop" manual="1">
	<parameter name="my_array" type="array" array_type="int">
		<value index="10">133</value>
	</parameter>
</property>

Attribute that allows specifying some additional conditions for the parameters of the file and slider types.

Available values:

• asset - indicates that the file parameter refers to an asset
• runtime - indicates that the file parameter refers to a runtime file (this flag is set by default)
• abspath - indicates that the file parameter stores an absolute file path
• log10 - a logarithmic slider (with the base ten)
• expand - a value indicating if the minimum and maximum values of the slider parameter can be exceeded
• min_expand - a value indicating if the minimum value of the slider parameter can be decreased
• max_expand - a value indicating if the maximum value of the slider parameter can be increased

The flags parameter of the mask type can have one of the following values defining the type of the bit mask: intersection, physics_intersection, collision, exclusion, viewport, shadows, material, sound_source, sound_reverb, sound_occlusion, navigation, obstacle, physical, field.

<parameter name="My_bit_mask" type="mask" flags="collision">1</parameter>

Flag indicating if the parameter is displayed in the Parameters window.

Available values:

• 0 - displayed (by default)
• 1 - hidden

Attribute that contains a set of values of the switch parameter. Each of these values may have an optional arbitrary name associated with it. Items can have positive or negative values, several items can have the same value.

<parameter name="material_color" type="switch" items="red,green,blue,orange,yellow">0</parameter>

For example, if a property switch parameter is declared as follows:

<parameter items="red=-1,green,blue=5,yellow"/>

After loading we'll have switch items with the following values: red = -1, green = 0, blue = 5, yellow = 6. When addressing these switch items via code, we can use either their ordinal numbers starting from 0, or the values assigned to them.

PropertyParameter::setValue(5); // "blue" is selected in the corresponding combobox in UnigineEditor
PropertyParameter::setSwitchItem(3); // "yellow" is selected (3rd item, starting from 0)

// If "green" item is selected in UnigineEditor:
PropertyParameter::getValueInt(); // returns 0, as "green" corresponds to the value of 0.
PropertyParameter::getSwitchItem() // returns 1, as "green" is the 1st element in the combobox (starting from 0).

Minimum and maximum available values of the integer, float and double parameters.

Unique name of the parameter.

Parameter title that will be displayed in the UnigineEditor.

Tooltip for the parameter. The tooltip will be displayed in the UnigineEditor when the parameter field is pointed with the mouse.

Group to which the parameter belongs. The parameter will be displayed in the specified group in the UnigineEditor. This attribute is optional: you can use the group element instead.

Type of the parameter.

Available values:

• int - type of the property parameter that allows accepting an integer value in a given range
• mask - type of the property parameter that allows specifying a mask (an integer value)
• float - type of the property parameter that allows accepting a float value in a given range
• double - type of the property parameter that allows accepting a double value in a given range
• string - type of the property parameter that allows accepting a string value
• switch - a set of several possible values (more than 2) for the parameter is available
• toggle - only 2 possible values for the parameter are available (default)
• vec2 - type of the property parameter that allows accepting a vec2 value
• vec3 - type of the property parameter that allows accepting a vec3 value
• vec4 - type of the property parameter that allows accepting a vec4 value
• dvec2 - type of the property parameter that allows accepting a dvec2 value
• dvec3 - type of the property parameter that allows accepting a dvec3 value
• dvec4 - type of the property parameter that allows accepting a dvec4 value
• ivec2 - type of the property parameter that allows accepting a ivec2 value
• ivec3 - type of the property parameter that allows accepting a ivec3 value
• ivec4 - type of the property parameter that allows accepting a ivec4 value
• color - type of the property parameter that allows specifying a color (a vec4 value)
• file - type of the property parameter that allows accepting any file GUID or path (e.g. to a runtime file or an asset)
• property - type of the property parameter that allows accepting a GUID value of a property
• material - type of the property parameter that allows accepting a GUID value of a material
• node - type of the property parameter that allows specifying a node or a node ID (an integer value)
• <struct_name> - type of the property parameter that allows specifying a structure.
  Notice

  <struct_name>here can be any name of a <struct/> element previously defined in the *.prop file.
• array - type of the property parameter that allows specifying an array of parameters, all having the same type (any of the above, including struct types previously defined), and accessed using a common name followed by an index: array[0].

String specifying the type of elements for an array parameter (see above).

Here you can specify any of the types listed above, plus any name of a <struct/> element previously defined in the *.prop file.

Dimension of the array parameter (see above). This attribute is used to declare multi-dimensional arrays.

By default it is assumed that array_dim = 1, So, this attribute is optional for one-dimensional arrays.

String specifying a filter for file, material or property parameter values. For example, you can specify ".xml|.node|.txt" to filter certain types of files.

The attribute is optional.

You can use conditions to display or hide the parameter in the UnigineEditor depending on the values of some other parameters. The condition should be declared as follows:

PARAMETER_NAME = "VALUE_1 [, VALUE_2, ..., VALUE_8]".

You can use multiple conditions (see the example below), the parameter will be displayed only when all specified conditions are true.

For example, to add a string parameter named "my_str" that will be displayed only when my_toggle parameter is enabled, my_switch parameter is set to type2 or type3, and my_int parameter is equal to 15 use the following:

<?xml version="1.0" encoding="utf-8"?>
<property version="2.14" name="custom_prop" manual="1">
	<parameter name="my_type" type="switch" items="type1,type2,type3">1</parameter>
	<parameter name="my_toggle" type="toggle">1</parameter>
	<parameter name="my_int">15</parameter>
	<parameter name="my_str" my_type="1,2" my_toggle="1" my_int="15" type="string">All conditions are true!</parameter>
</property>

Name of the group.

For example, some parameters of a property named "my_property" can be grouped as follows:

<?xml version="1.0" encoding="utf-8"?>
<property version="2.14" name="my_property" parent_name="node_base" manual="1">
	<group name="Default">
		<parameter name="Param1">15</parameter>
		<parameter name="Param2">25</parameter>
		<parameter name="my_file" type="file" flags="asset">1.png</parameter>
		<parameter name="Param3" title="test_title">150</parameter>
	</group>
</property>

Or the group attribute can be used instead of the corresponding element:

<?xml version="1.0" encoding="utf-8"?>
<property version="2.14" name="custom_prop" manual="1">
	<parameter name="Param1" group="Group1">15</parameter>
	<parameter name="Param2" group="Group1">25</parameter>
	<parameter name="Param3" title="test_title" type="string">Hello, World!!!</parameter>
</property>