Material Properties API

This module provides a simple way to define and manage material properties.
Material properties are key-value pairs that can be used to define the appearance of a material or the values of per-instance properties.
The values can be of the following types: float, float4, and int.

Defined in:

engine.render.material_properties

To define a new material property, use the add function.

For example:

var properties = MaterialProperties("color", GREEN_COLOR) // Adds a green color property

To add more properties, use the add function:

var properties = MaterialProperties("color", GREEN_COLOR)
add(properties, "uvRect", uvRect)

Or construct the properties in a single call:

var properties = MaterialProperties("color", GREEN_COLOR, "uvRect", uvRect)

To see the list of all available properties, refer to the corresponding shader documentation.

Constants

MAX_MATERIAL_PROPERTIES = 16

The maximum number of material properties that can be defined

Enumerations

FaceCullMode

Represents a value for “faceCullMode” property. We treat faces as back if they’re oriented counter-clockwise (CCW) after projection into screen space. We treat faces as front if they’re oriented clockwise (CW) after projection into screen space. For back faces their normals will be mirrored along interpolated surface normal.

Values:

  • None = 0 - Neither of the sides will be culled.

  • Back = 1 - Back faces will be culled. This is the default mode.

  • Front = 2 - Front faces will be culled.

TransparencyMode

Represents a transparency value for “transparencyMode” property.

Values:

  • Opaque = 0 - No blending (finalColor = srcColor)

  • Translucent = 1 - Default blending (finalColor = srcColor * srcAlpha + dstColor * (1 - srcAlpha))

  • Additive = 2 - Additive blending (finalColor = srcColor * srcAlpha + dstColor)

Structures

MaterialProperties

Represents a collection of material properties.

Fields:

  • names : string[16] - The names of the material properties

  • values : MaterialPropertyValue - The values of the material properties

  • cursor : int - The current cursor position in the material properties array

Functions

MaterialProperties(name1: string; value1: float|float4|int; name2: string; value2: float|float4|int; name3: string; value3: float|float4|int; name4: string; value4: float|float4|int): MaterialProperties

Creates a new material properties collection with four float properties.

Arguments:

  • name1 : string - the name of the first property

  • value1 : option<float| float4| int> - the value of the first property

  • name2 : string - the name of the second property

  • value2 : option<float| float4| int> - the value of the second property

  • name3 : string - the name of the third property

  • value3 : option<float| float4| int> - the value of the third property

  • name4 : string - the name of the fourth property

  • value4 : option<float| float4| int> - the value of the fourth property

Returns:
MaterialProperties(): MaterialProperties

Creates a new material properties collection.

Returns:
MaterialProperties(name1: string; value1: float|float4|int; name2: string; value2: float|float4|int; name3: string; value3: float|float4|int): MaterialProperties

Creates a new material properties collection with three float properties.

Arguments:

  • name1 : string - the name of the first property

  • value1 : option<float| float4| int> - the value of the first property

  • name2 : string - the name of the second property

  • value2 : option<float| float4| int> - the value of the second property

  • name3 : string - the name of the third property

  • value3 : option<float| float4| int> - the value of the third property

Returns:
MaterialProperties(name1: string; value1: float|float4|int; name2: string; value2: float|float4|int): MaterialProperties

Creates a new material properties collection with two float properties.

Arguments:

  • name1 : string - the name of the first property

  • value1 : option<float| float4| int> - the value of the first property

  • name2 : string - the name of the second property

  • value2 : option<float| float4| int> - the value of the second property

Returns:
MaterialProperties(name1: string; value1: float|float2|float3|float4|int|TextureId): MaterialProperties

Creates a new material properties collection with a single float property.

Arguments:

  • name1 : string - the name of the property

  • value1 : option<float| float2| float3| float4| int| TextureId> - the value of the property

Returns:
add(properties: MaterialProperties; name: string; value: TextureId): MaterialProperties&

Adds a texture material property to the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property

  • value : TextureId - the value of the property

Returns:
add(properties: MaterialProperties; name: string; value: int): MaterialProperties&

Adds an int material property to the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property

  • value : int - the value of the property

Returns:
add(properties: MaterialProperties; name: string; value: float3): MaterialProperties&

Adds a float3 material property to the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property

  • value : float3 - the value of the property

Returns:
add(properties: MaterialProperties; name: string; value: float): MaterialProperties&

Adds a float material property to the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property

  • value : float - the value of the property

Returns:
add(properties: MaterialProperties; name: string; value: float2): MaterialProperties&

Adds a float2 material property to the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property

  • value : float2 - the value of the property

Returns:
add(properties: MaterialProperties; name: string; value: float4): MaterialProperties&

Adds a float4 material property to the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property

  • value : float4 - the value of the property

Returns:
get(properties: MaterialProperties; name: string; out_value: auto(T)&): bool

Checks if a material property with the given name exists in the collection and retrieves its value.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property to check

  • out_value : auto(T)& - the variable to store the value of the property if it exists

Returns:

  • bool - true if the property exists, false otherwise

Example usage:

var my_value : float
if (properties.get("atest", my_value)) {
    // property "atest" exists in the collection and its value is stored in my_value
}
get_or(properties: MaterialProperties; name: string; def_value: auto(T)): T

Retrieves a float material property value by its name.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property

  • def_value : auto(T) - the default value to return if the property is not found

Returns:

  • T - the value of the property

Example usage::

let atest = properties.get_or(“atest”, 0.0) // returns the value of “my_property” if it exists, otherwise returns 0.0

has(properties: MaterialProperties; name: string; type_: auto(T)): bool

Checks if a material property with the given name and type exists in the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property to check

  • type_ : auto(T) - the type of the property to check

Returns:

  • bool - true if the property exists, false otherwise

Example usage:

if (properties.has("atest", type<float>)) {
    // property "atest" of type float exists in the collection
}
has(properties: MaterialProperties; name: string): bool

Checks if a material property with the given name exists in the collection.

Arguments:

  • properties : MaterialProperties - the material properties collection

  • name : string - the name of the property to check

Returns:

  • bool - true if the property exists, false otherwise