最后同步日期：2026-04-15 | Godot 官方原文 — GPUParticles3D

GPUParticles3D

节点继承关系

继承链：Node → Node3D → GeometryInstance3D → GPUParticles3D

GeometryInstance3D

类型	名称	说明
属性	MaterialOverride	材质覆盖
属性	CastShadow	阴影投射模式
属性	VisibilityRangeBegin	可见距离起始
属性	Transparency	透明度模式

Node3D

类型	名称	说明
属性	Position	本地位置（X / Y / Z）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（欧拉角，弧度）
属性	Scale	缩放比例
属性	TopLevel	是否脱离父节点的变换
方法	LookAt()	朝向目标点
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标
方法	RotateX/Y/Z()	绕指定轴旋转

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

运行在显卡（GPU）上的 3D 粒子系统（Particle System）——GPUParticles2D 的 3D 版本，能在三维空间中产生大量粒子，模拟更真实的三维特效。

就像 GPUParticles2D 是在一张纸上撒发光粉末，GPUParticles3D 则是在一个真实的三维空间里撒粉末。粒子可以前后左右上下飞散，配合 3D 光照和阴影，效果更加逼真。

使用频率：★★★★ 常用——3D 游戏中最常用的特效节点。

节点用途

• 3D 火焰、爆炸效果
• 3D 烟雾、蒸汽效果
• 雨滴、雪花（在 3D 空间中）
• 魔法特效、技能光效
• 场景装饰（萤火虫、灰尘、光斑）
• 水花、气泡效果

使用场景

典型场景

• 3D 角色技能：角色施放火球术时，火球周围产生火焰粒子
• 3D 环境效果：洞穴中的灰尘、森林中的萤火虫、瀑布产生的水雾
• 爆炸效果：炸弹爆炸时的碎片和烟尘
• 天气效果：3D 空间中的雨雪

不适用场景

• 2D 游戏中的粒子效果 → 使用 GPUParticles2D
• 需要逐粒子精确控制 → 使用 CPUParticles3D

常用节点搭配

搭配节点	用途	必需？
ParticleProcessMaterial	控制粒子的运动方式	必需
Texture2D（贴图资源）	粒子的外观图片	推荐
GPUParticlesCollision3D 系列	让粒子碰到物体后反弹	可选
GPUParticlesAttractor3D 系列	让粒子被吸引或排斥	可选

典型节点树：

Explosion (GPUParticles3D)
├── GPUParticlesCollisionSDF3D  ← 粒子碰撞（可选）
└── GPUParticlesAttractorSphere3D  ← 粒子吸引（可选）

生效必备素材/资源

资源	类型	说明
ParticleProcessMaterial	ShaderMaterial	赋给 process_material 属性，控制粒子运动
粒子贴图	Texture2D	赋给 texture 属性，决定粒子外观

节点属性与信号

粒子基础设置

属性	类型	默认值	继承自	说明
amount	int	—	—	粒子数量。3D 场景中建议根据重要性调整，远处效果可以少一些
process_material	ParticleProcessMaterial	—	—	粒子运动材质
texture	Texture2D	—	—	粒子贴图
draw_order	枚举	Index	—	粒子绘制顺序。Index 按索引、Lifetime 按剩余生命、ReverseLifetime 反向、ViewDepth 按深度

生命周期

属性	类型	默认值	继承自	说明
lifetime	float	—	—	每个粒子存活时间（秒）
one_shot	bool	false	—	是否只播放一次
explosiveness	float	0.0	—	爆炸性。0 = 均匀分布，1 = 同时爆发
randomness	float	0.0	—	随机性

3D 独有属性

属性	类型	默认值	继承自	说明
local_coords	bool	false	—	使用局部坐标。true = 粒子跟随父节点移动，false = 粒子在世界坐标中独立运动
draw_passes	int	1	—	绘制通道数量，可以同时使用多个 Mesh 来渲染粒子
trail_enabled	bool	false	—	是否开启粒子拖尾效果
trail_lifetime	float	0.3	—	拖尾持续时间
trail_sections	int	8	—	拖尾的段数，越多越平滑

信号

信号	触发时机	继承自	说明
finished	粒子系统播放完毕	—	仅在 one_shot = true 时触发

常用方法

方法	返回值	说明
Emit(count)	void	手动发射指定数量的粒子
Restart()	void	重启粒子系统
GetAmount()	int	获取粒子数量
GetLifetime()	float	获取粒子生命周期
SetEmitting(enabled)	void	设置是否正在发射粒子

代码示例

C

using Godot;

