Index of every page on this site: llms.txt
All skills
Run it yourself

Godot 4.7 Shading Language syntax and pipeline: canvas_item, spatial and particle shaders, built-ins, ShaderMaterial wiring, a headless compile check and 3.x porting. Use for a .gdshader, a SHADER ERROR, shader parameters set from GDScript, or an effect that looks washed out or sorts wrong. Not for effect maths such as dissolve or outline (`shader-programming`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/godot-shaders

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈95 tokens for metadata: the name and description. ≈2.2k when used: this file. ≈1.1k more on demand in 1 file.

Description uses 4.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈380 characters, or 4.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Godot Shaders (4.x)

Write .gdshader files in the Godot Shading Language, wire them to materials, and prove they compile. Targets Godot 4.7 (see Version notes). The effect technique (the maths of a dissolve, outline, toon ramp) lives in shader-programming; this skill covers Godot's syntax, built-ins and pipeline.

When to use

  • Writing or porting .gdshader code, fixing a SHADER ERROR, wiring a ShaderMaterial, picking render modes, or setting uniforms from code.

When not to use: cross-engine shading technique → shader-programming; StandardMaterial3D, lights and environment → godot-3d-essentials. GPUParticles node properties (as opposed to a particles shader) are outside this skill.

Core workflow

  1. Pick the shader type on the first line: shader_type canvas_item; for anything CanvasItem (Sprite2D, TextureRect, Control) or shader_type spatial; for 3D meshes. particles, sky and fog exist too.

  2. Write the output the type expects: COLOR in canvas_item; ALBEDO, EMISSION, ROUGHNESS, METALLIC in spatial. vertex() moves geometry; light() replaces lighting.

  3. Expose tunables as uniforms with hints (source_color for colors, hint_range for sliders) so they show in the Inspector and are color-managed.

  4. Wire the material. In a .tscn this is plain text, so no Inspector clicks are needed:

    [ext_resource type="Shader" path="res://fx/scroll.gdshader" id="1_fx"]
    
    [sub_resource type="ShaderMaterial" id="ShaderMaterial_fx"]
    shader = ExtResource("1_fx")
    shader_parameter/scroll_speed = 0.5
    
    [node name="Water" type="Sprite2D" parent="."]
    material = SubResource("ShaderMaterial_fx")

    From code: material.set_shader_parameter("scroll_speed", 0.5).

  5. Check before you finish.

    • Compile every shader headless with Pattern 4, then grep the log:

      godot --headless --path . --script res://tests/compile_shaders.gd > shaders.log 2>&1
      grep -nE "SHADER ERROR|Shader compilation failed" shaders.log   # no output = pass

      Headless uses a dummy renderer that still runs Godot's shader compiler, so syntax, unknown built-ins, wrong output variables and bad hints all show up. It does not run the GPU driver, so ask the user to open the scene with the project's renderer (Forward+, Mobile or Compatibility) and report how it looks and any errors in the Output panel.

    • If you wired a material in a .tscn, also run the godot-nodes-scenes skill's scripts/check_godot_project.py <project-dir> to confirm the ext_resource path.

    • With no Godot binary (godot, godot4 or $GODOT_BIN), ask the user to run the command above and paste shaders.log.

Patterns

1. canvas_item: tint and scrolling UV

shader_type canvas_item;

uniform vec4 tint : source_color = vec4(1.0);
uniform float scroll_speed : hint_range(0.0, 2.0) = 0.3;

void fragment() {
    vec2 uv = UV + vec2(TIME * scroll_speed, 0.0);
    COLOR = texture(TEXTURE, uv) * tint;          // TEXTURE = the node's own texture
}

The node's texture must repeat for the scroll to wrap: set texture_repeat on the CanvasItem, or sample your own uniform sampler2D tex : repeat_enable;.

2. spatial: emissive rim on an opaque material

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;
    float rim = pow(1.0 - clamp(dot(NORMAL, VIEW), 0.0, 1.0), rim_power);  // view space
    EMISSION = rim_color * rim;                   // no ALPHA write: stays opaque
}

