游戏引擎 / 系统课时
建立一套可调试的 Shader 验证场景
建立一套可调试的 Shader 验证场景
Shader 在编辑器里看起来正常,不代表它能通过参数极值、不同屏幕比例和导出平台的考验。本课搭建一个独立的 Godot 4 验证场景,用并排样本、单实例参数切换和跨设备对照,把视觉异常变成能够重复观察、定位和回归的测试结果。
学习目标
- 建立能同时观察 Shader 参数边界与材质实例差异的最小测试台。
- 检查不同视口尺寸、屏幕比例和目标平台下的视觉一致性。
- 用固定变量、截图和复现记录缩小异常范围。
先定义验证维度与通过条件
不要一边改 Shader、一边改纹理、灯光和窗口大小。先固定场景内容,每次只改变一个变量,再记录差异。下表把常见的“看起来不对”转为可验收的现象。
| 验证维度 | 测试动作 | 预期现象 |
|---|---|---|
| 参数边界 | 比较 strength 为 0、0.5、1 |
从蓝绿色棋盘逐步过渡为橙色,无黑块或突变 |
| 实例隔离 | 仅修改中间材质参数 | 左右两块保持原样 |
| 视口比例 | 比较横屏与竖屏 | 色块不越界,UV 图案保留完整 |
| 目标平台 | 在实际导出版本中运行 | 参数响应一致,无明显错色、闪烁或编译错误 |

搭建可运行的参数测试台
在 Godot 4 中新建一个 2D 场景,以 Node2D 为根节点,命名为 ShaderLab,附加 GDScript 脚本并将该场景设为主场景。以下脚本无需外部纹理:它动态创建三个 ColorRect,共用一份 Shader 代码,却为每块分配独立的 ShaderMaterial。
extends Node2D
const LEVELS = [0.0, 0.5, 1.0]
var panels: Array[ColorRect] = []
var captions: Array[Label] = []
var materials: Array[ShaderMaterial] = []
var elevated := false
func _ready() -> void:
var shader := Shader.new()
shader.code = """
shader_type canvas_item;
uniform float strength : hint_range(0.0, 1.0) = 0.5;
void fragment() {
vec2 cell = floor(UV * 8.0);
float checker = mod(cell.x + cell.y, 2.0);
vec3 base = mix(vec3(0.12, 0.27, 0.40), vec3(0.30, 0.70, 0.72), checker);
COLOR = vec4(mix(base, vec3(1.0, 0.45, 0.12), strength), 1.0);
}
"""
for i in range(LEVELS.size()):
# 共用 Shader 代码,但每块独享材质资源与参数。
var material := ShaderMaterial.new()
material.shader = shader
material.set_shader_parameter("strength", LEVELS[i])
materials.append(material)
var panel := ColorRect.new()
panel.color = Color.WHITE
panel.material = material
add_child(panel)
panels.append(panel)
var caption := Label.new()
caption.text = "strength = %.1f" % LEVELS[i]
add_child(caption)
captions.append(caption)
# 视口尺寸改变时重新排列测试样本。
get_viewport().size_changed.connect(_layout)
_layout()
func _layout() -> void:
var viewport_size := get_viewport_rect().size
var margin := 20.0
var gap := 12.0
var tile_width := maxf(1.0, (viewport_size.x - 2.0 * margin - 2.0 * gap) / 3.0)
var tile_height := maxf(1.0, minf(tile_width * 0.75, viewport_size.y * 0.5))
for i in range(panels.size()):
var x := margin + float(i) * (tile_width + gap)
panels[i].position = Vector2(x, 60.0)
panels[i].size = Vector2(tile_width, tile_height)
captions[i].position = Vector2(x, 24.0)
func _unhandled_input(event: InputEvent) -> void:
if event is InputEventKey and event.pressed and not event.echo and event.keycode == KEY_SPACE:
# 仅修改中间样本,检查是否发生实例参数串改。
elevated = not elevated
var value := 0.8 if elevated else 0.5
materials[1].set_shader_parameter("strength", value)
captions[1].text = "strength = %.1f" % value预期结果:运行场景后出现标为 0.0、0.5、1.0 的三个色块。左侧保留蓝绿棋盘,中间带橙色混合,右侧为纯橙色;每个色块的 UV 图案为 8×8 格。按空格键,中间样本在 0.5 与 0.8 之间切换,左右样本不变。改变有效视口尺寸后,三个样本重新排布。
验证尺寸、材质和平台差异
先在常见横屏尺寸(如 1280×720)观察三块内容,再在竖屏尺寸(如 720×1280)复测。可调整项目的窗口与视口设置,或使用能够实际改变视口尺寸的运行方式;窗口物理像素大小不一定等于逻辑视口大小,不能只凭拖大窗口就认定完成分辨率测试。
拍摄对比图时保持 Shader、色彩参数与渲染设置不变,重点看图案是否缺角、色块边缘是否出现接缝、标签是否被截断。棋盘始终是每块 8×8 格,但单格的屏幕形状可随色块宽高比变化,这不是 Shader 采样错误。
然后将同一测试场景放进项目实际使用的桌面、移动端或 Web 导出版本,在真实目标设备或浏览器中复测。记录 Godot 版本、渲染器、设备、视口大小、测试参数和截图;不能导出的平台标为“未验证”,不要以编辑器预览代替平台验收。
这个测试台刻意不依赖贴图和光照,因此只能证明当前 canvas_item 示例的参数与显示链路。检查真实的屏幕采样、纹理过滤或 3D 光照效果时,应在同一验证方法下替换为对应场景与 Shader,不可直接沿用它的通过结论。
出现异常时缩小变量范围
遇到黑屏或整块颜色异常,先看 Godot 的 Shader 编译报错,再确认材质是否确实分配给目标节点,以及 set_shader_parameter 名称是否与 uniform 的 strength 完全一致。若三个样本一起变化,重点检查是否误用了同一个 ShaderMaterial 资源,而不仅仅是共享 Shader 代码。
只有尺寸变化后才出错时,先检查视口、UV 和拉伸配置;只有某个导出平台才出错时,保留同一组输入,对照渲染器支持情况及目标设备表现。遇到卡顿,则在固定分辨率与相同硬件上使用性能分析器复测,不要把单张截图或一次帧率波动当作性能结论。
每次修复后重新跑参数边界、实例隔离、横竖屏和目标平台检查,并把失败前后的参数与截图一起保存。这样验证场景不只是临时演示,而是能够持续复用的 Shader 回归基线。