Table of Contents

Class CPUParticles3D

A CPU-based 3D particle emitter.

Inheritance
CPUParticles3D

Remarks

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.

See Also

Particle systems (3D)

Properties

amount

Number of particles emitted in one emission cycle.

var amount : int = 8

Property Value

int

Remarks

  • void set_amount(int value)
  • int get_amount

angle_curve

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

var angle_curve : Curve

Property Value

Curve

Remarks

angle_max

Maximum angle.

var angle_max : float = 0.0

Property Value

float

Remarks

angle_min

Minimum angle.

var angle_min : float = 0.0

Property Value

float

Remarks

angular_velocity_curve

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

var angular_velocity_curve : Curve

Property Value

Curve

Remarks

angular_velocity_max

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

var angular_velocity_max : float = 0.0

Property Value

float

Remarks

angular_velocity_min

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

var angular_velocity_min : float = 0.0

Property Value

float

Remarks

anim_offset_curve

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

var anim_offset_curve : Curve

Property Value

Curve

Remarks

anim_offset_max

Maximum animation offset.

var anim_offset_max : float = 0.0

Property Value

float

Remarks

anim_offset_min

Minimum animation offset.

var anim_offset_min : float = 0.0

Property Value

float

Remarks

anim_speed_curve

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

var anim_speed_curve : Curve

Property Value

Curve

Remarks

anim_speed_max

Maximum particle animation speed.

var anim_speed_max : float = 0.0

Property Value

float

Remarks

anim_speed_min

Minimum particle animation speed.

var anim_speed_min : float = 0.0

Property Value

float

Remarks

color

Each particle's initial color.

Note: color multiplies the particle mesh's vertex colors. To have a visible effect on a 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 : Color = Color(1, 1, 1, 1)

Property Value

Color

Remarks

color_initial_ramp

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, 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_initial_ramp : Gradient

Property Value

Gradient

Remarks

color_ramp

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, 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 color_ramp : Gradient

Property Value

Gradient

Remarks

damping_curve

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

var damping_curve : Curve

Property Value

Curve

Remarks

damping_max

Maximum damping.

var damping_max : float = 0.0

Property Value

float

Remarks

damping_min

Minimum damping.

var damping_min : float = 0.0

Property Value

float

Remarks

direction

Unit vector specifying the particles' emission direction.

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

Property Value

Vector3

Remarks

draw_order

Particle draw order. Uses DrawOrder values.

var draw_order : int = 0

Property Value

int

Remarks

  • void set_draw_order(int value)
  • int get_draw_order

emission_box_extents

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

var emission_box_extents : Vector3

Property Value

Vector3

Remarks

  • void set_emission_box_extents(Vector3 value)
  • Vector3 get_emission_box_extents

emission_colors

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

Note: emission_colors multiplies the particle mesh's vertex colors. To have a visible effect on a 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_colors : PackedColorArray = PackedColorArray()

Property Value

PackedColorArray

Remarks

emission_normals

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

var emission_normals : PackedVector3Array

Property Value

PackedVector3Array

Remarks

emission_points

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

var emission_points : PackedVector3Array

Property Value

PackedVector3Array

Remarks

emission_ring_axis

The axis of the ring when using the emitter CPUParticles3D.EMISSION_SHAPE_RING.

var emission_ring_axis : Vector3

Property Value

Vector3

Remarks

  • void set_emission_ring_axis(Vector3 value)
  • Vector3 get_emission_ring_axis

emission_ring_cone_angle

The angle of the cone when using the emitter CPUParticles3D.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_cone_angle : float

Property Value

float

Remarks

  • void set_emission_ring_cone_angle(float value)
  • float get_emission_ring_cone_angle

emission_ring_height

The height of the ring when using the emitter CPUParticles3D.EMISSION_SHAPE_RING.

var emission_ring_height : float

Property Value

float

Remarks

  • void set_emission_ring_height(float value)
  • float get_emission_ring_height

emission_ring_inner_radius

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

var emission_ring_inner_radius : float

Property Value

float

Remarks

  • void set_emission_ring_inner_radius(float value)
  • float get_emission_ring_inner_radius

emission_ring_radius

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

var emission_ring_radius : float

Property Value

float

