---
title: "Material"
description: "The Material namespace — the engine's Luau API reference for Material."
section: "API Reference"
slug: "api-material"
canonical: "https://origozero.ai/docs/api-material"
updated: "2026-09-02T13:33:31.477541360+00:00"
tags: ["api", "reference"]
---

# Material

The `Material` namespace — 17 functions.

## globals/Material/Apply {#globals-material-apply}

```lua
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 {#globals-material-create}

```lua
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.

```lua
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 {#globals-material-exists}

```lua
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 {#globals-material-getproperty}

```lua
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 {#globals-material-getpropertynames}

```lua
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 {#globals-material-setproperty}

```lua
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.

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

## globals/Material/SetTexture {#globals-material-settexture}

```lua
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 {#globals-material-update}

```lua
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.

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

## globals/Material/apply {#globals-material-apply}

```lua
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.

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

## globals/Material/create {#globals-material-create}

```lua
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.

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

## globals/Material/exists {#globals-material-exists}

```lua
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.

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

## globals/Material/getProperty {#globals-material-getproperty}

```lua
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.

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

## globals/Material/getPropertyNames {#globals-material-getpropertynames}

```lua
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.

```lua
local props = Material.getPropertyNames("gold")
```

## globals/Material/setProperties {#globals-material-setproperties}

```lua
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.

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

## globals/Material/setProperty {#globals-material-setproperty}

```lua
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).

```lua
Material.setProperty("gold", "roughness", 0.4)     -- by material name
Material.setProperty(entityId, "roughness", 0.4)   -- by entity
```

## globals/Material/setTexture {#globals-material-settexture}

```lua
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.

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

## globals/Material/update {#globals-material-update}

```lua
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.

```lua
Material.update("gold", { color = { 1, 0.85, 0.2 }, roughness = 0.15 })
```