GPUParticles3D

继承： GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

3D 粒子发射器。

描述

3D 粒子节点，用于创建各种粒子系统和效果。GPUParticles3D 的特点是，发射器以给定的速度产生一定数量的粒子。

使用 process_material 属性来添加一个配置粒子外观和行为的 ParticleProcessMaterial。或者，你可以添加一个应用于所有粒子的 ShaderMaterial。

教程

• 粒子系统（3D）

• 用粒子控制数千条鱼

• 第三人称射击（TPS）演示

属性

方法

信号

finished() 🔗

所有活动粒子完成处理时发出。立即发射新的粒子请调用 restart。

禁用 one_shot 时不会发出，因为会持续发出并处理粒子。

注意：由于粒子是在 GPU 上计算的，所以 one_shot 的发射器在收到该信号后可能存在一小段特殊时期，在此期间将 emitting 设为 true 无法重启发射周期。改成调用 restart 就可以避免这段延迟。

枚举

enum DrawOrder: 🔗

DrawOrder DRAW_ORDER_INDEX = 0

粒子按发射顺序绘制。

DrawOrder DRAW_ORDER_LIFETIME = 1

粒子按照剩余寿命的顺序绘制。换句话说，寿命最长的粒子被绘制在前面。

DrawOrder DRAW_ORDER_REVERSE_LIFETIME = 2

粒子按照剩余寿命的相反顺序绘制。换句话说，寿命最短的粒子被绘制在前面。

DrawOrder DRAW_ORDER_VIEW_DEPTH = 3

粒子按深度顺序绘制。

enum EmitFlags: 🔗

EmitFlags EMIT_FLAG_POSITION = 1

粒子在指定位置开始。

EmitFlags EMIT_FLAG_ROTATION_SCALE = 2

粒子以指定的旋转和缩放开始。

EmitFlags EMIT_FLAG_VELOCITY = 4

粒子从指定的速度向量开始，该向量定义了发射方向和速度。

EmitFlags EMIT_FLAG_COLOR = 8

粒子以指定的颜色开始。

EmitFlags EMIT_FLAG_CUSTOM = 16

粒子以指定的 CUSTOM 数据开始。

enum TransformAlign: 🔗

TransformAlign TRANSFORM_ALIGN_DISABLED = 0

该枚举目前没有描述，请帮我们贡献一个吧！

TransformAlign TRANSFORM_ALIGN_Z_BILLBOARD = 1

该枚举目前没有描述，请帮我们贡献一个吧！

TransformAlign TRANSFORM_ALIGN_Y_TO_VELOCITY = 2

该枚举目前没有描述，请帮我们贡献一个吧！

TransformAlign TRANSFORM_ALIGN_Z_BILLBOARD_Y_TO_VELOCITY = 3

该枚举目前没有描述，请帮我们贡献一个吧！

常量

MAX_DRAW_PASSES = 4 🔗

支持的最大绘制阶段数。

属性说明

int amount = 8 🔗

• void set_amount(value: int)

• int get_amount()

一个发射周期内发射的粒子数。有效发射速率为每秒 (amount * amount_ratio) / lifetime 个粒子。较高的值会增加 GPU 要求，即使在给定时间并非所有粒子都可见或 amount_ratio 减少。

注意：更改该值将导致粒子系统重新启动。为了避免这种情况，请更改 amount_ratio。

float amount_ratio = 1.0 🔗

• void set_amount_ratio(value: float)

• float get_amount_ratio()

实际应该发射的粒子的比率。如果被设置为低于 1.0 的值，则会将整个生命周期内发射的粒子数量设置为 amount * amount_ratio。与更改 amount 不同，发射时更改 amount_ratio 不会影响已发射的粒子，也不会导致粒子系统重新启动。amount_ratio 可用于创建使发射粒子的数量随时间变化的效果。

注意：减少 amount_ratio 不会带来性能优势，因为无论 amount_ratio 是多少，都需要为粒子总数 amount 分配和处理资源。如果你不打算在粒子发射时更改发射的粒子数量，请确保将 amount_ratio 设置为 1 并根据你的喜好更改 amount。

float collision_base_size = 0.01 🔗