Remarks

  • void set_emission_ring_radius(float value)
  • float get_emission_ring_radius

emission_shape

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

var emission_shape : int = 0

Property Value

int

Remarks

  • void set_emission_shape(int value)
  • int get_emission_shape

emission_sphere_radius

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

var emission_sphere_radius : float

Property Value

float

Remarks

  • void set_emission_sphere_radius(float value)
  • float get_emission_sphere_radius

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

var emitting : bool = true

Property Value

bool

Remarks

  • void set_emitting(bool value)
  • bool is_emitting

explosiveness

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 explosiveness : float = 0.0

Property Value

float

Remarks

  • void set_explosiveness_ratio(float value)
  • float get_explosiveness_ratio

fixed_fps

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 fixed_fps : int = 0

Property Value

int

Remarks

  • void set_fixed_fps(int value)
  • int get_fixed_fps

flatness

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

var flatness : float = 0.0

Property Value

float

Remarks

  • void set_flatness(float value)
  • float get_flatness

fract_delta

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

var fract_delta : bool = true

Property Value

bool

Remarks

  • void set_fractional_delta(bool value)
  • bool get_fractional_delta

gravity

Gravity applied to every particle.

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

Property Value

Vector3

Remarks

hue_variation_curve

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

var hue_variation_curve : Curve

Property Value

Curve

Remarks

hue_variation_max

Maximum hue variation.

var hue_variation_max : float = 0.0

Property Value

float

Remarks

hue_variation_min

Minimum hue variation.

var hue_variation_min : float = 0.0

Property Value

float

Remarks

initial_velocity_max

Maximum value of the initial velocity.

var initial_velocity_max : float = 0.0

Property Value

float

Remarks

initial_velocity_min

Minimum value of the initial velocity.

var initial_velocity_min : float = 0.0

Property Value

float

Remarks

lifetime

Amount of time each particle will exist.

var lifetime : float = 1.0

Property Value

float

Remarks

  • void set_lifetime(float value)
  • float get_lifetime

lifetime_randomness

Particle lifetime randomness ratio.

var lifetime_randomness : float = 0.0

Property Value

float

Remarks

  • void set_lifetime_randomness(float value)
  • float get_lifetime_randomness

linear_accel_curve

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

var linear_accel_curve : Curve

Property Value

Curve

Remarks

linear_accel_max

Maximum linear acceleration.

var linear_accel_max : float = 0.0

Property Value

float

Remarks

linear_accel_min

Minimum linear acceleration.

var linear_accel_min : float = 0.0

Property Value

float

Remarks

local_coords

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 local_coords : bool = false

Property Value

bool

Remarks

  • void set_use_local_coordinates(bool value)
  • bool get_use_local_coordinates

mesh

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

var mesh : Mesh

Property Value

Mesh

Remarks

  • void set_mesh(Mesh value)
  • Mesh get_mesh

one_shot

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

var one_shot : bool = false

Property Value

bool

Remarks

  • void set_one_shot(bool value)
  • bool get_one_shot

orbit_velocity_curve

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

var orbit_velocity_curve : Curve

Property Value

Curve

Remarks

orbit_velocity_max

Maximum orbit velocity.

var orbit_velocity_max : float

Property Value

float

Remarks

orbit_velocity_min

Minimum orbit velocity.

var orbit_velocity_min : float

Property Value

float

Remarks

particle_flag_align_y

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

var particle_flag_align_y : bool = false

Property Value

bool

Remarks

  • void set_particle_flag(int particle_flag, bool enable)
  • bool get_particle_flag(int particle_flag)

particle_flag_disable_z

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

var particle_flag_disable_z : bool = false

Property Value

bool

Remarks

  • void set_particle_flag(int particle_flag, bool enable)
  • bool get_particle_flag(int particle_flag)

particle_flag_rotate_y

If true, particles rotate around Y axis by angle_min.

var particle_flag_rotate_y : bool = false

Property Value

bool

Remarks

  • void set_particle_flag(int particle_flag, bool enable)
  • bool get_particle_flag(int particle_flag)

preprocess

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

var preprocess : float = 0.0

Property Value

float

Remarks

  • void set_pre_process_time(float value)
  • float get_pre_process_time

radial_accel_curve

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

var radial_accel_curve : Curve

Property Value

