Model Materials (Programming)

Overview

This documentation mainly describes how to set the model material in program codes (C++ and Lua) and some notes.

Model Materials refer to the materials used by Models, Skins, Decals and other objects, inherited from IVisbase.

For the combined types containing the above objects, such as the Actor Object and the Effect Model Object, the specific model object needs to be obtained to edit its materials.

If a model material needs to be set for a component object, you need to obtain the direct component objects LModelComponent, LSkinComponent, LDecalComponent, etc. of the above objects first. Then obtain its proxy object and use it to set the material. When set in Lua script, you can also edit the materials of the component objects LModelComponent, LSkinComponent, LDecalComponent, etc. directly. But it is not allowed in C++ code.

Setting Material File Interfaces

• SetExternalMaterialFile sets the material file of the object that references the same model file as it and supports setting the material file referenced by one material or multiple materials.

      bool SetExternalMaterialFile(const char* material_name, 
          const char* file,  const char* section);

• SetPrivateMaterialFile sets the material file of the current object and supports setting the material file referenced by one material or multiple materials.

      bool SetPrivateMaterialFile(const char* material_name, 
          const char* file,  const char* section);

• LoadMaterial loads the material file. And after the material file associated with the object is modified by SetExternalMaterialFile or SetPrivateMaterialFile, the LoadMaterial needs to be called to make the modification take effect immediately.

      bool LoadMaterial(bool asynchronization = true);

Parameter Description

SetExternalMaterialFile and SetPrivateMaterialFile share the same number and meaning of parameters.

• material_name: Material name. All material names can be queried through the interface GetMaterialNameList. Or you can browse all material names of the model in the Material Editor.

  void GetMaterialNameList(const IVarList& args,   IVarList& result)

  The material name can be set to "", which means all materials in the object reference the material file specified by the file parameter below.

• file: Material file. The material file used by the Engine, with the extension .mtl and format Ini , which means all the materials take effect.

• section: Deprecated property, just set to "". Originally, it means the section name in the material Ini file.

LoadMaterial has an optional parameter asynchronization, which means whether to use asynchronous loading mode or not. It is true by default and can be omitted.

Lua Code Example

Model resource: %EditorResource%mdl\base_shape\mat.xmod Material resource: %EditorResource%mdl\base_shape\pbr_metalic.mtl

--Set the material file referenced by the Mat_1 material of the model resource
Model:SetExternalMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--Set the material file referenced by all materials of the model resource
Model:SetExternalMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--Set the material file referenced by the Mat_1 material of the current object
Model:SetPrivateMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--Set the material file referenced by all materials of the current object
Model:SetPrivateMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

--Reload the material so that it takes effect immediately
Model:LoadMaterial()

C++ Code Example

Model resource: %EditorResource%mdl\base_shape\mat.xmod Material resource: %EditorResource%mdl\base_shape\pbr_metalic.mtl

IVisBase* pVisual;
//Set the material file referenced by the Mat_1 material of the model resource
pVisual->SetExternalMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

//Set the material file referenced by all materials of the model resource
pVisual->SetExternalMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

//Set the material file referenced by the Mat_1 material of the current object
pVisual->SetPrivateMaterialFile("Mat_1",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")

//Set the material file referenced by all materials of the current object
pVisual->SetPrivateMaterialFile("",  "%EditorResource%mdl\\base_shape\\pbr_metalic.mtl", "")
    
//Reload the material so that it takes effect immediately
pVisual->LoadMaterial()

Setting Material Property Interfaces

• SetCustomMaterialValue modifies the properties of the material instance of an object. It only affects the material of this object, and does not affect other objects that reference the same material file as it.

      bool SetCustomMaterialValue(const char* material_name, 
          const char* key,  const char* val);

• SetModelMaterialValue modifies the properties of all material instances of a material.

      bool SetModelMaterialValue(const char* material_name, 
          const char* key,  const char* val);

Parameter Description

SetCustomMaterialValue and SetModelMaterialValue share the same number and meaning of parameters.

• material_name: Material name. All material names can be queried through the interface GetMaterialNameList. Or you can browse all material names of the model in the Material Editor.

  void GetMaterialNameList(const IVarList& args,   IVarList& result) 

• key: Material property name. Ambient, Diffuse, Metallic, Roughness, SpecularLevel, DiffuseMap, NormalMap, MetallicMap, etc. are the commonly used material property names. It can be queried by the following configuration：

  • /00_flexi_engine/client/unique_editor/pro/skin/pl_material/material_config/model_material.xml
  • Any .mtl file

• val: Property value, the string format for various property type values (bool, float, int, color, vector, map), where the color property is represented in the floating number, as listed in the following table.

Type	Value	Property Value
bool	false	"false"
bool	true	"true"
float	0.0	"0.0"
int	0	"0"
color	1.0, 1.1, 0.5	"1.0, 1.1, 0.5"
color	255, 255, 0	"1.0, 1.0, 0.0"
vector	1.0, 2.0, 3.0	"1.0, 2.0, 3.0"
path	"c：\abc.dds"	"c：\abc.dds"

Lua Code Example

Model resource: %EditorResource%mdl\base_shape\mat.xmod

Model:SetCustomMaterialValue("Mat_1", "Diffuse", "1.0, 0, 0")

C++ Code Example

Model resource: %EditorResource%mdl\base_shape\mat.xmod

IVisBase* pVisual;
...
((IMeshVisual*)pVisual)->SetCustomMaterialValue("Mat_1", "Diffuse", "1.0, 0, 0")

or

CVarList result;
g_pCore->InvokeMethod(pVisual, "SetCustomMaterialValue", CVarList()<< "Mat_1" << "Diffuse" << "1.0, 0, 0", result)

Notes on Setting Material Files and Material Properties

Differences

• Setting the material file will set all properties inside the material file to the material.
• Setting material properties will modify the specified material properties only.

Using Both Settings Simultaneously

The material properties can be updated by either setting a material file or a material property. Generally, you don't have to set them both simultaneously, only in special cases.

• You need to set the material file first and make sure the material is completed loaded before setting the material properties through the material interface. Otherwise, the property settings will be replaced.
• Make sure the material has completed loaded. Either load synchronously with LoadMaterial(false) or load asynchronously with LoadMaterial(true) and then wait for loading.

Map Property Settings

• After the material set by the material file calls LoadMaterial(), the map will be automatically reloaded internally, and there is no need to call additional map reloading operations.
• If the properties set through the interface are map properties, you will need to call ReloadMaterialTexture or ReloadAllMaterialTextures for them to take effect.