Godot着色器基础教程：片段/顶点着色器、uniform变量与内置变量详解

绝对不要无条件使用 discard 进行优化 — 这会阻止深度预通道有效工作。被丢弃的像素仍然消耗顶点处理成本；有时不渲染对象反而更好 [1]。
绝对不要在高性能着色器中使用 if/else 处理动态状态 — GPU 讨厌分支。使用 mix()、step() 和 smoothstep() 进行数学化、硬件优化的选择 [5, 21]。
绝对不要精确比较浮点数 — 硬件精度各不相同；if (v == 0.5) 不可靠。使用 abs(a - b) < epsilon 或 step()。
绝对不要对大量植被使用标准 Alpha 混合 — 这会阻止阴影和屏幕空间反射。使用 Alpha 裁剪或 Alpha 哈希（抖动）来启用深度预通道和阴影投射 [7]。
绝对不要在 4.3+ 版本中为全屏四边形硬编码 POSITION 为 vec4(VERTEX, 1.0) — Godot 4.3 使用反转 Z 深度；这会导致裁剪。使用 POSITION = vec4(VERTEX.xy, 1.0, 1.0) [8, 9]。
绝对不要为了在许多敌人身上更改一个颜色/值而复制材质 — 使用 instance uniform。这允许为数千个节点设置唯一值，同时保持单个绘制调用（批处理）[10]。
绝对不要在没有速度乘数的情况下使用 TIME — 片段速度应可通过 uniform 变量控制，以确保不同游戏状态间的一致性。
绝对不要忘记为颜色 uniform 变量使用 hint_source_color — 没有它，引擎会将颜色视为线性数学计算，导致检查器中伽马值不正确和视觉发白。
绝对不要在 fragment() 中计算本可以在 vertex() 中计算的复杂数学运算 — vertex() 每个点运行一次；fragment() 每帧运行数百万次。应通过 varying 插值传递值。
绝对不要使用 #define 宏进行动态运行时切换 — 这会创建新的着色器变体，在游戏中首次遇到时导致大量编译卡顿。应改用 uniform 变量。
绝对不要忘记规范化向量 — 在未规范化的向量上使用 reflect(dir, normal) 会导致严重的渲染伪影和错误的光照计算。
绝对不要在没有边界检查或 fract() 的情况下修改 UV — 在没有 repeat 环绕或钳位的情况下将 UV 偏移超出 0.0-1.0 范围，将采样边缘像素或返回黑色，破坏纹理一致性。

shader_type canvas_item;

void fragment() {
    // Get texture color
    vec4 tex_color = texture(TEXTURE, UV);
    
    // Tint red
    COLOR = tex_color * vec4(1.0, 0.5, 0.5, 1.0);
}

应用到 Sprite：

选择 Sprite2D 节点
Material → New ShaderMaterial
Shader → New Shader
粘贴代码

shader_type canvas_item;

uniform float dissolve_amount : hint_range(0.0, 1.0) = 0.0;
uniform sampler2D noise_texture;

void fragment() {
    vec4 tex_color = texture(TEXTURE, UV);
    float noise = texture(noise_texture, UV).r;
    
    if (noise < dissolve_amount) {
        discard;  // Make pixel transparent
    }
    
    COLOR = tex_color;
}

shader_type canvas_item;

uniform float wave_speed = 2.0;
uniform float wave_amount = 0.05;

void fragment() {
    vec2 uv = UV;
    uv.x += sin(uv.y * 10.0 + TIME * wave_speed) * wave_amount;
    
    COLOR = texture(TEXTURE, uv);
}

shader_type canvas_item;

uniform vec4 outline_color : source_color = vec4(0.0, 0.0, 0.0, 1.0);
uniform float outline_width = 2.0;

void fragment() {
    vec4 col = texture(TEXTURE, UV);
    vec2 pixel_size = TEXTURE_PIXEL_SIZE * outline_width;
    
    float alpha = col.a;
    alpha = max(alpha, texture(TEXTURE, UV + vec2(pixel_size.x, 0.0)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(-pixel_size.x, 0.0)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(0.0, pixel_size.y)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(0.0, -pixel_size.y)).a);
    
    COLOR = mix(outline_color, col, col.a);
    COLOR.a = alpha;
}

shader_type spatial;

void fragment() {
    ALBEDO = vec3(1.0, 0.0, 0.0);  // Red material
}

卡通着色（赛璐珞着色）

