This page has been translated automatically.
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
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
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Property Class

Warning
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScipt (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.

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.

Property parameters are managed individually via the PropertyParameter class, to get any parameter by its name or ID you should use the getParameterPtr() method.

Source code (C++)
PropertyParameterPtr pPropertyParameter = pProperty->getParameterPtr(); // get "root" parameter
pTargetNode = pPropertyParameter->getChild(k)->getValueNode(); // get child with index "k", then its value
// ...
positionFactor = pPropertyParameter->getChild(k)->getValueFloat();
// etc.

If you know names, you can use:
pTargetNode = pProperty->getParameterPtr("target")->getValueNode();
positionFactor = pProperty->getParameterPtr("position_factor")->getValueFloat();

Automatic type conversion of property parameters make them act like some universal variables i.e. you can set a new value for an integer parameter int_param and type it like this:

Source code (C++)
PropertyParameterPtr int_param;

/* ... */

// setting a new value of integer parameter using a string
int_param->setValue(“15”);

// setting a new value of integer parameter using a float
int_param->setValue(5.0f);

// getting integer parameter’s value as a string
Log::message(“Integer parameter value: %s”, int_param->getValueString().get());
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#

Notice
The 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.3" 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>
    Notice
    If the new property is assigned to a surface, it must be inherited from the surface_base property or one of its children. Otherwise, the surface can behave incorrectly.
  • By inheriting from the existing property via the engine.properties.inheritProperty() function or inherit() function of the Property class. For example:
    Source code (UnigineScript)
    // inherit a GameObjectsUnit_0 property from the GameObjectsUnit property
    Property inherited_prop = engine.properties.findManualProperty("GameObjectsUnit").inherit("GameObjectsUnit_0", "game_object_unit_0.prop");
    
    // inherit a GameObjectsUnit_1 property from the GameObjectsUnit_0 property via the Manager
    engine.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 engine.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 engine.properties.removeProperty() function:

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

Usage Example#

To illustrate how properties and their parameters are managed let's make a simple viewer for all properties in the project as well as for their parameters. Our viewer will have the following features:

  • View the list of all properties used in the project.
  • View the list of parameters of the currently selected property. Inherited, overridden and unique parameters are displayed in different colors.
  • Change the value of the selected property parameter.
  • Reset the value of the selected property parameter.
  • Inherit a new property from the selected one.
  • Clone the selected property.
  • Save the currently selected property to a file.
  • Reload all properties.

We can add the the following *.prop files to the data folder of our project to check our viewer:

  • my_property.prop

    my_property.prop

    Source code (XML)
    <?xml version="1.0" encoding="utf-8"?>
    <property version="2.7.3.0" name="my_property" parent="node_base" manual="1">
    	
    	<parameter name="damage" type="int" max="1000">1</parameter>
    	<parameter name="mass" type="float" tooltip="Aircraft mass">1345</parameter>
    	<parameter name="attack" type="toggle">1</parameter>
    	<parameter name="weapon_type" type="switch" items="air,land,all_types">0</parameter>
    	<parameter name="Mask" type="mask"/>
    	<parameter name="Base Material" type="material"/>
    	<parameter name="Model Node" type="node"/>
    
    	<struct name="member">
    		<parameter name="name" type="string"></parameter>
    		<parameter name="rank" type="switch" items="2LT,1LT,CPT,MAJ,LTC,COL,BG,MG">0</parameter>
    		<parameter name="year" type="int"></parameter>
    		<parameter name="status" type="toggle">1</parameter>
    	</struct>
    	<parameter name="Members" type="array" array_type="member" group="Crew Information">
    			<value>
    				<parameter name="name">Mike Watts</parameter>
    				<parameter name="rank" type="switch" items="2LT,1LT,CPT,MAJ,LTC,COL,BG,MG">3</parameter>
    				<parameter name="year">1990</parameter>
    			</value>
    			<value>
    				<parameter name="name">John Doe</parameter>
    				<parameter name="rank" type="switch" items="2LT,1LT,CPT,MAJ,LTC,COL,BG,MG">2</parameter>
    				<parameter name="year">1995</parameter>
    			</value>
    			<value>
    				<parameter name="name">Vincent Preston</parameter>
    				<parameter name="rank" type="switch" items="2LT,1LT,CPT,MAJ,LTC,COL,BG,MG">1</parameter>
    				<parameter name="year">1997</parameter>
    			</value>
    		</parameter>
    	<parameter name="Service Flags" type="array" array_type="toggle" group="Auxiliary">
    		<value>1</value>
    		<value>0</value>
    		<value>1</value>
    		<value>0</value>
    	</parameter>
    </property>
  • custom_prop.prop

    custom_prop.prop

    Source code (XML)
    <?xml version="1.0" encoding="utf-8"?>
    <property version="2.7.3.0" name="custom_prop" manual="1">
    	 <!-- First structure declaration -->
    	 <struct name="struct1">
    			 <parameter name="param_a" type="int">1</parameter>
    			 <parameter name="param_b" type="toggle">0</parameter>
    			 <parameter name="param_c" type="int">1</parameter>
    	 </struct>
    	 <!-- Inherited structure declaration-->
    	 <struct name="struct2" parent_name="struct1">
    			 <parameter name="param2_a" type="toggle">0</parameter>
    			 <parameter name="param2_b" type="float">1.0</parameter>
    	 </struct>
    	 <!-- Struct parameter of struct2 type -->
    	 <parameter name="my_struct_param" type="struct2"></parameter>
    	 <!-- Nested structure declaration -->
    	 <struct name="struct3">
    			 <parameter name="param3_a" type="struct2">0</parameter>
    			 <parameter name="param3_b" type="int">15</parameter>
    	 </struct>
    
    	 <!-- Declaration of a one-dimensional array of struct3 elements-->
    	 <parameter name="my_struct_array" array_type="struct3"></parameter>
    </property>
  • custom_prop_0.prop inherited from the custom_prop property.

    custom_prop_0.prop

    Source code (XML)
    <?xml version="1.0" encoding="utf-8"?>
    <property version="2.7.3.0" name="custom_prop_0" manual="1" parent="custom_prop">
    	 <!-- Declaration of a 2-dimensional array (matrix) of integer elements-->
    	 <parameter name="my_int_array" array_type="int" array_dim="2"></parameter>
    </property>

Below is the source code in UnigineScript implementing our Property Viewer. You can copy and paste it to the corresponding files of your project.

my_world.usc

Source code (UnigineScript)
#include <core/unigine.h>
// This file is in UnigineScript language.
// World script, it takes effect only when the world is loaded.

	// declaring UI widgets to be used
    WidgetWindow window;
    WidgetHBox hbox;

    WidgetGroupBox properties_gb;
    WidgetTreeBox properties;
    WidgetGroupBox parameters_gb;
    WidgetTreeBox parameters;
    WidgetGroupBox value_gb;
    WidgetGroupBox menu_gb;

    WidgetVBox vbox2, vbox3;
    WidgetHBox hbox2;
    WidgetButton reload;
    WidgetButton clone;
    WidgetButton inherit;
    WidgetButton save_prop;

    // UI widgets for values
    WidgetLabel label[0];
    WidgetEditLine value;
    WidgetButton change;
    WidgetButton reset;

    WidgetLabel info;
    WidgetLabel prop_info;
	// lists of properties and parameters
    int item_prop[];
    int item_param[];

/// method refreshing properties
void refresh_properties()
{
	properties.setCallbackEnabled(GUI_CHANGED, 0);
	properties.clear();
	item_prop.clear();
	
	// recursive function iterating through all children properties and building property hierarchy
	void attach_children(int parent, Property prop_parent) 
	{
		for (int k = 0; k < prop_parent.getNumChildren(); k++)
		{
			Property prop = prop_parent.getChild(k);
			
			if ((prop.getParent() != NULL) && (prop != prop_parent) && (prop.getParent() == prop_parent))
			{
				int child = properties.addItem(prop.getName());
				properties.addItemChild(parent, child);
				item_prop.append(child, prop);
				attach_children(child, prop);
			}
		}
	}
	// building property hierarchy
	for (int i = 0; i < engine.properties.getNumProperties(); i++)
	{
		Property prop_base = engine.properties.getProperty(i);
		if (prop_base.isBase() == 1)
		{
			int parent = properties.addItem(prop_base.getName());
			item_prop.append(parent, prop_base);
			attach_children(parent, prop_base);
		}
	}
	properties.setCallbackEnabled(GUI_CHANGED, 1);
}

/// method refreshing property parameters
void properties_changed()
{
	parameters.setCallbackEnabled(GUI_CHANGED, 0);
	// clearing the list of property parameters and updating values displayed
	parameters.clear();
	value_gb.setEnabled(0);
	for (int i = 0; i <= 12; i++)
		label[i].setText("");

	item_param.clear();
	
	int item = properties.getCurrentItem();
	if (item == -1)
	{
		parameters.setCallbackEnabled(GUI_CHANGED, 1);
		return;
	}
	// getting a property from the list in accordance with current selection
	Property prop = item_prop[item];
	
	// getting a root parameter of the selected property
	PropertyParameter pp = prop.getParameterPtr();
            
	// recursive function iterating through all parameters of a property
	void add_parameters(int parent, PropertyParameter p)
	{
		for (int i = 0; i < p.getNumChildren(); i++)
		{
			PropertyParameter child = p.getChild(i);
			int child_index = parameters.addItem(child.getName());
			parameters.setItemColor(child_index,
				Vec4(
				(child.isInherited()),
				1,
				(1 - child.isOverridden()),
				(child.isHidden() == 1) ? 0.5f : 1.0f));
		item_param.append(child_index, child);

			if (parent != -1)
				parameters.addItemChild(parent, child_index);

			add_parameters(child_index, child);
		}
	}
	
	// building the hierarchy of parameters for the selected property
	add_parameters(-1, pp);
	
	// preparing property information
	string pi = format("\nName: %s\nPath: %s\nInternal: %d\nStructs: %d\n", prop.getName(), prop.getPath(), prop.isInternal(), prop.getNumStructs());
	// adding all structures defined in the property (if any)
	for (int i = 0; i < prop.getNumStructs(); i++)
		pi += format("%d) %s\n", i, prop.getStructName(i));
	// displaying property information
	prop_info.setText(pi);

	parameters.setCallbackEnabled(GUI_CHANGED, 1);
	parameters.setCurrentItem(-1);
}

/// method refreshing information about the currently selected property parameter
void parameters_changed()
{
    // checking if any property parameter is selected
	int item = parameters.getCurrentItem();
	if (item == -1)		
		return;
	
	value_gb.setEnabled(1);
	// getting the parameter from the list in accordance with current selection
	PropertyParameter p = item_param[item];
	int i = 0;
	label[i++].setText(format("<font color=ffff00>ID:</font> %d", p.getID()));
	label[i++].setText(format("<font color=ffff00>Name:</font> %s", p.getName()));
	label[i++].setText(format("<font color=ffff00>Title:</font> %s", p.getTitle()));
	label[i++].setText(format("<font color=ffff00>Tooltip:</font> %s", p.getTooltip()));
	label[i++].setText(format("<font color=ffff00>Group:</font> %s", p.getGroup()));
	label[i++].setText(format("<font color=ffff00>Filter:</font> %s", p.getFilter()));
	
	string s;
	// displaying parameter's type
	if (p.getType() == PROPERTY_PARAMETER_ARRAY)
		s = format("<font color=ffff00>Type:</font> array [<font color=ffff00>Size:</font> %d, <font color=ffff00>Type:</font> %s]", p.getArraySize(), p.getArrayTypeName());
	else if (p.getType() == PROPERTY_PARAMETER_STRUCT)
		s = format("<font color=ffff00>Type:</font> struct [<font color=ffff00>Struct Name:</font> %s]", p.getStructName());
	else
		s = format("<font color=ffff00>Type:</font> %s", p.getProperty().parameterNameByType(p.getType()));
	label[i++].setText(s);
	label[i++].setText(format("<font color=ffff00>Hidden:</font> %d", p.isHidden()));
	label[i++].setText(format("<font color=ffff00>Inherited:</font> %d", p.isInherited()));
	label[i++].setText(format("<font color=ffff00>Overridden:</font> %d", p.isOverridden()));
	label[i++].setText(format("<font color=ffff00>Has Min:</font> %d", p.hasSliderMinValue()));
	label[i++].setText(format("<font color=ffff00>Has Max:</font> %d", p.hasSliderMaxValue()));
	s = "";
	if (p.getType() == PROPERTY_PARAMETER_INT)
		s = format("<font color=ffff00>Min:</font> %d <font color=ffff00>Max:</font> %d", p.getIntMinValue(), p.getIntMaxValue());
	else if (p.getType() == PROPERTY_PARAMETER_FLOAT)
		s = format("<font color=ffff00>Min:</font> %d <font color=ffff00>Max:</font> %d", p.getFloatMinValue(), p.getFloatMaxValue());
	else if (p.getType() == PROPERTY_PARAMETER_DOUBLE)
		s = format("<font color=ffff00>Min:</font> %d <font color=ffff00>Max:</font> %d", p.getDoubleMinValue(), p.getDoubleMaxValue());
	else if (p.getType() == PROPERTY_PARAMETER_SWITCH)
		s = format("<font color=ffff00>Switch Num Items:</font> %d", p.getSwitchNumItems());
	label[i++].setText(s);
	value.setText(p.getValueString());
	reset.setEnabled(p.isOverridden());
}

/// change button on_click event handler
void change_clicked()
{
    // checking if any property parameter is currently selected
    int item = parameters.getCurrentItem();
    if (item == -1)
        return;
    // setting the value of the currently selected property parameter and refreshing information
    PropertyParameter pp = item_param[item];
    pp.setValue(value.getText());

    refresh_info();
}

/// reset button on_click event handler
void reset_clicked()
{
    // checking if any property parameter is currently selected
    int item = parameters.getCurrentItem();
    if (item == -1)
        return;
	
    // resetting the value of the currently selected property parameter and refreshing information
    PropertyParameter pp = item_param[item];
    pp.resetValue();

    refresh_info();
}

/// reload button on_click event handler
void reload_clicked()
{
    // reload all properties and refreshing information
    engine.properties.reloadProperties();
    refresh_info();
}

/// method refreshing property and parameter information
void refresh_info()
{
	// getting current indices of property and parameter selection
	int item_pr = properties.getCurrentItem();
	int item_pa = parameters.getCurrentItem();
	refresh_properties();
	
	// setting current items and updating information displayed
	properties.setCurrentItem(clamp(item_pr, -1, properties.getNumItems() - 1));
	properties_changed();
	parameters.setCurrentItem(clamp(item_pa, -1, parameters.getNumItems() - 1));
	parameters_changed();
}

/// clone button on_click event handler
void clone_clicked()
{
    // checking if any property is selected in the hierarchy
    int item = properties.getCurrentItem();
    if (item == -1)
        return;
    // cloning the selected property
    Property p = item_prop[item];
    Property p_clone = p.clone();
    p_clone.setName(format("%s_cloned", p.getName()));
	
    // refreshing information displayed
    refresh_info();
}

/// inherit button on_click event handler
void inherit_clicked()
{
    // checking if any property is selected in the hierarchy
    int item = properties.getCurrentItem();
    if (item == -1)
        return;
    // inheriting a new property from the selected one
    Property p = item_prop[item];
    p.inherit().setName(format("%s_inherited", p.getName()));
	
	// refreshing information displayed
    refresh_info();
}

/// method saving the currently selected property to the "my_test_prop.prop" file
void save_prop_clicked()
{	
    // checking if any property is selected in the hierarchy
    int item = properties.getCurrentItem();
    if (item == -1)
        return;
    // saving a property to the specified file
    Property p = item_prop[item];
    p.save("my_test_prop.prop");
}

int init() {
	// Write here code to be called on world initialization: initialize resources for your world scene during the world start.
	
	Player player = new PlayerSpectator();
	player.setPosition(Vec3(0.0f,3.401f,1.5f));
	player.setDirection(Vec3(0.0f,-1.0f,-0.4f));
	engine.game.setPlayer(player);
	Property property = engine.properties.findManualProperty("my_property");

	engine.app.setUpdate(1);

	// creating user interface
	Gui gui = engine.getGui();

	window = new WidgetWindow(gui, "Properties Viewer");
	window.setSizeable(1);
	window.setWidth(engine.app.getWidth());
	window.setHeight(engine.app.getHeight());
	gui.addChild(window, GUI_ALIGN_OVERLAP);

	vbox2 = new WidgetVBox(gui);
	window.addChild(vbox2, GUI_ALIGN_EXPAND);

	hbox = new WidgetHBox(gui);
	vbox2.addChild(hbox, GUI_ALIGN_EXPAND);

	properties_gb = new WidgetGroupBox(gui, "Properties");
	parameters_gb = new WidgetGroupBox(gui, "Parameters");
	hbox.addChild(properties_gb, GUI_ALIGN_EXPAND);
	hbox.addChild(parameters_gb, GUI_ALIGN_EXPAND);

	properties = new WidgetTreeBox(gui);
	parameters = new WidgetTreeBox(gui);
	properties_gb.addChild(properties, GUI_ALIGN_EXPAND);
	parameters_gb.addChild(parameters, GUI_ALIGN_EXPAND);

	vbox3 = new WidgetVBox(gui);
	hbox.addChild(vbox3, GUI_ALIGN_EXPAND);
	value_gb = new WidgetGroupBox(gui, "Value");
	value_gb.setWidth(300);
	value_gb.setHeight(300);
	value_gb.arrange();
	menu_gb = new WidgetGroupBox(gui, "Menu");
	vbox3.addChild(value_gb, GUI_ALIGN_LEFT);
	vbox3.addChild(menu_gb, GUI_ALIGN_EXPAND);

	label.append(new WidgetLabel(gui, ""));
	label[label.size()-1].setFontRich(1);
	value_gb.addChild(label[label.size()-1], GUI_ALIGN_LEFT);
	value = new WidgetEditLine(gui);
	value_gb.addChild(value, GUI_ALIGN_EXPAND);
	for (int i = 0; i <= 12; i++)
	{
		label.append(new WidgetLabel(gui, ""));
		label[label.size()-1].setFontRich(1);
		value_gb.addChild(label[label.size()-1], GUI_ALIGN_LEFT);
	}
	change = new WidgetButton(gui, "Change Value");
	value_gb.addChild(change, GUI_ALIGN_LEFT);
	reset = new WidgetButton(gui, "Reset Value");
	value_gb.addChild(reset, GUI_ALIGN_LEFT);

	reload = new WidgetButton(gui, "Reload Property Files");
	clone = new WidgetButton(gui, "Clone Property");
	inherit = new WidgetButton(gui, "Inherit Property");
	save_prop = new WidgetButton(gui, "Save Property");

	menu_gb.addChild(reload, GUI_ALIGN_EXPAND);
	menu_gb.addChild(clone, GUI_ALIGN_EXPAND);
	menu_gb.addChild(inherit, GUI_ALIGN_EXPAND);
	menu_gb.addChild(save_prop, GUI_ALIGN_EXPAND);

	info = new WidgetLabel(gui);
	info.setFontRich(1);
	info.setText("<font color=00ffff>Unique value</font><br><font color=ffffff>Inherited value</font><br><font color=ffff00>Overridden value</font><br>");
	menu_gb.addChild(info, GUI_ALIGN_LEFT);
	prop_info = new WidgetLabel(gui);
	menu_gb.addChild(prop_info, GUI_ALIGN_LEFT);
	
	// setting callbacks for UI elements
	properties.setCallback(GUI_CHANGED, "properties_changed");
	parameters.setCallback(GUI_CHANGED, "parameters_changed");

	change.setCallback(GUI_CLICKED, "change_clicked");
	reset.setCallback(GUI_CLICKED, "reset_clicked");
	reload.setCallback(GUI_CLICKED, "reload_clicked");        
			
	clone.setCallback(GUI_CLICKED, "clone_clicked");
	inherit.setCallback(GUI_CLICKED, "inherit_clicked");
	save_prop.setCallback(GUI_CLICKED, "save_prop_clicked");

	refresh_properties();

	return 1;
}

// start of the main loop
int update() {
	// Write here code to be called before updating each render frame: specify all graphics-related functions you want to be called every frame while your application executes.
	
	return 1;
}

int postUpdate() {
	// The engine calls this function before rendering each render frame: correct behavior after the state of the node has been updated.
	
	return 1;
}

int updatePhysics() {
	// Write here code to be called before updating each physics frame: control physics in your application and put non-rendering calculations.
	// The engine calls updatePhysics() with the fixed rate (60 times per second by default) regardless of the FPS value.
	// WARNING: do not create, delete or change transformations of nodes here, because rendering is already in progress.
	
	return 1;
}
// end of the main loop

Property Class

Members


static 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 an internal one.

Return value

1 if the property is internal; otherwise, 0.

int isManual ( ) #

Returns a value indicating if the property is a manual one.

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.

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 hasOverrides ( ) #

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

Return value

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

Property getParent ( ) #

Returns the parent property.

Return value

Parent property if it exists; if the property has no parent, NULL will be returned.

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.3" 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.3" 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 (UnigineScript)
// get a property named my_prop_0
Property property = engine.properties.findManualProperty("my_prop_0");
// perform parent check
log.message("%d\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 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 cloned
Property property = engine.properties.findProperty("surface_base_0");
// clone the property
property.clone("cloned_surface_base_0");

Arguments

  • string name - Cloned property name.

Return value

Cloned property.

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.

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.
Notice
This 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 restore_mode = 0 ) #

Restores the data of the property (all its parameters) from a binary stream in the specified mode.

Arguments

Return value

1 if the property parameter 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.

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 PROPERTY_PARAMETER_* variables.

string parameterNameByType ( int param_type ) #

Returns parameter type name by the type identifier specified.

Arguments

Return value

Parameter type name.

PropertyParameter getParameterPtr ( ) #

Returns the root property parameter.

You can't iterate through all parameters of the property in a single loop, a recursive function should be used instead:

Source code (UnigineScript)
void recursive_func (PropertyParameter p)
{

	for (int i = 0; i < p.getNumChildren(); i++)
	{
		PropertyParameter child = p.getChild(i);
		
		// do something... e.g. print parameter names and values
		log.message("- %s: %s \n", child.getName(), child.getValueString());

		recursive_func(child);
	}
}

/* ... */

int init() {
	/* ... */
	
	// getting the root parameter of the property
	PropertyParameter root_parameter = property.getParameterPtr();

	// iterating through all parameters of the property
	recursive_func(root_parameter);	

	return 1;
}

Return value

Root property parameter instance

getParameterPtr ( int id ) #

Returns a property parameter by its ID.

Arguments

  • int id - Property parameter ID.

Return value

Property parameter instance.
Notice
This method never returns NULL, regardless of whether a parameter with the specified ID exists or not. It only displays an error message in the console in case of a non-existing parameter. To check if such parameter really exists, use the PropertyParameter.isExist() method. For example:
Source code (UnigineScript)
// getting some property named "my_property"
Property pProperty = engine.properties.findManualProperty("my_property");

// trying to get a property parameter having the ID=30
PropertyParameter param = pProperty.getParameterPtr(30);

// checking if such parameter exists and displaying a message
if (param.isExist() == 1)
	log.message("Property parameter with the specified ID exists!\n");
else
	log.message("No such parameter!\n");
	return 1;

int getNumStructs ( ) #

Returns the number of structures of the property.

Return value

Number of structures of the property.

int findStruct ( string name ) #

Returns the number of the structure with the specified name.

Arguments

  • string name - Name of the structure to be found.

Return value

Number of the structure with the specified name, if it exists; otherwise, -1.

string getStructName ( int num ) #

Returns the name of the structure with the specified number.

Arguments

  • int num - Structure number.

Return value

Structure name, if such structure exists, otherwise nullptr.

Node getNode ( ) #

Last update: 2020-07-31
Build: ()