Godot Shaders (4.x)
Write canvas_item (2D) and spatial (3D) shaders in the Godot Shading Language, animate
with TIME/UV, expose uniforms, and read the screen. Targets Godot 4.7.
When to use
- Use when writing
.gdshader code or a ShaderMaterial: 2D effects (outline, dissolve,
flash, water), 3D surface shaders (rim light, toon, scrolling UV), or screen-space
post effects.
When not to use: the cross-engine concepts of shading (UVs, vertex/fragment
theory) → shader-programming; particles/VFX nodes → general 3D; non-shader visuals.
Core workflow
- Pick the shader type on the first line:
shader_type canvas_item; for 2D
(Sprite2D, TextureRect, anything CanvasItem) or shader_type spatial; for 3D
materials. (particles, sky, fog also exist.)
- Attach via a
ShaderMaterial. Create a ShaderMaterial, assign your .gdshader,
and put it on the node's material. Uniforms appear in the Inspector.
- Write
fragment() to set the output: COLOR (2D) or ALBEDO/EMISSION/ALPHA
(3D). Optionally vertex() to move geometry and light() for custom lighting.
- Expose tunables as
uniforms with hints (source_color, hint_range) so they are
editable and correctly color-managed.
- Animate with the built-in
TIME and sample textures with texture(tex, UV).
- Set uniforms from code with
material.set_shader_parameter("name", value).
Patterns
1. 2D (canvas_item): tint + scrolling UV
shader_type canvas_item;
uniform vec4 tint : source_color = vec4(1.0); // source_color = sRGB-correct color
uniform float scroll_speed : hint_range(0.0, 2.0) = 0.3;
void fragment() {
vec2 uv = UV;
uv.x += TIME * scroll_speed; // scroll horizontally over time
COLOR = texture(TEXTURE, uv) * tint; // TEXTURE = the node's texture
}
2. 2D dissolve using a noise threshold
shader_type canvas_item;
uniform sampler2D noise : repeat_enable; // a NoiseTexture2D
uniform float amount : hint_range(0.0, 1.0) = 0.0;
void fragment() {
vec4 tex = texture(TEXTURE, UV);
float n = texture(noise, UV).r;
if (n < amount) {
discard; // cut the pixel away
}
COLOR = tex;
}
3. 3D (spatial): emissive rim light
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;
// VIEW and NORMAL are view-space built-ins; rim is strong at grazing angles.
float rim = pow(1.0 - dot(NORMAL, VIEW), rim_power);
EMISSION = rim_color * rim;
}
4. Screen-reading post effect (4.x hint, not SCREEN_TEXTURE)
shader_type canvas_item;
// 4.x: declare the screen as a uniform with hint_screen_texture.
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;
}
Set a uniform from GDScript:
$Sprite2D.material.set_shader_parameter("amount", 0.7)
Pitfalls
- 3.x → 4.x renames.
SCREEN_TEXTURE is removed — declare
uniform sampler2D x : hint_screen_texture; and sample with SCREEN_UV. Color hints
hint_color/hint_albedo→source_color; hint_white/hint_black→
hint_default_white/hint_default_black; hint_range stays. Depth/normal use hint_depth_texture / hint_normal_roughness_texture.
- Wrong output variable. In
canvas_item write COLOR; in spatial write ALBEDO
(and EMISSION, ALPHA, ROUGHNESS, METALLIC). Writing COLOR in a spatial shader
does nothing.
- Color uniforms without
source_color are treated as raw linear values and look
wrong (washed/dark) because Godot won't sRGB-convert them.
- 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 always 1.0. Don't touch ALPHA in opaque shaders; for
hard cut-outs also set ALPHA_SCISSOR_THRESHOLD (alpha-scissor stays in the opaque pass).
- Sampling outside [0,1] UV without
repeat_enable clamps. Add : repeat_enable to
the sampler uniform for tiling/scroll.
- Effect jumps once an hour →
TIME (seconds since start, affected by time_scale, not
by pausing) wraps every rendering/limits/time/time_rollover_secs (3600 by default).
Pick periods that divide the rollover, or feed your own time through a uniform.
discard is costly on some hardware and breaks early-Z; prefer setting ALPHA/
COLOR.a when you can.
References
- For built-in variables per shader type, render modes,
varying, custom light(),
vertex() displacement, and the visual shader graph, read
references/shading-language.md.
Related skills
shader-programming — engine-agnostic shader concepts (GLSL/HLSL).
godot-3d-essentials — materials, environment, and where spatial shaders live.
godot-ui-control — applying shaders to UI for effects.
1---2name: godot-shaders3description: >4 Write Godot 4.7 shaders in the Godot Shading Language: canvas_item shaders for 2D5 and spatial shaders for 3D, with vertex/fragment functions, uniforms (source_color,6 hint_range), TIME/UV animation, and screen-reading via hint_screen_texture. Use7 when authoring .gdshader files, writing fragment/vertex code, making 2D/3D visual8 effects, or porting 3.x shaders (SCREEN_TEXTURE, hint_color) to 4.x.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-shaders11---1213# Godot Shaders (4.x)1415Write `canvas_item` (2D) and `spatial` (3D) shaders in the Godot Shading Language, animate16with `TIME`/`UV`, expose `uniform`s, and read the screen. Targets **Godot 4.7**.1718## When to use1920- Use when writing `.gdshader` code or a `ShaderMaterial`: 2D effects (outline, dissolve,21 flash, water), 3D surface shaders (rim light, toon, scrolling UV), or screen-space22 post effects.2324**When *not* to use:** the cross-engine *concepts* of shading (UVs, vertex/fragment25theory) → `shader-programming`; particles/VFX nodes → general 3D; non-shader visuals.2627## Core workflow28291. **Pick the shader type** on the first line: `shader_type canvas_item;` for 2D30 (Sprite2D, TextureRect, anything `CanvasItem`) or `shader_type spatial;` for 3D31 materials. (`particles`, `sky`, `fog` also exist.)322. **Attach via a `ShaderMaterial`.** Create a `ShaderMaterial`, assign your `.gdshader`,33 and put it on the node's `material`. Uniforms appear in the Inspector.343. **Write `fragment()`** to set the output: `COLOR` (2D) or `ALBEDO`/`EMISSION`/`ALPHA`35 (3D). Optionally `vertex()` to move geometry and `light()` for custom lighting.364. **Expose tunables as `uniform`s** with hints (`source_color`, `hint_range`) so they are37 editable and correctly color-managed.385. **Animate with the built-in `TIME`** and sample textures with `texture(tex, UV)`.396. **Set uniforms from code** with `material.set_shader_parameter("name", value)`.4041## Patterns4243### 1. 2D (canvas_item): tint + scrolling UV4445```glsl46shader_type canvas_item;4748uniform vec4 tint : source_color = vec4(1.0); // source_color = sRGB-correct color49uniform float scroll_speed : hint_range(0.0, 2.0) = 0.3;5051void fragment() {52 vec2 uv = UV;53 uv.x += TIME * scroll_speed; // scroll horizontally over time54 COLOR = texture(TEXTURE, uv) * tint; // TEXTURE = the node's texture55}56```5758### 2. 2D dissolve using a noise threshold5960```glsl61shader_type canvas_item;6263uniform sampler2D noise : repeat_enable; // a NoiseTexture2D64uniform float amount : hint_range(0.0, 1.0) = 0.0;6566void fragment() {67 vec4 tex = texture(TEXTURE, UV);68 float n = texture(noise, UV).r;69 if (n < amount) {70 discard; // cut the pixel away71 }72 COLOR = tex;73}74```7576### 3. 3D (spatial): emissive rim light7778```glsl79shader_type spatial;8081uniform vec4 base_color : source_color = vec4(0.2, 0.5, 1.0, 1.0);82uniform vec3 rim_color : source_color = vec3(0.6, 0.8, 1.0);83uniform float rim_power : hint_range(0.5, 8.0) = 3.0;8485void fragment() {86 ALBEDO = base_color.rgb;87 // VIEW and NORMAL are view-space built-ins; rim is strong at grazing angles.88 float rim = pow(1.0 - dot(NORMAL, VIEW), rim_power);89 EMISSION = rim_color * rim;90}91```9293### 4. Screen-reading post effect (4.x hint, not SCREEN_TEXTURE)9495```glsl96shader_type canvas_item;9798// 4.x: declare the screen as a uniform with hint_screen_texture.99uniform sampler2D screen_tex : hint_screen_texture, filter_linear_mipmap;100uniform float blur : hint_range(0.0, 4.0) = 1.0;101102void fragment() {103 vec2 px = SCREEN_PIXEL_SIZE * blur;104 vec4 c = texture(screen_tex, SCREEN_UV);105 c += texture(screen_tex, SCREEN_UV + vec2(px.x, 0.0));106 c += texture(screen_tex, SCREEN_UV - vec2(px.x, 0.0));107 COLOR = c / 3.0;108}109```110111Set a uniform from GDScript:112113```gdscript114$Sprite2D.material.set_shader_parameter("amount", 0.7)115```116117## Pitfalls118119- **3.x → 4.x renames.** `SCREEN_TEXTURE` is removed — declare120 `uniform sampler2D x : hint_screen_texture;` and sample with `SCREEN_UV`. Color hints121 `hint_color`/`hint_albedo`→`source_color`; `hint_white`/`hint_black`→122 `hint_default_white`/`hint_default_black`; `hint_range` stays. Depth/normal use `hint_depth_texture` / `hint_normal_roughness_texture`.123- **Wrong output variable.** In `canvas_item` write `COLOR`; in `spatial` write `ALBEDO`124 (and `EMISSION`, `ALPHA`, `ROUGHNESS`, `METALLIC`). Writing `COLOR` in a spatial shader125 does nothing.126- **Color uniforms without `source_color`** are treated as raw linear values and look127 wrong (washed/dark) because Godot won't sRGB-convert them.128- **Object drawn in the wrong order, casts no shadow, or skips SSAO (3D)** → the spatial129 shader reads or writes `ALPHA`, which moves the whole material to the transparent130 pipeline even if the value is always `1.0`. Don't touch `ALPHA` in opaque shaders; for131 hard cut-outs also set `ALPHA_SCISSOR_THRESHOLD` (alpha-scissor stays in the opaque pass).132- **Sampling outside [0,1] UV** without `repeat_enable` clamps. Add `: repeat_enable` to133 the sampler uniform for tiling/scroll.134- **Effect jumps once an hour** → `TIME` (seconds since start, affected by `time_scale`, not135 by pausing) wraps every `rendering/limits/time/time_rollover_secs` (3600 by default).136 Pick periods that divide the rollover, or feed your own time through a uniform.137- **`discard` is costly** on some hardware and breaks early-Z; prefer setting `ALPHA`/138 `COLOR.a` when you can.139140## References141142- For built-in variables per shader type, render modes, `varying`, custom `light()`,143 `vertex()` displacement, and the visual shader graph, read144 `references/shading-language.md`.145146## Related skills147148- `shader-programming` — engine-agnostic shader concepts (GLSL/HLSL).149- `godot-3d-essentials` — materials, environment, and where spatial shaders live.150- `godot-ui-control` — applying shaders to UI for effects.