Godot CanvasItemMaterial 完全指南：混合模式、光照模式与 2D 粒子翻页动画实战-平芜编程栈

文档
教程
游戏开发

【免费下载链接】godot-docs

Godot Engine official documentation

项目地址：https://gitcode.com/GitHub_Trending/go/godot-docs

CanvasItemMaterial 是 Godot 中为 2D 场景节点（CanvasItem）定制纹理渲染方式的专用材质。本文以仓库中 CanvasItemMaterial 官方类文档为骨架，系统讲解其五大混合模式、三大光照模式，以及专为 2D 粒子系统设计的翻页动画（Flipbook）属性，并结合仓库教程与类定义源码给出可直接落地的编辑器操作和 GDScript 配置方案。

一、CanvasItemMaterial 是什么：定位与继承关系

CanvasItemMaterial 是 Godot 引擎内置的一种材质，用于修改与 CanvasItem 相关联的纹理。其官方描述指出，它专精于描述纹理的**混合（Blend）与光照（Lighting）**行为；如果需要对 CanvasItem 与光照的交互进行更彻底的自定义，则应改用 ShaderMaterial（见 CanvasItemMaterial 类文档）。

继承链

CanvasItemMaterial < Material < Resource < RefCounted < Object

在 Godot 的类引用中，继承方向为从左到右（子类在前，父类在后）。CanvasItemMaterial 继承自 Material，而 Material 本身是一个 Resource（资源），因此材质可以像其他资源一样被保存、复用和共享。

Material 资源最终被挂载到某个CanvasItem节点上。CanvasItem 是所有 2D 空间的抽象基类：Node2D（2D 游戏对象）和Control（GUI 控件）都继承自它（见 CanvasItem 类文档）。CanvasItem 本身具备material、modulate、self_modulate、texture_filter、texture_repeat、z_index等属性，其中material属性就是 CanvasItemMaterial 的挂载点（CanvasItem 属性表）。

在仓库中的使用场景

2D 粒子系统的翻页动画：让 GPUParticles2D / CPUParticles2D 使用雪碧图（spritesheet）逐帧播放动画。
2D 光照与阴影：控制精灵在 2D 光照下的反应，例如不参与光照、只显示光照等。
纹理导入优化：配合预乘 Alpha（Premultiplied Alpha）纹理，修复带 Alpha 边缘的暗边问题。

二、BlendMode 混合模式：五种纹理合成方式

blend_mode属性决定了材质的渲染如何作用于其下的纹理，即当前像素如何与画布上已有的像素合成。CanvasItemMaterial 提供 5 种混合模式（枚举BlendMode）：

常量	值	说明
`BLEND_MODE_MIX`	`0`	标准混合（默认）。颜色被视为与 Alpha（不透明度）无关的独立值。
`BLEND_MODE_ADD`	`1`	加法混合。常用于火焰、光效、爆炸等发光效果。
`BLEND_MODE_SUB`	`2`	减法混合。
`BLEND_MODE_MUL`	`3`	乘法混合。常用于阴影、遮罩类效果。
`BLEND_MODE_PREMULT_ALPHA`	`4`	混合模式，但颜色被视为已经由 Alpha 预先乘过（Premultiplied Alpha）。

属性默认值为0（即BLEND_MODE_MIX），对应访问器为set_blend_mode(value)与get_blend_mode()（见 CanvasItemMaterial 属性描述）。

关键细节

MIX 与 PREMULT_ALPHA 的区别：两者表面都是"混合"，但前提不同——MIX 假设颜色通道独立于 Alpha；PREMULT_ALPHA 假设纹理颜色已经与透明度相乘（即 RGB 值被预先乘以 A 值）。后者配合"预乘 Alpha"导入格式的纹理使用，可避免半透明边缘出现暗色描边。

实战：为 Sprite2D 配置加法混合

在 2D 光照与阴影教程中，官方推荐用加法混合的精灵替代部分 2D 光源，以获得更快渲染性能，特别适合子弹、爆炸这类短命动态特效：

加法精灵的渲染不需要经过独立的光照渲染管线，因此比 2D 光源快得多，且可与 AnimatedSprite2D（或 Sprite2D + AnimationPlayer）组合，创建动画化的 2D"光源"。

但需要注意其局限（该教程原文明确列出）：

