Material Scripting API

Module:

engine.resources.material_resource

Handle Type:

MaterialId

Enumerations

MaterialReusePolicy

Policy for material reusing. It is important to reduce amount of materials in the scene to improve rendering performance. So we provide material reusing by default to reach maximum efficiency.

Values:

• ReuseExisting = 0 - Reuse existing material with same MaterialImport. We caclulate hash of MaterialImport and try to find material with same hash.

• AlwaysCreateNew = 1 - Always create new material, even if we have material with same MaterialImport.

Structures

MaterialImport

This struct allow to create materials from code, see Material Scripting.

Fields:

• name : string - Material name

• shaderName : string - Shader name, see Shaders

• transparencyMode : TransparencyMode = material_property_enums::TransparencyMode.Opaque - Transparency mode, see Material Properties API. Equal to TransparencyMode Opaque by default

• faceCullMode : FaceCullMode = material_property_enums::FaceCullMode.Back - Face cull mode, see Material Properties API. Equal to FaceCullMode Back by default

• diffuse : TextureId - Diffuse texture, slot 0

• normal : TextureId - Normal texture, slot 1

• specular : TextureId - Specular texture, slot 2

• roughness : TextureId - Roughness texture, slot 3

• ao : TextureId - Ambient occlusion texture, slot 4

• emission : TextureId - Emission texture, slot 5

• properties : MaterialProperties - Material properties

Functions

• request_material (path_to_asset: string) : MaterialId

• create_material (material: MaterialImport; reuse_policy: MaterialReusePolicy = material_resource::MaterialReusePolicy.ReuseExisting) : MaterialId

• copy_material (material: MaterialId) : MaterialId

• update_material (resId: MaterialId; import_settings: MaterialImport)

request_material(path_to_asset: string): MaterialId

Requests a material asset by the path to it and returns the corresponding resource ID.

Arguments:

• path_to_asset : string - the path to the material asset

Returns:

• MaterialId - the resource ID of the material asset

Usage example:

let materialId = request_material("my_material")

create_material(material: MaterialImport; reuse_policy: MaterialReusePolicy = material_resource::MaterialReusePolicy.ReuseExisting): MaterialId

Creates material resource with given MaterialImport and MaterialReusePolicy. If MaterialReusePolicy is ReuseExisting and material with same MaterialImport already exists, it will return existing material. If MaterialReusePolicy is AlwaysCreateNew it will always create new material. Returns new or existing MaterialId, depends on MaterialReusePolicy.

Note

It is recommended to use MaterialReusePolicy ReuseExisting to improve performance of render.

Arguments:

• material : MaterialImport

• reuse_policy : MaterialReusePolicy

copy_material(material: MaterialId): MaterialId

Create a copy of existed material.

Arguments:

• material : MaterialId

update_material(resId: MaterialId; import_settings: MaterialImport)

Update material resource with given import_settings

Arguments:

• resId : MaterialId

• import_settings : MaterialImport