Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

material

Functions for interacting with materials.

Functions

material.get_constants(path: Hash | string): material.ConstantInfo[]N

  • Since Defold 1.13.0

Returns a table of all the shader constants in the material. This function will return all the shader constants that are used in both the vertex and the fragment shaders.

// Get the shader constants from a material specified as a resource property
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registration from this field, and only this field types the property onto `self`.
  properties: { my_material: resource.material() },

  init(self) {
    const constants = material.get_constants(self.my_material);
  },
});
go.property("my_material", resource.material())

function init(self)
    local constants = material.get_constants(self.my_material)
end

Parameters

  • path: Hash | string — The path to the resource

Returns

material.get_samplers(path: Hash | string): material.SamplerInfo[]N

  • Since Defold 1.13.0

Returns a table of all the texture samplers in the material. This function will return all the texture samplers that are used in both the vertex and the fragment shaders.

// Get the texture samplers from a material specified as a resource property
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registration from this field, and only this field types the property onto `self`.
  properties: { my_material: resource.material() },

  init(self) {
    const samplers = material.get_samplers(self.my_material);
  },
});
go.property("my_material", resource.material())

function init(self)
    local samplers = material.get_samplers(self.my_material)
end

Parameters

  • path: Hash | string — The path to the resource

Returns

material.get_textures(path: Hash | string): LuaMap<number, material.TextureInfo>N

  • Since Defold 1.13.0

Returns a table of all the textures from the material.

// Get the textures from a material specified as a resource property
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registration from this field, and only this field types the property onto `self`.
  properties: { my_material: resource.material() },

  init(self) {
    const textures = material.get_textures(self.my_material);
  },
});
go.property("my_material", resource.material())

function init(self)
    local textures = material.get_textures(self.my_material)
end

Parameters

  • path: Hash | string — The path to the resource

Returns

material.get_vertex_attributes(path: Hash | string): material.VertexAttributeInfo[]N

  • Since Defold 1.13.0

Returns a table of all the vertex attributes in the material. This function will return all the vertex attributes that are used in the vertex shader of the material.

// Get the vertex attributes from a material specified as a resource property
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registration from this field, and only this field types the property onto `self`.
  properties: { my_material: resource.material() },

  init(self) {
    const vertex_attributes = material.get_vertex_attributes(self.my_material);
  },
});
go.property("my_material", resource.material())

function init(self)
    local vertex_attributes = material.get_vertex_attributes(self.my_material)
end

Parameters

  • path: Hash | string — The path to the resource

Returns

material.set_constants(path: Hash | string, constants: LuaMap<string | Hash, material.ConstantOptions> | Record<string, material.ConstantOptions>): voidN

  • Since Defold 1.13.0

Sets shader constants in a material, if the constants exist.

// Set a shader constant in a material specified as a resource property
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registration from this field, and only this field types the property onto `self`.
  properties: { my_material: resource.material() },

  init() {
    return { my_view_proj: vmath.matrix4() };
  },

  update(self) {
    // update the 'tint' constant
    material.set_constants(self.my_material, {
      tint: { value: vmath.vector4(1, 0, 0, 1) },
    });
    // change the type of the 'view_proj' constant to CONSTANT_TYPE_USER_MATRIX4 so the renderer can set our custom data
    material.set_constants(self.my_material, {
      view_proj: { value: self.my_view_proj, type: material.CONSTANT_TYPE_USER_MATRIX4 },
    });
  },
});
go.property("my_material", resource.material())

function update(self)
    -- update the 'tint' constant
    material.set_constants(self.my_material, {
        tint = { value = vmath.vector4(1, 0, 0, 1) }
    })
    -- change the type of the 'view_proj' constant to CONSTANT_TYPE_USER_MATRIX4 so the renderer can set our custom data
    material.set_constants(self.my_material, {
        view_proj = { value = self.my_view_proj, type = material.CONSTANT_TYPE_USER_MATRIX4 }
    })
end

Parameters

material.set_samplers(path: Hash | string, samplers: LuaMap<string | Hash, material.SamplerOptions> | Record<string, material.SamplerOptions>): voidN

  • Since Defold 1.13.0