混合公式不如"真正"的 2D 光照准确，无法正确照亮完全黑暗的区域；
加法精灵不是光源，无法投射阴影；
加法精灵会忽略其他精灵上的法线贴图和镜面贴图。

编辑器操作步骤：

创建 Sprite2D 节点并为其指定纹理；
在检视面板滚动到CanvasItem > Material区域，展开后点击Material属性旁的下拉菜单；
选择New CanvasItemMaterial，点击新创建的材质进入编辑；
将Blend Mode设置为Add（见 2D 光照与阴影教程）。

实战：Premultiplied Alpha 材质匹配

在导入图片教程中，官方指出"修复暗色边缘的另一种方案是使用预乘 Alpha"。启用该导入选项后，纹理会被转换为预乘格式，此时必须配合特定材质才能正确显示：

在 2D 中，为使用该纹理的 CanvasItem 创建 CanvasItemMaterial，并将其混合模式设为Premultiplied Alpha；
若使用自定义 CanvasItem Shader，则应使用render_mode blend_premul_alpha;。

GDScript 运行时配置示例

# 为 CanvasItem（如 Sprite2D）动态创建并配置 CanvasItemMaterial var mat := CanvasItemMaterial.new() mat.blend_mode = CanvasItemMaterial.BLEND_MODE_ADD # 挂载到节点 $Sprite2D.material = mat

三、LightMode 光照模式：控制材质对 2D 光照的反应

light_mode属性决定材质如何响应光照。CanvasItemMaterial 提供 3 种光照模式（枚举LightMode）：

常量	值	说明
`LIGHT_MODE_NORMAL`	`0`	正常模式（默认）。同时使用对光照敏感与不敏感两类材质属性进行渲染。
`LIGHT_MODE_UNSHADED`	`1`	无光照模式。材质渲染时如同不存在任何光照。
`LIGHT_MODE_LIGHT_ONLY`	`2`	仅光照模式。材质渲染时如同只存在光照。

属性默认值为0（LIGHT_MODE_NORMAL），对应访问器为set_light_mode(value)与get_light_mode()（见 CanvasItemMaterial 属性描述）。

典型用途

UNSHADED：UI 元素、背景装饰等不希望被 2D 光照影响的对象；或在不需要光照计算的渲染场景下节省开销。
LIGHT_ONLY：搭配modulate等属性，让对象只呈现光照效果，常用来制作纯受光物体或光照可视化调试。

GDScript 示例

var mat := CanvasItemMaterial.new() mat.light_mode = CanvasItemMaterial.LIGHT_MODE_UNSHADED # 让精灵完全不受 2D 光照影响 $Sprite2D.material = mat

四、粒子翻页动画（Flipbook）：particles_anim_* 四件套

这是 CanvasItemMaterial 最具特色的能力：让 2D 粒子系统播放雪碧图序列帧动画。官方文档将其应用范围明确限定在 GPUParticles2D 与 CPUParticles2D 节点上。

属性一览

属性	类型	默认值	说明
`particles_animation`	bool	`false`	启用基于雪碧图的动画功能。设为`true`后，其余`particles_anim_*`属性才会生效并在编辑器中可见。
`particles_anim_h_frames`	int	—	雪碧图的列数。
`particles_anim_v_frames`	int	—	雪碧图的行数。
`particles_anim_loop`	bool	—	设为`true`时，粒子动画将循环播放。

对应访问器：set_particles_animation(bool)/get_particles_animation()、set_particles_anim_h_frames(int)/get_particles_anim_h_frames()、set_particles_anim_v_frames(int)/get_particles_anim_v_frames()、set_particles_anim_loop(bool)/get_particles_anim_loop()。

关键约束（官方文档原文要点）

particles_anim_h_frames与particles_anim_v_frames只有在particles_animation为true时才被使用、并在编辑器中可见；
particles_animation开启后，还必须把ParticleProcessMaterial.anim_speed_max（GPUParticles2D 路径）或CPUParticles2D.anim_speed_max设置为正值，动画才会播放；
particles_animation（及依赖它的其他particles_anim_*属性）对其他类型的节点没有效果。

从类定义源码看依赖关系

在 CanvasItemMaterial 类文档中，particles_animation的说明明确引用：

