UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Программирование
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes

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" name="custom_property" manual="1" editable="0">
...
</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:

  • color - type of the property parameter that allows specifying a color (a vec4 value)
  • double - type of the property parameter that allows accepting a double value in a given range
  • float - type of the property parameter that allows accepting a float value in a given range
  • 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
  • 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)
  • node - type of the property parameter that allows specifying a node or a node ID (an integer value)
  • 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

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" 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" 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" 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>
Last update: 26.04.2018