Curve

Remarks

radial_accel_max

Maximum radial acceleration.

var radial_accel_max : float = 0.0

Property Value

float

Remarks

radial_accel_min

Minimum radial acceleration.

var radial_accel_min : float = 0.0

Property Value

float

Remarks

randomness

Emission lifetime randomness ratio.

var randomness : float = 0.0

Property Value

float

Remarks

  • void set_randomness_ratio(float value)
  • float get_randomness_ratio

scale_amount_curve

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

var scale_amount_curve : Curve

Property Value

Curve

Remarks

scale_amount_max

Maximum scale.

var scale_amount_max : float = 1.0

Property Value

float

Remarks

scale_amount_min

Minimum scale.

var scale_amount_min : float = 1.0

Property Value

float

Remarks

scale_curve_x

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

var scale_curve_x : Curve

Property Value

Curve

Remarks

  • void set_scale_curve_x(Curve value)
  • Curve get_scale_curve_x

scale_curve_y

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

var scale_curve_y : Curve

Property Value

Curve

Remarks

  • void set_scale_curve_y(Curve value)
  • Curve get_scale_curve_y

scale_curve_z

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

var scale_curve_z : Curve

Property Value

Curve

Remarks

  • void set_scale_curve_z(Curve value)
  • Curve get_scale_curve_z

seed

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

var seed : int = 0

Property Value

int

Remarks

  • void set_seed(int value)
  • int get_seed

speed_scale

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

var speed_scale : float = 1.0

Property Value

float

Remarks

  • void set_speed_scale(float value)
  • float get_speed_scale

split_scale

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

var split_scale : bool = false

Property Value

bool

Remarks

  • void set_split_scale(bool value)
  • bool get_split_scale

spread

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

var spread : float = 45.0

Property Value

float

Remarks

tangential_accel_curve

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

var tangential_accel_curve : Curve

Property Value

Curve

Remarks

tangential_accel_max

Maximum tangent acceleration.

var tangential_accel_max : float = 0.0

Property Value

float

Remarks

tangential_accel_min

Minimum tangent acceleration.

var tangential_accel_min : float = 0.0

Property Value

float

Remarks

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.

var use_fixed_seed : bool = false

Property Value

bool

Remarks

  • void set_use_fixed_seed(bool value)
  • bool get_use_fixed_seed

visibility_aabb

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.

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

Property Value

AABB

Remarks

  • void set_visibility_aabb(AABB value)
  • AABB get_visibility_aabb

Methods

capture_aabb

Qualifiers: const

Returns the axis-aligned bounding box that contains all the particles that are active in the current frame.

AABB capture_aabb

convert_from_particles(Node)

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

void convert_from_particles(Node particles)

Parameters

particles Node

get_param_curve(int)

Qualifiers: const

Returns the Curve of the parameter specified by Parameter.

Curve get_param_curve(int param)

Parameters

param int

get_param_max(int)

Qualifiers: const

Returns the maximum value range for the given parameter.

float get_param_max(int param)

Parameters

param int

get_param_min(int)

Qualifiers: const

Returns the minimum value range for the given parameter.

float get_param_min(int param)

Parameters

param int

get_particle_flag(int)

Qualifiers: const

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

bool get_particle_flag(int particle_flag)

Parameters

particle_flag int

request_particles_process(float)

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

Useful for particle playback, if used in combination with use_fixed_seed or by calling CPUParticles3D.restart with parameter keep_seed set to true.

void request_particles_process(float process_time)

Parameters

process_time float

restart(bool)

Restarts the particle emitter.

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

void restart(bool keep_seed)

Parameters

keep_seed bool

set_param_curve(int, Curve)

Sets the Curve of the parameter specified by Parameter. Should be a unit Curve.

void set_param_curve(int param, Curve curve)

Parameters

param int
curve Curve

set_param_max(int, float)

Sets the maximum value for the given parameter.

void set_param_max(int param, float value)

Parameters

param int
value float

set_param_min(int, float)

Sets the minimum value for the given parameter.

void set_param_min(int param, float value)

Parameters

param int
value float

set_particle_flag(int, bool)

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

void set_particle_flag(int particle_flag, bool enable)

Parameters

particle_flag int
enable bool

Events

finished

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

signal finished