Property File Format

Property File Structure#

A property is a .prop text file that contains the information to specify the way the object will behave and interact with other objects and the scene environment. Properties can be adjusted via the UnigineEditor (user properties), via API or by manually editing the corresponding .prop file.

It is based on the .xml file type and shares all its methods.

A document (a .prop file) should have the .xml file declaration, containing its version and the type of encoding you are using. For example, to specify the 1.0 version and UTF-8 encoding, type:

XML Code

<?xml version="1.0" encoding="utf-8"?>

There are 3 basic entities of the .prop file:

Element. A component that may contain attributes, other elements, some content etc.
Attribute. A component placed inside the element tag containing the specified value.
Value. A component specifying the value of the attribute.

The syntax is the following:

Source code (XML)

<parent_element attribute="value">
	<child_element_1/>
	<child_element_2>content</child_element_2>
</parent_element>

Property Element#

The <property/> element defines a property.

It can have the attributes listed below.

version#

Version of the .prop file.

name#

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.

Notice

You cannot use two manual properties with the same name.

guid#

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.

parent#

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

parent_name#

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

manual#

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

Available values:

0 - not manual (by default)
1 - manual

editable#

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

Notice

Manual properties are displayed as read-only in the Editor regardless of the value of this flag.

Available values:

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

hidden#

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

Usage Example#

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

Source code (XML)

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

Parameter Struct#

A <struct/> element defines a structured type to be used for a property parameter(s). The property can have an as many structures as necessary. You can think of structure as "a definition of a property inside a property", so it can have the same child elements as the <property/> element (i.e. <parameter/> and <struct/>)

Notice

A structure can be inherited from another structure, in this case the parent must be defined inside the *.prop file before its child.

The element can have the attributes listed below.

name#

Unique name of the structure.

Notice

Reserved attribute names ("name", "type", etc.) cannot be used.

parent_name#

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

Notice

Reserved attribute names ("name", "type", etc.) cannot be used.

Usage Example#

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:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.3.0" 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>

Value Element#

A <value/> element defines an element of an array parameter.

Notice

This element can be used only inside a <parameter> element having the array type

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.3.0" name="custom_prop" manual="1">
	<parameter name="my_array" type="array" array_type="int">
		<value>1</value>
		<value>2</value>
		<value>3</value>
	</parameter>
</property>

The element has the following attribute:

index#

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:

Source code (XML)

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

Parameter Element#

A <parameter/> element defines a single parameter of the property. The property can have several parameters.

The element can have the attributes listed below.

flags#

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

hidden#

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

Available values:

0 - displayed (by default)
1 - hidden

items#

Attribute that contains a list of items of the switch parameter.

Source code (XML)

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

min and max#

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

name#

Unique name of the parameter.

Notice

Reserved attribute names ("name", "type", etc.) cannot be used.

title#

Parameter title that will be displayed in the UnigineEditor.

tooltip#

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

group#

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#

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)
vec3 - type of the property parameter that allows accepting a vec3 value
vec4 - type of the property parameter that allows accepting a vec4 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].

array_type#

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

Notice

This attribute is available only for array parameter types.

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

array_dim#

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

Notice

This attribute is available only for array parameter types.

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

filter#

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.

Notice

This attribute is available only for file, material and property parameter types.

The attribute is optional.

Parameter Conditions#

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

Notice

Conditions can be evaluated for int, toggle and switch parameter types
Maximum number of values is 8.
Conditions for standard attributes ("name", "type", etc.) cannot be used.

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

Usage Example#

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:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.3.0" 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_type="15" type="string">All conditions are true!</parameter>
</property>

Group Element#

A <group/> element specifies the group to which the parameters of the property belong to. The element is optional: parameters can be defined out of it. You can also specify the group attribute for the <parameter/> element instead of using the <group/> element.

name#

Name of the group.

Usage Example#

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

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.3.0" 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:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.3.0" 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>

Declaring Arrays#

Array parameter type enables you to declare a collection of parameters, all having the same type (specified via the array_type attribute), and accessed using a common name followed by an index: array[0].

You can declare multi-dimensional (specifying dimension via the array_type attribute), but be careful: the amount of memory needed for an array increases exponentially with each dimension. Arrays of structures are also supported.

To specify values of array elements when declaring an array, use the <value/> element.

Notice

It is not necessary to declare all array elements. You can specify values only for some of them via the index attribute of the <value/> element (can be useful for declaring overrides).

Below is an example of declaring a propery with a 2-dimensional array of float elements, named my_array2D, and specifying values for some of the elements.

So, the array parameter of the property has 4 elements:

array containing three float values: 0.0, 0.5, 1.0
array containing two float values: 0.0 (default), 0.25
array containing a single float value: 3.25
empty array (no elements)

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.3.0" name="my_property" parent_name="node_base" manual="1">
<parameter name="my_array2D" type="array" array_type="float" array_dim="2">
  <value>
	<value>0.0</value>
	<value>0.5</value>
	<value>1.0</value>
  </value>
  <value>
   <value index="1">0.25</value>
  </value>
  <value>
   <value>3.25</value>
  </value>
  <value/>
 </parameter>
</property>

Last update: 27.12.2018

Помогите сделать статью лучше

Была ли эта статья полезной?

Сообщить о проблеме в этой статье

(или выберите слово/фразу и нажмите Ctrl+Enter

Property File Format

In This Article:

Property File Structure#

Property Element#

version#

name#

guid#

parent#

parent_name#

manual#

editable#

hidden#

Usage Example#

Parameter Struct#

name#

parent_name#

Usage Example#

Value Element#

index#

Parameter Element#

flags#

hidden#

items#

min and max#

name#

title#

tooltip#

group#

type#

array_type#

array_dim#

filter#

Parameter Conditions#

Usage Example#

Group Element#

name#

Usage Example#

Declaring Arrays#