ParticlesMaterial

Inherits: Material < Resource < RefCounted < Object

Particle properties for GPUParticles3D and GPUParticles2D nodes.

Description

ParticlesMaterial defines particle properties and behavior. It is used in the process_material of GPUParticles3D and GPUParticles2D emitter nodes.

Some of this material's properties are applied to each particle when emitted, while others can have a CurveTexture applied to vary values over the lifetime of the particle.

Particle animation is available only in GPUParticles2D. To use it, attach a CanvasItemMaterial, with CanvasItemMaterial.particles_animation enabled, to the particles node.

Properties

Texture2D

angle_curve

float

angle_max

0.0

float

angle_min

0.0

Texture2D

angular_velocity_curve

float

angular_velocity_max

0.0

float

angular_velocity_min

0.0

Texture2D

anim_offset_curve

float

anim_offset_max

0.0

float

anim_offset_min

0.0

Texture2D

anim_speed_curve

float

anim_speed_max

0.0

float

anim_speed_min

0.0

bool

attractor_interaction_enabled

true

float

collision_bounce

0.0

bool

collision_enabled

false

float

collision_friction

0.0

bool

collision_use_scale

false

Color

color

Color(1, 1, 1, 1)

Texture2D

color_initial_ramp

Texture2D

color_ramp

Texture2D

damping_curve

float

damping_max

0.0

float

damping_min

0.0

Vector3

direction

Vector3(1, 0, 0)

Vector3

emission_box_extents

Texture2D

emission_color_texture

Texture2D

emission_normal_texture

int

emission_point_count

Texture2D

emission_point_texture

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

float

flatness

0.0

Vector3

gravity

Vector3(0, -9.8, 0)

Texture2D

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_randomness

0.0

Texture2D

linear_accel_curve

float

linear_accel_max

0.0

float

linear_accel_min

0.0

Texture2D

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

Texture2D

radial_accel_curve

float

radial_accel_max

0.0

float

radial_accel_min

0.0

Texture2D

scale_curve

float

scale_max

1.0

float

scale_min

1.0

float

spread

45.0

int

sub_emitter_amount_at_end

float

sub_emitter_frequency

bool

sub_emitter_keep_velocity

false

SubEmitterMode

sub_emitter_mode

0

Texture2D

tangential_accel_curve

float

tangential_accel_max

0.0

float

tangential_accel_min

0.0

Methods

float

get_param_max ( Parameter param ) const

float

get_param_min ( Parameter param ) const

Texture2D

get_param_texture ( Parameter param ) const

bool

get_particle_flag ( ParticleFlags particle_flag ) const

void

set_param_max ( Parameter param, float value )

void

set_param_min ( Parameter param, float value )

void

set_param_texture ( Parameter param, Texture2D texture )

void

set_particle_flag ( ParticleFlags particle_flag, bool enable )

Enumerations

enum Parameter:


enum ParticleFlags:


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_SPHERE_SURFACE = 2 --- Particles will be emitted on the surface of a sphere.

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

  • EMISSION_SHAPE_POINTS = 4 --- Particles will be emitted at a position determined by sampling a random point on the emission_point_texture. Particle color will be modulated by emission_color_texture.

  • EMISSION_SHAPE_DIRECTED_POINTS = 5 --- Particles will be emitted at a position determined by sampling a random point on the emission_point_texture. Particle velocity and rotation will be set based on emission_normal_texture. Particle color will be modulated by emission_color_texture.

  • EMISSION_SHAPE_RING = 6 --- Particles will be emitted in a ring or cylinder.

  • EMISSION_SHAPE_MAX = 7 --- Represents the size of the EmissionShape enum.


enum SubEmitterMode:

  • SUB_EMITTER_DISABLED = 0

  • SUB_EMITTER_CONSTANT = 1

  • SUB_EMITTER_AT_END = 2

  • SUB_EMITTER_AT_COLLISION = 3

  • SUB_EMITTER_MAX = 4

Property Descriptions

Setter

set_param_texture(value)

Getter

get_param_texture()

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


Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum angle.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum angle.


Setter

set_param_texture(value)

Getter

get_param_texture()

Each particle's angular velocity (rotation speed) will vary along this CurveTexture 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.


Setter

set_param_texture(value)

Getter

get_param_texture()

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


Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum animation offset.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum animation offset.


Setter

set_param_texture(value)

Getter

get_param_texture()

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


Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum particle animation speed. Animation speed of 1 means that the particles will make full 0 to 1 offset cycle during lifetime, 2 means 2 cycles etc.

With animation speed greater than 1, remember to enable CanvasItemMaterial.particles_anim_loop property if you want the animation to repeat.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum particle animation speed.


  • bool attractor_interaction_enabled

Default

true

Setter

set_attractor_interaction_enabled(value)

Getter

is_attractor_interaction_enabled()

True if the interaction with particle attractors is enabled.


Default

0.0

Setter

set_collision_bounce(value)

Getter

get_collision_bounce()

Collision bounciness.


  • bool collision_enabled

Default

false

Setter

set_collision_enabled(value)