ParticleProcessMaterial.anim_speed_max（对应 ParticleProcessMaterial 类）；
CPUParticles2D.anim_speed_max，该类文档中该属性默认值为0.0（见 CPUParticles2D 类文档）。

即：粒子动画的播放速度由粒子节点的动画速度参数驱动，CanvasItemMaterial 只负责"如何切帧"，不负责"切多快"。

实战：为 GPUParticles2D 配置翻页动画

以下流程来自官方 2D 粒子系统教程的 "Using an animation flipbook" 小节。官方示例使用了一张5 列 × 7 行的翻转书纹理：

在场景中创建GPUParticles2D节点，并在检视面板的Process Material中添加New ParticleProcessMaterial；
在Texture属性中载入你的翻转书雪碧图（教程配图，示例纹理 5 列 7 行，来源为 JoesAlotofthings 的开源粒子素材，CC BY 4.0）；
在粒子节点的Material区域创建New CanvasItemMaterial（见创建截图）；
在新材质中勾选Particle Animation，将H Frames设为列数（5）、V Frames设为行数（7），并按需勾选Particles Anim Loop（见配置截图）；
随后，ParticleProcessMaterial（GPUParticles2D）或 CPUParticles2D 检视面板中的Animation 区域设置才会生效——将Speed Min / Speed Max设为正值（教程举例：设为 1 可线性播放），动画即可播放（参考粒子流程材质 2D 教程的 Animation 小节）。

重要提示（官方原文）：若翻转书纹理是黑色背景而非透明背景，需将混合模式改为Add才能正确显示；也可以先在图像编辑器中把纹理处理为透明背景（如 GIMP 的Color > Color to Alpha）。

粒子节点选型建议

官方 2D 粒子系统教程指出：

GPUParticles2D：更高级，使用 GPU 处理粒子效果，通过 ParticleProcessMaterial 配置；
CPUParticles2D：CPU 驱动，与 GPUParticles2D 功能几乎一致，但大量粒子时性能较低；在低端设备或 GPU 瓶颈场景可能反而表现更好；
官方明确表示今后不会再为 CPUParticles2D 添加新功能（但接受合并 GPUParticles2D 已有功能的 PR），因此推荐默认使用 GPUParticles2D，除非有明确理由；
可通过工具栏CPUParticles2D > Convert to GPUParticles2D相互转换（反向转换在使用了仅 GPU 特性时可能出问题）。

五、综合应用：一张可复制的完整 GDScript 配置

将混合模式、光照模式与粒子动画结合，可得到一段完整的运行时配置示例：

extends GPUParticles2D func _ready() -> void: # 为粒子节点创建 CanvasItemMaterial 并启用雪碧图动画 var mat := CanvasItemMaterial.new() mat.particles_animation = true mat.particles_anim_h_frames = 5 # 雪碧图列数 mat.particles_anim_v_frames = 7 # 雪碧图行数 mat.particles_anim_loop = true mat.blend_mode = CanvasItemMaterial.BLEND_MODE_ADD # 黑色背景翻转书需要加法混合 material = mat # 注意：还需在 ParticleProcessMaterial 上设置动画速度（正数）才会播放 # 例如 process_material.anim_speed_min / anim_speed_max

# 若使用 CPUParticles2D，则动画速度在节点属性上配置： # cpuparticles.anim_speed_min = 1.0 # cpuparticles.anim_speed_max = 1.0

六、相关资源速查

类文档：CanvasItemMaterial、CanvasItem、Material、ParticleProcessMaterial、GPUParticles2D、CPUParticles2D
教程：2D 粒子系统、粒子流程材质（2D）、2D 光照与阴影、导入图片
配图：粒子翻页动画创建截图、配置截图

小结：CanvasItemMaterial 用两个枚举（BlendMode 5 值、LightMode 3 值）加四个粒子动画属性，覆盖了 2D 纹理混合、光照响应与粒子翻页动画三大核心场景。编辑器中的每一步操作都能在官方教程与类文档中找到对应说明；将 Blend Mode 设为 Add、将 Light Mode 设为 Unshaded、勾选 Particle Animation 并配置行列帧数，是最常被组合使用的三组配置。若需更自由的着色器级控制（如逐像素光照、自定义混合公式），官方文档建议进一步使用 ShaderMaterial。