• void set_collision_base_size(value: float)

• float get_collision_base_size()

粒子碰撞的基本直径（以米为单位）。如果碰撞时粒子似乎沉入地下，请增加该值。如果粒子在碰撞时出现漂浮，请减小该值。仅当 ParticleProcessMaterial.collision_mode 为 ParticleProcessMaterial.COLLISION_RIGID 或 ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT 时有效。

注意：粒子始终具有球形碰撞形状。

DrawOrder draw_order = 0 🔗

• void set_draw_order(value: DrawOrder)

• DrawOrder get_draw_order()

粒子绘制顺序。使用 DrawOrder 值。

注意：DRAW_ORDER_INDEX 是支持 TAA 等效果的运动向量的唯一选项。如果粒子不透明，建议使用该绘制顺序来修复重影伪影。

Mesh draw_pass_1 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

第一绘制阶段所绘制的 Mesh。

Mesh draw_pass_2 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

第二绘制阶段所绘制的 Mesh。

Mesh draw_pass_3 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

第三绘制阶段所绘制的 Mesh。

Mesh draw_pass_4 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

第四绘制阶段所绘制的 Mesh。

int draw_passes = 1 🔗

• void set_draw_passes(value: int)

• int get_draw_passes()

渲染粒子时的绘制阶段数。

Skin draw_skin 🔗

• void set_skin(value: Skin)

• Skin get_skin()

该属性目前没有描述，请帮我们贡献一个吧！

bool emitting = true 🔗

• void set_emitting(value: bool)

• bool is_emitting()

如果为 true，则正在发射粒子。emitting 可用于启动和停止粒子发射。但是，如果 one_shot 为 true，则将 emitting 设置为 true 将不会重新启动该发射循环，除非所有活动粒子都已完成处理。一旦所有活动粒子完成处理，可以使用 finished 信号来收取通知。

注意：对于 one_shot 发射器，由于粒子是在 GPU 上计算的，因此在收到 finished 信号后可能会有一段短暂的时间，在此期间将其设置为 true 将不会重新启动发射循环。

提示：如果你的 one_shot 发射器需要在收到 finished 信号后立即重新启动发射粒子，请考虑调用 restart 而不是设置 emitting。

float explosiveness = 0.0 🔗

• void set_explosiveness_ratio(value: float)

• float get_explosiveness_ratio()

每次发射之间的时间比。如果为 0，则粒子是连续发射的。如果为 1，则所有的粒子都同时发射。

int fixed_fps = 30 🔗

• void set_fixed_fps(value: int)

• int get_fixed_fps()

粒子系统的帧速率被固定为一个值。例如，将值更改为 2 会使粒子以每秒 2 帧的速度渲染。请注意，这并不会降低粒子系统本身的模拟速度。

bool fract_delta = true 🔗

• void set_fractional_delta(value: bool)

• bool get_fractional_delta()

如果为 为true，则使用分数增量 delta 计算，将具有更平滑的粒子显示效果。

float interp_to_end = 0.0 🔗

• void set_interp_to_end(value: float)

• float get_interp_to_end()

导致该节点中的所有粒子插值到其生命周期结束时。

注意：这仅在与 ParticleProcessMaterial 一起使用时才有效。对于自定义进程着色器，需要手动实现。

bool interpolate = true 🔗

• void set_interpolate(value: bool)

• bool get_interpolate()

启用粒子插值，当fixed_fps 低于屏幕刷新率时，使粒子运动更平滑。

float lifetime = 1.0 🔗

• void set_lifetime(value: float)

• float get_lifetime()

每个粒子存在的时间（以秒为单位）。有效发射速率为每秒 (amount * amount_ratio) / lifetime 个粒子。

bool local_coords = false 🔗

• void set_use_local_coordinates(value: bool)

• bool get_use_local_coordinates()

如果为 true，则粒子使用父节点的坐标空间（称为局部坐标）。这将导致粒子在移动或旋转时沿着 GPUParticles3D 节点（及其父节点）移动和旋转。如果为 false，则粒子使用全局坐标；当移动或旋转时，它们不会沿着 GPUParticles3D 节点（及其父节点）移动或旋转。

bool one_shot = false 🔗