shader_type spatial;

uniform vec3 base_color : source_color = vec3(1.0);
uniform int color_steps = 3;

void light() {
    float NdotL = dot(NORMAL, LIGHT);
    float stepped = floor(NdotL * float(color_steps)) / float(color_steps);
    
    DIFFUSE_LIGHT = base_color * stepped;
}

shader_type canvas_item;

uniform float vignette_strength = 0.5;

void fragment() {
    vec4 color = texture(TEXTURE, UV);
    
    // Distance from center
    vec2 center = vec2(0.5, 0.5);
    float dist = distance(UV, center);
    
    float vignette = 1.0 - dist * vignette_strength;
    
    COLOR = color * vignette;
}

Uniform 变量（参数）

// Float slider
uniform float intensity : hint_range(0.0, 1.0) = 0.5;

// Color picker
uniform vec4 tint_color : source_color = vec4(1.0);

// Texture
uniform sampler2D noise_texture;

// Access in code:
material.set_shader_parameter("intensity", 0.8)

2D (canvas_item):

UV - 纹理坐标 (0-1)
COLOR - 输出颜色
TEXTURE - 当前纹理
TIME - 自开始以来的时间
SCREEN_UV - 屏幕坐标

ALBEDO - 基础颜色
NORMAL - 表面法线
ROUGHNESS - 表面粗糙度
METALLIC - 金属度值

1. 使用 Uniform 变量进行调整

// ✅ 良好 - 可调整
uniform float speed = 1.0;

void fragment() {
    COLOR.r = sin(TIME * speed);
}

// ❌ 不佳 - 硬编码
void fragment() {
    COLOR.r = sin(TIME * 2.5);
}

// Avoid expensive operations in fragment shader
// Pre-calculate values when possible
// Use textures for complex patterns

// Water wave effect
// Creates horizontal distortion based on sine wave
uniform float wave_amplitude = 0.02;

主技能：godot-master

🇺🇸English

Shader Basics

Fragment/vertex shaders, uniforms, and built-in variables define custom visual effects.

Available Scripts

vfx_port_shader.gdshader

Expert shader template with parameter validation and common effect patterns.

shader_parameter_animator.gd

Runtime shader uniform animation without AnimationPlayer - for dynamic effects.

dissolve_scissor_expert.gdshader

High-performance mask-based dissolve. Uses ALPHA_SCISSOR to enable depth-prepass optimization and shadow casting.

instance_uniform_hitflash.gdshader

Batch-friendly hit effects. Uses instance uniform to allow thousands of unique flashes in one draw call.

screenspace_hex_pixelate.gdshader

Post-processing logic for stylizing screen output. Uses hint_screen_texture and optimized coordinate quantization.

noise_terrain_displacement.gdshader

Procedural geometry displacement using NoiseTexture2D in the vertex() function for rolling terrain.

foliage_wind_sway_expert.gdshader

GPU-driven wind animation using world_vertex_coords for uniform sway across the environment.

global_grass_flatten.gdshader

World-interaction pattern using global uniform. Synchronizes player position to push grass down project-wide.

depth_world_reconstruction.gdshader

Expert depth-buffer logic. Reconstructs world-space coordinates from hint_depth_texture for water/fog effects.

triplanar_world_mapping.gdshader

UV-less texturing architecture. Seamlessly projects textures along world axes for procedural cliffs and rocks.

instance_texture_array.gdshader

Bypassing batching limits. Combines sampler2DArray with instance uniform to give unique textures to thousands of batched objects.

screenspace_full_quad.gdshader

Godot 4.3 specific full-rect shader. Handles Reversed-Z coordinate reconstruction to prevent clipping at the near plane.

NEVER Do in Shaders

NEVER usediscard 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 useif/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].

shader_type canvas_item;

void fragment() {
    // Get texture color
    vec4 tex_color = texture(TEXTURE, UV);
    
    // Tint red
    COLOR = tex_color * vec4(1.0, 0.5, 0.5, 1.0);
}

Apply to Sprite:

Select Sprite2D node
Material → New ShaderMaterial
Shader → New Shader
Paste code

Common 2D Effects

Dissolve Effect

shader_type canvas_item;

uniform float dissolve_amount : hint_range(0.0, 1.0) = 0.0;
uniform sampler2D noise_texture;

