Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🧱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.

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

1

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.

2

Confirm Model Material is empty

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

NOTE: Do not create a blank material and assign it “to be safe.” An empty override replaces the painted surface with a default.

3

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 and How to set up a light.

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.

1

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.

TIP: Name the file so the map type is obvious, for example T_GrassGround_Albedo.

2

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.

3

Open the material

Select the new material. Its settings appear in the Inspector.

4

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.

5

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.

6

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.

7

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.

8

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.

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.

TIP: Keep colour maps as .png or .jpg on the material. The Asset Compiler compresses them for Play. Do not retarget maps to other extensions by hand. The agent can create materials through Sandbox Studio MCP.

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.

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, or How to Set Up a Skybox if the environment should light those surfaces.

Last updated

Was this helpful?