---
name: shader-basics
description: Use when implementing shaders — Godot shader language, visual shaders, common visual recipes, and post-processing effects
title: shader-basics
canonical_url: https://skilld.dev/gh/jame581/godotprompter/shader-basics
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/2d-shader-recipes.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/2d-shader-recipes.md), [references/3d-shader-recipes.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/3d-shader-recipes.md), [references/compositor-effects.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/compositor-effects.md), [references/post-processing.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/post-processing.md), [references/shader-baker.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/shader-baker.md), [references/stencil-buffer.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/stencil-buffer.md), [references/visual-shaders.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/visual-shaders.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/shader-basics`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/shader-basics`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/shader-basics) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/shader-basics`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/shader-basics --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/shader-basics --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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

```glsl
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

```glsl
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 (writing it moves the material to the transparent pass) |
| `VERTEX` | `vec3` | Vertex position (in `vertex()`) |

### Uniforms (Shader Parameters)

Uniforms expose shader values to the Inspector and code.

```glsl
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

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

#### C#

```csharp
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](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/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](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/3d-shader-recipes.md) for the full shader source for each recipe.

---

## 5. Visual Shaders

Visual shaders are a node-based graph editor (New ShaderMaterial → New VisualShader). Use them for quick prototypes, artist-tweakable values, and simple effects; use code for complex math, branching, or loops. Both compile to the same GPU code, so performance is identical.

> See [references/visual-shaders.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/visual-shaders.md) for the choice table, steps, key nodes, and 4.7 node changes. In Godot 4.7 the `LinearToSRGB` node no longer clamps to `[0, 1]` on Forward+/Mobile; add a `Clamp` node if a graph relied on it.

---

## 6. Post-Processing Effects

The standard pattern: full-rect `ColorRect` with a canvas_item shader on top of the gameplay canvas. For 3D, use a `WorldEnvironment` Adjustment, Glow, or custom shader. For chained effects, render the world to a `SubViewport` then sample its texture in a final shader pass.

> See [references/post-processing.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/post-processing.md) for the ColorRect overlay pattern, vignette + CRT/scanline shader source, the SubViewport pipeline, and WorldEnvironment 3D post-processing notes.

---

## 7. Compositor Effects (Godot 4.3+)

`CompositorEffect` runs custom render passes at five points in the 3D render pipeline, from before the opaque pass to after the transparent pass — all before the built-in post effects and tonemapping. Use when ColorRect overlays aren't enough — multi-pass effects, depth-aware effects, custom AO/SSR variants. Heavier setup than a screen-space shader; reach for it only when needed.

> See [references/compositor-effects.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/compositor-effects.md) for setup, a custom CompositorEffect GDScript example, and built-in Compositor use cases.

---

## 8. Render Modes

Render modes go on the first line after `shader_type` and control how the shader interacts with the rendering pipeline.

### Canvas Item Render Modes

```glsl
shader_type canvas_item;
render_mode unshaded;           // Ignore all lighting
render_mode light_only;         // Only visible where lit
render_mode blend_add;          // Additive blending (glow, fire)
render_mode blend_mix;          // Standard alpha blending (default)
render_mode blend_premul_alpha; // Pre-multiplied alpha
```

### Spatial Render Modes

```glsl
shader_type spatial;
render_mode unshaded;              // No lighting calculations
render_mode cull_disabled;         // Render both sides of faces
render_mode depth_draw_always;     // Always write to depth buffer
render_mode specular_toon;         // Toon specular model
render_mode diffuse_toon;          // Toon diffuse model
render_mode blend_add;             // Additive blending
```

---

## 9. Stencil Buffer Effects (Godot 4.5+)

Godot 4.5 exposes stencil write/read in spatial shaders via the `stencil_mode` statement (`stencil_mode write, 1;` / `stencil_mode read, compare_equal, 1;`) and on `StandardMaterial3D` (Stencil: Outline / X-Ray / Custom), across all rendering backends. canvas_item shaders have no stencil modes. Enables portals, X-ray vision, outline masks, and holes-in-geometry effects that previously required compositor-level work.

> See [references/stencil-buffer.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/stencil-buffer.md) for the `stencil_mode` reference and the X-ray vision portal worked example.

---

## 10. SMAA Antialiasing (Godot 4.5+)

Sub-pixel Morphological Antialiasing (SMAA 1x) is a built-in post-processing AA mode added in Godot 4.5. It produces clearer results than FXAA at a slightly higher performance cost, and is much cheaper than MSAA.

### Enabling SMAA

1. Open **Project Settings**
2. Navigate to **Rendering → Anti Aliasing → Quality**
3. Set **Screen Space AA** to **SMAA**

SMAA can be combined with MSAA (for geometry edge aliasing) or used standalone. It does not require any shader code changes.

| AA Mode | Sharpness | GPU cost | Ghosting |
|---------|-----------|----------|----------|
| Disabled | N/A | None | None |
| FXAA | Low (blurry) | Very low | Low |
| **SMAA** | High | Low (slightly above FXAA) | Very low |
| TAA | Medium (slight blur) | Medium | Possible |
| MSAA 4x | High | High | None |

> **When to use SMAA:** Prefer SMAA over FXAA for most desktop projects — it delivers noticeably sharper text and thin edges for a slightly higher cost. Combine SMAA + MSAA 2x for best quality at moderate cost.

The project setting is read at startup only. To switch at runtime set `get_viewport().screen_space_aa = Viewport.SCREEN_SPACE_AA_SMAA` (C#: `GetViewport().ScreenSpaceAA = Viewport.ScreenSpaceAAEnum.Smaa`). Forward+ and Mobile only — not Compatibility.

---

## 11. Shader Baker — Export-time Pre-compilation (Godot 4.5+)

The Shader Baker converts project shaders to the target driver's format at export time, which shortens first-launch load — most on macOS/iOS (Metal) and Windows (D3D12), where that conversion is slow. It does not remove pipeline-compilation stutter the first time a material renders, works only on the Forward+ and Mobile renderers, and bakes only for drivers the exporting machine's OS supports. Enable it per export preset for release builds; leave it off for development.

> See [references/shader-baker.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/shader-basics/references/shader-baker.md) for enabling steps and the with/without comparison.

---

## 12. Common Pitfalls

| Symptom | Cause | Fix |
|-------------------------------------|----------------------------------------------------|------------------------------------------------------------------|
| Shader has no visible effect | Material not assigned or shader not saved | Check node's Material property in Inspector |
| Transparent parts render as black | Alpha not handled in shader | Set `COLOR.a = tex.a;` and use appropriate blend mode |
| Uniform doesn't appear in Inspector | Typo in uniform name or wrong type | Re-save the shader; check for compilation errors |
| Texture appears stretched/tiled | Missing `repeat_enable` or wrong UV scale | Add `repeat_enable` hint to sampler2D uniform |
| Shader works in editor but not in game | Screen texture uniform needs backbuffer | Use `hint_screen_texture` on a `sampler2D` uniform (Godot 4.x) |
| Performance drops with many shaders | Each unique shader = draw call break | Share ShaderMaterial instances; use uniforms for variation |
| Screen-space UV is wrong | `SCREEN_UV` not available in some contexts | Ensure the node is rendered in the correct viewport |
| Visual shader node missing | Node was renamed or removed in newer Godot version | Check Godot docs for the current node name |

> ⚠️ **Changed in Godot 4.7:** `textureQueryLod()` is available only in the fragment shader, and Godot 4.7 enforces this with a compile error — shaders calling it from `vertex()` stop compiling after upgrading. Move the call into `fragment()`. See [GH-118962](https://github.com/godotengine/godot/pull/118962).

---

## 13. Implementation Checklist

- [ ] Shader type matches the node type (`canvas_item` for 2D, `spatial` for 3D)
- [ ] Uniforms use appropriate hints (`hint_range`, `source_color`, `filter_linear_mipmap`)
- [ ] Shared visual effects use the same Shader resource with separate ShaderMaterial instances
- [ ] Post-processing shaders are on a CanvasLayer (2D) or WorldEnvironment (3D), not on game objects
- [ ] `TEXTURE` is sampled in canvas_item shaders (otherwise sprite content is lost)
- [ ] Alpha-transparent shaders set `COLOR.a` correctly and use `blend_mix` render mode
- [ ] Animated shader parameters (dissolve, flash) are driven by Tweens or AnimationPlayer, not `_process`
- [ ] Screen-reading shaders use `hint_screen_texture` on a `sampler2D` uniform (Godot 4.x approach)
- [ ] Complex shaders are profiled with the Godot profiler to check GPU frame time
- [ ] Stencil effects use two-pass materials (write pass first, read pass second) with correct render priority (Godot 4.5+)
- [ ] SMAA is preferred over FXAA for desktop builds (sharper edges, slightly higher cost) — set in Project Settings → Rendering → Anti Aliasing (Godot 4.5+)
- [ ] Shader Baker is enabled in release presets for D3D12 and Metal targets to shorten first-launch load (Forward+/Mobile only; Godot 4.5+)
