Skip to content

Materials and Textures

Materials define how surfaces look; textures (image items) supply maps such as albedo, normal, and roughness. Scripts work with Item handles — create materials at runtime or load them from the project.

Loading textures

local Loader = require 'engine/loader'

local wood = await(Loader.loadImage("/resources/textures/wood", {
    waitUntilFinished = true,
}))

Use flipY = false when the texture is for Canvas, not 3D meshes. See Asset Loading.

Creating materials at runtime

local Material = require 'engine/items/material'

local mat = await(Material.create({
    albedoMap = wood,
    -- metalness, roughness, normalMap, etc.
}))

Assign to a scene object:

-- through method
self.node:setMaterial(mat)
-- or directly
self.node.material = mat

Or pass material when creating primitives:

await(SgSphere.create({ radius = 1, material = mat }))

For designer-assigned materials, use Property.Link:

MyBehaviour:addProperty("bodyMaterial", Property.Link, nil, {
    allowedTypes = { "Material" },
})

Canvas textures

Render dynamic textures from Canvas into materials via CanvasTexture items. See CanvasTexture and Canvas and HUD Overlays.

Editor concepts

The material graph and PBR fields in the inspector are described in Materials. For custom surface and background shading with TSL Shader items, see TSL Shaders.

Further reading