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, process_time_residual: float = 0)

void

restart(keep_seed: bool = false)

訊號

finished() 🔗

Emitted when all active particles have finished processing. To immediately restart the emission cycle, call restart().

This signal is never emitted when one_shot is disabled, as particles will be emitted and processed continuously.

Note: For one_shot emitters, due to the particles being computed on the GPU, there may be a short period after receiving the signal during which setting emitting to true will not restart the emission cycle. This delay is avoided by instead calling restart().

列舉

enum DrawOrder: 🔗

DrawOrder DRAW_ORDER_INDEX = 0

粒子按發射順序繪製。

DrawOrder DRAW_ORDER_LIFETIME = 1

Particles are drawn in order of remaining lifetime. In other words, the particle with the highest lifetime is drawn at the front.

DrawOrder DRAW_ORDER_REVERSE_LIFETIME = 2

Particles are drawn in reverse order of remaining lifetime. In other words, the particle with the lowest lifetime is drawn at the front.

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()

The number of particles to emit in one emission cycle. The effective emission rate is (amount * amount_ratio) / lifetime particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if amount_ratio is decreased.

Note: Changing this value will cause the particle system to restart. To avoid this, change amount_ratio instead.

float amount_ratio = 1.0 🔗

  • void set_amount_ratio(value: float)

  • float get_amount_ratio()

The ratio of particles that should actually be emitted. If set to a value lower than 1.0, this will set the amount of emitted particles throughout the lifetime to amount * amount_ratio. Unlike changing amount, changing amount_ratio while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. amount_ratio can be used to create effects that make the number of emitted particles vary over time.

Note: Reducing the amount_ratio has no performance benefit, since resources need to be allocated and processed for the total amount of particles regardless of the amount_ratio. If you don't intend to change the number of particles emitted while the particles are emitting, make sure amount_ratio is set to 1 and change amount to your liking instead.

float collision_base_size = 1.0 🔗

  • void set_collision_base_size(value: float)

  • float get_collision_base_size()

Multiplier for particle's collision radius. 1.0 corresponds to the size of the sprite. If particles appear to sink into the ground when colliding, increase this value. If particles appear to float when colliding, decrease this value. Only effective if ParticleProcessMaterial.collision_mode is ParticleProcessMaterial.COLLISION_RIGID or ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT.

Note: Particles always have a spherical collision shape.

DrawOrder draw_order = 1 🔗

Particle draw order.

bool emitting = true 🔗

  • void set_emitting(value: bool)

  • bool is_emitting()

If true, particles are being emitted. emitting can be used to start and stop particles from emitting. However, if one_shot is true setting emitting to true will not restart the emission cycle unless all active particles have finished processing. Use the finished signal to be notified once all active particles finish processing.

Note: For one_shot emitters, due to the particles being computed on the GPU, there may be a short period after receiving the finished signal during which setting this to true will not restart the emission cycle.

Tip: If your one_shot emitter needs to immediately restart emitting particles once finished signal is received, consider calling restart() instead of setting 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()

Causes all the particles in this node to interpolate towards the end of their lifetime.

Note: This only works when used with a ParticleProcessMaterial. It needs to be manually implemented for custom process shaders.

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()

The amount of time each particle will exist (in seconds). The effective emission rate is (amount * amount_ratio) / lifetime particles per second.

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()

Particle system starts as if it had already run for this many seconds.

Note: This can be very expensive if set to a high number as it requires running the particle shader a number of times equal to the fixed_fps (or 30, if fixed_fps is 0) for every second. In extreme cases it can even lead to a GPU crash due to the volume of work done in a single frame.

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()

Sets the random seed used by the particle system. Only effective if use_fixed_seed is true.

float speed_scale = 1.0 🔗

  • void set_speed_scale(value: float)

  • float get_speed_scale()

粒子系統的運作速度的縮放率。0 值可用於暫停粒子。

NodePath sub_emitter = NodePath("") 🔗

Path to another GPUParticles2D node that will be used as a subemitter (see ParticleProcessMaterial.sub_emitter_mode). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more.

Note: When sub_emitter is set, the target GPUParticles2D node will no longer emit particles on its own.

Texture2D texture 🔗

Particle texture. If null, particles will be squares with a size of 1×1 pixels.

Note: To use a flipbook texture, assign a new CanvasItemMaterial to the GPUParticles2D's CanvasItem.material property, then enable CanvasItemMaterial.particles_animation and set CanvasItemMaterial.particles_anim_h_frames, CanvasItemMaterial.particles_anim_v_frames, and CanvasItemMaterial.particles_anim_loop to match the flipbook texture.

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()

If true, particles will use the same seed for every simulation using the seed defined in seed. This is useful for situations where the visual outcome should be consistent across replays, for example when using Movie Maker mode.

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) 🔗

設定該節點的屬性以配對給定的 GPUParticles2D 節點，該給定節點已分配了一個 ParticleProcessMaterial。

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

Emits a single particle. Whether xform, velocity, color and custom are applied depends on the value of flags. See EmitFlags.

The default ParticleProcessMaterial will overwrite color and use the contents of custom as (rotation, age, animation, lifetime).

Note: emit_particle() is only supported on the Forward+ and Mobile rendering methods, not Compatibility.

void request_particles_process(process_time: float, process_time_residual: float = 0) 🔗

Requests the particles to process for extra process time during a single frame.

process_time defines the time that the particles will process while emitting is on. process_time_residual defines the time that particles will process with emitting turned off for the simulation. When combined with speed_scale set to 0.0, this is useful to be able to seek a particle system timeline.

void restart(keep_seed: bool = false) 🔗

Restarts the particle emission cycle, clearing existing particles. To avoid particles vanishing from the viewport, wait for the finished signal before calling.

Note: The finished signal is only emitted by one_shot emitters.

If keep_seed is true, the current random seed will be preserved. Useful for seeking and playback.