shaders-and-rendering

name	shaders-and-rendering
description	Use when writing shaders or configuring rendering in Godot 4.x — covers the Godot shading language (GLSL-like), shader types (spatial, canvas_item, particles, sky, fog), vertex and fragment functions, Visual Shader editor, canvas_item shaders for 2D effects, spatial shaders for PBR and custom lighting, particle shaders, uniforms and shader parameters, screen-reading shaders (screen_texture, depth_texture), post-processing, rendering pipelines (Forward+, Mobile, Compatibility), and common shader recipes (dissolve, outline, water, hologram, CRT, blur). Make sure to use this skill whenever writing .gdshader files, creating visual effects, configuring rendering settings, or implementing custom materials in Godot.
version	1.0.1

Shaders & Rendering (Godot 4.x)

Complete reference for Godot 4.x shading language, visual shaders, rendering pipelines, and common shader effects.

When to Use

Use when writing custom shaders, implementing visual effects, configuring rendering pipelines, or optimizing graphics in Godot 4.x.

Prerequisites

• Godot 4.x project.
• Basic understanding of GLSL or Godot shading language.

Procedure

1. Shader Structure

shader_type canvas_item;  // spatial, canvas_item, particles, sky, fog

render_mode unshaded, blend_mix;  // rendering hints

// Uniforms — exposed as shader parameters in the inspector
uniform vec4 tint_color : source_color = vec4(1.0);
uniform float intensity : hint_range(0.0, 2.0) = 1.0;
uniform sampler2D noise_tex : filter_linear, repeat_enable;

// Instance uniforms — different value per instance (MultiMesh, etc.)
instance uniform vec4 instance_color : source_color = vec4(1.0);

// Varyings — pass data from vertex to fragment
varying vec2 world_pos;

void vertex() {
    world_pos = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
}

void fragment() {
    COLOR = texture(TEXTURE, UV) * tint_color * intensity;
}

2. Shader Types

Type	Use	Key Built-ins
canvas_item	2D sprites, UI, particles	UV, COLOR, TEXTURE, VERTEX
spatial	3D meshes, terrain	ALBEDO, METALLIC, ROUGHNESS, EMISSION, NORMAL_MAP
particles	GPU particle behavior	VELOCITY, TRANSFORM, COLOR, CUSTOM, INDEX
sky	Custom sky rendering	EYEDIR, SKY_COORDS, AT_HALF_RES_PASS
fog	Volumetric fog volumes	WORLD_POSITION, OBJECT_POSITION, DENSITY

3. Canvas Item Shaders (2D)

Built-in variables

// vertex():
VERTEX      // vec2 — position in local space
UV          // vec2 — texture coordinates
COLOR       // vec4 — vertex color (from modulate)

// fragment():
UV          // vec2 — interpolated texture coordinates
COLOR       // vec4 — output color (default = TEXTURE * vertex COLOR)
TEXTURE     // sampler2D — the node's texture
TEXTURE_PIXEL_SIZE  // vec2 — 1.0 / texture_size (useful for pixel-neighbor effects)
SCREEN_UV   // vec2 — screen-space UV (for screen-reading effects)
TIME        // float — engine time in seconds

Outline effect

shader_type canvas_item;

uniform vec4 outline_color : source_color = vec4(0.0, 0.0, 0.0, 1.0);
uniform float outline_width : hint_range(0.0, 10.0) = 1.0;

void fragment() {
    vec2 size = TEXTURE_PIXEL_SIZE * outline_width;
    float alpha = texture(TEXTURE, UV).a;

    // Sample 4 neighbors
    alpha = max(alpha, texture(TEXTURE, UV + vec2(size.x, 0.0)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(-size.x, 0.0)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(0.0, size.y)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(0.0, -size.y)).a);

    vec4 original = texture(TEXTURE, UV);
    COLOR = mix(vec4(outline_color.rgb, alpha), original, original.a);
}

