Programming
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 library is a .prop text file that contains all of the information to specify the way the object will behave and interact with other objects and the scene environment. Properties can be adjusted manually in the text file or via API.

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>

Properties Element

A <properties/> element defines a property library, so all of the properties should be placed inside this element.

It can have the attributes listed below.

editable

A flag indicating if all the child properties settings can be changed in Properties Editor.

Available values:

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

version

A version of the .prop file.

For example, to specify the 1.00 version of the .prop file and make the properties unchangeable, type:

Source code (XML)
<properties version="1.00" editable="0"></properties>

Property Element

A <property/> element defines a property.

It can have the attributes listed below.

editable

A flag indicating if settings of the property can be changed in Properties Editor.

Available values:

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

hidden

A flag indicating if a property is displayed in the property list of Properties Editor.

Available values:

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

name

A unique name of a property.

parent

A name of a parent property.

Usage Example

For example, to create the unchangeable property named custom_property, type:

Source code (XML)
<properties version="1.0">
	<property name="custom_property" editable="0">
	...
	</property>
</ptoperties>

Options Element

An <options/> element defines options for the current property. The options are also common to all children of the current property.

It can have the attributes listed below.

collision

A flag indicating if collision test is enabled/disabled for the surfaces that have the property assigned. The surface will be tested for collision only if both the property and the surface (Nodes -> Surfaces -> Collision) options specify that.

Available values:

  • 0 - disabled
  • 1 - enabled (by default)
Source code (XML)
<options collision="0"/>

intersection

A flag indicating if intesection test is enabled/disabled for the surfaces that have the property assigned. The surface will be tested for intersection only if both the property and the surface (Nodes -> Surfaces -> Intersection) options specify that.

Available values:

  • 0 - disabled
  • 1 - enabled (by default)
Source code (XML)
<options intersection="0"/>

Usage Example

For example, to create a property with intersection test disabled, type:

Source code (XML)
<properties version="1.0">
<property name="custom_property">
	<options intersection="0"/>
</property>
</ptoperties>

State Element

A <state/> element dynamically shows/hides parameters of the property. The property can have several states.

For the state to take an effect, it should be specified as an attribute of a parameter with the requred value. By default, a state can have 2 possible values:

  • If 0 is specified, the parameter will be displayed only when the state is disabled.
  • If 1 is specified, the parameter will be displayed when the state is enabled.

If the value isn't specified, 0 will be set by default.

The <state/> element can have the attributes listed below.

hidden

A flag indicating if the state is displayed in the states list of Properties Editor.

Available values:

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

items

An attribute that contains a list of items of the switch state.

Source code (XML)
<state name="light" type="switch" items="omni,projected,probe">0</state>

name

A unique name of the state.

type

A type of the state.

Available values:

  • aux - an auxiliary type
  • switch - a set of several possible values (more than 2) for the state is available
  • toggle - only 2 possible values for the state are available (default)

Usage Example

For example, you can create a state of the toggle type and specify it for the parameter so that it is shown in Properties Editor only when the state is enabled:

Source code (XML)
<properties version="1.0">
<property name="custom_property">
	<states name="dynamic">0</states>
	<parameter name="path" type="string" dynamic="1">unigine_project/meshes/box.mesh</parameter>
</property>
</ptoperties>
The state itself can have any value allowed.

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

An attribute that allows specifying some additional conditions for the parameters of the string and slider types.

Available values:

  • file - a file dialog window is opened when double-clicking the string parameter value
  • 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

A flag indicating if the parameter is displayed in the parameters list of Properties Editor.

Available values:

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

items

An attribute that contains a list of items of the switch parameter.

Source code (XML)
<parameter name="material" type="switch" items="properties_mesh_red,properties_mesh_green,properties_mesh_blue,properties_mesh_orange,properties_mesh_yellow">0</parameter>

min and max

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

name

A unique name of the parameter.

type

A type of the parameter.

Available values:

  • aux - auxiliary type
  • color - type of the property parameter that allows specifying the material 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
  • 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)
  • 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

State Attributes

For the parameter to be displayed only if the state is set to a definite value, the corresponding state should be specified as an attribute for the parameter.

Usage Example

For example, to add the float parameter that will be shown only when the dynamic state is enabled and to set the maximum value for this parameter that can be exceeded, type:

Source code (XML)
<properties version="1.0">
<property name="custom_property">
	<state name="dynamic">0</state>
	<parameter name="mass" type="float" dynamic="1" max="10" flags="max_expand">1</parameter>
</property>
</ptoperties>
Last update: 2017-10-20