Changing a 3D Model's Material in Godot 4: Overrides, GDScript and the Shared-Resource Trap

Godot 4 does not keep a material field on the imported GLB file. The file is read once at import time; after that, the material lives either on the mesh resource inside the project or on the MeshInstance3D node in your scene. Knowing which of those two places you are editing turns a fiddly job into a thirty-second one.

This guide walks through the editor route with Surface Material Override, the runtime route with GDScript, the choice between StandardMaterial3D and ShaderMaterial, and the shared-resource behaviour that makes a single colour change repaint every copy of a model in the level.

Where a Godot 4 model's material actually lives

Import a GLB, glTF or FBX file into a Godot 4 project and the importer builds a Mesh resource. Materials described in the file are kept inside that mesh as surface materials, one per material slot written by the exporter. A MeshInstance3D node that references the mesh can override all of those materials at once or override a single surface, and neither action touches the imported asset.

Three properties decide what you actually see, and they are evaluated in a fixed order. Material Override beats everything else. Surface Material Override for a given index beats that surface's own material. The surface material stored on the mesh is the fallback when no override exists. All three live in the scene or in a .tres resource you save yourself, so the .glb on disk is never rewritten.

The editor route: five steps from imported mesh to new material

1. Select the MeshInstance3D node in the Scene dock, not the root of the imported scene, so the change belongs to this instance and not the source asset.
2. Open the Geometry section of the Inspector. Material Override is a single slot; Surface Material Override is an array whose size you set to the number of surfaces you want to touch.
3. Click the empty slot, choose New StandardMaterial3D, then expand the resource and set Albedo, Metallic, Roughness and the texture slots.
4. Drag the base colour, normal and occlusion-roughness-metallic textures from the FileSystem dock into the matching slots.
5. Save the scene; the override is stored in the scene file, so the rest of the team sees the same result.

Finding the right surface index without guessing

Surface indices are not listed in the Scene dock, so the quickest way to identify one is to assign a bright red StandardMaterial3D to index 0 and step the index upward until the part you care about turns red. A car body exported from Blender often carries three to six surfaces, and the exporter's order decides the numbering, so glass is not reliably index 1. Renaming materials before export helps, because material names travel through glTF into Godot.

StandardMaterial3D or ShaderMaterial: choose by what has to change

StandardMaterial3D is the built-in PBR resource. It compiles to a shader for you and exposes albedo, metallic, roughness, normal, ambient occlusion, emission, transparency and culling as Inspector fields with matching GDScript properties. ShaderMaterial runs code written in Godot's shading language, which is what you need for anything the standard fields cannot express: scrolling UVs on water, triplanar mapping on a scanned mesh, toon ramps, dissolve effects or vertex motion. The standard resource is faster to set up; the shader resource becomes the only option once the effect stops being a surface property.

PBR values that read as real materials

• Metallic behaves almost like a switch: keep it at 0 for wood, skin, plastic, fabric and painted surfaces, and at 1 for bare steel, aluminium and chrome.
• Roughness does most of the work: 0.05–0.15 for polished chrome, 0.3–0.5 for painted metal and varnished wood, 0.7–0.95 for concrete, rubber and unfinished timber.
• Albedo should carry colour only, never lighting. If the base colour texture already contains shadows and you also plug in an ambient occlusion map, the model turns muddy under bright lights.
• Normal strength between roughly 0.5 and 1.5 covers most assets; above 2 the surface looks like embossed plastic.
• Emission needs values above 1 to trigger glow with WorldEnvironment glow enabled; plain white emission lights nothing.

Texture import settings decide whether any of that survives. Godot 4's texture import dock offers 2D, 3D, Normal Map and Detect 3D presets; use 3D for base colour and ORM textures and Normal Map for normal maps, which keeps the green channel handling a normal map needs. If a normal map appears to do nothing, the usual cause is a mesh without tangents, and the glTF import options can generate them (Ensure Tangents in Godot 4.x).

Changing the material from GDScript at runtime

Runtime swaps build damage states, team colours and selection highlights without duplicating whole scenes. The instance-level calls all accept a Material resource, so the pattern is to build the material once, keep a reference, and assign it when the state changes. Two calls cover most cases: material_override for the whole node, and set_surface_override_material with an index for a single part. A value that differs per instance, such as a tint or a flicker phase, can be declared as an instance uniform and set with set_instance_shader_parameter instead of duplicating the material.

1. Build the material in _ready() or as an exported resource, not inside _process(), so resources are not allocated every frame.
2. Assign material_override for a whole-prop swap, or set_surface_override_material(0, mat) when one part differs.
3. Keep the reference you get back, then animate the material's properties directly instead of looking the node up again each frame.
4. Reuse one material across similar objects and vary it through instance shader parameters.

The shared-resource trap, and the three ways out

An imported material is a single resource shared by every node that uses it. Set albedo_color on one enemy and all thirty enemies in the level change colour, because there is only one material behind them. Godot marks that in the Inspector with a small shared-resource indicator next to resources used by more than one node, which confirms the diagnosis before you touch any code.

• Duplicate in code: call duplicate() on the material and assign the copy to the node, the usual approach for damage tinting or a per-enemy colour.
• Turn on Resource > Local to Scene for the material: Godot then makes a copy per scene instance, the tidiest fix for props placed by hand in a level.
• Keep the material shared and vary one value through an instance shader parameter, which costs one material instead of dozens.

The second option deserves a cost warning. Local to Scene duplicates the resource and everything underneath it, so enabling it on a mesh rather than on the material copies vertex data and raises memory use for every instance in the scene. Duplicating a material is cheap because textures stay shared by reference; duplicating a mesh is not. For an asset from an AI generator or a marketplace pack, check how many copies the level places before choosing the per-instance route, and remember that none of these changes are written back into the source file.

Frequently Asked Questions

Run it yourself in Open3DAI

Send the same prompt or image to several engines, compare the meshes side by side, then export GLB, glTF, OBJ, STL, PLY or 3MF. Creating an account grants free credits and needs no card.