engine.properties Functions

List of functions:

The functions below are used to control the loading and managing of property libraries: you can create new libraries, load the existing ones, associate them with the current world. Also the functions provide access to properties stored in the libraries: you can get, clone, move, inherit or remove any property of the library.

Notice

To modify a property, use functions of the Property class.

Each library is a separate XML file with a .prop extension. Such file can be created manually, via Unigine API or via the Propertieswindow of UnigineEditor.

Notice

The library created via the engine.properties.create() function should be associated with the current world by using The engine.properties.addWorldLibrary() function. In this case, it will be automatically loaded/saved on world loading/saving. Otherwise, you will have toload and save by using the corresponding functions.

If you load the library as follows, all changes made in it will be saved on the worlds' saving:

Source code (UnigineScript)

// load the library and associate it with the current world
engine.properties.addWorldLibrary("unigine_project/my_new_lib.prop");
// change the property library: inherit a property
engine.properties.inheritProperty("my_surface_base","unigine_project/my_new_lib.prop","my_surface_base_0");

If you load the library without associating if with the world, you will need to save changes in the library as follows:

Source code (UnigineScript)

// load the library
engine.properties.load("unigine_project/my_new_lib.prop");
// change the property library: inherit a property
engine.properties.inheritProperty("my_surface_base","unigine_project/my_new_lib.prop","my_surface_base_0");
// save changes in the library
engine.properties.save("unigine_project/my_new_lib.prop");

Setting Loading Order for Libraries

The loading order set for property libraries is important when properties are stored in several .prop files: child properties cannot be loaded (and, therefore, modified) before their parents. The loading order can be set via Unigine API using the engine.properties.addWorldLibrary() function:

Source code (UnigineScript)

engine.properties.addWorldLibrary("unigine_project/game_objects.prop");
engine.properties.addWorldLibrary("unigine_project/game_objects_unit.prop");
engine.properties.addWorldLibrary("unigine_project/game_objects_unit_weapon.prop");

Or the properties to load and their order can be specified directly in the .world file:

Source code (XML)

<world version="1.11">
<materials>
	...
</materials>
<properties>
	<library>project/game_objects.prop</library>
	<library>project/game_objects_unit.prop</library>
	<library>project/game_objects_unit_weapon.prop</library>
</properties>
...

Properties Class

Members

int engine.properties.isLibrary(string name)

Checks if the property library with the given name exists.

Arguments

string name - Path to the property library. The path can be both absolute or relative to the data folder.

Return value

1 if the property library exists; otherwise, 0.

int engine.properties.isLibraryEditable(int num)

Returns a value indicating if properties can be added to or removed from the given library.

Arguments

int num - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).

Return value

1 if the property library is editable; otherwise, 0.

string engine.properties.getLibraryName(int num)

Returns the path to the property library by its number.

Source code (UnigineScript)

for (int i = 0; i < engine.properties.getNumLibraries(); i++){
	log.message("getLibraryName(%d) returned %s\n",i,engine.properties.getLibraryName(i));
}

Arguments

int num - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).

Return value

Path to the property library.

int engine.properties.getNumLibraries()

Returns the number of all loaded property libraries (i.e. associated and not associated with the current world).

Return value

The number of loaded property libraries.

int engine.properties.getNumProperties(int library)

Returns the number of properties in the given library.

Arguments

int library - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).

Return value

Number of properties in the library.

int engine.properties.getNumWorldLibraries()

Returns the number of property libraries associated with the current world.

Return value

Number of property libraries associated with the current world.

Property engine.properties.getProperty(int library, int num)

Returns a property by its number in the given library. The returned property can be modified by using methods of the Property class.

Source code (UnigineScript)

Property properties[];
int library = engine.properties.findLibrary("unigine_project/unigine_project.prop");
for (int i; i < engine.properties.getNumProperties(library); i++) {
	properties[i] = engine.properties.getProperty(library,i);
}

Arguments

int library - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).
int num - The number of the property in range from 0 to the total number of properties in the specified library.

Return value

A property (an instance of the Property class).

int engine.properties.isProperty(string name)

Checks if the property with the given name exists in one of the loaded libraries.

Arguments

string name - Name of the property.

Return value

1 if the given property exists; otherwise, 0.

string engine.properties.getPropertyName(int library, int num)

Returns the name of the property by its number in the given library.

Arguments

int library - The number of the property library in range from 0 to the total number of the loaded libraries (i.e. associated and not associated with the current world).
int num - The number of the property in range from 0 to the total number of properties in the specified library..

Return value

Name of the property.

string engine.properties.getWorldLibraryName(int num)

Returns the path to the property library associated with the current world by the library index.

Source code (UnigineScript)

for (int i = 0; i < engine.properties.getNumWorldLibraries(); i++){
	log.message("getWorldLibraryName(%d) returned %s\n",i,engine.properties.getWorldLibraryName(i));
}

Arguments

int num - The number of the property library in range from 0 to the total number of property libraries associated with the world.

Return value

Path to the property library.

int engine.properties.addWorldLibrary(string name)

Loads a library and associates it with the current world. If the library file does not exist, an empty library is created. The libraries loaded via this function will be loaded/saved on the current world loading/saving.

Arguments

string name - Path to the property library to load. The path can be both absolute or relative to the data folder.

Return value

1 if the library is loaded or created successfully; otherwise, 0.

