Fix: Godot 4 Shader Uniform Not Updating at Runtime

You write $Sprite2D.material.set_shader_parameter("tint", Color.RED). Sprite stays unchanged. Or every instance turns red because they all share the same resource. Both are fixable with a single duplicate call.

The Symptom

set_shader_parameter returns nothing, the inspector shows the new value if you select the resource, but the rendered output is unchanged. Or one set_shader_parameter call changes every instance of the same scene at once.

What Causes This

ShaderMaterial is a Resource. By default, when you author a sprite scene with a shader material, every instance of that scene shares the same Resource. Calling set_shader_parameter on it affects all instances. If you saved the resource as an .tres file shared across scenes, every node referencing it sees the change.

Conversely, if you grab the wrong material reference (Sprite2D’s material vs. its parent CanvasItem’s material_override), set_shader_parameter touches a material the renderer is not using.

The Fix: Per-Instance Material

extends Sprite2D

func _ready() -> void:
    # Make this sprite's material unique to this instance
    material = material.duplicate()

func set_tint(c: Color) -> void:
    material.set_shader_parameter("tint", c)

The duplicate produces a new ShaderMaterial referencing the same Shader. Subsequent set_shader_parameter calls now affect only this instance.

Type Matching

The mapping must be exact:

shader uniform     -> GDScript value
float              -> float (1.0, not 1)
int                -> int
vec2               -> Vector2
vec3               -> Vector3 or Color
vec4               -> Vector4 or Color or Quaternion
sampler2D          -> Texture2D
sampler2DArray     -> Texture2DArray
mat4               -> Transform3D or Projection

Passing a wrong type silently keeps the old value. Watch the editor output panel: in some cases Godot prints a warning, but not always.

Imported Scene Caveat

For glTF/FBX imports, materials are imported as part of the scene’s import resource. Editing them at runtime via the imported MeshInstance3D’s surface_material_override is the right hook:

var mat := mesh_instance.get_surface_override_material(0)
if mat == null:
    mat = mesh_instance.mesh.surface_get_material(0).duplicate()
    mesh_instance.set_surface_override_material(0, mat)
mat.set_shader_parameter("emission", Color.RED)

Verifying

Editor → Project Run with the scene live. Select the node in Remote tree. The Inspector shows live shader parameter values. Trigger your code; values should update there. If they don’t, you’re editing a different material reference than you think.

“Duplicate the material on _ready. Match types exactly. Edit the override, not the resource.”

Related Issues

For shader compile errors, see shader compile errors. For sampler2D not loading, see texture uniform.

Duplicate. Match types. Override on instances. Pixels respond.