CPUParticles3D

Inherits: GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

CPU-based 3D particle emitter.

Description

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

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

Properties

int	amount	8
Curve	angle_curve
float	angle_max	0.0
float	angle_min	0.0
Curve	angular_velocity_curve
float	angular_velocity_max	0.0
float	angular_velocity_min	0.0
Curve	anim_offset_curve
float	anim_offset_max	0.0
float	anim_offset_min	0.0
Curve	anim_speed_curve
float	anim_speed_max	0.0
float	anim_speed_min	0.0
Color	color	Color(1, 1, 1, 1)
Gradient	color_initial_ramp
Gradient	color_ramp
Curve	damping_curve
float	damping_max	0.0
float	damping_min	0.0
Vector3	direction	Vector3(1, 0, 0)
DrawOrder	draw_order	0
Vector3	emission_box_extents
PackedColorArray	emission_colors	PackedColorArray()
PackedVector3Array	emission_normals
PackedVector3Array	emission_points
Vector3	emission_ring_axis
float	emission_ring_height
float	emission_ring_inner_radius
float	emission_ring_radius
EmissionShape	emission_shape	0
float	emission_sphere_radius
bool	emitting	true
float	explosiveness	0.0
int	fixed_fps	0
float	flatness	0.0
bool	fract_delta	true
Vector3	gravity	Vector3(0, -9.8, 0)
Curve	hue_variation_curve
float	hue_variation_max	0.0
float	hue_variation_min	0.0
float	initial_velocity_max	0.0
float	initial_velocity_min	0.0
float	lifetime	1.0
float	lifetime_randomness	0.0
Curve	linear_accel_curve
float	linear_accel_max	0.0
float	linear_accel_min	0.0
bool	local_coords	true
Mesh	mesh
bool	one_shot	false
Curve	orbit_velocity_curve
float	orbit_velocity_max
float	orbit_velocity_min
bool	particle_flag_align_y	false
bool	particle_flag_disable_z	false
bool	particle_flag_rotate_y	false
float	preprocess	0.0
Curve	radial_accel_curve
float	radial_accel_max	0.0
float	radial_accel_min	0.0
float	randomness	0.0
Curve	scale_amount_curve
float	scale_amount_max	1.0
float	scale_amount_min	1.0
Curve	scale_curve_x
Curve	scale_curve_y
Curve	scale_curve_z
float	speed_scale	1.0
bool	split_scale	false
float	spread	45.0
Curve	tangential_accel_curve
float	tangential_accel_max	0.0
float	tangential_accel_min	0.0

Methods

