Godot 4.x Shader Development

Godot 4.x (baseline: 4.6) GDSL shaders. Three shader types: spatial (3D), canvas_item (2D/UI), particles (GPU particles). This skill is for a hobbyist developer; prefer built-in variables and render modes over custom implementations where they exist.

References

Shader Types

light() note: Defining light() overrides Godot's entire lighting pipeline. You must compute diffuse, specular, and any rim/fresnel manually. Built-in fragment() outputs like RIM and RIM_TINT are silently ignored when light() is defined.

Particles note: start() runs once on spawn; process() runs every frame. TRANSFORM, COLOR, CUSTOM, and USERDATA1–6 persist across frames — particle state accumulates naturally.

GDSL Essentials

Most-used built-ins across all shader types. For the full tables, see gdsl-reference.md.

Spatial — fragment() outputs (write to these)

Spatial — inputs available in fragment()

Spatial — vertex() key built-ins

Canvas Item — fragment() key built-ins

Coordinate Spaces

Object space → [MODEL_MATRIX] → World space → [VIEW_MATRIX] → View space → [PROJECTION_MATRIX] → Clip space → [÷W] → NDC → Screen

Key rule: light() receives NORMAL in view space. To get world-space normal: (INV_VIEW_MATRIX * vec4(NORMAL, 0.0)).xyz

Matrix multiplication order: Always MATRIX * vector, never vector * MATRIX. These produce different results for non-symmetric matrices.

Example Shaders

1. Spatial — Lambert Diffuse + Blinn-Phong Specular

Custom lighting in light(). Reads albedo texture, computes diffuse and specular manually.

shader_type spatial;
render_mode ambient_light_disabled;  // isolate custom lighting

uniform sampler2D _MainTex : source_color;
uniform float _Shininess : hint_range(1.0, 256.0, 1.0) = 64.0;

// Helper functions — place in a .gdshaderinc for reuse
float lambert(vec3 n, vec3 l, float attenuation) {
    return max(0.0, dot(n, l)) * attenuation;
}

float blinn_phong(vec3 n, vec3 l, vec3 v, float shininess) {
    vec3 h = normalize(l + v);                       // halfway vector
    float s = pow(max(0.0, dot(n, h)), shininess);
    s *= float(dot(n, l) > 0.0);                    // no specular in shadow
    return s;
}

void fragment() {
    ALBEDO = texture(_MainTex, UV).rgb;
    ROUGHNESS = 0.5;
}

void light() {
    // light() runs once per light per fragment, after fragment()
    // DIFFUSE_LIGHT and SPECULAR_LIGHT accumulate across lights — use +=
    float d = lambert(NORMAL, LIGHT, ATTENUATION);
    float s = blinn_phong(NORMAL, LIGHT, VIEW, _Shininess);

    DIFFUSE_LIGHT  += vec3(d) * ALBEDO;  // ALBEDO is readable in light()
    SPECULAR_LIGHT += vec3(s);
}

2. Canvas Item — Scrolling UV Distortion

2D post-processing effect: reads the screen texture and applies a time-based UV distortion.

shader_type canvas_item;

// hint_screen_texture: reads the rendered framebuffer
// repeat_disable: clamp to [0,1] — no tiling artifacts at screen edges
// filter_linear: smooth sampling for distortion effects
uniform sampler2D _ScreenTexture : hint_screen_texture, repeat_disable, filter_linear;
uniform float _DistortStrength : hint_range(0.0, 0.05, 0.001) = 0.01;
uniform float _ScrollSpeed : hint_range(0.0, 2.0, 0.1) = 0.5;

void fragment() {
    // Animate distortion offset with TIME
    vec2 offset = vec2(
        sin(SCREEN_UV.y * 20.0 + TIME * _ScrollSpeed) * _DistortStrength,
        cos(SCREEN_UV.x * 20.0 + TIME * _ScrollSpeed) * _DistortStrength
    );

    // Sample screen at distorted UV
    vec4 screen_color = texture(_ScreenTexture, SCREEN_UV + offset);
    COLOR = screen_color;
}

Setup: Attach to a ColorRect (Anchor: Full Rect) inside a CanvasLayer. Effect only appears at runtime, not in the editor viewport.

3. Particles — Gravity + Fade Out

Minimal particle shader: spawns particles at emitter position, applies gravity, fades alpha over lifetime.

shader_type particles;

void start() {
    // RESTART_* flags are true when particle first spawns
    if (RESTART_POSITION) {
        // Place particle at emitter world position
        TRANSFORM[3].xyz = EMISSION_TRANSFORM[3].xyz;
    }
    if (RESTART_VELOCITY) {
        // Spread particles in a cone using golden angle
        float angle = float(NUMBER) * 2.399963;
        VELOCITY = vec3(cos(angle) * 0.5, 2.0, sin(angle) * 0.5);
    }
    if (RESTART_CUSTOM) {
        CUSTOM.y = 0.0;  // initialize lifetime phase (0=just spawned, 1=dead)
    }
}

