/shader-basics

name: shader-basics
description: Use when implementing shaders — Godot shader language, visual shaders, common visual recipes, and post-processing effects

Shaders in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs.

> **Related skills:** **animation-system** for shader-driven effects like hit flash, **godot-optimization** for shader performance considerations, **camera-system** for post-processing camera effects, **2d-essentials** for 2D lighting, pixel-art shaders, and CanvasTexture normal maps, **3d-essentials** for spatial shaders and environment materials, **particles-vfx** for custom particle shaders, **tween-animation** for animating shader parameters at runtime.

---

1. Core Concepts

Shader Types

| Shader Type | Applied To | Use For | |------------------|--------------------------|--------------------------------------------------| | `canvas_item` | 2D nodes (Sprite2D, Control, etc.) | 2D effects — outlines, dissolve, color swap | | `spatial` | 3D meshes (MeshInstance3D) | 3D materials — water, terrain, toon shading | | `particles` | GPUParticles2D/3D | Custom particle behavior | | `sky` | WorldEnvironment | Procedural sky rendering | | `fog` | FogVolume | Volumetric fog effects |

Shader vs ShaderMaterial

Shader (.gdshader)        → The code (GLSL-like language)
ShaderMaterial            → Instance of a shader with specific uniform values
CanvasItemMaterial / StandardMaterial3D → Built-in materials (no code needed)

Multiple nodes can share the same Shader but have different ShaderMaterial instances with different uniform values (e.g., same dissolve shader but different dissolve progress per enemy).

Creating a Shader

1. Select a node (e.g., Sprite2D) 2. In Inspector → Material → New ShaderMaterial 3. On the ShaderMaterial → Shader → New Shader 4. Edit the `.gdshader` file in the built-in editor

Or create a `.gdshader` file directly in the FileSystem dock.

---

2. Godot Shader Language Basics

Godot uses a GLSL ES 3.0-like language with Godot-specific additions.

Minimal Canvas Item Shader

shader_type canvas_item;

void fragment() {
    // COLOR is the output pixel color
    // TEXTURE is the sprite's texture
    // UV is the texture coordinate (0,0 top-left to 1,1 bottom-right)
    vec4 tex = texture(TEXTURE, UV);
    COLOR = tex;
}

Minimal Spatial Shader

shader_type spatial;

void fragment() {
    // ALBEDO is the base color (vec3)
    ALBEDO = vec3(0.8, 0.2, 0.2);
}

Built-in Variables (canvas_item)

| Variable | Type | Description | |------------|--------|---------------------------------------| | `UV` | `vec2` | Texture coordinates | | `COLOR` | `vec4` | Output color (set this in `fragment()`) | | `TEXTURE` | `sampler2D` | The node's texture | | `VERTEX` | `vec2` | Vertex position (in `vertex()`) | | `TIME` | `float`| Elapsed time in seconds | | `SCREEN_UV`| `vec2` | Screen-space UV (for screen effects) |

> `SCREEN_TEXTURE` was removed in Godot 4.0. To read the screen, declare a uniform: `uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;`

Built-in Variables (spatial)

| Variable | Type | Description | |-------------|--------|---------------------------------------| | `ALBEDO` | `vec3` | Base surface color | | `METALLIC` | `float`| Metallic value (0.0–1.0) | | `ROUGHNESS` | `float`| Roughness value (0.0–1.0) | | `NORMAL` | `vec3` | Surface normal (for normal mapping) | | `EMISSION` | `vec3` | Emissive color | | `ALPHA` | `float`| Transparency (enable in render mode) | | `VERTEX` | `vec3` | Vertex position (in `vertex()`) |

Uniforms (Shader Parameters)

Uniforms expose shader values to the Inspector and code.

shader_type canvas_item;

uniform float speed : hint_range(0.0, 10.0, 0.1) = 1.0;
uniform vec4 tint_color : source_color = vec4(1.0, 1.0, 1.0, 1.0);
uniform sampler2D noise_texture : filter_linear_mipmap;

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

Common Uniform Hints

| Hint | Type | Description | |-----------------------------|--------------|-------------------------------------| | `hint_range(min, max, step)` | `float/int` | Slider in Inspector | | `source_color` | `vec4` | Color picker in Inspector | | `filter_linear_mipmap` | `sampler2D` | Texture filtering mode | | `repeat_enable` | `sampler2D` | Allow texture tiling | | `hint_normal` | `sampler2D` | Treat as normal map |

Setting Uniforms from Code

GDScript

var mat: ShaderMaterial = $Sprite2D.material
mat.set_shader_parameter("speed", 2.0)
mat.set_shader_parameter("tint_color", Color.RED)

C#

var mat = GetNode<Sprite2D>("Sprite2D").Material as ShaderMaterial;
mat.SetShaderParameter("speed", 2.0f);
mat.SetShaderParameter("tint_color", Colors.Red);

---

3. Common 2D Shader Recipes

The canvas_item recipes most projects need: **dissolve** (noise + edge glow), **outline** (sample neighbors, expand alpha), **flash-white** (uniform-driven hit effect), **color swap** (palette shift), **scrolling UV** (water/lava/clouds), **wave distortion**.

> See [references/2d-shader-recipes.md](references/2d-shader-recipes.md) for complete shader code for all six recipes.

---

4. Common 3D Shader Recipes

Spatial-shader recipes: **toon/cel shading** (banded NdotL), **rim lighting / Fresnel** (1 - NdotV), **simple water surface** (UV scroll + normal-map blend + Fresnel).

> See [references/3d-shader-recipes.md](references/3d-shader-recipes.md) for the full shader source for each recipe.

---

5. Visual Shaders

Visual shaders provide a node-based graph editor — no code required.

When to Use Visual Shaders

| Use Visual Shaders When | Use Code Shaders When | |--------------------------------|------------------------------------| | Prototyping effects quickly | Complex math or branching logic | | Artists need to tweak values | Need precise control over every line | | Learning