• void set_one_shot(value: bool)

• bool get_one_shot()

如果为 true，将只发出 amount 数量的粒子。

float preprocess = 0.0 🔗

• void set_pre_process_time(value: float)

• float get_pre_process_time()

动画开始前对粒子进行预处理的时间。让你在粒子开始发射后的一段时间内开始动画。

Material process_material 🔗

• void set_process_material(value: Material)

• Material get_process_material()

用于处理粒子的 Material 。可以是 ParticleProcessMaterial 或 ShaderMaterial 。

float randomness = 0.0 🔗

• void set_randomness_ratio(value: float)

• float get_randomness_ratio()

发出随机率。

float speed_scale = 1.0 🔗

• void set_speed_scale(value: float)

• float get_speed_scale()

速度缩放比例。0 的值可被用于暂停粒子。

NodePath sub_emitter = NodePath("") 🔗

• void set_sub_emitter(value: NodePath)

• NodePath get_sub_emitter()

到将被用作子发射器（请参阅 ParticleProcessMaterial.sub_emitter_mode）的另一个 GPUParticles3D 节点的路径。子发射器可被用于实现烟花、碰撞火花、气泡弹出水滴等效果。

注意：当 sub_emitter 被设置时，该目标 GPUParticles3D 节点将不再自行发射粒子。

bool trail_enabled = false 🔗

• void set_trail_enabled(value: bool)

• bool is_trail_enabled()

如果为 true，则使用网格蒙皮系统来启用粒子尾迹。旨在与 RibbonTrailMesh 和 TubeTrailMesh 一起使用。

注意：还必须在粒子网格的材质上启用 BaseMaterial3D.use_particle_trails。否则，将 trail_enabled 设置为 true 将无效。

注意：与 GPUParticles2D 不同，尾迹部分及其细分的数量是在 RibbonTrailMesh 或 TubeTrailMesh 的属性中设置的。

float trail_lifetime = 0.3 🔗

• void set_trail_lifetime(value: float)

• float get_trail_lifetime()

代表粒子轨迹的时间量（以秒为单位）。仅当 trail_enabled 为 true 时有效。

TransformAlign transform_align = 0 🔗

• void set_transform_align(value: TransformAlign)

• TransformAlign get_transform_align()

该属性目前没有描述，请帮我们贡献一个吧！

AABB visibility_aabb = AABB(-4, -4, -4, 8, 8, 8) 🔗

• void set_visibility_aabb(value: AABB)

• AABB get_visibility_aabb()

AABB 确定节点的区域，该区域需要在屏幕上可见，才能使粒子系统处于活动状态。GeometryInstance3D.extra_cull_margin 被添加到 AABB 的每个轴上。粒子碰撞和吸引只会发生在该区域内。

如果在节点进入/退出屏幕时，粒子突然出现/消失，则应该增大矩形。AABB 可以通过代码，或使用 粒子 → 生成 AABB 编辑器工具生成。

注意：如果该属性被设置为非默认值，visibility_aabb 会被 GeometryInstance3D.custom_aabb 覆盖。

方法说明

AABB capture_aabb() const 🔗

返回包含当前帧中所有活动粒子的轴对齐边界框。

void convert_from_particles(particles: Node) 🔗

设置该节点的属性以匹配给定的 CPUParticles3D 节点。

void emit_particle(xform: Transform3D, velocity: Vector3, color: Color, custom: Color, flags: int) 🔗

发射单个粒子。是否应用 xform、velocity、color 和 custom 取决于 flags 的值。请参阅 EmitFlags。

默认的 ParticleProcessMaterial 将覆盖 color 并使用 custom 的内容作为 (rotation, age, animation, lifetime)。

Mesh get_draw_pass_mesh(pass: int) const 🔗

返回在索引 pass 处绘制的 Mesh 。

void restart() 🔗

重新开始粒子发射周期，清除现存粒子。要避免粒子从视口中凭空消失，请在调用前等待 finished 信号。

注意：只有 one_shot 的发射器会发出 finished 信号。

void set_draw_pass_mesh(pass: int, mesh: Mesh) 🔗

设置在索引 pass 处绘制的 Mesh 。