Inheritance #

CPUParticles3D #

is_instantiable, Node3D, Node, core, not_builtin_classes

A CPU-based 3D particle emitter.

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.

Members #

var amount: int = 8#

Number of particles emitted in one emission cycle.

var angle_curve: Curve#

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

var angle_max: float = 0.0#

Maximum angle.

var angle_min: float = 0.0#

Minimum angle.

var angular_velocity_curve: Curve#

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

var angular_velocity_max: float = 0.0#

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

var angular_velocity_min: float = 0.0#

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

var anim_offset_curve: Curve#

Each particle's animation offset will vary along this Curve. Should be a unit Curve.

var anim_offset_max: float = 0.0#

Maximum animation offset.

var anim_offset_min: float = 0.0#

Minimum animation offset.

var anim_speed_curve: Curve#

Each particle's animation speed will vary along this Curve. Should be a unit Curve.

var anim_speed_max: float = 0.0#

Maximum particle animation speed.

var anim_speed_min: float = 0.0#

Minimum particle animation speed.

var color: Color = Color(1, 1, 1, 1)#

Each particle's initial color.

Note: color multiplies the particle mesh's vertex colors. To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, color will have no visible effect.

var color_initial_ramp: Gradient#

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

Note: color_initial_ramp multiplies the particle mesh's vertex colors. To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, color_initial_ramp will have no visible effect.

var color_ramp: Gradient#

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

Note: color_ramp multiplies the particle mesh's vertex colors. To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, color_ramp will have no visible effect.

var damping_curve: Curve#

Damping will vary along this Curve. Should be a unit Curve.

var damping_max: float = 0.0#

Maximum damping.

var damping_min: float = 0.0#

Minimum damping.

var direction: Vector3 = Vector3(1, 0, 0)#

Unit vector specifying the particles' emission direction.

var draw_order = DRAW_ORDER_INDEX#

Particle draw order. Uses DrawOrder values.

var emission_box_extents: Vector3#

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

var emission_colors: PackedColorArray = PackedColorArray()#

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

Note: emission_colors multiplies the particle mesh's vertex colors. To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, emission_colors will have no visible effect.

var emission_normals: PackedVector3Array#

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

var emission_points: PackedVector3Array#

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

var emission_ring_axis: Vector3#

The axis of the ring when using the emitter EMISSION_SHAPE_RING.

var emission_ring_cone_angle: float#

The angle of the cone when using the emitter EMISSION_SHAPE_RING. The default angle of 90 degrees results in a ring, while an angle of 0 degrees results in a cone. Intermediate values will result in a ring where one end is larger than the other.

Note: Depending on emission_ring_height, the angle may be clamped if the ring's end is reached to form a perfect cone.

var emission_ring_height: float#

The height of the ring when using the emitter EMISSION_SHAPE_RING.

var emission_ring_inner_radius: float#

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

var emission_ring_radius: float#

The radius of the ring when using the emitter EMISSION_SHAPE_RING.

var emission_shape = EMISSION_SHAPE_POINT#

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

var emission_sphere_radius: float#

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

var emitting: bool = true#

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 until after all active particles finish processing. You can use the finished signal to be notified once all active particles finish processing.

var explosiveness: float = 0.0#

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.

var fixed_fps: int = 0#

The particle system's frame rate is fixed to a value. For example, 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.

var flatness: float = 0.0#

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

var fract_delta: bool = true#

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

var gravity: Vector3 = Vector3(0, -9.8, 0)#

Gravity applied to every particle.

var hue_variation_curve: Curve#

Each particle's hue will vary along this Curve. Should be a unit Curve.

var hue_variation_max: float = 0.0#

Maximum hue variation.

var hue_variation_min: float = 0.0#

Minimum hue variation.

var initial_velocity_max: float = 0.0#

Maximum value of the initial velocity.

var initial_velocity_min: float = 0.0#

Minimum value of the initial velocity.

var lifetime: float = 1.0#

Amount of time each particle will exist.

var lifetime_randomness: float = 0.0#

Particle lifetime randomness ratio.

var linear_accel_curve: Curve#

Each particle's linear acceleration will vary along this Curve. Should be a unit Curve.

var linear_accel_max: float = 0.0#

Maximum linear acceleration.

var linear_accel_min: float = 0.0#

Minimum linear acceleration.

var local_coords: bool = false#

If true, particles use the parent node's coordinate space (known as local coordinates). This will cause particles to move and rotate along the CPUParticles3D node (and its parents) when it is moved or rotated. If false, particles use global coordinates; they will not move or rotate along the CPUParticles3D node (and its parents) when it is moved or rotated.

var mesh: Mesh#

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

var one_shot: bool = false#

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

var orbit_velocity_curve: Curve#

Each particle's orbital velocity will vary along this Curve. Should be a unit Curve.

var orbit_velocity_max: float#

Maximum orbit velocity.

var orbit_velocity_min: float#

