godot-shaders-basics

着色器中绝对不要做的事

• 绝对不要为了优化而无条件使用 discard — 这会妨碍深度预通道有效工作。丢弃像素仍会消耗顶点处理资源；有时不渲染该对象更好 [1]。
• 绝对不要在高性能着色器中用 if/else 处理动态状态 — GPU 不擅长分支。使用 mix()、step() 和 smoothstep() 进行数学运算，以实现硬件优化的选择 [5, 21]。
• 绝对不要精确比较浮点数 — 硬件精度各不相同；if (v == 0.5) 不可靠。请使用 abs(a - b) < epsilon 或 step()。
• 绝对不要对大量植被使用标准 Alpha 混合 — 这会使阴影和 SSR 无法生效。请使用 Alpha Scissor 或 Alpha Hash（抖动），以启用深度预通道和阴影投射 [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 — 将 UV 偏移到 0.0-1.0 范围之外，且不启用 repeat 环绕或钳制，会采样边缘像素或返回黑色，破坏纹理一致性。

场景 → 脚本触发条件

对于匹配的效果，必须使用。此处不要加载入门级 canvas_item 色调配方或内置变量词汇表。

目标	脚本
不破坏批次的逐敌人受击闪烁	必须使用 instance_uniform_hitflash.gdshader
叶片随风摆动 + 阴影	必须使用 foliage_wind_sway_expert.gdshader（alpha scissor/hash — 不要无条件使用 discard）
保留深度预通道的溶解效果	必须使用 dissolve_scissor_expert.gdshader
后处理像素化 / 风格化	必须使用 screenspace_hex_pixelate.gdshader
全屏四边形（反向 Z）	必须使用 screenspace_full_quad.gdshader
为水面 / 雾效将深度转换为世界坐标	必须使用 depth_world_reconstruction.gdshader
根据玩家位置压平草地	global_grass_flatten.gdshader
无 UV 的悬崖 / 岩石	triplanar_world_mapping.gdshader
实例化网格上的独特纹理	instance_texture_array.gdshader
地形顶点位移	noise_terrain_displacement.gdshader
在运行时为 uniform 设置动画	shader_parameter_animator.gd
VFX 移植模板	vfx_port_shader.gdshader

**镂空 / 溶解的首选方案：**使用 ALPHA_SCISSOR / alpha hash（参见 dissolve 和 foliage 脚本），不要为了优化而使用 discard。切勿列出解释原因的内容。

可用脚本

instance_uniform_hitflash.gdshader

使用实例 uniform 控制闪烁；一个材质，多种独立强度。

dissolve_scissor_expert.gdshader

使用 ALPHA_SCISSOR 实现遮罩溶解，同时保留深度预通道 + 阴影。

foliage_wind_sway_expert.gdshader

用于叶片批次的世界空间风力摆动。

global_grass_flatten.gdshader

使用 global uniform 根据玩家交互压平草地。

screenspace_hex_pixelate.gdshader

使用 hint_screen_texture 实现风格化后处理。

screenspace_full_quad.gdshader

适用于反向 Z 的全矩形后处理通道。

depth_world_reconstruction.gdshader

使用 hint_depth_texture → 世界坐标。

triplanar_world_mapping.gdshader

不使用 UV，沿世界坐标轴投影。

instance_texture_array.gdshader

使用 sampler2DArray + 实例 uniform，为批处理实例指定独特纹理。

noise_terrain_displacement.gdshader

顶点噪声位移。

vfx_port_shader.gdshader

经过验证的 VFX 着色器模板。

shader_parameter_animator.gd

无需 AnimationPlayer，即可为 uniform 设置 Tween / 运行时动画。

shader_warmup_loader.gd

在加载画面期间预热着色器管线，避免首帧卡顿。

专家提示

• 将不变的数学运算移至 vertex()；通过 varying 传递。
• 颜色 uniform 需要 hint_source_color。
• 着色语言内置项优先查阅 Official Docs；此技能负责批处理、scissor、屏幕空间和深度路由。

深度配方（按需查阅）

LLM 忽略规则：如果通用 Agent 在阅读前不会知道某项内容，它就应该放在这里或 scripts/ 中——绝不删除，只能移动。

主题	参考
2D 溶解／波浪／描边	2d-effect-recipes.md
3D 卡通渲染＋暗角	3d-and-postfx-recipes.md
Uniform／内置变量	uniforms-and-builtins.md
雾、计算、预热	expert-advanced-patterns.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作分配给同领域伙伴时加载相关技能——不要预加载整个技能体系。

官方文档

• 着色器简介 — 着色器类型、渲染模式，以及何时使用 ShaderMaterial 而非 StandardMaterial3D 的入门指南。
• 着色语言 — 本技能中广泛使用的核心 GLSL 类语法：uniform、提示、varying、内置变量和预处理器规则。
• CanvasItem 着色器 — 用于精灵、UI 和 2D 后期特效的 2D canvas_item 内置变量（UV、COLOR、TEXTURE、SCREEN_UV）。
• Spatial 着色器 — 用于材质和全屏四边形的 3D spatial 内置变量（ALBEDO、NORMAL、instance uniform、深度／屏幕纹理）。
• 你的第一个 2D 着色器 — 最精简的 canvas_item 工作流，涵盖从附加 ShaderMaterial 到片段着色的过程。
• 你的第一个 3D 着色器 — 最精简的 spatial 工作流，以及将 StandardMaterial3D 转换为可编写着色器的路径。
• ShaderMaterial — 动画师和受击闪光批处理所用的运行时 set_shader_parameter／实例参数 API。
• 自定义后期处理 — 屏幕读取着色器、hint_screen_texture，以及像素化／暗角类特效的合成模式。
• 高级后期处理 — 水面／雾效／调试可视化工具所需的深度缓冲区、反向 Z 和世界重建。
• 计算着色器 — 用于粒子模拟和其他非片段工作负载的 RenderingDevice GPGPU 路径。
• 使用 VisualShaders — 专家模式中涵盖的图形编辑器和 VisualShaderNodeCustom 扩展机制。
• GPU 优化 — 关于过度绘制、透明度和批处理的指导，说明了 alpha scissor、实例 uniform，以及顶点与片段成本之间取舍的依据。

相关技能

前置条件

• godot-project-foundations — 在附加 ShaderMaterial 和交付 .gdshader 资源之前必须掌握的节点、资源和项目布局知识。
• godot-resource-data-patterns — 共享或复制 ShaderMaterial／Shader 资源，确保 uniform 和实例参数适合批处理。

补充内容

• godot-3d-materials — 优先使用 StandardMaterial3D/ORM；对于三平面、溶解和实例统一效果，再升级到空间着色器。
• godot-3d-lighting — 介绍自定义 ALBEDO/EMISSION/light() 输出与 Forward+、GI 和雾体积之间的交互方式。
• godot-particles — 粒子处理/绘制材质和 Alpha 管线必须与此技能中的剪裁/哈希和混合选项相匹配。
• godot-2d-animation — 用于在动画精灵上实现风格化 2D 动态、轮廓和溶解效果的 CanvasItem 着色器钩子。
• godot-camera-systems — 屏幕空间和深度重建着色器所依赖的摄像机近/远裁剪面以及视图/投影矩阵。
• godot-performance-optimization — 绘制调用批处理、MultiMesh 和 GPU 预算有助于说明为何使用 instance uniform 并避免使用唯一材质。
• godot-debugging-profiling — 使用 GPU/过度绘制分析器和调试视图来验证着色器开销以及深度/法线可视化效果。

下游/使用方

• godot-procedural-generation — 程序化网格/地形会使用此技能中的噪声位移、三平面和无 UV 空间图案。
• godot-3d-world-building — 大型环境道具会在关卡尺度上应用植被风动、草地压平和世界投影着色器。
• godot-genre-open-world — 开放世界植被交互、距离特效和共享材质批处理会使用这些着色器模板。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。