Sets texture samplers in a material, if the samplers exist. Use this function to change the settings of texture samplers. To set actual textures that should be bound to the samplers, use the material.set_textures function instead.

// Configures a sampler in a material specified as a resource property
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registration from this field, and only this field types the property onto `self`.
  properties: { my_material: resource.material() },

  init(self) {
    material.set_samplers(self.my_material, {
      texture_sampler: { u_wrap: graphics.TEXTURE_WRAP_REPEAT, v_wrap: graphics.TEXTURE_WRAP_MIRRORED_REPEAT },
    });
  },
});
go.property("my_material", resource.material())

function init(self)
    material.set_samplers(self.my_material, {
        texture_sampler = { u_wrap = graphics.TEXTURE_WRAP_REPEAT, v_wrap = graphics.TEXTURE_WRAP_MIRRORED_REPEAT }
    })
end

Parameters

material.set_textures(path: Hash | string, textures: LuaMap<string | Hash, string | Hash> | Record<string, string | Hash>): voidN

  • Since Defold 1.13.0

Sets textures in a material, if the samplers exist.

// Set a texture in a material from a resource
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registrations from this field, and only this field types them onto `self`.
  properties: { my_material: resource.material(), my_texture: resource.texture() },

  init(self) {
    material.set_textures(self.my_material, {
      my_texture: self.my_texture,
    });
  },
});
go.property("my_material", resource.material())
go.property("my_texture", resource.texture())

function init(self)
    material.set_textures(self.my_material, {
        my_texture = self.my_texture
    })
end

Parameters

  • path: Hash | string — The path to the resource
  • textures: LuaMap<string | Hash, string | Hash> | Record<string, string | Hash> — A table keyed by sampler name with texture resources as values.

material.set_vertex_attributes(path: Hash | string, attributes: LuaMap<string | Hash, material.VertexAttributeOptions> | Record<string, material.VertexAttributeOptions> | material.NamedVertexAttributeOptions[]): voidN

  • Since Defold 1.13.0

Sets vertex attributes in a material, if the vertex attributes exist.

// Configures a vertex attribute in a material specified as a resource property
export default defineScript({
  // Never call `go.property` yourself: the transpiler emits the chunk-scope
  // registration from this field, and only this field types the property onto `self`.
  properties: { my_material: resource.material() },

  init(self) {
    material.set_vertex_attributes(self.my_material, {
      tint_attribute: { value: vmath.vector4(1, 0, 0, 1), semantic_type: graphics.SEMANTIC_TYPE_COLOR },
      weights: { value: vmath.vector4(0, 1, 0, 0), semantic_type: graphics.SEMANTIC_TYPE_NONE },
    });
  },
});
go.property("my_material", resource.material())

function init(self)
    material.set_vertex_attributes(self.my_material, {
        tint_attribute = { value = vmath.vec4(1, 0, 0, 1), semantic_type = graphics.SEMANTIC_TYPE_COLOR },
        weights        = { value = vmath.vec4(0, 1, 0, 0), semantic_type = graphics.SEMANTIC_TYPE_NONE }
    })
end

Parameters

Constants

material.CONSTANT_TYPE_NORMAL: number & { readonly __brand: "material.CONSTANT_TYPE_NORMAL" }N

  • Since Defold 1.13.2

Normal matrix constant.

material.CONSTANT_TYPE_PROJECTION: number & { readonly __brand: "material.CONSTANT_TYPE_PROJECTION" }N

  • Since Defold 1.13.2

Projection matrix constant.

material.CONSTANT_TYPE_PROJECTION_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_PROJECTION_INVERSE" }N

  • Since Defold 1.13.2

Inverse projection matrix constant.

material.CONSTANT_TYPE_TEXTURE: number & { readonly __brand: "material.CONSTANT_TYPE_TEXTURE" }N

  • Since Defold 1.13.2

Texture matrix constant.

material.CONSTANT_TYPE_TIME: number & { readonly __brand: "material.CONSTANT_TYPE_TIME" }N

  • Since Defold 1.13.2