3. Screen-reading post effect (4.x hint, not SCREEN_TEXTURE)

shader_type canvas_item;

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;
}

4. Headless compile check for every .gdshader

# res://tests/compile_shaders.gd
extends SceneTree

func _initialize() -> void:
    var paths := _find("res://", "gdshader")
    for path in paths:
        print("compiling ", path)                 # a SHADER ERROR prints right after this
        var shader := load(path) as Shader
        shader.get_shader_uniform_list()         # forces the compile; load() alone is lazy
    print("Compiled %d shaders" % paths.size())
    quit(0)

func _find(dir: String, ext: String) -> PackedStringArray:
    var found := PackedStringArray()
    for file in DirAccess.get_files_at(dir):
        if file.get_extension() == ext:
            found.append(dir.path_join(file))
    for sub in DirAccess.get_directories_at(dir):
        if not sub.begins_with("."):             # skips .godot/ and other hidden folders
            found.append_array(_find(dir.path_join(sub), ext))
    return found

Shaders embedded in a .tscn ([sub_resource type="Shader"]) are not files; cover them by smoke-running that scene (--scene res://... --quit-after 10) and grepping the same way.

Gotchas

  • 3.x → 4.x renames. SCREEN_TEXTURE and DEPTH_TEXTURE are removed; declare uniform sampler2D x : hint_screen_texture; (or hint_depth_texture) and sample with SCREEN_UV. Forward+ also offers hint_normal_roughness_texture. hint_color/hint_albedo → source_color; hint_white/hint_black → hint_default_white/hint_default_black. In canvas_item vertex(), 3.x's MODELVIEW_MATRIX is now MODEL_MATRIX / CANVAS_MATRIX / SCREEN_MATRIX.
  • Wrong output variable. In a spatial fragment(), COLOR is the read-only vertex color, so assigning to it is a compile error; write ALBEDO.
  • Color uniforms without source_color are treated as raw linear values and look washed out or dark.
  • 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. For hard cut-outs set ALPHA_SCISSOR_THRESHOLD, which stays in the opaque pass.
  • Sampling outside [0,1] UV clamps unless the sampler uniform has repeat_enable (or, for TEXTURE, the node's texture_repeat is on).
  • Effect jumps once an hour → TIME wraps at rendering/limits/time/time_rollover_secs (3600 by default). Pick periods that divide the rollover, or feed your own time uniform.
  • load() alone does not compile a shader. The Shader creates its GPU-side object on first use, which is why Pattern 4 calls get_shader_uniform_list().
  • discard breaks early depth testing and costs more on some GPUs; prefer alpha where the blend mode allows.

References

  • Read references/shading-language.md when you need the built-ins per shader type, render-mode names, sampler filter/repeat qualifiers, varying, vertex() displacement, a custom light() function, 2D normal maps, or performance rules.

Related skills

  • shader-programming for the effect technique (dissolve, outline, fresnel, vignette).
  • godot-3d-essentials for materials, environment and where spatial shaders live.
  • godot-ui-control for applying shaders to UI.
  • godot-gdscript-headless-testing to run Pattern 4 in CI.

Version notes

Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).

  • The headless (dummy) renderer compiles shaders with the engine's shader compiler and prints SHADER ERROR: lines; a Shader resource compiles lazily on first use.
  • The render modes and built-ins listed in the reference exist in 4.7.2's shader_types.cpp.

Sources: dummy material_storage.cpp @ 4.7.2-stable, shader.cpp @ 4.7.2-stable, shader_types.cpp @ 4.7.2-stable, Shading language, Upgrading from Godot 3 to 4.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill provides templates and workflows for writing Godot 4.7 shaders. It includes a utility script for headless shader compilation checks and references official Godot documentation and source code.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/godot-shaders