Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

material

Functions for interacting with materials.

Functions

material.get_constants(path: Hash | string): { name: Hash; type: number; value: Vector4 | Matrix4 }[]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

  • constants: material.constant_info[] — Shader constant information.

material.get_samplers(path: Hash | string): { name: Hash; u_wrap: number; v_wrap: number; min_filter: number; mag_filter: number; max_anisotropy: number }[]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

  • samplers: material.sampler_info[] — texture sampler information

material.get_textures(path: Hash | string): LuaMap<number, { path: Hash; handle: Hash; width: number; height: number; depth: number; mipmaps: number; type: number; flags: number }>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

  • textures: material.texture_info[] — material texture information

material.get_vertex_attributes(path: Hash | string): { name: Hash; value: Vector4 | Vector3 | Matrix4 | number | number[]; normalize: boolean; data_type: number; coordinate_space: number; semantic_type: number }[]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

  • attributes: material.vertex_attribute_info[] — vertex attribute information

material.set_constants(path: Hash | string, constants: Record<string, { type?: number; value?: Vector4 | Vector3 | Matrix4 | number | (Vector4 | Matrix4)[] }>): 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

  • path: Hash | string — The path to the resource
  • constants: Record<string, { type?: number; value?: Vector4 | Vector3 | Matrix4 | number | (Vector4 | Matrix4)[] }> — Shader constant updates keyed by constant name. Partial updates are supported.

material.set_samplers(path: Hash | string, samplers: Record<string, { u_wrap?: number; v_wrap?: number; min_filter?: number; mag_filter?: number; max_anisotropy?: number }>): 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

  • path: Hash | string — The path to the resource
  • samplers: Record<string, { u_wrap?: number; v_wrap?: number; min_filter?: number; mag_filter?: number; max_anisotropy?: number }> — Sampler updates keyed by sampler name. Partial updates are supported.

material.set_textures(path: Hash | string, textures: LuaMap<string, Hash> | Record<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> | Record<string, Hash> — A table keyed by sampler name with texture resources as values.

material.set_vertex_attributes(path: Hash | string, attributes: Record<string, { value?: Vector4 | Vector3 | Matrix4 | number | number[]; normalize?: boolean; data_type?: number; coordinate_space?: number; semantic_type?: number }>): 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

  • path: Hash | string — The path to the resource
  • attributes: Record<string, { value?: Vector4 | Vector3 | Matrix4 | number | number[]; normalize?: boolean; data_type?: number; coordinate_space?: number; semantic_type?: number }> — Vertex attributes keyed by name, or an array with explicit name fields. Partial updates are supported.

On this page