> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/the-editor/how-to-set-up-materials.md).

# How to set up materials

Kit art, marketplace packs, and AI-generated `.glb` files already carry their look **inside the file**. Select the Model Mesh Node. If **Model Material** is empty, you are using those packed materials. Leave it empty.

Create a `.material.json` only when you need a new surface: a primitive with no file, or an override on one node.

Lighting still comes from the scene (directional light, point lights, Scene Environment). Packed materials respond to that lighting. An empty **Model Material** does not mean unlit.

There is no Shader asset. A material is the surface. Do not rewrite `.material.json` by hand. Why the dialog may mention THREE: [What Three.js means in Sandbox Studio](/the-editor/what-threejs-means.md).

{% embed url="<https://youtu.be/4DO6IjkjKII?si=RnhiA3YDCdb6K9fg>" %}

## Packed vs override vs authored

| Situation                                                | What to do                                                                             |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Imported or generated `.glb` (building, prop, character) | Leave **Model Material** empty.                                                        |
| Same `.glb`, one copy needs a different look             | Create a material under `assets/materials/`. Set **Model Material** on that node only. |
| Mesh Node with no model (Ground, a test box)             | Create a material and assign it on the mesh.                                           |
| Water, fog cards, slash trails, other engine FX          | Those are custom node materials in TypeScript. Not this page.                          |

On a `.glb`, the Inspector field is **Model Material**. If the model has several slots, you will also see **Model Materials**. Empty means “use the file.” Filling a slot **replaces** that look. The `.glb` on disk does not change.

An empty `assets/materials/` folder is normal on a kitbashed level. Put files you **create** there, named with an `M_` prefix (for example `M_Floor`). Keep images in `assets/textures/`.

## Keep the packed look

{% stepper %}
{% step %}

## Select the model in the scene

Drag a `.glb` into the viewport, or select one already in the Outliner. Its class is `ENGINE.ModelMeshNode`. See [How to use mesh models and ModelMesh nodes](/the-editor/how-to-use-mesh-models-and-modelmesh.md).
{% endstep %}

{% step %}

## Confirm Model Material is empty

In the Inspector, **Model Material** should be empty. That is the packed look from the file.

{% hint style="info" %}
*NOTE: Do not create a blank material and assign it “to be safe.” An empty override replaces the painted surface with a default.*
{% endhint %}
{% endstep %}

{% step %}

## Light the surface from the scene

Turn **Cast Shadow** and **Receive Shadow** on when the model should take part in lighting. Aim the directional light by rotating it. See [How to use shadow](/the-editor/how-to-use-shadow.md) and [How to set up a light](/the-editor/how-to-set-up-a-light.md).
{% endstep %}
{% endstepper %}

## Override the look on one node

Use this when the packed materials are wrong for that copy, or you want every object that shares one `.material.json` to update together.

{% stepper %}
{% step %}

## Add the texture to the project

In the Asset panel, open or create `textures/`, then add your image. A PNG works well for a colour texture.

{% hint style="info" %}
*TIP: Name the file so the map type is obvious, for example `T_GrassGround_Albedo`.*
{% endhint %}
{% endstep %}

{% step %}

## Create a material

Open or create `materials/` in the Asset panel. Right-click an empty area, select New Asset, then Material. Name it something like `M_Floor`, then select Create Material.

If the dialog asks for a type, choose **Mesh Standard Node Material** for a normal lit surface (metal and roughness). Other types (basic, physical, dissolve, and similar) are still materials; this walkthrough uses Standard.
{% endstep %}

{% step %}

## Open the material

Select the new material. Its settings appear in the Inspector.
{% endstep %}

{% step %}

## Assign the colour texture

Set **Color map path** to the PNG you imported. **Diffuse color** tints that image. With no map, Diffuse color is the whole surface.
{% endstep %}

{% step %}

## Assign extra maps if you have them

Use the matching slot for each image: roughness, metalness, normal, bump, and so on. A normal map in the colour slot will look wrong.

You do not need every slot. Colour plus roughness and metalness is enough for many surfaces.
{% endstep %}

{% step %}

## Adjust the surface

Watch the preview and the mesh in the scene while you change values.

**Roughness** — matte vs polished. Higher is more matte.

**Metalness** — use this for metal, not as a generic shine control.

**Diffuse color** — overall tint.

**Bump scale** — how strong a bump map looks.

If the surface should be see-through, turn **Transparent** on and lower **Opacity**.
{% endstep %}

{% step %}

## Set Model Material on the node

Select the Model Mesh Node. Set **Model Material** to the file you created, for example `@project/assets/materials/M_Floor.material.json`.

Other nodes that still have an empty **Model Material** keep the packed look.

If several copies should share the override, point them at the same `.material.json`. Duplicate the material file if one copy needs a different look.
{% endstep %}

{% step %}

## Refine the material, not a one-off on the mesh

Change the **material** in the Asset panel. Save with `Ctrl+S` / `Cmd+S`. Every node using that file updates.
{% endstep %}
{% endstepper %}

## Author a material on a Mesh Node

A Mesh Node (Ground, a box from the primitives panel) has no `.glb` and no packed materials.

Create the material as in the override steps. Select the mesh. In the Inspector, open the material field and choose the material.

{% hint style="info" %}
*TIP: Keep colour maps as `.png` or `.jpg` on the material. The* [*Asset Compiler*](/the-editor/how-to-use-asset-compiler.md) *compresses them for Play. Do not retarget maps to other extensions by hand. The agent can create materials through* [*Sandbox Studio MCP*](/working-efficiently-with-ai/set-up-and-use-sandbox-studio-mcp.md)*.*
{% endhint %}

## Common mistakes

| What went wrong                                            | What to do                                                                                                         |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Assigned a new material and the kit mesh went grey or flat | Clear **Model Material** so the packed look returns.                                                               |
| Looked for Shader in New Resource                          | Create **New Asset → Material**.                                                                                   |
| Expected the material to light the scene                   | Lights and Scene Environment light the surface. See [How to set up a light](/the-editor/how-to-set-up-a-light.md). |
| Assigned one `.material.json` and every copy changed       | They share the file. Duplicate it for a one-off look.                                                              |
| Hand-edited `.material.json`                               | Use the Inspector on the material asset.                                                                           |

## What You've Done

You can leave packed `.glb` materials alone, override **Model Material** when one node needs a new surface, and author a material on a Mesh Node. Next: [How to set up a light](/the-editor/how-to-set-up-a-light.md), or [How to Set Up a Skybox](/the-editor/how-to-set-up-a-skybox.md) if the environment should light those surfaces.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/the-editor/how-to-set-up-materials.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.