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 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:
<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:
<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:
<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)
<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)
<options intersection="0"/>Usage Example
For example, to create a property with intersection test disabled, type:
<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.
<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:
<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>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.
<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
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:
<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>