Material Scripting

Material Asset Request

The simplest way to get a material from code:

let material = request_material("my_material.material")

Material Creation

See MaterialImport for additional info.

Create a material with the standard shader and red color:

let material = create_material(MaterialImport(
    shaderName = "standard_diffuse_shader",
    properties = MaterialProperties("color", RED_COLOR)
))

The standard shader can be omitted:

let material = create_material(MaterialImport(
    properties = MaterialProperties("color", RED_COLOR)
))

Create a material with a specified diffuse texture and green color:

let noiseTexture = request_texture("%builtin_package/logo.png")
let material = create_material(MaterialImport(
    shaderName = "standard_diffuse_shader",
    diffuse = noiseTexture,
    properties = MaterialProperties("color", GREEN_COLOR)
))

Material Update

You can change material properties after creation:

let material = request_material("my_material.material")

update_material(material, MaterialImport(
    properties = MaterialProperties("color", GREEN_COLOR)
))

Material Copy

You can create a copy of a material and update some of its properties:

let material = request_material("my_material.material")
let team1Material = copy_material(material)
let team2Material = copy_material(material)

update_material(team1Material, MaterialImport(
    properties = MaterialProperties("color", GREEN_COLOR)
))

update_material(team2Material, MaterialImport(
    properties = MaterialProperties("color", RED_COLOR)
))

Material Request

There is a way to reduce the number of materials in the scene. You can call request to avoid creating a new material every time. This function will return an already created material if a request with the same settings was called before.

Example:

let materialSettings = MaterialImport(
    properties = MaterialProperties("color", RED_COLOR)
)

let requestedMaterial1 = create_material(materialSettings)
let requestedMaterial2 = create_material(materialSettings)
assert(requestedMaterial1 == requestedMaterial2)

let createdMaterial1 = create_material(materialSettings, MaterialReusePolicy AlwaysCreateNew)
let createdMaterial2 = create_material(materialSettings, MaterialReusePolicy AlwaysCreateNew)
assert(createdMaterial1 != createdMaterial2)

Note

Instead of creating multiple materials with different colors, it is better (for render performance) to create one material and use Mesh.setPerInstanceData.