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.

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

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

dissolve_scissor_expert.gdshader

Mask dissolve with ALPHA_SCISSOR for depth-prepass + shadows.

foliage_wind_sway_expert.gdshader

World-space wind sway for foliage batches.

global_grass_flatten.gdshader

global uniform player interaction flattening grass.

screenspace_hex_pixelate.gdshader

hint_screen_texture stylized postFX.

screenspace_full_quad.gdshader

Reversed-Z-safe full-rect post pass.

depth_world_reconstruction.gdshader

hint_depth_texture → world position.

triplanar_world_mapping.gdshader

World-axis projection without UVs.

instance_texture_array.gdshader

sampler2DArray + instance uniform for unique batched textures.

noise_terrain_displacement.gdshader

Vertex noise displacement.

vfx_port_shader.gdshader

Validated VFX shader template.

shader_parameter_animator.gd

Tween/runtime uniform animation without AnimationPlayer.

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.

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.