Time constant.

material.CONSTANT_TYPE_USER: number & { readonly __brand: "material.CONSTANT_TYPE_USER" }N

  • Since Defold 1.13.2

User vector constant.

material.CONSTANT_TYPE_USER_COLOR: number & { readonly __brand: "material.CONSTANT_TYPE_USER_COLOR" }N

  • Since Defold 1.13.2

User color constant.

material.CONSTANT_TYPE_USER_MATRIX4: number & { readonly __brand: "material.CONSTANT_TYPE_USER_MATRIX4" }N

  • Since Defold 1.13.2

User matrix constant.

material.CONSTANT_TYPE_VIEW: number & { readonly __brand: "material.CONSTANT_TYPE_VIEW" }N

  • Since Defold 1.13.2

View matrix constant.

material.CONSTANT_TYPE_VIEW_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_VIEW_INVERSE" }N

  • Since Defold 1.13.2

Inverse view matrix constant.

material.CONSTANT_TYPE_VIEWPROJ: number & { readonly __brand: "material.CONSTANT_TYPE_VIEWPROJ" }N

  • Since Defold 1.13.2

View-projection matrix constant.

material.CONSTANT_TYPE_VIEWPROJ_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_VIEWPROJ_INVERSE" }N

  • Since Defold 1.13.2

Inverse view-projection matrix constant.

material.CONSTANT_TYPE_WORLD: number & { readonly __brand: "material.CONSTANT_TYPE_WORLD" }N

  • Since Defold 1.13.2

World matrix constant.

material.CONSTANT_TYPE_WORLD_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_WORLD_INVERSE" }N

  • Since Defold 1.13.2

Inverse world matrix constant.

material.CONSTANT_TYPE_WORLDVIEW: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEW" }N

  • Since Defold 1.13.2

World-view matrix constant.

material.CONSTANT_TYPE_WORLDVIEW_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEW_INVERSE" }N

  • Since Defold 1.13.2

Inverse world-view matrix constant.

material.CONSTANT_TYPE_WORLDVIEWPROJ: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEWPROJ" }N

  • Since Defold 1.13.2

World-view-projection matrix constant.

material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE" }N

  • Since Defold 1.13.2

Inverse world-view-projection matrix constant.

Types

interface material.ConstantInfo { name: Hash; type: material.ConstantType; value?: material.ConstantInfoValue; }

type material.ConstantInfoValue = Vector4 | Matrix4 | Vector4[] | Matrix4[]

interface material.ConstantOptions { type?: material.ConstantType; value?: material.ConstantValue; }

type material.ConstantType = typeof material.CONSTANT_TYPE_USER | typeof material.CONSTANT_TYPE_USER_COLOR | typeof material.CONSTANT_TYPE_USER_MATRIX4 | typeof material.CONSTANT_TYPE_VIEWPROJ | typeof material.CONSTANT_TYPE_WORLD | typeof material.CONSTANT_TYPE_TEXTURE | typeof material.CONSTANT_TYPE_VIEW | typeof material.CONSTANT_TYPE_PROJECTION | typeof material.CONSTANT_TYPE_NORMAL | typeof material.CONSTANT_TYPE_WORLDVIEW | typeof material.CONSTANT_TYPE_WORLDVIEWPROJ | typeof material.CONSTANT_TYPE_TIME | typeof material.CONSTANT_TYPE_WORLD_INVERSE | typeof material.CONSTANT_TYPE_VIEW_INVERSE | typeof material.CONSTANT_TYPE_PROJECTION_INVERSE | typeof material.CONSTANT_TYPE_VIEWPROJ_INVERSE | typeof material.CONSTANT_TYPE_WORLDVIEW_INVERSE | typeof material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE

type material.ConstantValue = number | Vector3 | Vector4 | Matrix4 | (number | Vector3 | Vector4 | Matrix4)[]

interface material.NamedVertexAttributeOptions { name: string | Hash; value?: material.VertexAttributeValue; normalize?: boolean; data_type?: graphics.DataType; coordinate_space?: graphics.CoordinateSpace; semantic_type?: graphics.SemanticType; }

