Unigine.Property Class

Sort by:

List of functions:

List of Variables:

PARAMETER_COLOR
PARAMETER_DOUBLE
PARAMETER_FLOAT

PARAMETER_INT
PARAMETER_MASK

PARAMETER_NODE

PARAMETER_STRING
PARAMETER_SWITCH
PARAMETER_TOGGLE
PARAMETER_VEC3
PARAMETER_VEC4

This class provides an interface for property manipulation: it is used to modify properties that allow you to control values of the logic-related parameters. When a property is assigned to a node, an instanced internal property is created and saved into a .world or .node file. However, rather than the whole list of parameters it contains only the modified ones.

The concepts of a path and a name of the property should be distinguished:

The path specifies where the property is stored on the disk. The path includes a property file name.
The name specifies how the property will be displayed in the UnigineEditor (the Property Hierarchy window, the nodes surface section of the Parameters window). The name can also be used to refer to a property from the code.

By default, the property name and the *.prop file name coincide.

By using functions of this class, you can, for example, implement a properties editor.

Properties specify the way the object will behave and interact with other objects and the scene environment.

A property is a "material" for application logic represented by a set of logic-related parameters. Properties can be used to build components to extend the functionality of nodes.

All properties in the project are organized into a hierarchy. To be modified, properties should be obtained from the hierarchy via API functions.

For example, if we have the following *.prop files in the data folder:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.0.1" manual="1" name="surface_base_0" parent_name="surface_base">
	<parameter name="friction">1.833</parameter>
	<parameter name="restitution">0.194</parameter>
	<parameter name="occlusion">0.791</parameter>
	<parameter name="my_parameter">190</parameter>
</property>

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.0.1" manual="1" name="surface_base_1" parent_name="surface_base">
	<parameter name="my_parameter">191</parameter>
</property>

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.0.1" manual="1" name="surface_base_2" parent_name="surface_base">
	<parameter name="my_parameter">192</parameter>
</property>

You can implement a function that changes a parameter of a given property stored in this library:

Source code (C#)

// 1. Declare the array to store instances of the Property class
Property[] my_properties;

// 2. Implement the function that sets the given value of the parameter named "my_parameter" for the given property
void set_my_parameter(int num, int value){
	Property property = my_properties[num];
	int index = property.findParameter("my_parameter");
	if (index != -1)
	{
		property.setParameterInt(index,value);
	}
} 

// 3. On the application initialization, form the array of properties.
// It can be used for fast access to the required properties later
public override int init(){
	// get a pointer to the property manager
	Properties properties = Properties.get();

	// initialize the array of Property instances
	my_properties = new Property[properties.getNumProperties()];
	for (int num = 0; num < properties.getNumProperties(); num++) {
		// get a property from the library and add it to the array of properties
		my_properties[num] = properties.getProperty(num);
	}
	
	return 1;
}

// 4. Call the implemented function when it is necessary
public override int update()

	...
	set_my_parameter(num,num+100);
	...
	
	return 1;

}

Notice

You can modify only existing parameters of the property. To add or remove new parameters, you should manually edit the .prop file or use API to edit the XML file via the code.

Adding and Removing Properties

NoticeThe Property class doesn't allow adding a new property to the property hierarchy.

A new property can be added to the hierarchy in one of the following ways:

By creating and editing the corresponding .prop file manually. For example, in the data folder let us create the following file describing a property for a GameObjectUnit:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.0.1" manual="1" editable="0" name="GameObjectsUnit">
	<parameter name="weapon_type" type="switch" items="air,land,all_types">0</parameter>
	<parameter name="attack" type="toggle">1</parameter>
	<parameter name="damage" type="int" max="1000">1</parameter>
	<parameter name="velocity" type="float" max="100">30</parameter>
	<parameter name="material" type="string"/>
</property>

