engine.materials Functions

Interface for managing the list of material libraries that belong to the world manually via script. These material libraries are loaded/saved on world loading/saving. (This list is stored at the beginning of the corresponding *.world file.)

Materials Class

Members

---

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.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.

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.

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.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.

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.

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.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.

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.

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.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.

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.

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.

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.

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.load(string filename, int addToWorldLibrary = 0)

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.
• int addToWorldLibrary - Set 1 to add material to the world library.

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.reload(string name)

Reloads the material library from the file.

Arguments

• string name - Material library name.

Return value

1 if the material library is reloaded successfully; otherwise, 0.

void engine.materials.reloadMaterials()

Reloads all material libraries.

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.

int engine.materials.replaceMaterial(string name, string new_name)

Replaces the specified material with a new one.

Arguments

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

Return value

1 if the material is replaced successfully; otherwise - 0.

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.