/// <summary>
/// 创建 3D 爆炸粒子效果
/// 包含火焰和烟雾两个粒子系统
/// </summary>
public partial class Explosion3D : Node3D
{
    private GPUParticles3D _fireParticles;
    private GPUParticles3D _smokeParticles;

    public override void _Ready()
    {
        // 创建火焰粒子
        _fireParticles = CreateFireParticles();
        AddChild(_fireParticles);

        // 创建烟雾粒子
        _smokeParticles = CreateSmokeParticles();
        AddChild(_smokeParticles);
    }

    private GPUParticles3D CreateFireParticles()
    {
        var particles = new GPUParticles3D
        {
            Amount = 100,
            Lifetime = 0.5f,
            OneShot = true,
            Explosiveness = 1.0f,   // 所有粒子同时爆发
            ProcessMaterial = CreateFireMaterial()
        };
        return particles;
    }

    private GPUParticles3D CreateSmokeParticles()
    {
        var particles = new GPUParticles3D
        {
            Amount = 50,
            Lifetime = 2.0f,
            OneShot = true,
            Explosiveness = 0.5f,   // 烟雾扩散稍慢
            ProcessMaterial = CreateSmokeMaterial()
        };
        return particles;
    }

    private ParticleProcessMaterial CreateFireMaterial()
    {
        var mat = new ParticleProcessMaterial
        {
            Direction = new Vector3(0, 1, 0),
            Spread = 180f,
            Gravity = new Vector3(0, -10, 0),
            InitialVelocityMin = 5f,
            InitialVelocityMax = 15f,
            DampingMin = 2f,
            DampingMax = 5f
        };
        return mat;
    }

    private ParticleProcessMaterial CreateSmokeMaterial()
    {
        var mat = new ParticleProcessMaterial
        {
            Direction = new Vector3(0, 1, 0),
            Spread = 30f,
            Gravity = new Vector3(0, 2, 0),  // 烟雾向上飘
            InitialVelocityMin = 1f,
            InitialVelocityMax = 3f,
            DampingMin = 0.5f,
            DampingMax = 1f
        };
        return mat;
    }

    // 调用此方法触发爆炸效果
    public void Explode()
    {
        _fireParticles.Restart();
        _smokeParticles.Restart();
    }
}

GDScript

## 创建 3D 爆炸粒子效果
## 包含火焰和烟雾两个粒子系统
extends Node3D

var fire_particles: GPUParticles3D
var smoke_particles: GPUParticles3D

func _ready():
    # 创建火焰粒子
    fire_particles = _create_fire_particles()
    add_child(fire_particles)

    # 创建烟雾粒子
    smoke_particles = _create_smoke_particles()
    add_child(smoke_particles)

func _create_fire_particles() -> GPUParticles3D:
    var particles := GPUParticles3D.new()
    particles.amount = 100
    particles.lifetime = 0.5
    particles.one_shot = true
    particles.explosiveness = 1.0  # 所有粒子同时爆发
    particles.process_material = _create_fire_material()
    return particles

func _create_smoke_particles() -> GPUParticles3D:
    var particles := GPUParticles3D.new()
    particles.amount = 50
    particles.lifetime = 2.0
    particles.one_shot = true
    particles.explosiveness = 0.5  # 烟雾扩散稍慢
    particles.process_material = _create_smoke_material()
    return particles

func _create_fire_material() -> ParticleProcessMaterial:
    var mat := ParticleProcessMaterial.new()
    mat.direction = Vector3(0, 1, 0)
    mat.spread = 180.0
    mat.gravity = Vector3(0, -10, 0)
    mat.initial_velocity_min = 5.0
    mat.initial_velocity_max = 15.0
    mat.damping_min = 2.0
    mat.damping_max = 5.0
    return mat

func _create_smoke_material() -> ParticleProcessMaterial:
    var mat := ParticleProcessMaterial.new()
    mat.direction = Vector3(0, 1, 0)
    mat.spread = 30.0
    mat.gravity = Vector3(0, 2, 0)  # 烟雾向上飘
    mat.initial_velocity_min = 1.0
    mat.initial_velocity_max = 3.0
    mat.damping_min = 0.5
    mat.damping_max = 1.0
    return mat

## 调用此方法触发爆炸效果
func explode():
    fire_particles.restart()
    smoke_particles.restart()

使用建议

• 3D 粒子比 2D 粒子更耗性能，注意控制 amount 的值
• 开启 trail_enabled（拖尾）可以显著提升视觉效果，但也会增加性能消耗
• local_coords 设为 true 时粒子会跟随父节点移动，适合做角色脚底灰尘等效果
• 配合 GPUParticlesCollision3D 和 GPUParticlesAttractor3D 可以让粒子与场景产生交互