This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Rendering
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Animations-Related Classes
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

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

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.14" 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 10th element of the array of integer elements, you can use:

Source code (XML)
<?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>

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

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.

Source code (XML)
<parameter name="My_bit_mask" type="mask" flags="collision">1</parameter>

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

Source code (XML)
<parameter name="material_color" type="switch" items="red,green,blue,orange,yellow">0</parameter>
Notice
The space in the items attribute declaration is also a symbol included in the item name. Thus, items="red, green" shall produce the items with the following names: "red" and " green" (with the space before the word).

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

Source code (XML)
<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.

Source code (C++)
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).

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)
  • 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].

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

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

Source code (XML)
<?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>

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 property 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:

  1. array containing three float values: 0.0, 0.5, 1.0
  2. array containing two float values: 0.0 (default), 0.25
  3. array containing a single float value: 3.25
  4. empty array (no elements)
Source code (XML)
<?xml version="1.0" encoding="utf-8"?>
<property version="2.14" 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: 2022-01-21
Build: ()