游戏引擎 / 系统课时

建立一套可调试的 Shader 验证场景

建立一套可调试的 Shader 验证场景

Shader 在编辑器里看起来正常,不代表它能通过参数极值、不同屏幕比例和导出平台的考验。本课搭建一个独立的 Godot 4 验证场景,用并排样本、单实例参数切换和跨设备对照,把视觉异常变成能够重复观察、定位和回归的测试结果。

学习目标

  • 建立能同时观察 Shader 参数边界与材质实例差异的最小测试台。
  • 检查不同视口尺寸、屏幕比例和目标平台下的视觉一致性。
  • 用固定变量、截图和复现记录缩小异常范围。

先定义验证维度与通过条件

不要一边改 Shader、一边改纹理、灯光和窗口大小。先固定场景内容,每次只改变一个变量,再记录差异。下表把常见的“看起来不对”转为可验收的现象。

验证维度 测试动作 预期现象
参数边界 比较 strength 为 0、0.5、1 从蓝绿色棋盘逐步过渡为橙色,无黑块或突变
实例隔离 仅修改中间材质参数 左右两块保持原样
视口比例 比较横屏与竖屏 色块不越界,UV 图案保留完整
目标平台 在实际导出版本中运行 参数响应一致,无明显错色、闪烁或编译错误

Shader 验证场景的三维测试矩阵

搭建可运行的参数测试台

在 Godot 4 中新建一个 2D 场景,以 Node2D 为根节点,命名为 ShaderLab,附加 GDScript 脚本并将该场景设为主场景。以下脚本无需外部纹理:它动态创建三个 ColorRect,共用一份 Shader 代码,却为每块分配独立的 ShaderMaterial。

gdscript
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 回归基线。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立一套可调试的 Shader 验证场景

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通