CPUParticles2D

Inherits: Node2D < CanvasItem < Node < Object

CPU-based 2D particle emitter.

Description

CPU-based 2D particle node used to create a variety of particle systems and effects.

See also Particles2D, which provides the same functionality with hardware acceleration, but may not run on older devices.

Tutorials

• Particle systems (2D)

Properties

int	amount	8
float	angle	0.0
Curve	angle_curve
float	angle_random	0.0
float	angular_velocity	0.0
Curve	angular_velocity_curve
float	angular_velocity_random	0.0
float	anim_offset	0.0
Curve	anim_offset_curve
float	anim_offset_random	0.0
float	anim_speed	0.0
Curve	anim_speed_curve
float	anim_speed_random	0.0
Color	color	Color( 1, 1, 1, 1 )
Gradient	color_ramp
float	damping	0.0
Curve	damping_curve
float	damping_random	0.0
Vector2	direction	Vector2( 1, 0 )
DrawOrder	draw_order	0
PoolColorArray	emission_colors
PoolVector2Array	emission_normals
PoolVector2Array	emission_points
Vector2	emission_rect_extents
EmissionShape	emission_shape	0
float	emission_sphere_radius
bool	emitting	true
float	explosiveness	0.0
int	fixed_fps	0
bool	flag_align_y	false
bool	fract_delta	true
Vector2	gravity	Vector2( 0, 98 )
float	hue_variation	0.0
Curve	hue_variation_curve
float	hue_variation_random	0.0
float	initial_velocity	0.0
float	initial_velocity_random	0.0
float	lifetime	1.0
float	lifetime_randomness	0.0
float	linear_accel	0.0
Curve	linear_accel_curve
float	linear_accel_random	0.0
bool	local_coords	true
Texture	normalmap
bool	one_shot	false
float	orbit_velocity	0.0
Curve	orbit_velocity_curve
float	orbit_velocity_random	0.0
float	preprocess	0.0
float	radial_accel	0.0
Curve	radial_accel_curve
float	radial_accel_random	0.0
float	randomness	0.0
float	scale_amount	1.0
Curve	scale_amount_curve
float	scale_amount_random	0.0
float	speed_scale	1.0
float	spread	45.0
float	tangential_accel	0.0
Curve	tangential_accel_curve
float	tangential_accel_random	0.0
Texture	texture

Methods

void	convert_from_particles ( Node particles )
float	get_param ( Parameter param ) const
Curve	get_param_curve ( Parameter param ) const
float	get_param_randomness ( Parameter param ) const
bool	get_particle_flag ( Flags flag ) const
void	restart ( )
void	set_param ( Parameter param, float value )
void	set_param_curve ( Parameter param, Curve curve )
void	set_param_randomness ( Parameter param, float randomness )
void	set_particle_flag ( Flags flag, bool enable )

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.

enum Parameter:

• PARAM_INITIAL_LINEAR_VELOCITY = 0 --- Use with set_param, set_param_randomness, and set_param_curve to set initial velocity properties.
• PARAM_ANGULAR_VELOCITY = 1 --- Use with set_param, set_param_randomness, and set_param_curve to set angular velocity properties.
• PARAM_ORBIT_VELOCITY = 2 --- Use with set_param, set_param_randomness, and set_param_curve to set orbital velocity properties.
• PARAM_LINEAR_ACCEL = 3 --- Use with set_param, set_param_randomness, and set_param_curve to set linear acceleration properties.
• PARAM_RADIAL_ACCEL = 4 --- Use with set_param, set_param_randomness, and set_param_curve to set radial acceleration properties.
• PARAM_TANGENTIAL_ACCEL = 5 --- Use with set_param, set_param_randomness, and set_param_curve to set tangential acceleration properties.
• PARAM_DAMPING = 6 --- Use with set_param, set_param_randomness, and set_param_curve to set damping properties.
• PARAM_ANGLE = 7 --- Use with set_param, set_param_randomness, and set_param_curve to set angle properties.
• PARAM_SCALE = 8 --- Use with set_param, set_param_randomness, and set_param_curve to set scale properties.
• PARAM_HUE_VARIATION = 9 --- Use with set_param, set_param_randomness, and set_param_curve to set hue variation properties.
• PARAM_ANIM_SPEED = 10 --- Use with set_param, set_param_randomness, and set_param_curve to set animation speed properties.
• PARAM_ANIM_OFFSET = 11 --- Use with set_param, set_param_randomness, and set_param_curve to set animation offset properties.
• PARAM_MAX = 12 --- Represents the size of the Parameter enum.