int engine.properties.clear(string name)

Unloads a given library and all its contents (if it was previously loaded). Note that you cannot unload a library, if some of its properties are parent to properties from other libraries.

Arguments

string name - Name of the property library.

Return value

1 if the property library is cleared successfully; otherwise, 0.

void engine.properties.clearWorldLibraries()

Clears the list of the property libraries associated with the current world. At that, the libraries will stay loaded.

int engine.properties.cloneProperty(string name, string new_library, string new_name)

Copies a property into the specified property library under the specified name.

NoticeThe root property (the property that has no parent) cannot be copied by using this function.

The loading order of the libraries should be taken into account: if the property to be copied has a parent property stored in the source library and the destination library is loaded before the source library, the parent property should be copied first.

NoticeThe property cannot be copied if the destination library or the property itself is non-editable.

Arguments

string name - Name of the property to copy.
string new_library - Path to the destination library, into which the property will be copied. The path can be both absolute or relative to the data folder.
string new_name - Name, under which the property will be added to the destination library.

Return value

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

int engine.properties.create(string name)

Creates an empty property library. To be used, the created library should be loaded to the current world.

Source code (UnigineScript)

engine.properties.create("unigine_project/property_library.prop");

Arguments

string name - Path to the property library including its name. A path can be both absolute or relative to the data folder.

Return value

1 if the property library is created successfully; otherwise, 0.

int engine.properties.findLibrary(string name)

Returns the number of the property library by its name.

Arguments

string name - Path to the property library. The path can be both absolute or relative to the data folder.

Return value

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

int engine.properties.findLibraryProperty(int library, string name)

Searches for the property with the given name in the given library.

Arguments

int library - Index of the property library.
string name - Name of the property.

Return value

The number of the property in the library, if it is found; otherwise, -1.

Property engine.properties.findProperty(string name)

Searches for the property with the given name. The returned property can be modified by using methods of the Property class.

Arguments

string name - Name of the property.

Return value

A property, if it is found ((an instance of the Property class)); otherwise, 0.

int engine.properties.findPropertyLibrary(string name)

Searches for the property library containing the given property.

Arguments

string name - Name of the property.

Return value

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

int engine.properties.inheritProperty(string name, string new_library, string new_name)

Inherits a property from the given property and adds it to the specified library under the specified name. The loading order of the libraries should be taken into account: if the property to inherit from has a parent property stored in the source library and the destination library is loaded before the source library, the property won't be inherited.

NoticeThe property cannot be inherited if the destination library is non-editable.

Arguments

string name - Name of the property to inherit from.
string new_library - Path to the destination library, into which the inherited property will be added. The path can be both absolute or relative to the data folder.
string new_name - Name, under which the inherited property will be added to the destination library.

Return value

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

int engine.properties.load(string name)

Loads the property library from the given file. Loaded in such way, the library won't be associated with the current world and, therefore, it won't be automatically loaded/saved on world loading/saving. So, if you want to save changes made in the loaded library (if any), you should call save() function.

Source code (UnigineScript)

engine.properties.load("unigine_project/property_library.prop");

Arguments

string name - Path to the .prop file with the property library. A path can be both absolute or relative to the data folder.

Return value

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

int engine.properties.moveProperty(string name, string new_library, string new_name)

Moves a property into the specified property library under the specified name.

NoticeThe root property (the property that has no parent) cannot be moved by using this function.

The loading order of the libraries should be taken into account:

If the property to be moved has a parent property stored in the source library and the destination library is loaded before the source library, the parent property should be moved first.
If the property to be moved has a child property stored in the source library and this source library is loaded before the destination library, the child property should also be moved.

Otherwise, the property will be simply renamed.

NoticeThe property cannot be moved if the destination or source library or the property itself is non-editable.

Arguments

string name - Name of the property to move.
string new_library - Path to the destination library, into which the property will be moved. The path can be both absolute or relative to the data folder.
string new_name - Name, under which the property will be added to the destination library.

Return value

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

int engine.properties.removeProperty(string name)

Removes the property and all its children from the property library.

NoticeThe root property (the property that has no parent) or non-editable property cannot be removed by using this function. The property stored in the non-editable library cannot be removed as well.

Arguments

string name - Name of the property to remove.

Return value

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

int engine.properties.removeWorldLibrary(string name)

Removes the property library associated with the world from the list of preloaded property libraries. The library remains loaded so its properties stay available.

Arguments

string name - Path to the property library to remove. The path can be both absolute or relative to the data folder.

Return value

1 if the library is removed successfully; otherwise, 0.

int engine.properties.replaceProperty(string name, string new_name)

Replaces the specified property with a new one for all nodes. The property itself won't be replaced in the library. The new property that replaces the specified one should exist in a property library. For example, if you have 3 nodes with the surface_base_0 property, calling this method will change this property to the specified one for all these nodes (e.g. it can be changed to surface_base_3).

Arguments

string name - Name of the property to be replaced.
string new_name - Name of the new property.

Return value

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

int engine.properties.save(string name)

Saves the property library into the specified file. The file name should be the same as the library name. This function should be called if you need to save changes in the library that isn't associated with the current world (loaded via the load() function). However, you can call it for the associated library, if you want to save changes in any way (independently of world saving).

Arguments

string name - Path to the file into which the property library should be saved. The path can be both absolute or relative to the data folder.

Return value

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

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

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