void	convert_from_particles ( Node particles )
Curve	get_param_curve ( Parameter param ) const
float	get_param_max ( Parameter param ) const
float	get_param_min ( Parameter param ) const
bool	get_particle_flag ( ParticleFlags particle_flag ) const
void	restart ( )
void	set_param_curve ( Parameter param, Curve curve )
void	set_param_max ( Parameter param, float value )
void	set_param_min ( Parameter param, float value )
void	set_particle_flag ( ParticleFlags particle_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.

• DRAW_ORDER_VIEW_DEPTH = 2 --- Particles are drawn in order of depth.

---

enum Parameter:

• PARAM_INITIAL_LINEAR_VELOCITY = 0 --- Use with set_param_min, set_param_max, and set_param_curve to set initial velocity properties.

• PARAM_ANGULAR_VELOCITY = 1 --- Use with set_param_min, set_param_max, and set_param_curve to set angular velocity properties.

• PARAM_ORBIT_VELOCITY = 2 --- Use with set_param_min, set_param_max, and set_param_curve to set orbital velocity properties.

• PARAM_LINEAR_ACCEL = 3 --- Use with set_param_min, set_param_max, and set_param_curve to set linear acceleration properties.

• PARAM_RADIAL_ACCEL = 4 --- Use with set_param_min, set_param_max, and set_param_curve to set radial acceleration properties.

• PARAM_TANGENTIAL_ACCEL = 5 --- Use with set_param_min, set_param_max, and set_param_curve to set tangential acceleration properties.

• PARAM_DAMPING = 6 --- Use with set_param_min, set_param_max, and set_param_curve to set damping properties.

• PARAM_ANGLE = 7 --- Use with set_param_min, set_param_max, and set_param_curve to set angle properties.

• PARAM_SCALE = 8 --- Use with set_param_min, set_param_max, and set_param_curve to set scale properties.

• PARAM_HUE_VARIATION = 9 --- Use with set_param_min, set_param_max, and set_param_curve to set hue variation properties.

• PARAM_ANIM_SPEED = 10 --- Use with set_param_min, set_param_max, and set_param_curve to set animation speed properties.

• PARAM_ANIM_OFFSET = 11 --- Use with set_param_min, set_param_max, and set_param_curve to set animation offset properties.

• PARAM_MAX = 12 --- Represents the size of the Parameter enum.

---

enum ParticleFlags:

• PARTICLE_FLAG_ALIGN_Y_TO_VELOCITY = 0 --- Use with set_particle_flag to set particle_flag_align_y.

• PARTICLE_FLAG_ROTATE_Y = 1 --- Use with set_particle_flag to set particle_flag_rotate_y.

• PARTICLE_FLAG_DISABLE_Z = 2 --- Use with set_particle_flag to set particle_flag_disable_z.

• PARTICLE_FLAG_MAX = 3 --- Represents the size of the ParticleFlags enum.

---

enum EmissionShape:

• EMISSION_SHAPE_POINT = 0 --- All particles will be emitted from a single point.

• EMISSION_SHAPE_SPHERE = 1 --- Particles will be emitted in the volume of a sphere.

• EMISSION_SHAPE_BOX = 2 --- Particles will be emitted in the volume of a box.

• 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_RING = 5 --- Particles will be emitted in a ring or cylinder.

• EMISSION_SHAPE_MAX = 6 --- 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.

---

• Curve angle_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

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

---

• float angle_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum angle.

---

• float angle_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum angle.

---

• Curve angular_velocity_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Each particle's angular velocity (rotation speed) will vary along this Curve over its lifetime.

---

• float angular_velocity_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum initial angular velocity (rotation speed) applied to each particle in degrees per second.

---

• float angular_velocity_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum initial angular velocity (rotation speed) applied to each particle in degrees per second.

---

• 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_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum animation offset.

---

• float anim_offset_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum animation offset.

---

• 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_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum particle animation speed.

---

• float anim_speed_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum particle animation speed.

---

• Color color

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

Each particle's initial color. To have particle display color in a BaseMaterial3D make sure to set BaseMaterial3D.vertex_color_use_as_albedo to true.

---

• Gradient color_initial_ramp

Setter	set_color_initial_ramp(value)
Getter	get_color_initial_ramp()

Each particle's initial color will vary along this GradientTexture1D (multiplied with color).

---

• Gradient color_ramp

Setter	set_color_ramp(value)
Getter	get_color_ramp()

Each particle's color will vary along this GradientTexture1D over its lifetime (multiplied with color).

---

• Curve damping_curve

Setter	set_param_curve(value)
Getter	get_param_curve()

Damping will vary along this Curve.

---

• float damping_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum damping.

---

• float damping_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum damping

---

• Vector3 direction

Default	Vector3(1, 0, 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.

---

• Vector3 emission_box_extents

Setter	set_emission_box_extents(value)
Getter	get_emission_box_extents()

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

---

• PackedColorArray emission_colors

Default	PackedColorArray()
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.

---

• PackedVector3Array 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.

---

• PackedVector3Array 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.

---

• Vector3 emission_ring_axis

Setter	set_emission_ring_axis(value)
Getter	get_emission_ring_axis()

The axis of the ring when using the emitter EMISSION_SHAPE_RING.

---

• float emission_ring_height

Setter	set_emission_ring_height(value)
Getter	get_emission_ring_height()

The height of the ring when using the emitter EMISSION_SHAPE_RING.

---

• float emission_ring_inner_radius

Setter	set_emission_ring_inner_radius(value)
Getter	get_emission_ring_inner_radius()

The inner radius of the ring when using the emitter EMISSION_SHAPE_RING.

---

• float emission_ring_radius

Setter	set_emission_ring_radius(value)
Getter	get_emission_ring_radius()

The radius of the ring when using the emitter EMISSION_SHAPE_RING.

---

• 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 EmissionShape 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 particle system itself.

---

• float flatness

Default	0.0
Setter	set_flatness(value)
Getter	get_flatness()

Amount of spread in Y/Z plane. A value of 1 restricts particles to X/Z plane.

---

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

---

• Vector3 gravity

Default	Vector3(0, -9.8, 0)
Setter	set_gravity(value)
Getter	get_gravity()

Gravity applied to every 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_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum hue variation.

---

• float hue_variation_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum hue variation.

---

• float initial_velocity_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum value of the initial velocity.

---

• float initial_velocity_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum value of the initial velocity.

---

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

---

• 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_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum linear acceleration.

---

• float linear_accel_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum linear acceleration.

---

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

---

• Mesh mesh

Setter	set_mesh(value)
Getter	get_mesh()

The Mesh used for each particle. If null, particles will be spheres.

---

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

---

• 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_max

Setter	set_param_max(value)
Getter	get_param_max()

Maximum orbit velocity.

---

• float orbit_velocity_min

Setter	set_param_min(value)
Getter	get_param_min()

Minimum orbit velocity.

---

• bool particle_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 particle_flag_disable_z

Default	false
Setter	set_particle_flag(value)
Getter	get_particle_flag()

If true, particles will not move on the Z axis.

---

• bool particle_flag_rotate_y

Default	false
Setter	set_particle_flag(value)
Getter	get_particle_flag()

If true, particles rotate around Y axis by angle_min.

---

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

---

• 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_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum radial acceleration.

---

• float radial_accel_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum radial acceleration.

---

• float randomness

Default	0.0
Setter	set_randomness_ratio(value)
Getter	get_randomness_ratio()

Emission lifetime randomness ratio.

---

• 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_max

Default	1.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum scale.

---

• float scale_amount_min

Default	1.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum scale.

---

• Curve scale_curve_x

Setter	set_scale_curve_x(value)
Getter	get_scale_curve_x()

Curve for the scale over life, along the x axis.

---

• Curve scale_curve_y

Setter	set_scale_curve_y(value)
Getter	get_scale_curve_y()

Curve for the scale over life, along the y axis.

---

• Curve scale_curve_z

Setter	set_scale_curve_z(value)
Getter	get_scale_curve_z()

Curve for the scale over life, along the z axis.

---

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

---

• bool split_scale

Default	false
Setter	set_split_scale(value)
Getter	get_split_scale()

If set to true, three different scale curves can be specified, one per scale axis.

---

• float spread

Default	45.0
Setter	set_spread(value)
Getter	get_spread()

Each particle's initial direction range from +spread to -spread degrees. Applied to X/Z plane and Y/Z planes.

---

• 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_max

Default	0.0
Setter	set_param_max(value)
Getter	get_param_max()

Maximum tangent acceleration.

---

• float tangential_accel_min

Default	0.0
Setter	set_param_min(value)
Getter	get_param_min()

Minimum tangent acceleration.

Method Descriptions

• void convert_from_particles ( Node particles )

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

---

• Curve get_param_curve ( Parameter param ) const

Returns the Curve of the parameter specified by Parameter.

---

• float get_param_max ( Parameter param ) const

---

• float get_param_min ( Parameter param ) const

---

• bool get_particle_flag ( ParticleFlags particle_flag ) const

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

---

• void restart ( )

Restarts the particle emitter.

---

• void set_param_curve ( Parameter param, Curve curve )

Sets the Curve of the parameter specified by Parameter.

---

• void set_param_max ( Parameter param, float value )

Sets the maximum value for the given parameter

---

• void set_param_min ( Parameter param, float value )

Sets the minimum value for the given parameter

---

• void set_particle_flag ( ParticleFlags particle_flag, bool enable )

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