GPUParticles2D¶

Inherits: Node2D < CanvasItem < Node < Object

2D particle emitter.

Description¶

2D particle node used to create a variety of particle systems and effects. GPUParticles2D features an emitter that generates some number of particles at a given rate.

Use the process_material property to add a ParticlesMaterial to configure particle appearance and behavior. Alternatively, you can add a ShaderMaterial which will be applied to all particles.

Tutorials¶

Properties¶

int	amount	`8`
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	lifetime	`1.0`
bool	local_coords	`true`
bool	one_shot	`false`
float	preprocess	`0.0`
Material	process_material
float	randomness	`0.0`
float	speed_scale	`1.0`
NodePath	sub_emitter	`NodePath("")`
Texture2D	texture
bool	trail_enabled	`false`
float	trail_length_secs	`0.3`
int	trail_section_subdivisions	`4`
int	trail_sections	`8`
Rect2	visibility_rect	`Rect2(-100, -100, 200, 200)`

Methods¶

Rect2	capture_rect ( ) const
void	emit_particle ( Transform2D xform, Vector2 velocity, Color color, Color custom, int flags )
void	restart ( )

Enumerations¶

enum DrawOrder:

DRAW_ORDER_INDEX = 0 --- Particles are drawn in the order emitted.
DRAW_ORDER_LIFETIME = 1 --- Particles are drawn in order of remaining lifetime.
DRAW_ORDER_REVERSE_LIFETIME = 2

enum EmitFlags:

EMIT_FLAG_POSITION = 1 --- Particle starts at the specified position.
EMIT_FLAG_ROTATION_SCALE = 2 --- Particle starts with specified rotation and scale.
EMIT_FLAG_VELOCITY = 4 --- Particle starts with the specified velocity vector, which defines the emission direction and speed.
EMIT_FLAG_COLOR = 8 --- Particle starts with specified color.
EMIT_FLAG_CUSTOM = 16 --- Particle starts with specified CUSTOM data.

Property Descriptions¶

int amount

Default	`8`
Setter	set_amount(value)
Getter	get_amount()

Number of particles emitted in one emission cycle.

float collision_base_size

Default	`1.0`
Setter	set_collision_base_size(value)
Getter	get_collision_base_size()

DrawOrder draw_order

Default	`1`
Setter	set_draw_order(value)
Getter	get_draw_order()

Particle draw order. Uses DrawOrder values.

bool emitting

Default	`true`
Setter	set_emitting(value)
Getter	is_emitting()

If true, particles are being emitted.

float explosiveness

Default	`0.0`
Setter	set_explosiveness_ratio(value)
Getter	get_explosiveness_ratio()

How rapidly particles in an emission cycle are emitted. If greater than 0, there will be a gap in emissions before the next cycle begins.

int fixed_fps

Default	`30`
Setter	set_fixed_fps(value)
Getter	get_fixed_fps()

The particle system's frame rate is fixed to a value. For instance, changing the value to 2 will make the particles render at 2 frames per second. Note this does not slow down the simulation of the particle system itself.

bool fract_delta

Default	`true`
Setter	set_fractional_delta(value)
Getter	get_fractional_delta()

If true, results in fractional delta calculation which has a smoother particles display effect.

float lifetime

Default	`1.0`
Setter	set_lifetime(value)
Getter	get_lifetime()

Amount of time each particle will exist.

bool local_coords

Default	`true`
Setter	set_use_local_coordinates(value)
Getter	get_use_local_coordinates()

If true, particles use the parent node's coordinate space. If false, they use global coordinates.

bool one_shot

Default	`false`
Setter	set_one_shot(value)
Getter	get_one_shot()

If true, only one emission cycle occurs. If set true during a cycle, emission will stop at the cycle's end.

float preprocess

Default	`0.0`
Setter	set_pre_process_time(value)
Getter	get_pre_process_time()

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

Material process_material

Setter	set_process_material(value)
Getter	get_process_material()

Material for processing particles. Can be a ParticlesMaterial or a ShaderMaterial.

float randomness

Default	`0.0`
Setter	set_randomness_ratio(value)
Getter	get_randomness_ratio()

Emission lifetime randomness ratio.

float speed_scale

Default	`1.0`
Setter	set_speed_scale(value)
Getter	get_speed_scale()

Particle system's running speed scaling ratio. A value of 0 can be used to pause the particles.

NodePath sub_emitter

Default	`NodePath("")`
Setter	set_sub_emitter(value)
Getter	get_sub_emitter()

The NodePath to the GPUParticles2D used for sub-emissions.

Texture2D texture

Setter	set_texture(value)
Getter	get_texture()

Particle texture. If null, particles will be squares.

bool trail_enabled

Default	`false`
Setter	set_trail_enabled(value)
Getter	is_trail_enabled()

float trail_length_secs

Default	`0.3`
Setter	set_trail_length(value)
Getter	get_trail_length()

int trail_section_subdivisions

Default	`4`
Setter	set_trail_section_subdivisions(value)
Getter	get_trail_section_subdivisions()

int trail_sections

Default	`8`
Setter	set_trail_sections(value)
Getter	get_trail_sections()

Rect2 visibility_rect

Default	`Rect2(-100, -100, 200, 200)`
Setter	set_visibility_rect(value)
Getter	get_visibility_rect()

The Rect2 that determines the node's region which needs to be visible on screen for the particle system to be active.

Grow the rect if particles suddenly appear/disappear when the node enters/exits the screen. The Rect2 can be grown via code or with the Particles → Generate Visibility Rect editor tool.

Method Descriptions¶

Rect2 capture_rect ( ) const

Returns a rectangle containing the positions of all existing particles.

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

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

void restart ( )

Restarts all the existing particles.