Godot Shaders (4.x)
Write .gdshader files in the Godot Shading Language, wire them to materials, and prove
they compile. Targets Godot 4.7 (see Version notes). The effect technique (the maths
of a dissolve, outline, toon ramp) lives in shader-programming; this skill covers
Godot's syntax, built-ins and pipeline.
When to use
- Writing or porting
.gdshadercode, fixing aSHADER ERROR, wiring aShaderMaterial, picking render modes, or setting uniforms from code.
When not to use: cross-engine shading technique → shader-programming;
StandardMaterial3D, lights and environment → godot-3d-essentials. GPUParticles
node properties (as opposed to a particles shader) are outside this skill.
Core workflow
Pick the shader type on the first line:
shader_type canvas_item;for anythingCanvasItem(Sprite2D, TextureRect, Control) orshader_type spatial;for 3D meshes.particles,skyandfogexist too.Write the output the type expects:
COLORincanvas_item;ALBEDO,EMISSION,ROUGHNESS,METALLICinspatial.vertex()moves geometry;light()replaces lighting.Expose tunables as
uniforms with hints (source_colorfor colors,hint_rangefor sliders) so they show in the Inspector and are color-managed.Wire the material. In a
.tscnthis is plain text, so no Inspector clicks are needed:[ext_resource type="Shader" path="res://fx/scroll.gdshader" id="1_fx"] [sub_resource type="ShaderMaterial" id="ShaderMaterial_fx"] shader = ExtResource("1_fx") shader_parameter/scroll_speed = 0.5 [node name="Water" type="Sprite2D" parent="."] material = SubResource("ShaderMaterial_fx")From code:
material.set_shader_parameter("scroll_speed", 0.5).Check before you finish.
Compile every shader headless with Pattern 4, then grep the log:
godot --headless --path . --script res://tests/compile_shaders.gd > shaders.log 2>&1 grep -nE "SHADER ERROR|Shader compilation failed" shaders.log # no output = passHeadless uses a dummy renderer that still runs Godot's shader compiler, so syntax, unknown built-ins, wrong output variables and bad hints all show up. It does not run the GPU driver, so ask the user to open the scene with the project's renderer (Forward+, Mobile or Compatibility) and report how it looks and any errors in the Output panel.
If you wired a material in a
.tscn, also run thegodot-nodes-scenesskill'sscripts/check_godot_project.py <project-dir>to confirm theext_resourcepath.With no Godot binary (
godot,godot4or$GODOT_BIN), ask the user to run the command above and pasteshaders.log.
Patterns
1. canvas_item: tint and scrolling UV
shader_type canvas_item;
uniform vec4 tint : source_color = vec4(1.0);
uniform float scroll_speed : hint_range(0.0, 2.0) = 0.3;
void fragment() {
vec2 uv = UV + vec2(TIME * scroll_speed, 0.0);
COLOR = texture(TEXTURE, uv) * tint; // TEXTURE = the node's own texture
}The node's texture must repeat for the scroll to wrap: set texture_repeat on the
CanvasItem, or sample your own uniform sampler2D tex : repeat_enable;.
2. spatial: emissive rim on an opaque material
shader_type spatial;
uniform vec4 base_color : source_color = vec4(0.2, 0.5, 1.0, 1.0);
uniform vec3 rim_color : source_color = vec3(0.6, 0.8, 1.0);
uniform float rim_power : hint_range(0.5, 8.0) = 3.0;
void fragment() {
ALBEDO = base_color.rgb;
float rim = pow(1.0 - clamp(dot(NORMAL, VIEW), 0.0, 1.0), rim_power); // view space
EMISSION = rim_color * rim; // no ALPHA write: stays opaque
}3. Screen-reading post effect (4.x hint, not SCREEN_TEXTURE)
shader_type canvas_item;
uniform sampler2D screen_tex : hint_screen_texture, filter_linear_mipmap;
uniform float blur : hint_range(0.0, 4.0) = 1.0;
void fragment() {
vec2 px = SCREEN_PIXEL_SIZE * blur;
vec4 c = texture(screen_tex, SCREEN_UV);
c += texture(screen_tex, SCREEN_UV + vec2(px.x, 0.0));
c += texture(screen_tex, SCREEN_UV - vec2(px.x, 0.0));
COLOR = c / 3.0;
}4. Headless compile check for every .gdshader
# res://tests/compile_shaders.gd
extends SceneTree
func _initialize() -> void:
var paths := _find("res://", "gdshader")
for path in paths:
print("compiling ", path) # a SHADER ERROR prints right after this
var shader := load(path) as Shader
shader.get_shader_uniform_list() # forces the compile; load() alone is lazy
print("Compiled %d shaders" % paths.size())
quit(0)
func _find(dir: String, ext: String) -> PackedStringArray:
var found := PackedStringArray()
for file in DirAccess.get_files_at(dir):
if file.get_extension() == ext:
found.append(dir.path_join(file))
for sub in DirAccess.get_directories_at(dir):
if not sub.begins_with("."): # skips .godot/ and other hidden folders
found.append_array(_find(dir.path_join(sub), ext))
return foundShaders embedded in a .tscn ([sub_resource type="Shader"]) are not files; cover them
by smoke-running that scene (--scene res://... --quit-after 10) and grepping the same way.
Gotchas
- 3.x → 4.x renames.
SCREEN_TEXTUREandDEPTH_TEXTUREare removed; declareuniform sampler2D x : hint_screen_texture;(orhint_depth_texture) and sample withSCREEN_UV. Forward+ also offershint_normal_roughness_texture.hint_color/hint_albedo→source_color;hint_white/hint_black→hint_default_white/hint_default_black. Incanvas_itemvertex(), 3.x'sMODELVIEW_MATRIXis nowMODEL_MATRIX/CANVAS_MATRIX/SCREEN_MATRIX. - Wrong output variable. In a spatial
fragment(),COLORis the read-only vertex color, so assigning to it is a compile error; writeALBEDO. - Color uniforms without
source_colorare treated as raw linear values and look washed out or dark. - Object drawn in the wrong order, casts no shadow, or skips SSAO (3D) → the spatial
shader reads or writes
ALPHA, which moves the whole material to the transparent pipeline even if the value is always1.0. For hard cut-outs setALPHA_SCISSOR_THRESHOLD, which stays in the opaque pass. - Sampling outside [0,1] UV clamps unless the sampler uniform has
repeat_enable(or, forTEXTURE, the node'stexture_repeatis on). - Effect jumps once an hour →
TIMEwraps atrendering/limits/time/time_rollover_secs(3600 by default). Pick periods that divide the rollover, or feed your own time uniform. load()alone does not compile a shader. TheShadercreates its GPU-side object on first use, which is why Pattern 4 callsget_shader_uniform_list().discardbreaks early depth testing and costs more on some GPUs; prefer alpha where the blend mode allows.
References
- Read
references/shading-language.mdwhen you need the built-ins per shader type, render-mode names, sampler filter/repeat qualifiers,varying,vertex()displacement, a customlight()function, 2D normal maps, or performance rules.
Related skills
shader-programmingfor the effect technique (dissolve, outline, fresnel, vignette).godot-3d-essentialsfor materials, environment and where spatial shaders live.godot-ui-controlfor applying shaders to UI.godot-gdscript-headless-testingto run Pattern 4 in CI.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
- The headless (dummy) renderer compiles shaders with the engine's shader compiler and
prints
SHADER ERROR:lines; aShaderresource compiles lazily on first use. - The render modes and built-ins listed in the reference exist in 4.7.2's
shader_types.cpp.
Sources: dummy material_storage.cpp @ 4.7.2-stable, shader.cpp @ 4.7.2-stable, shader_types.cpp @ 4.7.2-stable, Shading language, Upgrading from Godot 3 to 4.