Dissolve effect

shader_type canvas_item;

uniform float dissolve_amount : hint_range(0.0, 1.0) = 0.0;
uniform sampler2D noise_texture;
uniform vec4 edge_color : source_color = vec4(1.0, 0.5, 0.0, 1.0);
uniform float edge_width : hint_range(0.0, 0.1) = 0.05;

void fragment() {
    vec4 original = texture(TEXTURE, UV);
    float noise = texture(noise_texture, UV).r;

    if (noise < dissolve_amount) {
        discard;
    }

    float edge = smoothstep(dissolve_amount, dissolve_amount + edge_width, noise);
    COLOR = mix(edge_color, original, edge);
    COLOR.a = original.a;
}

CRT / scanline effect

shader_type canvas_item;

uniform float scanline_intensity : hint_range(0.0, 1.0) = 0.3;
uniform float curvature : hint_range(0.0, 0.1) = 0.02;

void fragment() {
    // Apply barrel distortion (curvature)
    vec2 uv = SCREEN_UV * 2.0 - 1.0;
    uv *= 1.0 + curvature * dot(uv, uv);
    uv = uv * 0.5 + 0.5;

    // Discard pixels outside screen
    if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) {
        COLOR = vec4(0.0);
        return;
    }

    vec4 color = texture(TEXTURE, uv);

    // Scanlines
    float scanline = sin(uv.y * 800.0) * scanline_intensity;
    color.rgb -= scanline;

    COLOR = color;
}

Wave distortion (water surface)

shader_type canvas_item;

uniform float wave_speed : hint_range(0.0, 10.0) = 2.0;
uniform float wave_amplitude : hint_range(0.0, 0.1) = 0.01;
uniform float wave_frequency : hint_range(0.0, 50.0) = 10.0;

void fragment() {
    vec2 uv = UV;
    uv.x += sin(uv.y * wave_frequency + TIME * wave_speed) * wave_amplitude;
    uv.y += cos(uv.x * wave_frequency + TIME * wave_speed) * wave_amplitude * 0.5;
    COLOR = texture(TEXTURE, uv);
}

4. Spatial Shaders (3D)

PBR properties

shader_type spatial;
render_mode cull_back, diffuse_burley, specular_schlick_ggx;

uniform vec4 albedo_color : source_color = vec4(1.0);
uniform sampler2D albedo_tex : source_color;
uniform float metallic : hint_range(0.0, 1.0) = 0.0;
uniform float roughness : hint_range(0.0, 1.0) = 0.5;
uniform sampler2D normal_map : hint_normal;
uniform float normal_strength : hint_range(0.0, 2.0) = 1.0;
uniform vec3 emission_color : source_color = vec3(0.0);
uniform float emission_energy : hint_range(0.0, 16.0) = 0.0;

void fragment() {
    vec4 tex = texture(albedo_tex, UV);
    ALBEDO = tex.rgb * albedo_color.rgb;
    METALLIC = metallic;
    ROUGHNESS = roughness;
    NORMAL_MAP = texture(normal_map, UV).rgb;
    NORMAL_MAP_DEPTH = normal_strength;
    EMISSION = emission_color * emission_energy;
    ALPHA = tex.a * albedo_color.a;
}

Toon/cel shading

shader_type spatial;
render_mode diffuse_toon, specular_toon;

uniform vec4 albedo_color : source_color = vec4(1.0);
uniform sampler2D albedo_tex : source_color;
uniform float shadow_threshold : hint_range(0.0, 1.0) = 0.3;
uniform vec4 shadow_color : source_color = vec4(0.5, 0.3, 0.4, 1.0);

void fragment() {
    ALBEDO = texture(albedo_tex, UV).rgb * albedo_color.rgb;
    ROUGHNESS = 1.0;
    METALLIC = 0.0;
}

