| name | godot-shaders-basics |
| description | Expert Godot shader patterns for batch-safe hitflash, alpha-scissor foliage/dissolve, screenspace postFX, depth reconstruction, triplanar, and instance uniforms — not first-shader tutorials. Trigger on draw-call batching breaks, discard vs depth-prepass, foliage shadows, post-process quads, or world-position FX. Keywords: instance uniform, ALPHA_SCISSOR, hint_screen_texture, hint_depth_texture, global uniform, sampler2DArray, canvas_item, spatial, post-processing. |
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 flashes; one material, many unique intensities.
Mask dissolve with ALPHA_SCISSOR for depth-prepass + shadows.
World-space wind sway for foliage batches.
global uniform player interaction flattening grass.
hint_screen_texture stylized postFX.
Reversed-Z-safe full-rect post pass.
hint_depth_texture → world position.
World-axis projection without UVs.
sampler2DArray + instance uniform for unique batched textures.
Vertex noise displacement.
Validated VFX shader template.
Tween/runtime uniform animation without AnimationPlayer.
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.
- 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.