By inheriting from the existing property via Properties.inheritProperty() function or inherit() function of the Property class. For example:
Source code (C#)
```
// get a pointer to the property manager
Properties properties = Properties.get();

// inherit a GameObjectsUnit_0 property from the GameObjectsUnit property
Property inherited_prop = properties.findManualProperty("GameObjectsUnit").inherit("GameObjectsUnit_0", "game_object_unit_0.prop");

// inherit a GameObjectsUnit_1 property from the GameObjectsUnit_0 property via the Manager
properties.inheritProperty(inherited_prop.getGUID(), "GameObjectsUnit_1", "game_object_unit_1.prop");
```
To save all properties in the hierarchy that can be saved (i.e., editable, having a path specified, and not internal or manual ones) via the Properties.saveProperties() function.
Notice
By default, all parameters and states of the inherited property are the same as specified in the parent property. A child property can override some parameters of its parent or add new ones.
By editing the corresponding .prop file via API: you can open an XML file, write data into it and save it.

To delete a property, you can simply call the removeProperty() function:

Source code (C#)

// remove the property with the given name with all its children and delete the *.prop file
properties.removeProperty(properties.findProperty("GameObjectsUnit_0").getGUID(), 1, 1);

Property Class

Members

Property()

Constructor. Creates a new property instance.

Property getChild(int num)

Returns the child property of the current property.

Arguments

int num - The number of the target child property.

Return value

Child property.

int getID()

Returns the ID of the property.

Return value

Property ID.

UGUID getGUID()

Returns the GUID of the property.

Return value

GUID of the property.

int isBase()

Returns a value indicating if the property is a base property.

Return value

1 if the property is a base property; otherwise, 0.

void setEditable(int editable)

Sets a value indicating if the property can be edited.

Arguments

int editable - 1 to make the property editable; 0 to make it read-only.

int isEditable()

Returns a value indicating if the property can be edited.

Return value

1 if the property is editable; otherwise, 0.

int isHidden()

Returns a value indicating if the property is hidden.

Return value

1 if the property is hidden; otherwise, 0.

int isEngine()

Returns a value indicating if the property is engine-related (i.e. required for engine operation). Such properties are stored in the core, editor and editor2 folders.

Return value

1 if the property is engine-related; otherwise, 0.

int isInternal()

Returns a value indicating if the property is internal.

Return value

1 if the property is internal; otherwise, 0.

int isManual()

Returns a value indicating if the property is manual.

Return value

1 if the property is manual; otherwise, 0.

int isHierarchyValid()

Returns a value indicating if there are no missing parents in the hierarchy of the property.

Return value

1 if there are no missing parents in the hierarchy of the property; otherwise, 0.

int isParameterInherited(int num)

Returns a value indicating if the given parameter is inherited from a parent.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

1 if the given parameter is inherited from a parent; otherwise, 0.

int isParameterHidden(int num)

Returns a value indicating if the given parameter is hidden.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

1 if the given parameter is hidden; otherwise, 0.

int isParameterOverridden(int num)

Returns a value indicating if a given parameter is overridden.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

1 if the given parameter is overridden; otherwise, 0.

void setName(string name)

Sets a new name for the property.

Notice

This method is not available for manual and non-editable properties.

Arguments

string name - Name of the property.

string getName()

Returns the property name.

Return value

Name of the property.

Notice

If the property is internal and has a parent, the parent's name will be returned.

int getNumChildren()

Returns the number of children of the current property.

Return value

Number of child properties.

int getNumParameters()

Returns the number of property's parameters.

Return value

Number of property parameters.

int hasOverrides()

Returns a value indicating if the property has at least one overriden parameter.

Return value

1 if the property has at least one overriden parameter; otherwise, 0.

int findParameter(string name)

Searches for a parameter by the given name among all parameters of the current property and also among all parameters of the parent property that aren't overridden in the current property.

Arguments

string name - Name of the parameter.

Return value

The number of the parameter, if it is found; otherwise, -1.

int fetchParameter(string name, int fast_id)

Searches for a parameter by a given name among all parameters of the property.

Arguments

string name - Parameter name.
int fast_id - Parameter number in users auxiliary parameters cache. The value must be in the range [0; 128].

Return value

Parameter number, if it is found; otherwise, -1.

bool setParameter(int num, Variable value)

Updates the value of the given parameter.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
Variable value - New value of the parameter.

Variable getParameter(int num)

Returns the value of the given parameter.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the parameter.

string getParameterGroup(int num)

Returns the name of the group, to which the specified property parameter belongs. Property parameters are displayed in groups in the Parameters window of the UnigineEditor.

Arguments

int num - Parameter number.

Return value

Name of the group to which the specified property parameter belongs.

string getParameterFilter(int num)

Returns the filter string associated with the specified property parameter. This string specifies a filter for file, material or property parameter values thet will be used in the UnigineEditor. For example, you can specify ".xml|.node|.txt" to filter certain types of assets, or specify a base material to filter out materials, that cannot be used in a particular case (e.g. to avoid an attempt of assigning a post material to a mesh).

Notice

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

Arguments

int num - Parameter number.

Return value

String specifying a filter for file, material or property parameter values.

string getParameterTitle(int num)

Returns the title of the specified property parameter. This title is displayed in the UnigineEditor's UI.

Arguments

int num - Parameter number.

Return value

Title of the specified property parameter.

string getParameterTooltip(int num)

Returns the tooltip of the specified property parameter. This tooltip is displayed in the UnigineEditor, when user hovers a mouse over the property field.

Arguments

int num - Parameter number.

Return value

Tooltip text of the specified property parameter.

void setParameterFile(int num, string value)

Updates the value of the given file parameter. If the property is not editable, the value won't be updated.

The value stored in the file parameter (this value will be returned by the getParameterFile() method) depends on the flags set for the parameter:

Source code (C++)

// flags = "asset"
setParameterFile("guid://asset_guid"); 		// getParameterFile() -> asset_path
setParameterFile("guid://runtime_guid");	// getParameterFile() -> asset_path
setParameterFile("asset_path");				// getParameterFile() -> asset_path
setParameterFile("runtime_path");			// getParameterFile() -> asset_path

// flags = "runtime" - default
setParameterFile("guid://asset_guid"); 		// getParameterFile() -> runtime_path
setParameterFile("guid://runtime_guid");	// getParameterFile() -> runtime_path
setParameterFile("asset_path");				// getParameterFile() -> runtime_path
setParameterFile("runtime_path");			// getParameterFile() -> runtime_path

// flags = "abspath"
setParameterFile(file_path);				// getParameterFile() -> file_path

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
string value - New value for the file parameter.

string getParameterFile(int num, int fast)

Returns the current value of the given file parameter.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list. An index in users auxiliary parameters cache can laso be specified, in this case the fast flag should be set to 1.
int fast - 1 to use the specified number as an index in users auxiliary parameters cache; otherwise, 0.

Return value

Current file parameter value depending on the flags set for the parameter:

Source code (C++)

// flags = "asset"
setParameterFile("guid://asset_guid"); 		// getParameterFile() -> asset_path
setParameterFile("guid://runtime_guid");	// getParameterFile() -> asset_path
setParameterFile("asset_path");				// getParameterFile() -> asset_path
setParameterFile("runtime_path");			// getParameterFile() -> asset_path

// flags = "runtime" - default
setParameterFile("guid://asset_guid"); 		// getParameterFile() -> runtime_path
setParameterFile("guid://runtime_guid");	// getParameterFile() -> runtime_path
setParameterFile("asset_path");				// getParameterFile() -> runtime_path
setParameterFile("runtime_path");			// getParameterFile() -> runtime_path

// flags = "abspath"
setParameterFile(file_path);				// getParameterFile() -> file_path

Notice

To get a GUID of the file, use the getParameterGUID() method.

int getParameterFileIsAsset(int num)

Returns a value indicating if the specified file parameter stores a reference to an asset file.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

1 if the specified file parameter stores a reference to an asset file; otherwise, 0.

int getParameterFileIsRuntime(int num)

Returns a value indicating if the specified file parameter stores a reference to a runtime file.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

1 if the specified file parameter stores a reference to a runtime file; otherwise, 0.

int getParameterFileIsAbsPath(int num)

Returns a value indicating if the specified file parameter stores an absolute file path.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

1 if the specified file parameter stores an absolute file path; otherwise, 0.

int isParameterFileExist(int num)

Returns a value indicating if a file corresponding to the specified file parameter of the property exists.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

1 if a file corresponding to the specified property parameter exists; otherwise, 0.

void setParameterMaterial(int num, Material value)

Updates the value of the given material parameter. If the PARAMETER_MATERIAL variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
Material value - Material to be set as a value of the specified parameter.

Material getParameterMaterial(int num)

Returns the current value of the given material parameter. If the PARAMETER_MATERIAL variable isn't set for the parameter, the function will return NULL.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Material currently set as a value of the specified parameter.

void setParameterProperty(int num, Property value)

Updates the value of the given property parameter. If the PARAMETER_PROPERTY variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
Property value - Property to be set as a value of the specified parameter.

Property getParameterProperty(int num)

Returns the current value of the given property parameter. If the PARAMETER_PROPERTY variable isn't set for the parameter, the function will return NULL.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Property currently set as a value of the specified parameter.

void setParameterColor(int num, vec4 value)

Updates a value of the given color parameter. If the PARAMETER_COLOR variable isn't set for the parameter, the color value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
vec4 value - New value for the color parameter.

vec4 getParameterColor(int num)

Returns the current color set for the given color parameter. If the PARAMETER_COLOR variable isn't set for the parameter, the function will return (0,0,0,0).

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Color value of the color parameter. If an error occurs, (0,0,0,0) will be returned.

void setParameterDouble(int num, double value)

Updates the value of the given double parameter. If the PARAMETER_DOUBLE variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
double value - New value for the double parameter.

double getParameterDouble(int num)

Returns the current value of the given double parameter. If the PARAMETER_DOUBLE variable isn't set for the parameter, the function will return 0.0f.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the douuble parameter.

double getParameterDoubleMaxValue(int num)

Returns the maximum allowed value of the given double parameter. If the PARAMETER_DOUBLE variable isn't set for the parameter, the function will return 1.0f.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Maximum allowed value of the double parameter.

double getParameterDoubleMinValue(int num)

Returns the minimum allowed value of the given double parameter. If the PARAMETER_DOUBLE variable isn't set for the parameter, the function will return 0.0f.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Minimum allowed value for the double parameter.

void setParameterFloat(int num, float value)

Updates the value of the given float parameter. If the PARAMETER_FLOAT variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
float value - New value of the float parameter.

float getParameterFloat(int num)

Returns the current value of the given float parameter. If the PARAMETER_FLOAT variable isn't set for the parameter, the function will return 0.0f.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the float parameter.

float getParameterFloatMaxValue(int num)

Returns the maximum allowed value of the given float parameter. If the PARAMETER_FLOAT variable isn't set for the parameter, the function will return 1.0f.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Maximum allowed value of the float parameter.

float getParameterFloatMinValue(int num)

Returns the minimum allowed value of the given float parameter. If the PARAMETER_FLOAT variable isn't set for the parameter, the function will return 0.0f.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Minimum allowed value of the float parameter.

void setParameterGUID(int num, UGUID value)

Updates the value of the given file, material, or property parameter using the specified GUID. If the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
UGUID value - New GUID value for the specified parameter.

UGUID getParameterGUID(int num)

Returns the current value of the given file, material, or property parameter as a GUID (i.e. a GUID of a material, a property or a file will be returned).

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the specified parameter as a GUID.

void setParameterNode(int num, Node value)

Updates the value of the given Node parameter. If the PARAMETER_NODE variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
Node value - Node to be set as a value of the specified parameter.

Node getParameterNode(int num)

Returns the current value of the given Node parameter. If the PARAMETER_NODE variable isn't set for the parameter, the function will return NULL.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Node currently set as a value of the specified parameter.

void setParameterNodeID(int num, int value)

Updates the value of the given Node parameter by the specified node ID. If the PARAMETER_NODE variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
int value - ID of a node to be set as a value of the specified parameter.

int getParameterNodeID(int num)

Returns the current value of the given Node parameter. If the PROPERTY_PARAMETER_NODE variable isn't set for the parameter, the function will return 0.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

ID of a node currently set as a value of the specified parameter.

void setParameterInt(int num, int value)

Updates the value of the given integer parameter. If the PARAMETER_INT variable isn't set for the parameter, or the property is not editable, the value won't be updated.

For example, the values of collision and intersection parameters for the property inherited from the surface_base can be set as follows:

Source code (C#)

property.setParameterInt(property.findParameter("collision"), 1);
property.setParameterInt(property.findParameter("intersection"), 1);

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
int value - New value for the integer parameter.

int getParameterInt(int num)

Returns the current value of the given integer parameter. If the PARAMETER_INT variable isn't set for the parameter, the function will return 0.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the integer parameter.

int getParameterIntMaxValue(int num)

Returns the maximum allowed value of the given integer parameter. If the PARAMETER_INT variable isn't set for the parameter, the function will return 1.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Maximum allowed value of the integer parameter.

int getParameterIntMinValue(int num)

Returns the minimum allowed value of the given integer parameter. If the PARAMETER_INT variable isn't set for the parameter, the function will return 0.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Minimum allowed value of the integer parameter.

void setParameterMask(int num, int value)

Updates a value of the given mask parameter. If the PARAMETER_MASK variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
int value - New value for the mask parameter.

int getParameterMask(int num)

Returns the current value set for the given mask parameter. If the PARAMETER_MASK variable isn't set for the parameter, the function will return 0.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the mask parameter. If an error occurs, 0 will be returned.

string getParameterName(int num)

Returns the name of the given property's parameter name.

Arguments

int num - The number of the target parameter in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account).

Return value

Name of the parameter.

int getParameterSliderLog10(int num)

Returns a value indicating if the given slider parameter of the current property uses a logarithmic scale (with the base ten). The slider parameter is a parameter of one of the following types: PARAMETER_INT, PARAMETER_FLOAT, PARAMETER_DOUBLE.

Arguments

int num - The number of the slider parameter in range from 0 to the total number of the property's parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account).

Return value

1 if the parameter uses a logarithmic scale; otherwise, 0.

int getParameterSliderMaxExpand(int num)

Returns a value indicating if the maximum value of the given slider parameter can be increased. The slider parameter is a parameter of one of the following types: PARAMETER_INT, PARAMETER_FLOAT, PARAMETER_DOUBLE.

Arguments

int num - The number of the slider parameter in range from 0 to the total number of the property's parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account).

Return value

1 if the maximum value can be changed; otherwise, 0.

int getParameterSliderMinExpand(int num)

Returns a value indicating if the minimum value of the given slider parameter can be decreased. The slider parameter is a parameter of one of the following types: PARAMETER_INT, PARAMETER_FLOAT, PARAMETER_DOUBLE.

Arguments

int num - The number of the slider parameter in range from 0 to the total number of the property's parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account).

Return value

1 if the minimum value can be changed; otherwise, 0.

int hasParameterSliderMaxValue(int num)

Returns a value indicating if a slider parameter with a given number has the maximum value specified.

Arguments

int num - The number of the slider parameter in range from 0 to the total number of the property's parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account).

Return value

1 if a slider parameter with a given number has the maximum value specified; otherwise, 0.

int hasParameterSliderMinValue(int num)

Returns a value indicating if a slider parameter with a given number has the minimum value specified.

Arguments

int num - The number of the slider parameter in range from 0 to the total number of the property's parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account).

Return value

1 if a slider parameter with a given number has the minimum value specified; otherwise, 0.

void setParameterString(int num, string value)

Updates the value of the given string parameter. If the PARAMETER_STRING variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
string value - New value for the string parameter.

string getParameterString(int num)

Returns the current value of the given string parameter. If the PARAMETER_STRING variable isn't set for the parameter, the function will return NULL.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the string parameter.

void setParameterSwitch(int num, int value)

Updates the value of the given switch parameter. If the PARAMETER_SWITCH variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
int value - New value for the switch parameter.

int getParameterSwitch(int num)

Returns the current value of the given switch parameter. If the PARAMETER_SWITCH variable isn't set for the parameter, the function will return 0.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the switch parameter.

string getParameterSwitchItem(int num, int item)

Returns the value of the item of the given switch parameter. If the PARAMETER_SWITCH variable isn't set for the parameter, the function will return NULL.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
int item - The number of the item of the switch parameter.

Return value

Value of the item. If an error occurs, NULL will be returned.

int getParameterSwitchNumItems(int num)

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Number of the items of the switch parameter.

void setParameterToggle(int num, int value)

Updates the value of the given toggle parameter. If the PARAMETER_TOGGLE variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
int value - New value of the toggle parameter.

int getParameterToggle(int num)

Returns the current value of the given toggle parameter. If the PARAMETER_TOGGLE variable isn't set for the parameter, the function will return 0.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the toggle parameter.

int getParameterType(int num)

Returns the type of the given parameter.

Arguments

int num - The number of the target parameter in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account).

Return value

One of the PARAMETER_* pre-defined variables; if an error occurs, -1 will be returned.

void setParameterVec3(int num, vec3 value)

Updates the value of the given vector (vec3) parameter. If the PARAMETER_VEC3 variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
vec3 value - New value for the vector (vec3) parameter.

vec3 getParameterVec3(int num)

Returns the current value of the given vector (vec3) parameter. If the PARAMETER_VEC3 variable isn't set for the parameter, the function will return (0,0,0).

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the vector (vec3) parameter.

void setParameterVec4(int num, vec4 value)

Updates the value of the given vector (vec4) parameter. If the PARAMETER_VEC4 variable isn't set for the parameter, or the property is not editable, the value won't be updated.

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.
vec4 value - New value for the vector (vec4) parameter.

vec4 getParameterVec4(int num)

Returns the current value of the given vector (vec4) parameter. If the PARAMETER_VEC4 variable isn't set for the parameter, the function will return (0,0,0,0).

Arguments

int num - Parameter number in range from 0 to the total number of the property parameters (including parameters of its parent; if a parameter of the current property overrides the parent property's parameter, the parent property's parameter isn't taken into account). New parameters are added to the end of the parameters list.

Return value

Value of the vector (vec4) parameter.

void resetParameter(int num)

Resets the overriden value of the given parameter to the parent's value.

Arguments

int num - Parameter number.

Property getParent()

Returns the parent property.

Return value

Parent property smart pointer.

int isParent(string name)

Returns a value indicating if the property with the given name is a parent of this property.

Suppose we have the following two manual properties in our project:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.0.1" name="my_prop" parent_name="surface_base" manual="1">
	<parameter name="my_parameter">100</parameter>
</property>

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<property version="2.7.0.1" name="my_prop_0" parent_name="my_prop" manual="1">
	<parameter name="my_parameter1">101</parameter>
	<parameter name="my_parameter2">101</parameter>
</property>

The following code will return 1 as the my_prop property is the parent of the my_prop_0 property:

Source code (C#)

// get a property named my_prop_0
Property property = Properties.get().findManualProperty("my_prop_0");
// perform parent check
Log.message("{0}\n",property.isParent("my_prop"));

Arguments

string name - Parent property name.

Return value

1 if the property with the given name is a parent of this property; otherwise, 0.

int isParent(UGUID guid)

Returns a value indicating if the property with the given GUID is a parent of this property.

Arguments

UGUID guid - Parent property GUID.

Return value

1 if the property with the given GUID is a parent of this property; otherwise, 0.

int setParent(Property property, int save_all_values = 0)

Sets the given property as the parent for this property and saves the parameter values of the property (if the corresponding flag is set).

Notice

The method is not available for manual and non-editable properties.

Arguments

Property property - Property to be set as the parent for this property.
int save_all_values - Flag indicating if parameter values of the property will be saved after reparenting.

Return value

1 if the given property was successfully set as the parent for this property; otherwise, 0.

void setPath(string path)

Sets a new path for the property.

Arguments

string path - New path to the property file.

void setFileGUID(UGUID fileguid)

Sets a new GUID for the property file.

Arguments

UGUID fileguid - New GUID for the property file.

UGUID getFileGUID()

Returns the current GUID of the property file.

Return value

GUID of the property file.

string getPath()

Returns a path to the property.

Return value

Path to the property.

Property clone()

Clones the property. The cloned property won't have a name, a path and won't be displayed in the properties hierarchy.

Return value

Cloned property.

Property clone(string name, string path)

Clones the property and assigns the specified name and path to the clone. The cloned property will be saved to the specified path on saveProperties() call. This method may be used, for example, to create a property missed during project's migration.

Arguments

string name - Cloned property name.
string path - Path to save the cloned property.

Return value

Cloned property.

Property clone(string name, string path, UGUID guid)

Clones the property and assigns the specified name, GUID and path to the clone. The cloned property will be saved to the specified path on saveProperties() call. This method may be used, for example, to create a property missed during project's migration.

Arguments

string name - Cloned property name.
string path - Path to save the cloned property.
UGUID guid - Cloned property GUID.

Return value

Cloned property.

Property clone(string name)

Clones the property.

Source code (UnigineScript)

// get a property to be clones
Properties properties = Properties.get();
Property property = properties.findProperty("surface_base_0");
// clone the property
Property cloned = property.clone("cloned_surface_base_0");
// perform something on the cloned pointer
// ...
// delete the pointer
cloned.grab();
cloned.destroyPtr();

Arguments

string name - Cloned property name.

Return value

Cloned property.

void grab()

Sets the owner flag to 1 for the Property pointer. The Property should not be handled by the class after this function is called

int isOwner()

Returns the owner flag. If the pointer is the owner, on its deletion the property also will be deleted. Use grab() and release() functions to change ownership.

Return value

The owner flag.

void release()

Releases the Property (sets the owner flag to 0 for the pointer). The Property should be handled by the class after this function is called.

Property inherit()

Inherits a new property from this one. The inherited property will be empty: it won't have a name, a path and won't be displayed in the properties hierarchy.

Return value

Inherited property.

Property inherit(string name)

Inherits a new property from this one and assigns the specified name to it.

Arguments

string name - Inherited property name.

Return value

Inherited property smart pointer.

Property inherit(string name, string path)

Inherits a new property from this one and assigns the specified name and path to it. The inherited property will be saved to the specified path on saveProperties() call.

Arguments

string name - Inherited property name.
string path - Path to save the inherited property.

Return value

Inherited property.

Property inherit(string name, string path, UGUID guid)

Inherits a new property from this one and assigns the specified name, GUID and path to it. The inherited property will be saved to the specified path on saveProperties() call.

Arguments

string name - Inherited property name.
string path - Path to save the inherited property.
UGUID guid - Inherited property GUID.

Return value

Inherited property.

int load()

Loads the property from the file specified by the setPath() function.

NoticeThis function can be used to load properties created during application execution or stored outside the data directory.

Return value

1 if the property data is loaded successfully; otherwise, 0.

int load(string path)

Loads the property from the specified *.prop file.

Arguments

string path - Path to the *.prop file to load the property data from.

Return value

1 if the property data is loaded successfully; otherwise, 0.

int loadXml(Xml xml)

Loads data of the property (all its parameters) from the given instance of the Xml class.

Arguments

Xml xml - Xml class instance in which the property data is stored.

Return value

1 if the property data is loaded successfully; otherwise, 0.

int loadWorld(Xml xml)

Loads data of the current property (all its options, states and parameters) from the given instance of the Xml class.

Arguments

Xml xml - Xml class instance in which the property data is stored.

Return value

1 if the property data is loaded successfully; otherwise, 0.

int reload()

Reloads the property and all its children.

Return value

1 if the property is reloaded successfully; otherwise, 0.

int restoreState(Stream stream, int force = 0)

Restores data of the current property (all its parameters) from a binary stream.

Arguments

Stream stream - The stream in which the saved property data is stored.
int force - A value indicating if forced restoring of property data is used: 1 to enable forced saving, 0 to disable it.

Return value

1 if the property data is restored successfully; otherwise, 0.

int canSaveInFile()

Returns a value indicating if the property can be saved to a file. For example, this function will return 0 for an internal or manual property.

Return value

1 if the property can be saved to a file; otherwise, 0.

int saveState(Stream stream)

Saves data of the current property (all its parameters) into a binary stream.

Arguments

Stream stream - Stream into which the property data will be saved.

Return value

1 if the property data is saved successfully; otherwise, 0.

int save()

Saves the property data to the file specified by the setPath() function.

Notice

This method is not available for manual and internal properties.

Return value

1 if the property data is saved successfully; otherwise, 0.

int save(string path)

Saves the property data to the specified *.prop file.

Notice

This method is not available for manual properties.

Arguments

string path - Path to the *.prop file to save the property data to.

Return value

1 if the property data is saved successfully; otherwise, 0.

int saveXml(Xml xml)

Saves data of the property (all its parameters) to the given instance of the Xml class.

Notice

This method is not available for manual properties.

Arguments

Xml xml - Xml class instance into which the property data will be saved.

Return value

1 if the property data is saved successfully; otherwise, 0.

int saveWorld(Xml xml, int force = 0)

Saves data of the current property (all its parameters) into the given instance of the Xml class.

Arguments

Xml xml - Xml class instance into which the property data will be saved.
int force - A value indicating if forced saving of property data is used: 1 to enable forced saving, 0 to disable it.

Return value

1 if the property data is saved successfully; otherwise, 0.

void removeCallback(int callback, Unigine::CallbackBase * func)

Removes a callback with the given number from the list of callbacks of the specified type. Callback functions can be used to determine actions to be performed when any changes to the property are made.

Arguments

int callback
Unigine::CallbackBase * func - Callback pointer.

void clearCallbacks(int callback)

Clears all added callbacks of the specified type. Callback functions can be used to determine actions to be performed when any changes to the property are made.

Arguments

int callback

int parameterTypeByName(string param_type)

Returns parameter type identifier by the type name specified.

Arguments

string param_type - Parameter type name.

Return value

Parameter type identifier, one of the PARAMETER_* variables.

string parameterNameByType(int param_type)

Returns parameter type name by the type identifier specified.

Arguments

int param_type - Parameter type identifier, one of the PARAMETER_* variables.

Return value

Parameter type name.

int PARAMETER_COLOR

Description

Type of the property parameter that allows specifying the material color (a vec4 value).

int PARAMETER_DOUBLE

Description

Type of the property parameter that allows accepting any double value in a given range.

int PARAMETER_FLOAT

Description

Type of the property parameter that allows accepting float value in a given range.

int

Description

Type of the property parameter that allows accepting any file GUID value.

int PARAMETER_INT

Description

Type of the property parameter that allows accepting any integer value in a given range.

int PARAMETER_MASK

Description

Type of the property parameter that allows specifying a mask (an integer value).

int

Description

Type of the property parameter that allows accepting any material GUID value.

int PARAMETER_NODE

Description

Type of the property parameter that allows accepting any Node.

int

Description

Type of the property parameter that allows accepting any property GUID value.

int PARAMETER_STRING

Description

Type of the property parameter that allows accepting any string value.

int PARAMETER_SWITCH

Description

Type of the property parameter that allows specifying a set of several possible values (more than 2).

int PARAMETER_TOGGLE

Description

Type of the property parameter that allows only 2 possible values.

int PARAMETER_VEC3

Description

Type of the property parameter that allows accepting any vec3 value.

int PARAMETER_VEC4

Description

Type of the property parameter that allows accepting any vec4 value.

int

Description

Property destroy callback. This callback is fired when the property is destroyed.

int

Description

Property parameter changed callback. This callback is fired when the value of any parameter of the property is changed or reset to default.

int

Description

Property reparented callback. This callback is fired when the parent of the property is changed.

int

Description

Property renamed callback. This callback is fired when the name of the property is changed.

int

Description

Property moved callback. This callback is fired when the path of the property is changed.

int

Description

Property reloaded callback. This callback is fired when the property is reloaded.

Last update: 2018-08-10

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)