Minimum orbit velocity.

var particle_flag_align_y: bool = false#

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

var particle_flag_disable_z: bool = false#

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

var particle_flag_rotate_y: bool = false#

If true, particles rotate around Y axis by angle_min.

var preprocess: float = 0.0#

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

var radial_accel_curve: Curve#

Each particle's radial acceleration will vary along this Curve. Should be a unit Curve.

var radial_accel_max: float = 0.0#

Maximum radial acceleration.

var radial_accel_min: float = 0.0#

Minimum radial acceleration.

var randomness: float = 0.0#

Emission lifetime randomness ratio.

var scale_amount_curve: Curve#

Each particle's scale will vary along this Curve. Should be a unit Curve.

var scale_amount_max: float = 1.0#

Maximum scale.

var scale_amount_min: float = 1.0#

Minimum scale.

var scale_curve_x: Curve#

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

var scale_curve_y: Curve#

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

var scale_curve_z: Curve#

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

var seed: int = 0#

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

var speed_scale: float = 1.0#

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

var split_scale: bool = false#

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

var spread: float = 45.0#

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

var tangential_accel_curve: Curve#

Each particle's tangential acceleration will vary along this Curve. Should be a unit Curve.

var tangential_accel_max: float = 0.0#

Maximum tangent acceleration.

var tangential_accel_min: float = 0.0#

Minimum tangent acceleration.

var use_fixed_seed: bool = false#

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.

var visibility_aabb: AABB = AABB(0, 0, 0, 0, 0, 0)#

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

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

Methods #

Annotations #

Constants #

const DRAW_ORDER_INDEX = 0 enum DrawOrder#

Particles are drawn in the order emitted.

const DRAW_ORDER_LIFETIME = 1 enum DrawOrder#

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

const DRAW_ORDER_VIEW_DEPTH = 2 enum DrawOrder#

Particles are drawn in order of depth.

const PARAM_INITIAL_LINEAR_VELOCITY = 0 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set initial velocity properties.

const PARAM_ANGULAR_VELOCITY = 1 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set angular velocity properties.

const PARAM_ORBIT_VELOCITY = 2 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set orbital velocity properties.

const PARAM_LINEAR_ACCEL = 3 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set linear acceleration properties.

const PARAM_RADIAL_ACCEL = 4 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set radial acceleration properties.

const PARAM_TANGENTIAL_ACCEL = 5 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set tangential acceleration properties.

const PARAM_DAMPING = 6 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set damping properties.

const PARAM_ANGLE = 7 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set angle properties.

const PARAM_SCALE = 8 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set scale properties.

const PARAM_HUE_VARIATION = 9 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set hue variation properties.

const PARAM_ANIM_SPEED = 10 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set animation speed properties.

const PARAM_ANIM_OFFSET = 11 enum Parameter#

Use with set_param_min, set_param_max, and set_param_curve to set animation offset properties.

const PARAM_MAX = 12 enum Parameter#

Represents the size of the Parameter enum.

const PARTICLE_FLAG_ALIGN_Y_TO_VELOCITY = 0 enum ParticleFlags#

Use with set_particle_flag to set particle_flag_align_y.

const PARTICLE_FLAG_ROTATE_Y = 1 enum ParticleFlags#

Use with set_particle_flag to set particle_flag_rotate_y.

const PARTICLE_FLAG_DISABLE_Z = 2 enum ParticleFlags#

Use with set_particle_flag to set particle_flag_disable_z.

const PARTICLE_FLAG_MAX = 3 enum ParticleFlags#

Represents the size of the ParticleFlags enum.

const EMISSION_SHAPE_POINT = 0 enum EmissionShape#

All particles will be emitted from a single point.

const EMISSION_SHAPE_SPHERE = 1 enum EmissionShape#

Particles will be emitted in the volume of a sphere.

const EMISSION_SHAPE_SPHERE_SURFACE = 2 enum EmissionShape#

Particles will be emitted on the surface of a sphere.

const EMISSION_SHAPE_BOX = 3 enum EmissionShape#

Particles will be emitted in the volume of a box.

const EMISSION_SHAPE_POINTS = 4 enum EmissionShape#

Particles will be emitted at a position chosen randomly among emission_points. Particle color will be modulated by emission_colors.

const EMISSION_SHAPE_DIRECTED_POINTS = 5 enum EmissionShape#

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.

const EMISSION_SHAPE_RING = 6 enum EmissionShape#

Particles will be emitted in a ring or cylinder.

const EMISSION_SHAPE_MAX = 7 enum EmissionShape#

Represents the size of the EmissionShape enum.

Constructors #

Enums #

DrawOrder#

Parameter#

ParticleFlags#

EmissionShape#

Operators #

Signals #

signal finished()#

Emitted when all active particles have finished processing. When one_shot is disabled, particles will process continuously, so this is never emitted.

Theme Items #

Tutorials #