interface material.SamplerInfo { name: Hash; type: graphics.TextureType | 6 | 7 | 8 | 9 | 10; u_wrap: graphics.TextureWrap; v_wrap: graphics.TextureWrap; w_wrap: graphics.TextureWrap; min_filter: graphics.TextureFilter; mag_filter: graphics.TextureFilter; max_anisotropy: number; }

interface material.SamplerOptions { u_wrap?: graphics.TextureWrap; v_wrap?: graphics.TextureWrap; w_wrap?: graphics.TextureWrap; min_filter?: graphics.TextureFilter; mag_filter?: graphics.TextureFilter; max_anisotropy?: number; }

interface material.TextureInfo { path?: Hash; handle: Opaque<"texture">; width: number; height: number; depth: number; page_count: number; mipmaps: number; type: graphics.TextureType; flags: graphics.TextureUsageFlag | number; }

interface material.VertexAttributeInfo { name: Hash; value: material.VertexAttributeValue; normalize: boolean; data_type: graphics.DataType; coordinate_space: graphics.CoordinateSpace; semantic_type: graphics.SemanticType; }

interface material.VertexAttributeOptions { value?: material.VertexAttributeValue; normalize?: boolean; data_type?: graphics.DataType; coordinate_space?: graphics.CoordinateSpace; semantic_type?: graphics.SemanticType; }

type material.VertexAttributeValue = number | Vector3 | Vector4 | Matrix4 | number[]

On this page