void light() {
    float NdotL = dot(NORMAL, LIGHT);
    float stepped = step(shadow_threshold, NdotL);
    DIFFUSE_LIGHT += mix(shadow_color.rgb, ALBEDO, stepped) * ATTENUATION * LIGHT_COLOR;
}

Hologram effect

shader_type spatial;
render_mode cull_disabled, unshaded;

uniform vec4 holo_color : source_color = vec4(0.0, 0.8, 1.0, 0.5);
uniform float scan_speed : hint_range(0.0, 5.0) = 1.0;
uniform float scan_line_count : hint_range(10.0, 200.0) = 50.0;
uniform float flicker_speed : hint_range(0.0, 20.0) = 5.0;

void fragment() {
    float scan = sin(UV.y * scan_line_count + TIME * scan_speed) * 0.5 + 0.5;
    float fresnel = pow(1.0 - abs(dot(NORMAL, VIEW)), 2.0);
    float flicker = sin(TIME * flicker_speed) * 0.1 + 0.9;

    ALBEDO = holo_color.rgb;
    ALPHA = (scan * 0.5 + fresnel * 0.5) * holo_color.a * flicker;
}

5. Particle Shaders

shader_type particles;

uniform float spread : hint_range(0.0, 3.14) = 1.0;
uniform vec3 gravity = vec3(0.0, -9.8, 0.0);
uniform float initial_speed : hint_range(0.0, 100.0) = 10.0;

void start() {
    // Called once when particle spawns
    float angle = (float(INDEX) / float(AMOUNT)) * spread * 2.0 - spread;
    VELOCITY = vec3(sin(angle), cos(angle), 0.0) * initial_speed;
    COLOR = vec4(1.0, 0.5, 0.0, 1.0);
    CUSTOM.x = 0.0;  // custom data per particle
}

void process() {
    // Called every frame for each living particle
    VELOCITY += gravity * DELTA;
    COLOR.a = 1.0 - (CUSTOM.x / LIFETIME);
    CUSTOM.x += DELTA;  // track age
}

6. Uniforms and Shader Parameters

# Set shader parameters from GDScript:
var material: ShaderMaterial = sprite.material as ShaderMaterial
material.set_shader_parameter("dissolve_amount", 0.5)
material.set_shader_parameter("tint_color", Color.RED)

# Animate shader parameters with Tween:
var tween := create_tween()
tween.tween_method(
    func(value: float) -> void:
        material.set_shader_parameter("dissolve_amount", value),
    0.0, 1.0, 2.0  # from, to, duration
)

Uniform hints

Hint	Type	Effect in Inspector
source_color	vec4/vec3	Color picker
hint_range(min, max, step)	float/int	Slider
hint_normal	sampler2D	Marks as normal map
filter_nearest	sampler2D	Nearest-neighbor filtering
filter_linear	sampler2D	Bilinear filtering
repeat_enable	sampler2D	Enable texture tiling

7. Screen-Reading Shaders

shader_type canvas_item;

// Access screen contents (must be behind a transparent object)
uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;

// Blur effect using screen texture:
void fragment() {
    vec2 pixel_size = 1.0 / vec2(textureSize(screen_texture, 0));
    vec4 color = vec4(0.0);
    float total = 0.0;

    for (int x = -2; x <= 2; x++) {
        for (int y = -2; y <= 2; y++) {
            color += texture(screen_texture, SCREEN_UV + vec2(float(x), float(y)) * pixel_size * 2.0);
            total += 1.0;
        }
    }
    COLOR = color / total;
}

3D screen textures

shader_type spatial;

// Available in spatial shaders:
uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;
uniform sampler2D depth_texture : hint_depth_texture;
uniform sampler2D normal_roughness_texture : hint_normal_roughness_texture;

void fragment() {
    // Glass refraction example:
    vec2 ref_uv = SCREEN_UV + NORMAL.xy * 0.02;
    vec3 bg = texture(screen_texture, ref_uv).rgb;
    ALBEDO = bg;
}

