Material Editor

The Material Editor is where you decide how a surface looks — its color, how shiny or rough it is, whether it glows. Instead of typing code, you connect little boxes called nodes together, and the editor turns that into a real, fast material on your mesh.

Opening the editor

Switch to the Materials workspace in the editor, then pick what you want to edit:

• Click a mesh in the viewport. Its material loads straight into the graph, ready to tweak.
• Or double-click a .material file in the asset browser to open it on its own tab.

Your changes save automatically as you work, and the mesh updates live so you can see the result right away. There's also an Apply button in the panel toolbar if you want to force a save.

Materials are saved as .material files (plain JSON). When you import a 3D model, every material on it is written out as a .material next to the model automatically — so you can open and edit any imported look as a node graph.

The node graph

You build a material by dragging nodes out of the category menu and wiring them together: drag from a node's output dot (on its right edge) into another node's input dot (on its left edge). Anything you leave unconnected just uses the value typed into the node.

In the shot above, a color texture feeds the Base Color pin, another texture drives Metallic and Roughness, and a normal map plugs into Normal — all flowing into the Surface Output node on the right. That output node is the heart of every material.

Adding nodes: right-click the graph (or press Spacebar with the cursor over it) to open a searchable palette at the cursor — type to filter, Enter picks the first match — and the node spawns where you clicked. The toolbar Add Node button opens the same palette. You can also drag a cable off a pin and release on empty space: the palette opens and the node you pick is auto-wired to that pin.

Dropping a texture: drag an image straight from the Assets browser onto the graph and release — a Sample Texture node appears under the cursor with that image already bound, ready to wire into a pin. Drop several images at once and you get one node per image, cascaded so they don't stack exactly on top of each other.

Switching a sample's type: every 2D texture-sample node carries a small caret button in its header. Click it to pick a different sampling mode for the same image — Sample Texture, Sample Normal Map, Sample Texture LOD, or Sample Texture Grad — without re-dropping it. The bound image is kept; any wires to pins the new mode doesn't have are dropped. (The rest of the header stays a drag handle for moving the node.) The switcher stays within plain-2D modes; array, 3D, and cubemap samples need a matching texture, so add those from the palette.

Comments / groups: select some nodes and press C to wrap them in a labelled comment box. Dragging the box moves every node inside it; drag the corner grip to resize, edit the header to rename, and ✕ deletes the box (keeping its nodes). Comments are visual only and saved in the .material file.

The Surface Output node

The Surface Output node is what shows up on your mesh. The pins you'll reach for most often are:

• Base Color — the main color or texture.
• Metallic — usually 0 for non-metal, 1 for metal.
• Roughness — 0 is mirror-smooth, 1 is fully matte.
• Normal — plug in a normal map for surface bumps and detail.
• Emissive — makes a surface glow (great for screens, lava, neon).

A minimal material only needs Base Color — everything you leave unplugged just keeps its sensible default. There are more advanced pins too (clearcoat for car paint, transmission for glass and water, anisotropy for brushed metal), all listed in the Material API reference.

Nodes you can wire in

There are around 150 node types, grouped into friendly categories. You don't need to learn them all — here's the shape of what's available:

• Input — UVs, time, world position, vertex colors.
• Texture — sample an image, a normal map, or do triplanar projection.
• Math & Vector — add, multiply, blend (lerp), and other building blocks.
• Color — palettes, fresnel rim glow, hue shifts, blends.
• Procedural — noise, checkerboard, brick, and other patterns with no texture needed.
• Animation — scroll UVs, wind sway, flipbook frames.

For the complete catalog — every node, with its inputs, outputs, and what it does — see the Material Node Reference.

Material types (domains)

Every material has a domain that decides what it's for. Pick this when you create a new graph:

Domain	Use it for
Surface (default)	Normal props, walls, characters — standard PBR
Terrain Layer	A paintable layer on terrain
Vegetation	Surfaces that sway in the wind (grass, leaves)
Unlit	Flat color with no lighting (UI bits, effects)

Two more switches live on the material itself, not on a node:

• Alpha mode — Opaque (default), Mask for cut-out edges like leaves and fences, or Blend for see-through glass and smoke.
• Double sided — render the back faces too, handy for thin surfaces like paper or foliage.

Putting a material on an object

Select the object, open the Inspector, and use the Material card to point it at a .material file. To swap an object to a different material later, just change that reference — there's no runtime "swap material" command in scripts.

Reusing one look in many flavors (instances)

Often you want lots of materials that share the same setup but differ in a couple of values — say the same wood shader in five different stains. That's what material instances are for.

You author named Parameter nodes (like BaseColor or Roughness) on a master material, then create instances that only override those named values. Every instance reuses the master's compiled shader, which keeps things fast.

{
  "master": "models/Wood/materials/Wood.material",
  "overrides": {
    "BaseColor": { "Color": [0.45, 0.22, 0.10, 1.0] },
    "Roughness": { "Float": 0.85 }
  }
}

You'll usually set these up visually in the editor rather than by hand. See the Material API reference for the full instance and .material file format.

Textures: which image files work

Texture nodes point at an image on disk. Stick to these formats so they load correctly in your game:

• Loads at runtime: PNG, JPEG, HDR.
• Don't ship these as textures: BMP, TGA, WebP, KTX2, DDS, and especially EXR — they won't decode in the running game.

Changing color from a script

If you just need to tint a material at runtime, Lua can recolor the base color of the object the script is attached to:

function on_update()
    -- RGBA in 0.0-1.0; alpha is optional (defaults to 1.0)
    set_material_color(1.0, 0.0, 0.0, 1.0)
end

set_material_color is Lua-only and only changes base color on the script's own entity. For anything richer — animated patterns, glows that react to gameplay — build it in the node graph with Parameter nodes and material instances. See the Scripting overview for what scripts can do.

Previewing your material

The Preview panel renders your material on a test shape with an orbit camera — drag to rotate, right-drag to pan, scroll to zoom. Its toolbar gives you:

• Shape selector — swap between sphere, cube, cylinder, torus, and plane.
• Auto-rotate — spin the shape slowly so you can judge it from every angle.
• Background — flip the flat backdrop between dark and light.
• Backdrop — a switch that turns on a built-in HDRI environment. With it on, the preview shows a real outdoor sky behind the shape and lights the material with image-based reflections — the quickest way to see how metal, glass, or glossy surfaces actually catch the light. Turn it off to fall back to the plain dark/light background.

The HDRI is built into the editor, so the backdrop works in any project with nothing to set up.

Tips

• Keep roughness above ~0.05. Perfectly smooth surfaces can sparkle with artifacts.
• Metallic is usually 0 or 1. In-between values are rarely realistic.
• Reuse materials and instances. Objects sharing a material draw faster, and instances of one master share a single compiled shader.
• Keep graphs simple when you can. A plain texture-plus-color material runs on the engine's fast path; heavy procedural nodes are a little more expensive.