engine.materials Functions

List of Functions:

This set of functions allows to manage manually via script the list of material libraries that belong with a world. These material libraries are loaded/saved on world loading/saving. (This list is stored at the beginning of the corresponding *.world file.)

int engine.materials.addWorldLibrary (string filename)

Loads a library and associates it with the current world (such libraries are specified in the *.world file and automatically loaded on the world initialization). If the library file does not exist, an empty library is created. (For simple loading without association, see engine.materials.load().)

Arguments

string filename - Name of a material library to be loaded:
- A full path (relative to the data folder).
- Name without a file path. The first found library with this name is used in this case.

Return value

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

Examples

Source code (UnigineScript)

engine.materials.addWorldLibrary("my_materials.mat");
engine.materials.addWorldLibrary("project/my_materials_sfx.mat");

int engine.materials.clear (string library)

Unloads a loaded material library. (The library is not deleted from the list of world libraries. It still belong to the world and will be automatically loaded on the world initialization). A library cannot be cleared if any of its materials are a parent to materials from other libraries.

Arguments

string library - Name of the library:
- A full path (relative to the data folder); also used if a library is loaded from *.world file.
- The same name as passed to engine.materials.addWorldLibrary()). The first found library with this name is used in this case.

Return value

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

Examples

Source code (UnigineScript)

engine.materials.addWorldLibrary("my_materials.mat");
engine.materials.clear("my_materials.mat");

engine.materials.addWorldLibrary("project/my_materials_sfx.mat");
engine.materials.clear("project/my_materials_sfx.mat"); // to be used when a library is loaded from *.world file

int engine.materials.cloneMaterial (string name, string dest_library, string dest_name)

Copies a material into a specified material library, with a given name.

Base materials (without parents) cannot be copied, only the inherited ones can be.
A library to copy to should be editable.
It is not possible to copy a material from a library that is loaded after the destination library. (To make sure that parent materials are always loaded before the inherited ones, if cross-library inheritance is present).

Arguments

string name - Name of the material (from any of the loaded libraries) to copy.
string dest_library - Name of the destination library to copy material into:
- A full path (relative to the data folder); also used if a library is loaded from *.world file.
- The same name as passed to engine.materials.addWorldLibrary()). The first found library with this name is used in this case.
string dest_name - New name for the copied material.

Return value

1 if the material is cloned successfully; otherwise, 0.

int engine.materials.create (string name)

Creates an empty material library.

Arguments

string name - Material library name.

Return value

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

int engine.materials.findLibraryMaterial (int library, string name)

Searches for a specified material by its name in a given library.

Arguments

int library - Index of a library to search a material in.
string name - Name of the material.

Return value

Index of the material in the library, if found; otherwise, -1.

int engine.materials.findLibrary (string name)

Searches for a loaded library by its name.

Arguments

string name - Name of the library:
- A full path (relative to the data folder); also used if a library is loaded from *.world file.
- The same name as passed to engine.materials.addWorldLibrary()). The first found library with this name is used in this case.

Return value

Index of the library, if found; otherwise, -1.

Examples

Source code (UnigineScript)

engine.materials.addWorldLibrary("my_materials.mat");
int a = engine.materials.findLibrary("my_materials.mat");

engine.materials.addWorldLibrary("project/my_materials_sfx.mat");
int b = engine.materials.findLibrary("project/my_materials_sfx.mat"); // to be used when a library is loaded from *.world file

int engine.materials.findMaterialLibrary (string name)

Searches for a loaded library containing a given material.

Arguments

string name - Name of the material.

Return value

Index of the library, if found; otherwise, -1.

Material engine.materials.findMaterial (string name)

Searches for a material with a given name in all loaded libraries.

Arguments

string name - Name of the material.

Return value

Material, if found; otherwise, 0.

string engine.materials.getLibraryName (int index)

Returns the name of a loaded library by its index. It is either a full path (relative to the data folder; returned if a library is loaded from *.world file) or the same name as passed to engine.materials.addWorldLibrary().

Arguments

int index - Index of the library.

Return value

Name of the library.

string engine.materials.getMaterialName (int library, int num)

Returns the name of a material by its index in a given library.

Arguments

int library - Index of the library.
int num - Index of the material.

Return value

Name of the material.

Material engine.materials.getMaterial (int library, int num)

Returns a material by its index in a given library.