8. Post-Processing

Full-screen shader via ColorRect

# Apply post-processing:
# 1. Create a CanvasLayer (layer = 100, to render above everything)
# 2. Add a ColorRect child (full screen via anchors)
# 3. Assign ShaderMaterial with your post-processing shader
# 4. Enable "Use Parent Material" = false

# ColorRect must cover entire viewport:
# Anchor preset: "Full Rect" (all anchors = 0 or 1)

Environment post-processing (3D)

WorldEnvironment provides built-in effects without custom shaders:

Effect	Setting	Description
Glow/Bloom	Environment > Glow	Bright areas bleed light
SSAO	Environment > SSAO	Ambient shadows in crevices
SSR	Environment > SSR	Screen-space reflections
SSIL	Environment > SSIL	Screen-space indirect lighting
Fog	Environment > Volumetric Fog	Atmospheric depth fog
Tonemap	Environment > Tonemap	HDR to LDR conversion
DOF	Camera3D > Attributes > DOF	Depth of field blur
Color correction	Environment > Adjustment	Brightness, contrast, saturation, LUT

9. Rendering Pipelines

Feature	Forward+	Mobile	Compatibility (GL)
Target hardware	Desktop/console	Mobile/mid-range	Low-end/web
SDFGI	✅	❌	❌
VoxelGI	✅	❌	❌
Volumetric fog	✅	❌	❌
SSR	✅	❌	❌
SSAO	✅	❌	❌
Clustered lighting	✅ (unlimited)	Limited (8 per mesh)	Limited (8 per mesh)
Decals	✅	Limited	❌
Screen-space effects	All	Limited	Few
API	Vulkan/D3D12/Metal	Vulkan/D3D12/Metal	OpenGL 3.3/ES 3.0/WebGL2

Choose in Project Settings > Rendering > Renderer > Rendering Method.

10. Visual Shader Editor

Node-based shader creation for non-coders:

• Open via Shader Editor dock when a VisualShader resource is selected
• Key node categories: Input, Output, Scalar, Vector, Color, Texture, Transform, Logic, Math
• Custom Expression node: embed GLSL code inside a visual shader graph
• Convert to text: right-click VisualShader resource > "Convert to ShaderMaterial" for hand-tuning

11. Multi-pass Rendering

# next_pass creates layered shader effects:
# Pass 1: base material (StandardMaterial3D or ShaderMaterial)
# Pass 2: outline effect (via material.next_pass)
# Pass 3: glow overlay (via material.next_pass.next_pass)

var outline_material := ShaderMaterial.new()
outline_material.shader = preload("res://shaders/outline.gdshader")
base_material.next_pass = outline_material

Pitfalls

• if branching in fragment: GPU branch divergence. Use mix(), step(), smoothstep() instead.
• screen_texture everywhere: Forces framebuffer copies. Use only when necessary.
• High-res fullscreen shaders: Kills GPU on mobile. Render at lower resolution in SubViewport.
• Untyped uniforms: No inspector controls. Always add hints (source_color, hint_range).
• Recomputing constants per pixel: Wasted GPU cycles. Precompute in vertex() or pass as uniform.
• render_mode unshaded on lit objects: No lighting. Only for UI, particles, or custom light().

Verification

• shader_type matches the node (canvas_item for 2D, spatial for 3D).
• All uniforms have appropriate hints (source_color, hint_range, etc.).
• Shader parameters set from GDScript use set_shader_parameter().
• Screen-reading shaders use hint_screen_texture.
• Transparent shaders use render_mode with appropriate blend mode.
• No unnecessary branching in fragment functions.
• Visual Shaders consider conversion to text for complex effects.
• Rendering pipeline chosen matches target platform.

Related skills

• 2D visual effects → 2d-development
• 3D environment setup → 3d-development
• Performance optimization → performance-optimization
• Animation effects → animation-system
• GDScript shader parameters → gdscript