Log inGet started

Material

Updated 2 September 2026

The Material namespace — 17 functions.

globals/Material/Apply

Material.Apply(entityId: string, materialRef: MaterialRefOrName) -> boolean

PascalCase back-compat alias for apply.

Parameters

  • entityId string — Target entity id.
  • materialRef MaterialRefOrName — Either an AssetRef envelope or a material-name string.

Returns boolean — True on success.

globals/Material/Create

Material.Create(name: string, opts_or_shader: MaterialOpts | string | nil?, props: MaterialOpts?) -> MaterialRef?

PascalCase back-compat alias for create. Accepts the legacy 3-arg form (name, shader_string, opts_table) by folding shader into opts, and the canonical 2-arg form (name, opts).

Parameters

  • name string — Material name.
  • opts_or_shader MaterialOpts | string | nil (optional) — Either an options table OR a legacy shader string.
  • props MaterialOpts (optional) — Optional extra options table — only used when opts_or_shader is a shader string.

Returns MaterialRef? — The AssetRef envelope, or nil on failure.

Material.Create("gold", "pbr", { color = { 1, 0.85, 0.2 } })  -- legacy 3-arg
Material.Create("gold", { shader = "pbr", color = { 1, 0.85, 0.2 } })  -- canonical
Material.Create("neon", { shader = "pbr", emissive_color = { 0.1, 0.9, 1 }, emissive = 5 })  -- cyan glow at 5× intensity

globals/Material/Exists

Material.Exists(name: MaterialRefOrName) -> boolean

PascalCase back-compat alias for exists.

Parameters

  • name MaterialRefOrName — AssetRef envelope or material-name string.

Returns boolean — True when the material is registered.

globals/Material/GetProperty

Material.GetProperty(materialName: MaterialRefOrName, propertyName: string) -> any

PascalCase back-compat alias for getProperty.

Parameters

  • materialName MaterialRefOrName — AssetRef envelope or material-name string.
  • propertyName string — Property name.

Returns any — The property value, or nil when not found.

globals/Material/GetPropertyNames

Material.GetPropertyNames(materialName: MaterialRefOrName) -> { string }?

PascalCase back-compat alias for getPropertyNames.

Parameters

  • materialName MaterialRefOrName — AssetRef envelope or material-name string.

Returns { string }? — Array of property names, or nil when the material is not found.

globals/Material/SetProperty

Material.SetProperty(materialName: MaterialRefOrName, property: string, value: any?) -> any

PascalCase alias. Writes the property on the material ASSET by name/ref (a runtime change every entity using it takes; matRef:saveDefinition() writes it into mat.yaml) — distinct from M.setProperty, which targets the material on one entity's model.

Parameters

  • materialName MaterialRefOrName — AssetRef envelope or material-name string.
  • property string — Property name.
  • value any (optional) — New value.

Returns any — True on success.

Material.SetProperty("gold", "roughness", 0.1)

globals/Material/SetTexture

Material.SetTexture(materialName: MaterialRefOrName, slot: string, textureRef: string) -> boolean

PascalCase back-compat alias for setTexture.

Parameters

  • materialName MaterialRefOrName — AssetRef envelope or material-name string.
  • slot string — Texture slot name ("albedo", "normal", etc.).
  • textureRef string — Texture reference string.

Returns boolean — True on success.

globals/Material/Update

Material.Update(target: any?, props: { [string]: any }) -> number

PascalCase alias for update.

Parameters

  • target any (optional) — Material name / AssetRef, OR an entity — a proxy, an entity-id, or the display name the entity carries.
  • props { [string]: any } — Table of { [propertyName] = value } pairs.

Returns number — Number of properties applied.

Material.Update("gold", { base_color = { 1, 0, 0 }, roughness = 0.15 })

globals/Material/apply

Material.apply(entity: any?, materialRef: MaterialRefOrName) -> boolean

Apply a material to an entity's Model / SkinnedModel component by setting its material field. Accepts either an AssetRef envelope (from Material.create) or a bare material-name string. Errors when the entity has no Model or SkinnedModel — a material only renders where there is a mesh.

Parameters

  • entity any (optional) — The entity to apply to — an entity proxy (recommended: a validated handle to a real entity), an entity-id string, or the display name the entity carries.
  • materialRef MaterialRefOrName — Either an AssetRef envelope or a material-name string.

Returns boolean — True on success.

Material.apply(entityId, "gold")
local mat = Material.create("gold", { ... }); Material.apply(entityId, mat)

globals/Material/create

