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

GPUParticlesAttractor3D 系列

节点继承关系

继承链：Node → Node3D → GPUParticlesAttractor3D

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

定义

粒子吸引器——放在 3D 空间中，像一个"磁铁"一样吸引或排斥附近的 GPU 粒子，让粒子的运动轨迹发生弯曲。

打个比方：想象你在桌上撒了一把铁粉，然后在桌上放了一块磁铁。铁粉会向磁铁方向移动。GPUParticlesAttractor3D 就是这块"磁铁"，粒子就是"铁粉"。你可以设置吸引力度、衰减距离，甚至让"磁铁"反过来"排斥"粒子。

GPUParticlesAttractor3D 系列包括：

• GPUParticlesAttractorSphere3D：球形吸引区域
• GPUParticlesAttractorBox3D：方形吸引区域

使用频率：★★ 偶尔使用——需要让粒子产生有方向性的运动时使用。

节点用途

• 让粒子向某个点聚拢（如黑洞效果）
• 让粒子绕某个轴旋转（如漩涡效果）
• 让粒子被推开（如爆炸冲击波推开周围粒子）
• 创建粒子流（如水流汇聚到排水口）

使用场景

典型场景

• 魔法特效：火球术的火焰向中心聚拢后爆发
• 科幻效果：引力井吸引周围的能量粒子
• 水特效：水流被排水口吸引
• 漩涡效果：粒子围绕中心旋转

不适用场景

• 粒子运动轨迹固定不变 → 只需调整 GPUParticles3D 的属性即可
• 2D 游戏 → 不支持

常用节点搭配

搭配节点	用途	必需？
GPUParticles3D	被吸引的粒子系统（Particle System）	必需

典型节点树：

VortexEffect (Node3D)
├── GPUParticles3D          ← 粒子系统
├── GPUParticlesAttractorSphere3D  ← 球形吸引器
└── ...

生效必备素材/资源

资源	类型	说明
无特殊资源	—	吸引器的参数通过节点属性设置

节点属性与信号

GPUParticlesAttractor3D 基础属性

属性	类型	默认值	继承自	说明
strength	float	-1.0	—	吸引力度。负值 = 吸引（粒子向中心聚拢），正值 = 排斥（粒子被推开）
attenuation	float	1.0	—	衰减系数。值越大，力度随距离增加衰减越快
directionality	float	0.0	—	方向性。0 = 各方向等力，1 = 只沿粒子发射方向

GPUParticlesAttractorSphere3D 属性

属性	类型	默认值	继承自	说明
radius	float	1.0	—	球形吸引区域的半径

GPUParticlesAttractorBox3D 属性

属性	类型	默认值	继承自	说明
extents	Vector3	(1, 1, 1)	—	方形吸引区域的大小（半尺寸）

信号

信号	触发时机	继承自	说明
无自有信号	—	—	GPUParticlesAttractor3D 自身不发出信号

常用方法

方法	返回值	说明
无特有方法	—	所有操作通过属性控制

代码示例

C

using Godot;

/// <summary>
/// 漩涡特效控制器
/// 使用球形吸引器让粒子围绕中心旋转
/// </summary>
public partial class VortexEffect : Node3D
{
    private GPUParticles3D _particles;
    private GPUParticlesAttractorSphere3D _attractor;

    public override void _Ready()
    {
        // 创建粒子系统
        _particles = new GPUParticles3D
        {
            Amount = 200,
            Lifetime = 3.0f,
            ProcessMaterial = new ParticleProcessMaterial
            {
                Direction = new Vector3(0, 1, 0),
                Spread = 180f,
                InitialVelocityMin = 1f,
                InitialVelocityMax = 3f,
                Gravity = new Vector3(0, 0, 0) // 不使用重力，让吸引器控制
            }
        };
        AddChild(_particles);

        // 创建球形吸引器（漩涡中心）
        _attractor = new GPUParticlesAttractorSphere3D
        {
            Radius = 2f,
            Strength = -2f,     // 负值 = 吸引
            Attenuation = 0.5f,  // 较低的衰减，远处的粒子也能被影响
            Directionality = 0.3f // 稍有方向性，让粒子旋转而不是直线飞入
        };
        AddChild(_attractor);
    }

    // 动态调整漩涡强度
    public void SetVortexIntensity(float intensity)
    {
        _attractor.Strength = -intensity;
    }
}

GDScript

## 漩涡特效控制器
## 使用球形吸引器让粒子围绕中心旋转
extends Node3D

var particles: GPUParticles3D
var attractor: GPUParticlesAttractorSphere3D

func _ready():
    # 创建粒子系统
    particles = GPUParticles3D.new()
    particles.amount = 200
    particles.lifetime = 3.0

    var mat := ParticleProcessMaterial.new()
    mat.direction = Vector3(0, 1, 0)
    mat.spread = 180.0
    mat.initial_velocity_min = 1.0
    mat.initial_velocity_max = 3.0
    mat.gravity = Vector3(0, 0, 0)  # 不使用重力，让吸引器控制
    particles.process_material = mat
    add_child(particles)

    # 创建球形吸引器（漩涡中心）
    attractor = GPUParticlesAttractorSphere3D.new()
    attractor.radius = 2.0
    attractor.strength = -2.0      # 负值 = 吸引
    attractor.attenuation = 0.5     # 较低的衰减，远处的粒子也能被影响
    attractor.directionality = 0.3  # 稍有方向性，让粒子旋转而不是直线飞入
    add_child(attractor)

## 动态调整漩涡强度
func set_vortex_intensity(intensity: float):
    attractor.strength = -intensity

使用建议

• strength 为负值时吸引粒子，正值时排斥粒子
• 多个吸引器可以叠加效果，创造出复杂的粒子运动轨迹
• attenuation 值越大，吸引效果越集中在吸引器附近
• directionality 可以让粒子产生旋转效果，适合做漩涡
• 吸引器只对 GPUParticles3D 生效，对 CPUParticles3D 无效