> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: materials
description: Material property manipulation
icon: layers
---

The `materials` namespace loads, creates, and manipulates material objects and their properties.

## get

```lua
materials.get(path: string[, force_load: boolean]): Material
```

> Returns the material object in the specified path.

<Schema title="Parameters">
  <SchemaField name="path" type="string" required>
    Directory to the specified material.
  </SchemaField>

  <SchemaField name="force_load" type="boolean">
    Loads the material if not loaded.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="material" type="Material">
    The material object in the specified path.
  </SchemaField>
</Schema>

## get\_materials

```lua
materials.get_materials(partial_path: string[, force_load: boolean, callback: function]): table
```

> If the callback is `nil`, it returns the table of material objects along the specified path. Otherwise the callback will be called. Access the material object using the arguments of the specified callback.

<Schema title="Parameters">
  <SchemaField name="partial_path" type="string" required>
    Directory to the specified materials.
  </SchemaField>

  <SchemaField name="force_load" type="boolean">
    Loads each material if not loaded.
  </SchemaField>

  <SchemaField name="callback" type="function">
    A callback with a pointer to the material object as the argument.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="materials" type="table">
    The table of material objects along the specified path.
  </SchemaField>
</Schema>

## create

```lua
materials.create(name: strings, key_values: string): Material
```

> Creates and returns a new material object.

<Schema title="Parameters">
  <SchemaField name="name" type="string" required>
    New material name.
  </SchemaField>

  <SchemaField name="key_values" type="string" required>
    New material values.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="material" type="Material">
    The new material object.
  </SchemaField>
</Schema>

### struct `Material`

## get\_name

```lua
material:get_name(): string
```

> Returns the name of the material.

<Schema title="Returns">
  <SchemaField name="name" type="string">
    The name of the material.
  </SchemaField>
</Schema>

## get\_texture\_group\_name

```lua
material:get_texture_group_name(): string
```

> Returns the texture group name of the material.

<Schema title="Returns">
  <SchemaField name="name" type="string">
    The texture group name of the material.
  </SchemaField>
</Schema>

## var\_flag

```lua
material:var_flag(flag: number[, value: boolean]): boolean
```

> Gets or sets the value of the material var flag.

<Schema title="Parameters">
  <SchemaField name="flag" type="number" required>
    Material var flag.
  </SchemaField>

  <SchemaField name="value" type="boolean">
    New material var flag value.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="boolean">
    The value of the material var flag.
  </SchemaField>
</Schema>

## shader\_param

```lua
material:shader_param(name: string[, value: any]): any
```

> Gets or sets the value of the material shader parameter.

<Schema title="Parameters">
  <SchemaField name="name" type="string" required>
    Shader parameter name.
  </SchemaField>

  <SchemaField name="value" type="any">
    New shader parameter value.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="any">
    The value of the material shader parameter.
  </SchemaField>
</Schema>

## color\_modulate

```lua
material:color_modulate([color: color])
```

> Gets or sets the material color modulation value.

<Schema title="Parameters">
  <SchemaField name="color" type="color">
    New color modulation value.
  </SchemaField>
</Schema>

## alpha\_modulate

```lua
material:alpha_modulate([alpha: number])
```

> Gets or sets the material alpha modulation value.

<Schema title="Parameters">
  <SchemaField name="alpha" type="number">
    New alpha modulation value.
  </SchemaField>
</Schema>

## is\_valid

```lua
material:is_valid(): boolean
```

> Returns `true` if the material is valid.

<Schema title="Returns">
  <SchemaField name="value" type="boolean">
    `true` if the material is valid.
  </SchemaField>
</Schema>

## reset

```lua
material:reset()
```

> Resets the material properties to its original values along with discarding the override.

## override

```lua
material:override(mat: Material)
```

> Overrides material properties to properties from another material without setting them.

<Schema title="Parameters">
  <SchemaField name="mat" type="Material" required>
    Material object with the needed properties.
  </SchemaField>
</Schema>