Functionsmaterial.get_constants(path: Hash | string): material.ConstantInfo[]Nmaterial.get_samplers(path: Hash | string): material.SamplerInfo[]Nmaterial.get_textures(path: Hash | string): LuaMap<number, material.TextureInfo>Nmaterial.get_vertex_attributes(path: Hash | string): material.VertexAttributeInfo[]Nmaterial.set_constants(path: Hash | string, constants: LuaMap<string | Hash, material.ConstantOptions> | Record<string, material.ConstantOptions>): voidNmaterial.set_samplers(path: Hash | string, samplers: LuaMap<string | Hash, material.SamplerOptions> | Record<string, material.SamplerOptions>): voidNmaterial.set_textures(path: Hash | string, textures: LuaMap<string | Hash, string | Hash> | Record<string, string | Hash>): voidNmaterial.set_vertex_attributes(path: Hash | string, attributes: LuaMap<string | Hash, material.VertexAttributeOptions> | Record<string, material.VertexAttributeOptions> | material.NamedVertexAttributeOptions[]): voidNConstantsmaterial.CONSTANT_TYPE_NORMAL: number & { readonly __brand: "material.CONSTANT_TYPE_NORMAL" }Nmaterial.CONSTANT_TYPE_PROJECTION: number & { readonly __brand: "material.CONSTANT_TYPE_PROJECTION" }Nmaterial.CONSTANT_TYPE_PROJECTION_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_PROJECTION_INVERSE" }Nmaterial.CONSTANT_TYPE_TEXTURE: number & { readonly __brand: "material.CONSTANT_TYPE_TEXTURE" }Nmaterial.CONSTANT_TYPE_TIME: number & { readonly __brand: "material.CONSTANT_TYPE_TIME" }Nmaterial.CONSTANT_TYPE_USER: number & { readonly __brand: "material.CONSTANT_TYPE_USER" }Nmaterial.CONSTANT_TYPE_USER_COLOR: number & { readonly __brand: "material.CONSTANT_TYPE_USER_COLOR" }Nmaterial.CONSTANT_TYPE_USER_MATRIX4: number & { readonly __brand: "material.CONSTANT_TYPE_USER_MATRIX4" }Nmaterial.CONSTANT_TYPE_VIEW: number & { readonly __brand: "material.CONSTANT_TYPE_VIEW" }Nmaterial.CONSTANT_TYPE_VIEW_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_VIEW_INVERSE" }Nmaterial.CONSTANT_TYPE_VIEWPROJ: number & { readonly __brand: "material.CONSTANT_TYPE_VIEWPROJ" }Nmaterial.CONSTANT_TYPE_VIEWPROJ_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_VIEWPROJ_INVERSE" }Nmaterial.CONSTANT_TYPE_WORLD: number & { readonly __brand: "material.CONSTANT_TYPE_WORLD" }Nmaterial.CONSTANT_TYPE_WORLD_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_WORLD_INVERSE" }Nmaterial.CONSTANT_TYPE_WORLDVIEW: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEW" }Nmaterial.CONSTANT_TYPE_WORLDVIEW_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEW_INVERSE" }Nmaterial.CONSTANT_TYPE_WORLDVIEWPROJ: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEWPROJ" }Nmaterial.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE: number & { readonly __brand: "material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE" }NTypesinterface material.ConstantInfo { name: Hash; type: material.ConstantType; value?: material.ConstantInfoValue; }type material.ConstantInfoValue = Vector4 | Matrix4 | Vector4[] | Matrix4[]interface material.ConstantOptions { type?: material.ConstantType; value?: material.ConstantValue; }type material.ConstantType = typeof material.CONSTANT_TYPE_USER | typeof material.CONSTANT_TYPE_USER_COLOR | typeof material.CONSTANT_TYPE_USER_MATRIX4 | typeof material.CONSTANT_TYPE_VIEWPROJ | typeof material.CONSTANT_TYPE_WORLD | typeof material.CONSTANT_TYPE_TEXTURE | typeof material.CONSTANT_TYPE_VIEW | typeof material.CONSTANT_TYPE_PROJECTION | typeof material.CONSTANT_TYPE_NORMAL | typeof material.CONSTANT_TYPE_WORLDVIEW | typeof material.CONSTANT_TYPE_WORLDVIEWPROJ | typeof material.CONSTANT_TYPE_TIME | typeof material.CONSTANT_TYPE_WORLD_INVERSE | typeof material.CONSTANT_TYPE_VIEW_INVERSE | typeof material.CONSTANT_TYPE_PROJECTION_INVERSE | typeof material.CONSTANT_TYPE_VIEWPROJ_INVERSE | typeof material.CONSTANT_TYPE_WORLDVIEW_INVERSE | typeof material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSEtype material.ConstantValue = number | Vector3 | Vector4 | Matrix4 | (number | Vector3 | Vector4 | Matrix4)[]interface material.NamedVertexAttributeOptions { name: string | Hash; value?: material.VertexAttributeValue; normalize?: boolean; data_type?: graphics.DataType; coordinate_space?: graphics.CoordinateSpace; semantic_type?: graphics.SemanticType; }interface material.SamplerInfo { name: Hash; type: graphics.TextureType | 6 | 7 | 8 | 9 | 10; u_wrap: graphics.TextureWrap; v_wrap: graphics.TextureWrap; w_wrap: graphics.TextureWrap; min_filter: graphics.TextureFilter; mag_filter: graphics.TextureFilter; max_anisotropy: number; }interface material.SamplerOptions { u_wrap?: graphics.TextureWrap; v_wrap?: graphics.TextureWrap; w_wrap?: graphics.TextureWrap; min_filter?: graphics.TextureFilter; mag_filter?: graphics.TextureFilter; max_anisotropy?: number; }interface material.TextureInfo { path?: Hash; handle: Opaque<"texture">; width: number; height: number; depth: number; page_count: number; mipmaps: number; type: graphics.TextureType; flags: graphics.TextureUsageFlag | number; }interface material.VertexAttributeInfo { name: Hash; value: material.VertexAttributeValue; normalize: boolean; data_type: graphics.DataType; coordinate_space: graphics.CoordinateSpace; semantic_type: graphics.SemanticType; }interface material.VertexAttributeOptions { value?: material.VertexAttributeValue; normalize?: boolean; data_type?: graphics.DataType; coordinate_space?: graphics.CoordinateSpace; semantic_type?: graphics.SemanticType; }type material.VertexAttributeValue = number | Vector3 | Vector4 | Matrix4 | number[]