Arguments

int library - Index of the library.
int num - Index of the material.

Return value

The material.

int engine.materials.getNumLibraries ()

Returns the number of all loaded material libraries, including the base ones. (To get only the materials that belong to the world, see engine.materials.getNumWorldLibraries()).

Return value

Number of the loaded material libraries.

int engine.materials.getNumMaterials (int index)

Returns the number of materials in a given library.

Arguments

int index - Index of the library.

Return value

Number of materials in the library.

int engine.materials.getNumWorldLibraries ()

Returns the number of material libraries that belong to the current world (such libraries are specified in the *.world file and automatically loaded on the world initialization).

Return value

Number of libraries belonging to the world.

string engine.materials.getWorldLibraryName (int index)

Returns the name of a library belonging to the current world by its index.

Arguments

int index - Index of the library.

Return value

Name of the library.

int engine.materials.inheritMaterial (string name, string dest_library, string new_name)

Creates a new material that inherits from a specified one and adds it to a given library.

A library to add a material to should be editable.
It is not possible to inherit a material from a library that is loaded after the destination library. (To make sure that parent materials are always loaded before the inherited ones).

Arguments

string name - Name of the material to inherit from.
string dest_library - Name of the destination library to add a material into:
- A full path (relative to the data folder); also used if a library is loaded from *.world file.
- The same name as passed to engine.materials.addWorldLibrary()). The first found library with this name is used in this case.
string new_name - Name for the inherited material.

Return value

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

int engine.materials.isLibraryEditable (int index)

Checks if it is possible to add or removed materials from a given library (its editable flag is not set to 0).

Arguments

int index - Index of the library.

Return value

1 if the library is editable; otherwise, 0.

int engine.materials.isLibrary (string name)

Checks if there is a library with a given name.

Arguments

string name - Name of the library to check:
- A full path (relative to the data folder); also used if a library is loaded from *.world file.
- The same name as passed to engine.materials.addWorldLibrary()). The first found library with this name is used in this case.

Return value

1 if the library exists; otherwise, 0.

int engine.materials.isMaterial (string name)

Checks if there is a material with a given name in any of the loaded libraries.

Arguments

string name - Name of the material.

Return value

1 if the material exists; otherwise, 0.

int engine.materials.load (string filename)

Loads a library from a given file. This function does not associate a library with a world.

Arguments

string filename - File with the library to load.

Return value

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

int engine.materials.moveMaterial (string name, string dest_library, string dest_name)

Moves a material to another library.

Base materials (without parents) cannot be moved, only the inherited ones can be.
A library to move a material to should be editable.
It is not possible to move a material from a library that is loaded after the destination library. (To make sure that parent materials are always loaded before the inherited ones, if cross-library inheritance is present).

Arguments

string name - Name of the material to be moved.
string dest_library - Name of the destination library to add a material into:
- A full path (relative to the data folder); also used if a library is loaded from *.world file.
- The same name as passed to engine.materials.addWorldLibrary()). The first found library with this name is used in this case.
string dest_name - New name for the moved material.

Return value

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

int engine.materials.removeMaterial (string name)

Removes a material (from any of the loaded libraries) and all its children.

Base materials (without parents) cannot be removed, only the inherited ones can be.
A library to remove a material to should be editable.

Arguments

string name - Name of the material to be removed.

Return value

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

int engine.materials.removeWorldLibrary (string name)

Deletes a given library from the list of material libraries that belong to the world (such libraries are specified in the *.world file and automatically loaded on the world initialization). This function does not unload the library if it has already been loaded.

Arguments

string name - Name of the library to be dissociated:
- A full path (relative to the data folder); also used if a library is loaded from *.world file.
- The same name as passed to engine.materials.addWorldLibrary()). The first found library with this name is used in this case.

Return value

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

Examples

Source code (UnigineScript)

engine.materials.addWorldLibrary("my_materials.mat");
engine.materials.removeWorldLibrary("my_materials.mat");

engine.materials.addWorldLibrary("project/my_materials_sfx.mat");
engine.materials.removeWorldLibrary("project/my_materials_sfx.mat"); // to be used when a library is loaded from *.world file

int engine.materials.save (string name)

Saves a library on disk. The file is named after the library. To be saved, a library should be editable.

Arguments

string name - Name of the library to be saved.

Return value

1 if the 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)