.. _stdlib_material_scripting:

====================
Material Scripting
====================

++++++++++++++++++++++
Material Asset Request
++++++++++++++++++++++

The simplest way to get a material from code::

    let material = request_material("my_material.material")


++++++++++++++++++++++
Material Creation
++++++++++++++++++++++

See :ref:`MaterialImport <struct-material_resource-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 :ref:`Mesh.setPerInstanceData <function-mesh_component_Mesh_rq_setPerInstanceData_Mesh_float4_float4>`.