enum Flags:

• FLAG_ALIGN_Y_TO_VELOCITY = 0 --- Use with set_particle_flag to set flag_align_y.
• FLAG_ROTATE_Y = 1 --- Present for consistency with 3D particle nodes, not used in 2D.
• FLAG_DISABLE_Z = 2 --- Present for consistency with 3D particle nodes, not used in 2D.
• FLAG_MAX = 3 --- Represents the size of the Flags enum.

enum EmissionShape:

• EMISSION_SHAPE_POINT = 0 --- All particles will be emitted from a single point.
• EMISSION_SHAPE_SPHERE = 1 --- Particles will be emitted on the surface of a sphere flattened to two dimensions.
• EMISSION_SHAPE_RECTANGLE = 2 --- Particles will be emitted in the area of a rectangle.
• EMISSION_SHAPE_POINTS = 3 --- Particles will be emitted at a position chosen randomly among emission_points. Particle color will be modulated by emission_colors.
• EMISSION_SHAPE_DIRECTED_POINTS = 4 --- Particles will be emitted at a position chosen randomly among emission_points. Particle velocity and rotation will be set based on emission_normals. Particle color will be modulated by emission_colors.
• EMISSION_SHAPE_MAX = 5 --- Represents the size of the EmissionShape enum.

Property Descriptions

int amount

Default	8
Setter	set_amount(value)
Getter	get_amount()

Number of particles emitted in one emission cycle.

float angle

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial rotation applied to each particle, in degrees.

Curve angle_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's rotation will be animated along this Curve.

float angle_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Rotation randomness ratio.

float angular_velocity

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial angular velocity applied to each particle. Sets the speed of rotation of the particle.

Curve angular_velocity_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's angular velocity will vary along this Curve.

float angular_velocity_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Angular velocity randomness ratio.

float anim_offset

Default	0.0
Setter	set_param(value)
Getter	get_param()

Particle animation offset.

Curve anim_offset_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's animation offset will vary along this Curve.

float anim_offset_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Animation offset randomness ratio.

float anim_speed

Default	0.0
Setter	set_param(value)
Getter	get_param()

Particle animation speed.

Curve anim_speed_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's animation speed will vary along this Curve.

float anim_speed_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Animation speed randomness ratio.

Color color

Default	Color( 1, 1, 1, 1 )
Setter	set_color(value)
Getter	get_color()

Each particle's initial color. If texture is defined, it will be multiplied by this color.

Gradient color_ramp

Setter	set_color_ramp(value)
Getter	get_color_ramp()

Each particle's color will vary along this Gradient.

float damping

Default	0.0
Setter	set_param(value)
Getter	get_param()

The rate at which particles lose velocity.

Curve damping_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Damping will vary along this Curve.

float damping_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Damping randomness ratio.

Vector2 direction

Default	Vector2( 1, 0 )
Setter	set_direction(value)
Getter	get_direction()

Unit vector specifying the particles' emission direction.

DrawOrder draw_order

Default	0
Setter	set_draw_order(value)
Getter	get_draw_order()

Particle draw order. Uses DrawOrder values.

PoolColorArray emission_colors

Setter	set_emission_colors(value)
Getter	get_emission_colors()

Sets the Colors to modulate particles by when using EMISSION_SHAPE_POINTS or EMISSION_SHAPE_DIRECTED_POINTS.

PoolVector2Array emission_normals

Setter	set_emission_normals(value)
Getter	get_emission_normals()

Sets the direction the particles will be emitted in when using EMISSION_SHAPE_DIRECTED_POINTS.

PoolVector2Array emission_points

Setter	set_emission_points(value)
Getter	get_emission_points()

Sets the initial positions to spawn particles when using EMISSION_SHAPE_POINTS or EMISSION_SHAPE_DIRECTED_POINTS.

Vector2 emission_rect_extents

Setter	set_emission_rect_extents(value)
Getter	get_emission_rect_extents()

The rectangle's extents if emission_shape is set to EMISSION_SHAPE_RECTANGLE.

EmissionShape emission_shape

Default	0
Setter	set_emission_shape(value)
Getter	get_emission_shape()

