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

CPUParticles3D

节点继承关系

继承链：Node → Node3D → GeometryInstance3D → CPUParticles3D

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()	获取父节点

定义

运行在处理器（CPU）上的 3D 粒子系统（Particle System）——CPUParticles2D 的 3D 版本。在三维空间中逐粒子计算位置，可以直接读写每个粒子的数据。

和 GPUParticles3D 的关系就像 CPUParticles2D 和 GPUParticles2D 的关系：GPU 版本快但不精确可控，CPU 版本慢但完全可控。

使用频率：★★ 偶尔使用——优先使用 GPUParticles3D，只在需要逐粒子控制时使用。

节点用途

• 3D 空间中需要精确控制每个粒子的场景
• 粒子需要与游戏逻辑深度交互（如命中检测）
• 需要查询粒子实时位置的场景
• 显卡性能较弱时的备选方案

使用场景

典型场景

• 自定义 3D 物理交互：粒子飞行途中碰到物体需要产生游戏逻辑事件
• 少量精确 3D 粒子：只需要少量粒子但需要精确控制
• 原型开发调试：快速测试粒子效果

不适用场景

• 大量 3D 粒子特效 → 使用 GPUParticles3D
• 2D 游戏 → 使用 CPUParticles2D

常用节点搭配

搭配节点	用途	必需？
Mesh（网格资源）	粒子的 3D 外观形状	推荐

典型节点树：

CustomParticles3D (CPUParticles3D)
└── （通过属性配置参数）

生效必备素材/资源

资源	类型	说明
粒子网格	Mesh	赋给 mesh 属性，决定粒子的 3D 形状

节点属性与信号

粒子基础设置

属性	类型	默认值	继承自	说明
amount	int	—	—	粒子数量
mesh	Mesh	—	—	粒子的 3D 网格形状
lifetime	float	—	—	粒子存活时间
one_shot	bool	false	—	是否只播放一次
explosiveness	float	0.0	—	爆炸性
randomness	float	0.0	—	随机性

运动参数

属性	类型	默认值	继承自	说明
direction	Vector3	(0, -1, 0)	—	粒子发射方向
spread	float	45.0	—	发射角度范围
gravity	Vector3	(0, -98, 0)	—	重力向量
initial_velocity_min	float	0.0	—	最小初始速度
initial_velocity_max	float	0.0	—	最大初始速度
linear_accel_min	float	0.0	—	最小线性加速度
linear_accel_max	float	0.0	—	最大线性加速度
tangential_accel_min	float	0.0	—	最小切向加速度
tangential_accel_max	float	0.0	—	最大切向加速度
damping_min	float	0.0	—	最小阻尼
damping_max	float	0.0	—	最大阻尼

缩放与旋转

属性	类型	默认值	继承自	说明
scale_min	float	1.0	—	最小缩放
scale_max	float	1.0	—	最大缩放
scale_curve	Curve	—	—	缩放随生命周期的变化曲线
angle_min	float	0.0	—	最小初始旋转角度
angle_max	float	0.0	—	最大初始旋转角度
angular_velocity_min	float	0.0	—	最小旋转速度
angular_velocity_max	float	0.0	—	最大旋转速度

颜色

属性	类型	默认值	继承自	说明
color_ramp	Gradient	—	—	颜色渐变
color_initial_ramp	Gradient	—	—	初始颜色随机渐变

信号

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

常用方法

方法	返回值	说明
Emit(count)	void	手动发射指定数量的粒子
Restart()	void	重启粒子系统
GetParticleEmissionTransform(index)	Transform3D	获取指定粒子的发射变换
SetParticleEmissionTransform(index, xform)	void	设置指定粒子的发射变换

代码示例

C

using Godot;

/// <summary>
/// 使用 CPU 粒子创建 3D 魔法阵效果
/// 粒子沿圆形轨道旋转上升
/// </summary>
public partial class MagicCircle : CPUParticles3D
{
    public override void _Ready()
    {
        Amount = 60;
        Lifetime = 2.0f;
        OneShot = false;

        // 向上发射
        Direction = new Vector3(0, 1, 0);
        Spread = 5f;

        // 速度较慢
        InitialVelocityMin = 1f;
        InitialVelocityMax = 2f;

        // 切向加速度让粒子旋转
        TangentialAccelMin = 20f;
        TangentialAccelMax = 40f;

        // 重力拉回
        Gravity = new Vector3(0, -3, 0);

        // 粒子大小
        ScaleMin = 0.1f;
        ScaleMax = 0.3f;

        // 颜色：紫色 -> 蓝色 -> 透明
        var colorRamp = new Gradient();
        colorRamp.SetColor(0, new Color(0.8f, 0.2f, 1, 1));
        colorRamp.SetColor(0.5, new Color(0.3f, 0.4f, 1, 0.7f));
        colorRamp.SetColor(1, new Color(0.1f, 0.1f, 0.5f, 0));
        ColorRamp = colorRamp;
    }
}

GDScript

## 使用 CPU 粒子创建 3D 魔法阵效果
## 粒子沿圆形轨道旋转上升
extends CPUParticles3D

func _ready():
    amount = 60
    lifetime = 2.0
    one_shot = false

    # 向上发射
    direction = Vector3(0, 1, 0)
    spread = 5.0

    # 速度较慢
    initial_velocity_min = 1.0
    initial_velocity_max = 2.0

    # 切向加速度让粒子旋转
    tangential_accel_min = 20.0
    tangential_accel_max = 40.0

    # 重力拉回
    gravity = Vector3(0, -3, 0)

    # 粒子大小
    scale_min = 0.1
    scale_max = 0.3

    # 颜色：紫色 -> 蓝色 -> 透明
    var color_ramp := Gradient.new()
    color_ramp.set_color(0, Color(0.8, 0.2, 1, 1))
    color_ramp.set_color(0.5, Color(0.3, 0.4, 1, 0.7))
    color_ramp.set_color(1, Color(0.1, 0.1, 0.5, 0))
    color_ramp = color_ramp

CPUParticles3D 的优势场景

• 需要让粒子精确命中某个目标（通过 GetParticleEmissionTransform 查询位置）
• 粒子数量很少（< 100）但需要复杂的自定义运动逻辑
• 需要通过代码实时修改单个粒子的颜色或缩放