void fragment() {
    vec4 tex_color = texture(TEXTURE, UV);
    float noise = texture(noise_texture, UV).r;
    
    if (noise < dissolve_amount) {
        discard;  // Make pixel transparent
    }
    
    COLOR = tex_color;
}

Wave Distortion

shader_type canvas_item;

uniform float wave_speed = 2.0;
uniform float wave_amount = 0.05;

void fragment() {
    vec2 uv = UV;
    uv.x += sin(uv.y * 10.0 + TIME * wave_speed) * wave_amount;
    
    COLOR = texture(TEXTURE, uv);
}

Outline

shader_type canvas_item;

uniform vec4 outline_color : source_color = vec4(0.0, 0.0, 0.0, 1.0);
uniform float outline_width = 2.0;

void fragment() {
    vec4 col = texture(TEXTURE, UV);
    vec2 pixel_size = TEXTURE_PIXEL_SIZE * outline_width;
    
    float alpha = col.a;
    alpha = max(alpha, texture(TEXTURE, UV + vec2(pixel_size.x, 0.0)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(-pixel_size.x, 0.0)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(0.0, pixel_size.y)).a);
    alpha = max(alpha, texture(TEXTURE, UV + vec2(0.0, -pixel_size.y)).a);
    
    COLOR = mix(outline_color, col, col.a);
    COLOR.a = alpha;
}

3D Shaders

Basic 3D Shader

shader_type spatial;

void fragment() {
    ALBEDO = vec3(1.0, 0.0, 0.0);  // Red material
}

Toon Shading (Cel-Shading)

shader_type spatial;

uniform vec3 base_color : source_color = vec3(1.0);
uniform int color_steps = 3;

void light() {
    float NdotL = dot(NORMAL, LIGHT);
    float stepped = floor(NdotL * float(color_steps)) / float(color_steps);
    
    DIFFUSE_LIGHT = base_color * stepped;
}

Screen-Space Effects

Vignette

shader_type canvas_item;

uniform float vignette_strength = 0.5;

void fragment() {
    vec4 color = texture(TEXTURE, UV);
    
    // Distance from center
    vec2 center = vec2(0.5, 0.5);
    float dist = distance(UV, center);
    
    float vignette = 1.0 - dist * vignette_strength;
    
    COLOR = color * vignette;
}

Uniforms (Parameters)

// Float slider
uniform float intensity : hint_range(0.0, 1.0) = 0.5;

// Color picker
uniform vec4 tint_color : source_color = vec4(1.0);

// Texture
uniform sampler2D noise_texture;

// Access in code:
material.set_shader_parameter("intensity", 0.8)

Built-in Variables

2D (canvas_item):

UV - Texture coordinates (0-1)
COLOR - Output color
TEXTURE - Current texture
TIME - Time since start
SCREEN_UV - Screen coordinates

3D (spatial):

ALBEDO - Base color
NORMAL - Surface normal
ROUGHNESS - Surface roughness
METALLIC - Metallic value

Best Practices

1. Use Uniforms for Tweaking

// ✅ Good - adjustable
uniform float speed = 1.0;

void fragment() {
    COLOR.r = sin(TIME * speed);
}

// ❌ Bad - hardcoded
void fragment() {
    COLOR.r = sin(TIME * 2.5);
}

2. Optimize Performance

// Avoid expensive operations in fragment shader
// Pre-calculate values when possible
// Use textures for complex patterns

3. Comment Shaders

// Water wave effect
// Creates horizontal distortion based on sine wave
uniform float wave_amplitude = 0.02;

Reference

Master Skill: godot-master

Weekly Installs

114

Repository

thedivergentai/…c-skills

GitHub Stars

First Seen

Feb 10, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli112

codex111

opencode111

github-copilot108

kimi-cli108

amp108

Minecraft旧版主机版C++重制项目 - 支持模组开发、局域网联机和专用服务器

551 周安装

NEVER hardcodePOSITION 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 useTIME without a speed multiplier — Fragment speed should be controllable via uniforms to ensure consistency across different gameplay states.

NEVER forgethint_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 infragment() 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 orfract() — Shifting UVs beyond 0.0-1.0 without repeat wrapping or clamping will sample edge pixels or return black, breaking texture consistency.

Godot着色器基础教程：片段/顶点着色器、uniform变量与内置变量详解

🇨🇳中文介绍

着色器基础

可用脚本

相关 Skills

着色器中绝对不要做的事

常见 2D 效果

溶解效果

波浪扭曲

描边

3D 着色器

基础 3D 着色器