Particles will be emitted inside this region. See EmissionShape for possible values.

float emission_sphere_radius

Setter	set_emission_sphere_radius(value)
Getter	get_emission_sphere_radius()

The sphere's radius if emission_shape is set to EMISSION_SHAPE_SPHERE.

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	0
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 flag_align_y

Default	false
Setter	set_particle_flag(value)
Getter	get_particle_flag()

Align Y axis of particle with the direction of its velocity.

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.

Vector2 gravity

Default	Vector2( 0, 98 )
Setter	set_gravity(value)
Getter	get_gravity()

Gravity applied to every particle.

float hue_variation

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial hue variation applied to each particle.

Curve hue_variation_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's hue will vary along this Curve.

float hue_variation_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Hue variation randomness ratio.

float initial_velocity

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial velocity magnitude for each particle. Direction comes from spread and the node's orientation.

float initial_velocity_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Initial velocity randomness ratio.

float lifetime

Default	1.0
Setter	set_lifetime(value)
Getter	get_lifetime()

Amount of time each particle will exist.

float lifetime_randomness

Default	0.0
Setter	set_lifetime_randomness(value)
Getter	get_lifetime_randomness()

Particle lifetime randomness ratio.

float linear_accel

Default	0.0
Setter	set_param(value)
Getter	get_param()

Linear acceleration applied to each particle in the direction of motion.

Curve linear_accel_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's linear acceleration will vary along this Curve.

float linear_accel_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Linear acceleration randomness ratio.

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.

Texture normalmap

Setter	set_normalmap(value)
Getter	get_normalmap()

Normal map to be used for the texture property.

Note: Godot expects the normal map to use X+, Y-, and Z+ coordinates. See this page for a comparison of normal map coordinates expected by popular engines.

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 orbit_velocity

Default	0.0
Setter	set_param(value)
Getter	get_param()

Orbital velocity applied to each particle. Makes the particles circle around origin. Specified in number of full rotations around origin per second.

Curve orbit_velocity_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's orbital velocity will vary along this Curve.

float orbit_velocity_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Orbital velocity randomness ratio.

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.

float radial_accel

Default	0.0
Setter	set_param(value)
Getter	get_param()

Radial acceleration applied to each particle. Makes particle accelerate away from origin.

Curve radial_accel_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's radial acceleration will vary along this Curve.

float radial_accel_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Radial acceleration randomness ratio.

float randomness

Default	0.0
Setter	set_randomness_ratio(value)
Getter	get_randomness_ratio()

Emission lifetime randomness ratio.

float scale_amount

Default	1.0
Setter	set_param(value)
Getter	get_param()

Initial scale applied to each particle.

Curve scale_amount_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's scale will vary along this Curve.

float scale_amount_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Scale 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.

float spread

Default	45.0
Setter	set_spread(value)
Getter	get_spread()

Each particle's initial direction range from +spread to -spread degrees.

float tangential_accel

Default	0.0
Setter	set_param(value)
Getter	get_param()

Tangential acceleration applied to each particle. Tangential acceleration is perpendicular to the particle's velocity giving the particles a swirling motion.

Curve tangential_accel_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's tangential acceleration will vary along this Curve.

float tangential_accel_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Tangential acceleration randomness ratio.

Texture texture

Setter	set_texture(value)
Getter	get_texture()

Particle texture. If null, particles will be squares.

Method Descriptions

void convert_from_particles ( Node particles )

Sets this node's properties to match a given Particles2D node with an assigned ParticlesMaterial.

float get_param ( Parameter param ) const

Returns the base value of the parameter specified by Parameter.

Curve get_param_curve ( Parameter param ) const

Returns the Curve of the parameter specified by Parameter.

float get_param_randomness ( Parameter param ) const

Returns the randomness factor of the parameter specified by Parameter.

bool get_particle_flag ( Flags flag ) const

Returns the enabled state of the given flag (see Flags for options).

void restart ( )

Restarts the particle emitter.

void set_param ( Parameter param, float value )

Sets the base value of the parameter specified by Parameter.

void set_param_curve ( Parameter param, Curve curve )

Sets the Curve of the parameter specified by Parameter.

void set_param_randomness ( Parameter param, float randomness )

Sets the randomness factor of the parameter specified by Parameter.

void set_particle_flag ( Flags flag, bool enable )

Enables or disables the given flag (see Flags for options).