Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-shaders

godot-shaders

Verified

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`).

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.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall