godot-shaders-basics

NEVER Do in Shaders

• NEVER use discard unconditionally for optimization — It prevents the depth prepass from working effectively. A discarded pixel still costs vertex processing; sometimes not rendering the object is better [1].
• NEVER use if/else for dynamic states in high-performance shaders — GPUs hate branching. Use mix(), step(), and smoothstep() for mathematical, hardware-optimized selection [5, 21].
• NEVER compare floats exactly — Hardware precision varies; if (v == 0.5) is unreliable. Use abs(a - b) < epsilon or step().
• NEVER use standard Alpha Blending for massive foliage — It prevents shadows and SSR. Use Alpha Scissor or Alpha Hash (dithering) to enable depth prepass and shadow casting [7].
• NEVER hardcode POSITION to vec4(VERTEX, 1.0) for full-screen quads in 4.3+ — Godot 4.3 uses Reversed-Z depth; this will cause clipping. Use POSITION = vec4(VERTEX.xy, 1.0, 1.0) [8, 9].
• NEVER duplicate materials to change one color/value on many enemies — Use instance uniform. This allows unique values for thousands of nodes while maintaining a single draw call (batching) [10].
• NEVER use TIME without a speed multiplier — Fragment speed should be controllable via uniforms to ensure consistency across different gameplay states.
• NEVER forget hint_source_color for color uniforms — Without it, the engine treats colors as linear math, leading to incorrect gamma and washed-out visuals in the inspector.
• NEVER calculate complex math in fragment() that could be in vertex() — vertex() runs once per point; fragment() runs millions of times per frame. Interpolate values via varying instead.
• NEVER use #define macros for dynamic runtime toggles — These create new shader permutations, causing massive compilation stutters when first encountered in-game. Use uniforms instead.
• NEVER forget to normalize vectors — Using reflect(dir, normal) on unnormalized vectors causes severe rendering artifacts and incorrect lighting math.
• NEVER modify UV without bounds checking or fract() — Shifting UVs beyond 0.0-1.0 without repeat wrapping or clamping will sample edge pixels or return black, breaking texture consistency.

Scenario → Script Triggers

> MANDATORY for the matching effect. Do NOT Load beginner canvas_item tint recipes or built-in variable glossaries here.

| Goal | Script |

|------|--------|

| Per-enemy hitflash without breaking batches | MANDATORY [instance_uniform_hitflash.gdshader](scripts/instance_uniform_hitflash.gdshader) |

| Foliage wind + shadows | MANDATORY [foliage_wind_sway_expert.gdshader](scripts/foliage_wind_sway_expert.gdshader) (alpha scissor/hash — not unconditional discard) |

| Dissolve that keeps depth-prepass | MANDATORY [dissolve_scissor_expert.gdshader](scripts/dissolve_scissor_expert.gdshader) |

| PostFX pixelate / stylize | MANDATORY [screenspace_hex_pixelate.gdshader](scripts/screenspace_hex_pixelate.gdshader) |

| Full-screen quad (Reversed-Z) | MANDATORY [screenspace_full_quad.gdshader](scripts/screenspace_full_quad.gdshader) |

| Depth → world for water/fog | MANDATORY [depth_world_reconstruction.gdshader](scripts/depth_world_reconstruction.gdshader) |

| Grass flatten from player | [global_grass_flatten.gdshader](scripts/global_grass_flatten.gdshader) |

| UV-less cliffs/rocks | [triplanar_world_mapping.gdshader](scripts/triplanar_world_mapping.gdshader) |

| Unique textures on instanced meshes | [instance_texture_array.gdshader](scripts/instance_texture_array.gdshader) |

| Vertex displacement terrain | [noise_terrain_displacement.gdshader](scripts/noise_terrain_displacement.gdshader) |

| Animate uniforms at runtime | [shader_parameter_animator.gd](scripts/shader_parameter_animator.gd) |

| VFX port template | [vfx_port_shader.gdshader](scripts/vfx_port_shader.gdshader) |

Golden path for cutouts/dissolve: ALPHA_SCISSOR / alpha hash (see dissolve + foliage scripts) — not discard for optimization. NEVER list explains why.

Available Scripts

[instance_uniform_hitflash.gdshader](scripts/instance_uniform_hitflash.gdshader)

Instance-uniform flashes; one material, many unique intensities.

[dissolve_scissor_expert.gdshader](scripts/dissolve_scissor_expert.gdshader)

Mask dissolve with ALPHA_SCISSOR for depth-prepass + shadows.

[foliage_wind_sway_expert.gdshader](scripts/foliage_wind_sway_expert.gdshader)

World-space wind sway for foliage batches.

[global_grass_flatten.gdshader](scripts/global_grass_flatten.gdshader)

global uniform player interaction flattening grass.

[screenspace_hex_pixelate.gdshader](scripts/screenspace_hex_pixelate.gdshader)

hint_screen_texture stylized postFX.

[screenspace_full_quad.gdshader](scripts/screenspace_full_quad.gdshader)

Reversed-Z-safe full-rect post pass.

[depth_world_reconstruction.gdshader](scripts/depth_world_reconstruction.gdshader)

hint_depth_texture → world position.

[triplanar_world_mapping.gdshader](scripts/triplanar_world_mapping.gdshader)

World-axis projection without UVs.

[instance_texture_array.gdshader](scripts/instance_texture_array.gdshader)

sampler2DArray + instance uniform for unique batched textures.

[noise_terrain_displacement.gdshader](scripts/noise_terrain_displacement.gdshader)

Vertex noise displacement.

[vfx_port_shader.gdshader](scripts/vfx_port_shader.gdshader)

Validated VFX shader template.

[shader_parameter_animator.gd](scripts/shader_parameter_animator.gd)

Tween/runtime uniform animation without AnimationPlayer.

[shader_warmup_loader.gd](scripts/shader_warmup_loader.gd)

Pre-warm shader pipelines during loading screens to avoid first-frame stutter.

Expert Pointers

• Move invariant math to vertex(); pass via varying.
• Color uniforms need hint_source_color.
• Prefer Official Docs for shading-language builtins; this skill owns batching, scissor, screenspace, and depth routing.

Deep recipes (on demand)

> LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

| Topic | Reference |

|-------|-----------|

| 2D dissolve/wave/outline | [2d-effect-recipes.md](references/2d-effect-recipes.md) |

| 3D toon + vignette | [3d-and-postfx-recipes.md](references/3d-and-postfx-recipes.md) |

| Uniforms / built-ins | [uniforms-and-builtins.md](references/uniforms-and-builtins.md) |

| Fog, compute, warmup | [expert-advanced-patterns.md](references/expert-advanced-patterns.md) |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API;

> load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

• Introduction to shaders — Entry map of shader types, render modes, and when to use ShaderMaterial vs StandardMaterial3D.
• Shading language — Core GLSL-like syntax: uniforms, hints, varyings, built-ins, and preprocessor rules used throughout this skill.
• CanvasItem shaders — 2D canvas_item built-ins (UV, COLOR, TEXTURE, SCREEN_UV) for sprites, UI, and 2D post FX.
• Spatial shaders — 3D spatial built-ins (ALBEDO, NORMAL, instance uniform, depth/screen textures) for materials and full-screen quads.
• Your first 2D shader — Minimal canvas_item workflow from ShaderMaterial attach through fragment tinting.
• Your first 3D shader — Minimal spatial workflow and conversion path from StandardMaterial3D into writable shaders.
• ShaderMaterial — Runtime set_shader_parameter / instance parameter API used by animators and hit-flash batching.
• Custom post-processing — Screen-reading shaders, hint_screen_texture, and compositing patterns for pixelate/vignette-style FX.
• Advanced post-processing — Depth buffer, reversed-Z, and world reconstruction needed for water/fog/debug visualizers.
• Compute shaders — RenderingDevice GPGPU path for particle sims and other non-fragment workloads.
• Using VisualShaders — Graph editor + VisualShaderNodeCustom extensibility covered in the expert patterns.
• GPU optimization — Overdraw, transparency, and batching guidance that motivates alpha scissor, instance uniforms, and vertex-vs-fragment cost.

Related Skills

Prerequisites

• godot-project-foundations — Nodes, Resources, and project layout required before attaching ShaderMaterials and shipping .gdshader assets.
• godot-resource-data-patterns — Sharing vs duplicating ShaderMaterial/Shader Resources so uniforms and instance parameters stay batch-friendly.

Complements

• godot-3d-materials — StandardMaterial3D/ORM first; graduate to spatial shaders for triplanar, dissolve, and instance-uniform effects.
• godot-3d-lighting — How custom ALBEDO/EMISSION/light() output interacts with Forward+, GI, and fog volumes.
• godot-particles — Particle process/draw materials and alpha pipelines that must match scissor/hash vs blend choices from this skill.
• godot-2d-animation — CanvasItem shader hooks for stylized 2D motion, outline, and dissolve on animated sprites.
• godot-camera-systems — Camera near/far and view/projection matrices that screen-space and depth-reconstruction shaders depend on.
• godot-performance-optimization — Draw-call batching, MultiMesh, and GPU budgets that justify instance uniform and avoiding unique materials.
• godot-debugging-profiling — GPU/overdraw profilers and debug views to validate shader cost and depth/normal visualizers.

Downstream / consumers

• godot-procedural-generation — Procedural meshes/terrain consume noise displacement, triplanar, and UV-less spatial patterns from this skill.
• godot-3d-world-building — Large environment props apply foliage wind, grass flatten, and world-projection shaders at level scale.
• godot-genre-open-world — Open-world foliage interaction, distance FX, and shared-material batching consume these shader templates.

Master

• godot-master — Library router and mirrored module entry for cross-skill discovery.