Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

GPUParticles2D

继承： Node2D < CanvasItem < Node < Object

2D 粒子发射器。

描述

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

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

2D 粒子可以选择与 LightOccluder2D 碰撞，但它们不会与 PhysicsBody2D 节点碰撞。

教程

属性

int

amount

8

float

amount_ratio

1.0

float

collision_base_size

1.0

DrawOrder

draw_order

1

bool

emitting

true

float

explosiveness

0.0

int

fixed_fps

30

bool

fract_delta

true

float

interp_to_end

0.0

bool

interpolate

true

float

lifetime

1.0

bool

local_coords

false

bool

one_shot

false

float

preprocess

0.0

Material

process_material

float

randomness

0.0

int

seed

0

float

speed_scale

1.0

NodePath

sub_emitter

NodePath("")

Texture2D

texture

bool

trail_enabled

false

float

trail_lifetime

0.3

int

trail_section_subdivisions

4

int

trail_sections

8

bool

use_fixed_seed

false

Rect2

visibility_rect

Rect2(-100, -100, 200, 200)

方法

Rect2

capture_rect() const

void

convert_from_particles(particles: Node)

void

emit_particle(xform: Transform2D, velocity: Vector2, color: Color, custom: Color, flags: int)

void

request_particles_process(process_time: float)

void

restart(keep_seed: bool = false)

信号

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

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

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 数据开始。

属性说明

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 = 1.0 🔗

  • void set_collision_base_size(value: float)

  • float get_collision_base_size()

粒子碰撞半径的乘数。1.0 对应于该精灵的大小。如果碰撞时粒子似乎沉入地下，请增加该值。如果粒子在碰撞时出现漂浮，请减小该值。仅当 ParticleProcessMaterial.collision_mode 为 ParticleProcessMaterial.COLLISION_RIGID 或 ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT 时有效。

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

DrawOrder draw_order = 1 🔗

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

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，则在下一个发射周期开始之前，发射会出现一个间隔。

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

bool one_shot = false 🔗

  • void set_one_shot(value: bool)

  • bool get_one_shot()

如果为 true，则只发生一个发射周期。如果在某个周期内设置为 true，则发射将在该周期结束时停止。

float preprocess = 0.0 🔗

  • void set_pre_process_time(value: float)

  • float get_pre_process_time()

粒子系统启动时仿佛已经运行了这么多秒。

注意：如果设置为较高的数字可能会非常耗费资源，因为它需要每秒运行与 fixed_fps 相等次数的粒子着色器（如果 fixed_fps 为 0 则为 30 次）。在极端情况下，这甚至可能导致 GPU 崩溃，因为在单个帧中完成的工作量过大。

Material process_material 🔗

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

float randomness = 0.0 🔗

  • void set_randomness_ratio(value: float)

  • float get_randomness_ratio()

发射寿命随机率。

int seed = 0 🔗

  • void set_seed(value: int)

  • int get_seed()

设置粒子系统所使用的随机数种子。仅在 use_fixed_seed 为 true 时有效。

float speed_scale = 1.0 🔗

  • void set_speed_scale(value: float)

  • float get_speed_scale()

粒子系统的运行速度的缩放率。0 值可用于暂停粒子。

NodePath sub_emitter = NodePath("") 🔗

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

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

Texture2D texture 🔗

粒子纹理。如果为 null，则粒子将是大小为 1×1 像素的正方形。

注意：要使用翻页纹理，请将新的 CanvasItemMaterial 分配给 GPUParticles2D 的 CanvasItem.material 属性，然后启用 CanvasItemMaterial.particles_animation 并设置 CanvasItemMaterial.particles_anim_h_frames、CanvasItemMaterial.particles_anim_v_frames 和 CanvasItemMaterial.particles_anim_loop 来匹配该翻页纹理。

bool trail_enabled = false 🔗

  • void set_trail_enabled(value: bool)

  • bool is_trail_enabled()

如果true ，可以使用网格换肤系统来启用粒子轨迹。

注意：与GPUParticles3D不同的是，trail sections和subdivisions的数量是通过属性trail_sections和trail_section_subdivisions设置的。

float trail_lifetime = 0.3 🔗

  • void set_trail_lifetime(value: float)

  • float get_trail_lifetime()

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

int trail_section_subdivisions = 4 🔗

  • void set_trail_section_subdivisions(value: int)

  • int get_trail_section_subdivisions()

用于粒子尾迹渲染的细分数。较高的值可以产生更平滑的尾迹曲线，但由于增加了网格的复杂度，因此会牺牲性能。另见 trail_sections。仅当 trail_enabled 为 true 时有效。

int trail_sections = 8 🔗

  • void set_trail_sections(value: int)

  • int get_trail_sections()

用于粒子轨迹渲染的部分数。较高的值可以产生更平滑的尾迹曲线，但由于增加了网格的复杂度，因此会牺牲性能。另见 trail_section_subdivisions。仅当 trail_enabled 为 true 时有效。

bool use_fixed_seed = false 🔗

  • void set_use_fixed_seed(value: bool)

  • bool get_use_fixed_seed()

如果为 true，则每次模拟中粒子会使用 seed 中定义的种子。适用于需要在重放时保持视觉效果一致的情况，例如使用 Movie Maker 模式时。

Rect2 visibility_rect = Rect2(-100, -100, 200, 200) 🔗

  • void set_visibility_rect(value: Rect2)

  • Rect2 get_visibility_rect()

Rect2 确定节点的区域，该区域需要在屏幕上可见才能使粒子系统处于活动状态。

如果当节点进入/退出屏幕时粒子突然出现/消失，则增长矩形。Rect2 可以通过代码或使用 Particles → Generate Visibility Rect 编辑器工具生成。

方法说明

Rect2 capture_rect() const 🔗

返回一个包含所有已有粒子位置的矩形。

注意：当使用线程渲染时，该方法会同步渲染线程。经常调用它可能会对性能产生负面影响。

void convert_from_particles(particles: Node) 🔗

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

void emit_particle(xform: Transform2D, velocity: Vector2, color: Color, custom: Color, flags: int) 🔗

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

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

注意：emit_particle() 只有 Forward+ 和 Mobile 渲染方法支持，Compatibility 不支持。

void request_particles_process(process_time: float) 🔗

请求让粒子在一帧中使用额外的处理时间进行处理。

适用于粒子回放，需要与 use_fixed_seed 配合使用，或者调用 restart() 时将 keep_seed 参数设为 true。

void restart(keep_seed: bool = false) 🔗

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

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

如果 keep_seed 为 true，则会保留当前的随机数种子。适用于跳转播放。