Material.create(name: string, opts: MaterialOpts?) -> MaterialRef?

Create a named material in the MaterialRegistry. Returns the canonical AssetRef envelope ({ __ref, type="material", name, guid }) — pass directly to Material.apply, the Model / SkinnedModel material field, or any AssetRef<material> consumer.

Parameters

  • name string — Material name. Must be a non-empty string.
  • opts MaterialOpts (optional) — Optional material options. shader?, color?, roughness?, metallic?, emissive? (the HDR glow intensity as a number, or a glow colour), emissive_color? (the glow colour), textures?.

Returns MaterialRef? — The AssetRef envelope on success, or nil on failure.

local gold = Material.create("gold", { color = { 1, 0.85, 0.2 }, metallic = 1 })

globals/Material/exists

Material.exists(name: MaterialRefOrName) -> boolean

Check whether a material exists in the registry. Accepts an AssetRef envelope or a bare material name.

Parameters

  • name MaterialRefOrName — AssetRef envelope or material-name string.

Returns boolean — True when the material is registered.

if Material.exists("gold") then ... end

globals/Material/getProperty

Material.getProperty(materialName: MaterialRefOrName, propertyName: string) -> any

Read the current value of a material property.

Parameters

  • materialName MaterialRefOrName — AssetRef envelope or material-name string.
  • propertyName string — Property name ("roughness", "metallic", "base_color", etc.).

Returns any — The property value, or nil when not found.

local r = Material.getProperty("gold", "roughness")

globals/Material/getPropertyNames

Material.getPropertyNames(materialName: MaterialRefOrName) -> { string }?

List the property names exposed by a registered material.

Parameters

  • materialName MaterialRefOrName — AssetRef envelope or material-name string.

Returns { string }? — Array of property names, or nil when the material is not found.

local props = Material.getPropertyNames("gold")

globals/Material/setProperties

Material.setProperties(target: any?, props: { [string]: any }) -> number

Set many material properties in one call. Addresses the target the same way setProperty does: a material name / AssetRef writes the material ASSET (affecting every entity using it), an entity proxy / entity-id / entity name writes the material bound to that entity's Model / SkinnedModel. Each key resolves against the shader's declared vocabulary, so the spellings create accepts reach the same uniforms; a key the shader does not expose is skipped, which lets one patch table serve materials built on different shaders.

Parameters

  • target any (optional) — Material name / AssetRef, OR an entity — a proxy, an entity-id, or the display name the entity carries.
  • props { [string]: any } — Table of { [propertyName] = value } pairs.

Returns number — Number of properties applied.

Material.setProperties("gold", { roughness = 0.2, metallic = 0.9 })
Material.setProperties(entityId, { base_color = { 1, 0, 0 } })

globals/Material/setProperty

Material.setProperty(target: any?, property: string, value: any?)

Set a material property. Addresses the target the same way getProperty does: pass a material name / AssetRef to write the material ASSET (affecting every entity using it), or an entity — a proxy, an id, or a display name — to write the material bound to that entity's Model / SkinnedModel. Errors when an entity target has no Model or SkinnedModel.

Parameters

  • target any (optional) — Material name / AssetRef, OR an entity — a proxy, an entity-id, or the display name the entity carries.
  • property string — Property name.
  • value any (optional) — New value (type depends on the property).
Material.setProperty("gold", "roughness", 0.4)     -- by material name
Material.setProperty(entityId, "roughness", 0.4)   -- by entity

globals/Material/setTexture

Material.setTexture(materialName: MaterialRefOrName, slot: string, textureRef: any?) -> boolean

Set a texture slot on a named material.

Parameters

  • materialName MaterialRefOrName — AssetRef envelope or material-name string.
  • slot string — Texture slot name ("albedo", "normal", etc.).
  • textureRef any (optional) — Texture reference. Formats: "color:r,g,b,a", "@builtin::textures.foo", or a render-output guid (camera target, video handle).

Returns boolean — True on success.

Material.setTexture("gold", "albedo", "@builtin::textures.gold")

globals/Material/update

Material.update(target: any?, props: { [string]: any }) -> number

Change an existing material from a property table — the counterpart to create, taking the same table shape. Addresses its target and counts its writes the way setProperties does.

Parameters

  • target any (optional) — Material name / AssetRef, OR an entity — a proxy, an entity-id, or the display name the entity carries.
  • props { [string]: any } — Table of { [propertyName] = value } pairs.

Returns number — Number of properties applied.

Material.update("gold", { color = { 1, 0.85, 0.2 }, roughness = 0.15 })
  • api
  • reference