godot-shaders

Godot 着色器（4.x）

使用 Godot 着色语言编写 canvas_item（2D）和 spatial（3D）着色器，使用 TIME/UV 制作动画，公开 uniform，并读取屏幕内容。目标版本为 Godot 4.7。

适用场景

• 编写 .gdshader 代码或使用 ShaderMaterial 时：2D 效果（描边、溶解、闪光、水面）、3D 表面着色器（边缘光、卡通着色、滚动 UV）或屏幕空间后期效果。

不适用场景： 跨引擎的着色概念（UV、顶点/片段理论）→ shader-programming；粒子/VFX 节点 → 通用 3D；非着色器视觉效果。

核心工作流

1. 在第一行选择着色器类型： 2D 使用 shader_type canvas_item;（Sprite2D、TextureRect 以及任何 CanvasItem），3D 使用 shader_type spatial;。 （此外还有 particles、sky、fog。）
2. 通过 ShaderMaterial 附加着色器。 创建 ShaderMaterial，指定 .gdshader，并将其赋给节点的 material。Uniform 会显示在检查器中。
3. 编写 fragment() 来设置输出：2D 使用 COLOR，3D 使用 ALBEDO/EMISSION/ALPHA。也可以编写 vertex() 移动几何体，并编写 light() 自定义光照。
4. **使用带提示的 uniform 暴露可调参数，**例如 source_color、hint_range，以便编辑并正确管理颜色。
5. **使用内置的 TIME 制作动画，**并使用 texture(tex, UV) 采样纹理。
6. **通过代码设置 uniform，**使用 material.set_shader_parameter("name", value)。

常用模式

1. 2D（canvas_item）：着色 + UV 滚动

shader_type canvas_item;

uniform vec4 tint : source_color = vec4(1.0);     // source_color = sRGB-correct color
uniform float scroll_speed : hint_range(0.0, 2.0) = 0.3;

void fragment() {
    vec2 uv = UV;
    uv.x += TIME * scroll_speed;                  // scroll horizontally over time
    COLOR = texture(TEXTURE, uv) * tint;          // TEXTURE = the node's texture
}

2. 使用噪声阈值实现 2D 溶解

shader_type canvas_item;

uniform sampler2D noise : repeat_enable;          // a NoiseTexture2D
uniform float amount : hint_range(0.0, 1.0) = 0.0;

void fragment() {
    vec4 tex = texture(TEXTURE, UV);
    float n = texture(noise, UV).r;
    if (n < amount) {
        discard;                                  // cut the pixel away
    }
    COLOR = tex;
}

3. 3D（spatial）：发光边缘光

shader_type spatial;

uniform vec4 base_color : source_color = vec4(0.2, 0.5, 1.0, 1.0);
uniform vec3 rim_color : source_color = vec3(0.6, 0.8, 1.0);
uniform float rim_power : hint_range(0.5, 8.0) = 3.0;

void fragment() {
    ALBEDO = base_color.rgb;
    // VIEW and NORMAL are view-space built-ins; rim is strong at grazing angles.
    float rim = pow(1.0 - dot(NORMAL, VIEW), rim_power);
    EMISSION = rim_color * rim;
}

4. 读取屏幕的后期效果（4.x 提示，不使用 SCREEN_TEXTURE）

shader_type canvas_item;

// 4.x: declare the screen as a uniform with hint_screen_texture.
uniform sampler2D screen_tex : hint_screen_texture, filter_linear_mipmap;
uniform float blur : hint_range(0.0, 4.0) = 1.0;

void fragment() {
    vec2 px = SCREEN_PIXEL_SIZE * blur;
    vec4 c = texture(screen_tex, SCREEN_UV);
    c += texture(screen_tex, SCREEN_UV + vec2(px.x, 0.0));
    c += texture(screen_tex, SCREEN_UV - vec2(px.x, 0.0));
    COLOR = c / 3.0;
}

使用 GDScript 设置 uniform：

$Sprite2D.material.set_shader_parameter("amount", 0.7)

常见问题

• 3.x → 4.x 名称变更。 SCREEN_TEXTURE 已移除——声明 uniform sampler2D x : hint_screen_texture; 并使用 SCREEN_UV 采样。颜色提示 hint_color→source_color；hint_albedo/hint_white→source_color； hint_range 保持不变。深度/法线使用 hint_depth_texture / hint_normal_roughness_texture。
• 输出变量错误。 在 canvas_item 中写入 COLOR；在 spatial 中写入 ALBEDO （以及 EMISSION、ALPHA、ROUGHNESS、METALLIC）。在 spatial 着色器中写入 COLOR 不会产生任何效果。
• 颜色 uniform 未使用 source_color 时会被视为原始线性值，显示效果会不正确（泛白/发暗），因为 Godot 不会将其转换为 sRGB。
• 透明效果需要主动启用（3D）。 若要让 ALPHA < 1.0 产生混合效果，请添加渲染模式或设置材质透明度；否则会呈现不透明/裁切效果。
• **对 [0,1] 之外的 UV 采样时，**若未启用 repeat_enable，坐标会被钳制。要平铺/滚动，请在采样器 uniform 中添加 : repeat_enable。
• **TIME 是从启动开始计算的秒数，**并会持续增长——周期性效果请使用 fract()/mod() 循环，以避免精度漂移。
• **discard 在某些硬件上开销较大，**且会破坏提前 Z；可以时优先设置 ALPHA/COLOR.a。

参考资料

• 有关各着色器类型的内置变量、渲染模式、varying、自定义 light()、vertex() 位移以及视觉着色器图，请阅读 references/shading-language.md。

相关技能

• shader-programming — 与引擎无关的着色器概念（GLSL/HLSL）。
• godot-3d-essentials — 材质、环境以及 spatial 着色器所在位置。
• godot-ui-control — 将着色器应用于 UI 效果。