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

  • shaderId : ShaderId - Shader ID, in case of using shaders created in shader graph editor

Functions

copy_material(material: MaterialId): MaterialId

Create a copy of existed material.

Arguments:
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:
replace_material(resId: MaterialId; import_settings: MaterialImport)

Rebuilds the material from import_settings, as if it was just created. Everything not listed in import_settings is dropped, including properties set by update_material. To change a few properties of an existing material use update_material instead.

Arguments:
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")
update_material(resId: MaterialId; import_settings: MaterialImport)

Warning

Deprecated: use update_material(materialId, MaterialProperties) to change properties, or replace_material to rebuild the material from scratch.

Games using this function cannot be published.

Update material resource with given import_settings

Arguments:
update_material(resId: MaterialId; properties: MaterialProperties)

Changes material properties, keeping the rest of the material as is: its shader, textures and the properties that are not listed. Properties are matched by name, so the same call covers shader parameters, texture slots (diffuse, normal, …) and the transparencyMode / faceCullMode render state.

The change is remembered per material, so it is also applied to a material asset that is still loading, and it survives a reload of that asset.

Usage example:

let material = request_material("my_material.material")
update_material(material, MaterialProperties("color", GREEN_COLOR))

Note

Materials from request_material are shared by everything that uses the asset. Use copy_material first to change a single instance.

Arguments: