游戏引擎 / 系统课时
让脚本在运行时修改 Shader 参数
让脚本在运行时修改 Shader 参数
角色受击闪光、技能蓄力和进度条填充都需要在游戏运行时改变 Shader 效果,而不是反复创建新材质。本课使用 Godot 4 制作一个两秒内逐渐展开的色块,演示如何从节点取得 ShaderMaterial,安全修改颜色、强度和时间进度,并验证最终效果。
学习目标
- 理解 Shader 的 uniform 参数如何与 GDScript 中的游戏状态关联。
- 掌握读取、检查和修改 ShaderMaterial 参数的方法。
- 实现一个由脚本控制颜色、强度和显示进度的动态效果。
Shader 参数怎样接收游戏状态
Shader 负责计算像素的最终表现,但通常不知道角色当前生命值、技能蓄力百分比或 UI 动画进度。脚本掌握这些游戏状态,需要通过 ShaderMaterial 把数值传递给 Shader。
在 Godot 4 中,Shader 通过 uniform 声明外部参数。ShaderMaterial 保存这些参数的实际取值,GDScript 则使用 set_shader_parameter() 修改它们。
例如,一个受击效果可以包含三个参数:
| 参数 | Shader 类型 | GDScript 类型 | 作用 |
|---|---|---|---|
effect_color |
vec4 |
Color |
指定效果颜色 |
intensity |
float |
float |
控制颜色混合强度 |
progress |
float |
float |
控制效果展开进度 |
这三个参数的职责不同。颜色决定视觉方向,强度决定效果覆盖程度,进度决定效果显示多少。将它们分开,可以让同一个 Shader 服务于不同的游戏行为。

这里需要区分两个对象:Shader 是效果计算程序,ShaderMaterial 是保存 Shader 引用和参数值的资源。多个材质可以使用同一个 Shader,却保留不同的参数值。
准备一个可以控制的 Shader
在 Godot 4 中创建一个以 Node2D 为根节点的场景,添加名为 Panel 的 ColorRect 子节点,将其颜色设置为白色,尺寸设置为 320×90,并放在可视区域内。
为 Panel 创建一个 ShaderMaterial,再创建 Shader 资源,保存为 res://progress.gdshader,将它指定给 ShaderMaterial。
以下是这个 Shader 文件的完整内容:
shader_type canvas_item;
uniform vec4 effect_color : source_color = vec4(0.1, 0.75, 1.0, 1.0);
uniform float intensity : hint_range(0.0, 1.0) = 0.0;
uniform float progress : hint_range(0.0, 1.0) = 0.0;
void fragment() {
vec4 base_color = COLOR;
// 根据水平UV坐标生成从左向右展开的可见区域。
float visible = step(UV.x, progress);
vec3 final_color = mix(base_color.rgb, effect_color.rgb, intensity);
COLOR = vec4(final_color, base_color.a * visible);
}effect_color 使用 source_color 提示,使颜色参数按照颜色数据处理。两个浮点参数使用 hint_range,方便在检查器中调整,但运行时代码仍应自行限制取值范围。
mix() 根据 intensity 在原始颜色与目标颜色之间插值。step() 比较像素的水平 UV 坐标和 progress,决定当前像素是否可见。
当 progress 为 0 时,色块几乎完全隐藏;为 0.5 时,左半部分可见;为 1 时,整个色块显示出来。
使用 GDScript 更新参数
把下面的完整脚本挂到场景根节点 Node2D 上。脚本读取 Panel 的材质,在确认类型正确后复制一个运行时实例,然后设置初始参数并逐帧推进显示进度。
extends Node2D
@onready var panel: ColorRect = $Panel
var runtime_material: ShaderMaterial
var elapsed_seconds: float = 0.0
func _ready() -> void:
var source_material := panel.material as ShaderMaterial
# 先检查资源类型,避免对空引用调用材质接口。
if source_material == null:
push_error("Panel 必须配置 ShaderMaterial")
set_process(false)
return
# 复制材质,避免运行时修改影响其他共享该资源的节点。
runtime_material = source_material.duplicate() as ShaderMaterial
panel.material = runtime_material
runtime_material.set_shader_parameter("effect_color", Color(0.15, 0.7, 1.0))
runtime_material.set_shader_parameter("intensity", 0.8)
runtime_material.set_shader_parameter("progress", 0.0)
print("Shader 参数初始化完成")
func _process(delta: float) -> void:
# 用真实经过的时间驱动动画,而不是按帧数累加。
elapsed_seconds += delta
var progress: float = clampf(elapsed_seconds / 2.0, 0.0, 1.0)
runtime_material.set_shader_parameter("progress", progress)
if progress >= 1.0:
set_process(false)预期输出:
Shader 参数初始化完成预期画面:运行场景后,Panel 从左向右逐渐显示蓝色系填充,约两秒后完全展开并停止更新。颜色不是纯蓝,而是根据 intensity = 0.8 与原始白色混合的结果。
这里有几个值得注意的设计:
- 使用
as ShaderMaterial获取材质,并处理获取失败的情况。 - 在修改前调用
duplicate(),隔离当前节点的运行时参数。 - 通过
delta累积时间,避免不同帧率导致动画速度不同。 - 使用
clampf()把进度限制在 0~1,防止数据越界。 - 动画结束后关闭
_process(),避免继续写入不再变化的参数。
参数修改无效时怎样定位
运行后如果没有看到效果,不要立即重写 Shader。可以按照数据传递顺序检查问题。
首先确认 Panel 的 Material 确实是 ShaderMaterial,而不是普通的 CanvasItemMaterial。再确认 ShaderMaterial 的 Shader 属性指向包含上述 uniform 定义的资源。
其次检查参数名称。set_shader_parameter() 的第一个参数必须与 Shader 中的 uniform 名称完全一致,而且区分大小写。检查器中的显示名称可能经过格式化,不能直接作为脚本参数名。
最后检查类型和数值范围。vec4 颜色参数可以使用 Color,浮点参数使用浮点数。如果 intensity 始终为 0,即使脚本正确修改颜色,也不会看到颜色混合效果。
在游戏逻辑中选择更新时机
并不是所有 Shader 参数都需要每帧更新。受击闪白可以在受击时设置强度,再在短暂动画期间衰减;角色阵营颜色通常只需在角色创建或阵营变化时更新;血条进度可以在生命值改变时更新。
如果数值只在事件发生时变化,应优先使用事件驱动的更新方式。只有持续动画、连续输入或逐帧变化的状态才需要在 _process() 中传值。
还要区分游戏时间与 Shader 内置的 TIME。自动循环的波纹、噪声滚动可以直接使用 Shader 时间;需要与技能开始、暂停、重播或网络状态严格对应的进度,则更适合由脚本计算后写入 uniform。
最终应把 Shader 看作接收参数并生成画面的渲染模块。游戏逻辑负责决定参数什么时候变化、变化到多少;Shader 不必知道技能、生命值或任务系统的内部实现。