NEVER Do in Shaders
- NEVER use
discardunconditionally 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/elsefor dynamic states in high-performance shaders — GPUs hate branching. Usemix(),step(), andsmoothstep()for mathematical, hardware-optimized selection [5, 21]. - NEVER compare floats exactly — Hardware precision varies;
if (v == 0.5)is unreliable. Useabs(a - b) < epsilonorstep(). - 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
POSITIONtovec4(VERTEX, 1.0)for full-screen quads in 4.3+ — Godot 4.3 uses Reversed-Z depth; this will cause clipping. UsePOSITION = 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
TIMEwithout a speed multiplier — Fragment speed should be controllable via uniforms to ensure consistency across different gameplay states. - NEVER forget
hint_source_colorfor 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 invertex()—vertex()runs once per point;fragment()runs millions of times per frame. Interpolate values viavaryinginstead. - NEVER use
#definemacros 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 withoutrepeatwrapping 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 |
| Foliage wind + shadows | MANDATORY foliage_wind_sway_expert.gdshader (alpha scissor/hash — not unconditional discard) |
| Dissolve that keeps depth-prepass | MANDATORY dissolve_scissor_expert.gdshader |
| PostFX pixelate / stylize | MANDATORY screenspace_hex_pixelate.gdshader |
| Full-screen quad (Reversed-Z) | MANDATORY screenspace_full_quad.gdshader |
| Depth → world for water/fog | MANDATORY depth_world_reconstruction.gdshader |
| Grass flatten from player | global_grass_flatten.gdshader |
| UV-less cliffs/rocks | triplanar_world_mapping.gdshader |
| Unique textures on instanced meshes | instance_texture_array.gdshader |
| Vertex displacement terrain | noise_terrain_displacement.gdshader |
| Animate uniforms at runtime | shader_parameter_animator.gd |
| VFX port template | 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
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 viavarying. - 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 |
| 3D toon + vignette | 3d-and-postfx-recipes.md |
| Uniforms / built-ins | uniforms-and-builtins.md |
| Fog, compute, warmup | 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_itembuilt-ins (UV,COLOR,TEXTURE,SCREEN_UV) for sprites, UI, and 2D post FX. - Spatial shaders — 3D
spatialbuilt-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 +
VisualShaderNodeCustomextensibility 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
.gdshaderassets. - 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 uniformand 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.