Getter

is_collision_enabled()

True if collisions are enabled for this particle system.


  • float collision_friction

Default

0.0

Setter

set_collision_friction(value)

Getter

get_collision_friction()

Collision friction.


  • bool collision_use_scale

Default

false

Setter

set_collision_use_scale(value)

Getter

is_collision_using_scale()

Should collision take scale into account.


Default

Color(1, 1, 1, 1)

Setter

set_color(value)

Getter

get_color()

Each particle's initial color. If the GPUParticles2D's texture is defined, it will be multiplied by this color. To have particle display color in a BaseMaterial3D make sure to set BaseMaterial3D.vertex_color_use_as_albedo to true.


Setter

set_color_initial_ramp(value)

Getter

get_color_initial_ramp()

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


Setter

set_color_ramp(value)

Getter

get_color_ramp()

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


Setter

set_param_texture(value)

Getter

get_param_texture()

Damping will vary along this CurveTexture.


Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()


Default

Vector3(1, 0, 0)

Setter

set_direction(value)

Getter

get_direction()

Unit vector specifying the particles' emission direction.


Setter

set_emission_box_extents(value)

Getter

get_emission_box_extents()

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


Setter

set_emission_color_texture(value)

Getter

get_emission_color_texture()

Particle color will be modulated by color determined by sampling this texture at the same point as the emission_point_texture.


Setter

set_emission_normal_texture(value)

Getter

get_emission_normal_texture()

Particle velocity and rotation will be set by sampling this texture at the same point as the emission_point_texture. Used only in EMISSION_SHAPE_DIRECTED_POINTS. Can be created automatically from mesh or node by selecting "Create Emission Points from Mesh/Node" under the "Particles" tool in the toolbar.


  • int emission_point_count

Setter

set_emission_point_count(value)

Getter

get_emission_point_count()

The number of emission points if emission_shape is set to EMISSION_SHAPE_POINTS or EMISSION_SHAPE_DIRECTED_POINTS.


Setter

set_emission_point_texture(value)

Getter

get_emission_point_texture()

Particles will be emitted at positions determined by sampling this texture at a random position. Used with EMISSION_SHAPE_POINTS and EMISSION_SHAPE_DIRECTED_POINTS. Can be created automatically from mesh or node by selecting "Create Emission Points from Mesh/Node" under the "Particles" tool in the toolbar.


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.


Default

0

Setter

set_emission_shape(value)

Getter

get_emission_shape()

Particles will be emitted inside this region. Use EmissionShape constants for 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.


Default

0.0

Setter

set_flatness(value)

Getter

get_flatness()

Amount of spread along the Y axis.


Default

Vector3(0, -9.8, 0)

Setter

set_gravity(value)

Getter

get_gravity()

Gravity applied to every particle.


Setter

set_param_texture(value)

Getter

get_param_texture()

Each particle's hue will vary along this CurveTexture.


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


  • float initial_velocity_min

Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum initial velocity.


  • float lifetime_randomness

Default

0.0

Setter

set_lifetime_randomness(value)

Getter

get_lifetime_randomness()

Particle lifetime randomness ratio. The lifetime will be multiplied by a value interpolated between 1.0 and a random number less than one. For example a random ratio of 0.4 would scale the original lifetime between 0.4-1.0 of its original value.


Setter

set_param_texture(value)

Getter

get_param_texture()

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


Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum linear acceleration.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum linear acceleration.


Setter

set_param_texture(value)

Getter

get_param_texture()

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


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


Setter

set_param_texture(value)

Getter

get_param_texture()

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


Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum radial acceleration.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum radial acceleration.


Setter

set_param_texture(value)

Getter

get_param_texture()

Each particle's scale will vary along this CurveTexture. If a CurveXYZTexture is supplied instead, the scale will be separated per-axis.


Default

1.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum scale.


Default

1.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum scale.


Default

45.0

Setter

set_spread(value)

Getter

get_spread()

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


  • int sub_emitter_amount_at_end

Setter

set_sub_emitter_amount_at_end(value)

Getter

get_sub_emitter_amount_at_end()


  • float sub_emitter_frequency

Setter

set_sub_emitter_frequency(value)

Getter

get_sub_emitter_frequency()


  • bool sub_emitter_keep_velocity

Default

false

Setter

set_sub_emitter_keep_velocity(value)

Getter

get_sub_emitter_keep_velocity()


Default

0

Setter

set_sub_emitter_mode(value)

Getter

get_sub_emitter_mode()


Setter

set_param_texture(value)

Getter

get_param_texture()

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


  • float tangential_accel_max

Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum tangential acceleration.


  • float tangential_accel_min

Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum tangential acceleration.

Method Descriptions

Returns the maximum value range for the given parameter.


Returns the minimum value range for the given parameter.


Returns the Texture2D used by the specified parameter.


Returns true if the specified particle flag is enabled. See ParticleFlags for options.


Sets the maximum value range for the given parameter.


Sets the minimum value range for the given parameter.


Sets the Texture2D for the specified Parameter.


If true, enables the specified particle flag. See ParticleFlags for options.