void process() {
    // Manually track lifetime phase
    // Guard against LIFETIME == 0 to avoid NaN
    CUSTOM.y = clamp(CUSTOM.y + DELTA / max(LIFETIME, 1e-6), 0.0, 1.0);
    float age = CUSTOM.y;  // CUSTOM persists across frames

    // Apply gravity and integrate position
    VELOCITY.y -= 9.8 * DELTA;
    TRANSFORM[3].xyz += VELOCITY * DELTA;  // TRANSFORM persists — position accumulates

    // Fade alpha over lifetime
    COLOR.a = 1.0 - age;

    // Deactivate when lifetime expires
    if (age >= 1.0) {
        ACTIVE = false;
    }
}

Common Patterns

Read the screen texture (post-processing / refraction)

// Declare at top of shader
uniform sampler2D _ScreenTexture : hint_screen_texture, repeat_disable, filter_linear;

void fragment() {
    vec4 screen = texture(_ScreenTexture, SCREEN_UV);
    // For refraction: offset SCREEN_UV by NORMAL.xy before sampling
    // Caveat: only captures objects rendered before this draw call
}

Pass data from vertex() to fragment()

// Declare outside all functions
varying vec3 vertex_world;  // suffix _ws = world space convention
varying vec2 custom_uv;

void vertex() {
    vertex_world = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
    custom_uv = UV * 2.0 - 1.0;  // remap to [-1,1]
}

void fragment() {
    // vertex_world and custom_uv are available here, interpolated across the triangle
    // Restriction: varyings cannot be assigned in custom functions or in light()
}

Make a property editable in the Inspector

// Scalar with slider
uniform float _Speed : hint_range(0.0, 10.0, 0.1) = 1.0;

// Color picker (applies sRGB→linear conversion automatically)
uniform vec4 _Tint : source_color = vec4(1.0);

// Texture with normal map hint (triggers correct reimport in editor)
uniform sampler2D _NormalMap : hint_normal;

// Set from GDScript at runtime:
// material.set_shader_parameter("_Speed", 2.5)

Sample a texture in vertex() (heightmap displacement)

uniform sampler2D _HeightMap;
uniform float _HeightScale = 1.0;

void vertex() {
    // Must use textureLod — implicit derivatives are unavailable in vertex()
    float height = textureLod(_HeightMap, UV, 0.0).r;
    VERTEX.y += height * _HeightScale;
    // Update NORMAL after displacing VERTEX or lighting will be wrong
}

Common Pitfalls

Forgetting render_mode ambient_light_disabled when isolating custom lighting. If you implement all lighting in light() but omit render_mode ambient_light_disabled, Godot's ambient and environment lighting still accumulates on top of your result. Add render_mode ambient_light_disabled to isolate custom lighting, or accept the engine ambient as a base layer. Note: render_mode unshaded is different — it disables the entire lighting pipeline (no light() runs at all), which is for fully self-lit materials like particles or UI overlays.

Writing to ALBEDO inside light(). ALBEDO is read-only in light() — it reflects the value set in fragment(). Write diffuse contributions to DIFFUSE_LIGHT and specular to SPECULAR_LIGHT. Using = instead of += on these also breaks multi-light scenes — always accumulate.

Wrong matrix multiplication order. GLSL uses column-vector convention: MATRIX * vector, not vector * MATRIX. These are transposes of each other and produce incorrect results for non-symmetric matrices. Applies to all transforms: MODEL_MATRIX * vec4(VERTEX, 1.0), EULER_ZXY * VERTEX, etc.

Assigning remapped values to NORMAL_MAP. NORMAL_MAP expects a raw [0,1] texture sample — Godot remaps to [-1,1] internally. If you remap first (* 2.0 - 1.0) and then assign, the normal will be double-remapped and incorrect. Assign the raw texture(...).rgb directly.

Using texture() in vertex(). Implicit mip-level derivatives are unavailable in vertex(), so texture() produces undefined results. Always use textureLod(tex, uv, 0.0) for deterministic sampling in vertex().

pow(negative, float) is undefined in GLSL. This surfaces in SDF shapes and lighting. For SDF: use abs() before pow() — pow(abs(u), 4.0). For lighting: guard with max(value, 0.0) before any pow() call.

hint_screen_texture feedback loops. The screen texture only captures objects rendered before this draw call. Sampling it while rendering to the same viewport creates undefined behavior. For transparent objects that need screen sampling, add render_mode depth_draw_always to ensure correct draw ordering.