ParticleProcessMaterial

Inherits: Material < Resource < RefCounted < Object

Particle properties for GPUParticles3D and GPUParticles2D nodes.

Description

ParticleProcessMaterial 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

float

collision_friction

CollisionMode

collision_mode

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_collision

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

bool

turbulence_enabled

false

float

turbulence_influence_max

0.1

float

turbulence_influence_min

0.1

Texture2D

turbulence_influence_over_life

float

turbulence_initial_displacement_max

0.0

float

turbulence_initial_displacement_min

0.0

float

turbulence_noise_scale

9.0

Vector3

turbulence_noise_speed

Vector3(0.5, 0.5, 0.5)

float

turbulence_noise_speed_random

0.0

float

turbulence_noise_strength

1.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 --- Represents the size of the SubEmitterMode enum.


enum CollisionMode:

  • COLLISION_DISABLED = 0 --- No collision for particles. Particles will go through GPUParticlesCollision3D nodes.

  • COLLISION_RIGID = 1 --- RigidBody3D-style collision for particles using GPUParticlesCollision3D nodes.

  • COLLISION_HIDE_ON_CONTACT = 2 --- Hide particles instantly when colliding with a GPUParticlesCollision3D node. This can be combined with a subemitter that uses the COLLISION_RIGID collision mode to "replace" the parent particle with the subemitter on impact.

  • COLLISION_MAX = 3 --- Represents the size of the CollisionMode enum.

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 initial rotation applied to each particle, in degrees.

Only applied when particle_flag_disable_z or particle_flag_rotate_y are true or the BaseMaterial3D being used to draw the particle is using BaseMaterial3D.BILLBOARD_PARTICLES.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum equivalent of angle_max.


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.

Only applied when particle_flag_disable_z or particle_flag_rotate_y are true or the BaseMaterial3D being used to draw the particle is using BaseMaterial3D.BILLBOARD_PARTICLES.


  • float angular_velocity_min

Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum equivalent of angular_velocity_max.


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 that corresponds to frame index in the texture. 0 is the first frame, 1 is the last one. See CanvasItemMaterial.particles_animation.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum equivalent of anim_offset_max.


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 equivalent of anim_speed_max.


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


Setter

set_collision_bounce(value)

Getter

get_collision_bounce()

The particles' bounciness. Values range from 0 (no bounce) to 1 (full bounciness). Only effective if collision_mode is COLLISION_RIGID.


  • float collision_friction

Setter

set_collision_friction(value)

Getter

get_collision_friction()

The particles' friction. Values range from 0 (frictionless) to 1 (maximum friction). Only effective if collision_mode is COLLISION_RIGID.


Default

0

Setter

set_collision_mode(value)

Getter

get_collision_mode()

The particles' collision mode.

Note: Particles can only collide with GPUParticlesCollision3D nodes, not PhysicsBody3D nodes. To make particles collide with various objects, you can add GPUParticlesCollision3D nodes as children of PhysicsBody3D nodes.


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

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.


Setter

set_color_initial_ramp(value)

Getter

get_color_initial_ramp()

Each particle's initial color will vary along this GradientTexture1D (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.


Setter

set_color_ramp(value)

Getter

get_color_ramp()

Each particle's color will vary along this GradientTexture1D 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.


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()

The maximum rate at which particles lose velocity. For example value of 100 means that the particle will go from 100 velocity to 0 in 1 second.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum equivalent of damping_max.


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.

Note: emission_color_texture 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_color_texture will have no visible effect.


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 initial hue variation applied to each particle. It will shift the particle color's hue.


  • float hue_variation_min

Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum equivalent of hue_variation_max.


  • float initial_velocity_max

Default

0.0

Setter

set_param_max(value)

Getter

get_param_max()

Maximum initial velocity magnitude for each particle. Direction comes from direction and spread.


  • float initial_velocity_min

Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum equivalent of initial_velocity_max.


  • 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 applied to each particle in the direction of motion.


Default

0.0

Setter

set_param_min(value)

Getter

get_param_min()

Minimum equivalent of linear_accel_max.


Setter

set_param_texture(value)

Getter

get_param_texture()

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