Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

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:

Parameter PARAM_INITIAL_LINEAR_VELOCITY = 0

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

Parameter PARAM_ANGULAR_VELOCITY = 1

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

Parameter PARAM_ORBIT_VELOCITY = 2

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

Parameter PARAM_LINEAR_ACCEL = 3

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

Parameter PARAM_RADIAL_ACCEL = 4

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

Parameter PARAM_TANGENTIAL_ACCEL = 5

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

Parameter PARAM_DAMPING = 6

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

Parameter PARAM_ANGLE = 7

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

Parameter PARAM_SCALE = 8

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

Parameter PARAM_HUE_VARIATION = 9

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

Parameter PARAM_ANIM_SPEED = 10

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

Parameter PARAM_ANIM_OFFSET = 11

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

Parameter PARAM_MAX = 15

Represents the size of the Parameter enum.

Parameter PARAM_TURB_VEL_INFLUENCE = 13

Use with set_param_min and set_param_max to set the turbulence minimum und maximum influence on each particles velocity.

Parameter PARAM_TURB_INIT_DISPLACEMENT = 14

Use with set_param_min and set_param_max to set the turbulence minimum and maximum displacement of the particles spawn position.

Parameter PARAM_TURB_INFLUENCE_OVER_LIFE = 12

Use with set_param_texture to set the turbulence influence over the particles life time.

enum ParticleFlags:

ParticleFlags PARTICLE_FLAG_ALIGN_Y_TO_VELOCITY = 0

Use with set_particle_flag to set particle_flag_align_y.

ParticleFlags PARTICLE_FLAG_ROTATE_Y = 1

Use with set_particle_flag to set particle_flag_rotate_y.

ParticleFlags PARTICLE_FLAG_DISABLE_Z = 2

Use with set_particle_flag to set particle_flag_disable_z.

ParticleFlags PARTICLE_FLAG_MAX = 3

Represents the size of the ParticleFlags enum.

enum EmissionShape:

EmissionShape EMISSION_SHAPE_POINT = 0

All particles will be emitted from a single point.

EmissionShape EMISSION_SHAPE_SPHERE = 1

Particles will be emitted in the volume of a sphere.

EmissionShape EMISSION_SHAPE_SPHERE_SURFACE = 2

Particles will be emitted on the surface of a sphere.

EmissionShape EMISSION_SHAPE_BOX = 3

Particles will be emitted in the volume of a box.

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

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

EmissionShape EMISSION_SHAPE_RING = 6

Particles will be emitted in a ring or cylinder.

EmissionShape EMISSION_SHAPE_MAX = 7

Represents the size of the EmissionShape enum.

enum SubEmitterMode:

SubEmitterMode SUB_EMITTER_DISABLED = 0

SubEmitterMode SUB_EMITTER_CONSTANT = 1

SubEmitterMode SUB_EMITTER_AT_END = 2

SubEmitterMode SUB_EMITTER_AT_COLLISION = 3

SubEmitterMode SUB_EMITTER_MAX = 4

Represents the size of the SubEmitterMode enum.

enum CollisionMode:

CollisionMode COLLISION_DISABLED = 0

No collision for particles. Particles will go through GPUParticlesCollision3D nodes.

CollisionMode COLLISION_RIGID = 1

RigidBody3D-style collision for particles using GPUParticlesCollision3D nodes.

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

CollisionMode COLLISION_MAX = 3

Represents the size of the CollisionMode enum.

Property Descriptions

Texture2D angle_curve

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

float angle_max = 0.0

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.

float angle_min = 0.0

Minimum equivalent of angle_max.

Texture2D angular_velocity_curve

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

float angular_velocity_max = 0.0

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 = 0.0

Minimum equivalent of angular_velocity_max.

Texture2D anim_offset_curve

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

float anim_offset_max = 0.0

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.

float anim_offset_min = 0.0

Minimum equivalent of anim_offset_max.

Texture2D anim_speed_curve

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

float anim_speed_max = 0.0

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.

float anim_speed_min = 0.0

Minimum equivalent of anim_speed_max.

bool attractor_interaction_enabled = true

  • void set_attractor_interaction_enabled ( bool value )

  • bool is_attractor_interaction_enabled ( )

True if the interaction with particle attractors is enabled.

float collision_bounce

  • void set_collision_bounce ( float value )

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

  • void set_collision_friction ( float value )

  • float get_collision_friction ( )

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

CollisionMode collision_mode = 0

The particles' collision mode.

Note: 3D 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.

Note: 2D Particles can only collide with LightOccluder2D nodes, not PhysicsBody2D nodes.

bool collision_use_scale = false

  • void set_collision_use_scale ( bool value )

  • bool is_collision_using_scale ( )

Should collision take scale into account.

Color color = Color(1, 1, 1, 1)

  • void set_color ( Color value )

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

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

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

Texture2D damping_curve

Damping will vary along this CurveTexture.

float damping_max = 0.0

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.

float damping_min = 0.0

Minimum equivalent of damping_max.

Vector3 direction = Vector3(1, 0, 0)

Unit vector specifying the particles' emission direction.

Vector3 emission_box_extents

  • void set_emission_box_extents ( Vector3 value )

  • Vector3 get_emission_box_extents ( )

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

Texture2D emission_color_texture

  • void set_emission_color_texture ( Texture2D value )

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

Texture2D emission_normal_texture

  • void set_emission_normal_texture ( Texture2D value )

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

  • void set_emission_point_count ( int value )

  • int get_emission_point_count ( )

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

Texture2D emission_point_texture

  • void set_emission_point_texture ( Texture2D value )

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

Vector3 emission_ring_axis

  • void set_emission_ring_axis ( Vector3 value )

  • Vector3 get_emission_ring_axis ( )

The axis of the ring when using the emitter EMISSION_SHAPE_RING.

float emission_ring_height

  • void set_emission_ring_height ( float value )

  • float get_emission_ring_height ( )

The height of the ring when using the emitter EMISSION_SHAPE_RING.

float emission_ring_inner_radius

  • void set_emission_ring_inner_radius ( float value )

  • float get_emission_ring_inner_radius ( )

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

float emission_ring_radius

  • void set_emission_ring_radius ( float value )

  • float get_emission_ring_radius ( )

The radius of the ring when using the emitter EMISSION_SHAPE_RING.

EmissionShape emission_shape = 0

Particles will be emitted inside this region. Use EmissionShape constants for values.

float emission_sphere_radius

  • void set_emission_sphere_radius ( float value )

  • float get_emission_sphere_radius ( )

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

float flatness = 0.0

  • void set_flatness ( float value )

  • float get_flatness ( )

Amount of spread along the Y axis.

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

Gravity applied to every particle.

Texture2D hue_variation_curve

Each particle's hue will vary along this CurveTexture.

float hue_variation_max = 0.0

Maximum initial hue variation applied to each particle. It will shift the particle color's hue.

float hue_variation_min = 0.0

Minimum equivalent of hue_variation_max.

float initial_velocity_max = 0.0

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

float initial_velocity_min = 0.0

Minimum equivalent of initial_velocity_max.

float lifetime_randomness = 0.0

  • void set_lifetime_randomness ( float value )

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

Texture2D linear_accel_curve

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

float linear_accel_max = 0.0

Maximum linear acceleration applied to each particle in the direction of motion.

float linear_accel_min = 0.0

Minimum equivalent of linear_accel_max.

Texture2D orbit_velocity_curve

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

float orbit_velocity_max

Maximum orbital velocity applied to each particle. Makes the particles circle around origin. Specified in number of full rotations around origin per second.

Only available when particle_flag_disable_z is true.

float orbit_velocity_min

Minimum equivalent of orbit_velocity_max.

bool particle_flag_align_y = false

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

bool particle_flag_disable_z = false

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

bool particle_flag_rotate_y = false

If true, particles rotate around Y axis by angle_min.

Texture2D radial_accel_curve

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

float radial_accel_max = 0.0

Maximum radial acceleration applied to each particle. Makes particle accelerate away from the origin or towards it if negative.

float radial_accel_min = 0.0

Minimum equivalent of radial_accel_max.

Texture2D scale_curve

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

float scale_max = 1.0

Maximum initial scale applied to each particle.

float scale_min = 1.0

Minimum equivalent of scale_max.

float spread = 45.0

  • void set_spread ( float value )

  • float get_spread ( )

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

int sub_emitter_amount_at_collision

  • void set_sub_emitter_amount_at_collision ( int value )

  • int get_sub_emitter_amount_at_collision ( )

Sub particle amount on collision.

Maximum amount set in the sub particles emitter.

int sub_emitter_amount_at_end

  • void set_sub_emitter_amount_at_end ( int value )

  • int get_sub_emitter_amount_at_end ( )

There is currently no description for this property. Please help us by contributing one!

float sub_emitter_frequency

  • void set_sub_emitter_frequency ( float value )

  • float get_sub_emitter_frequency ( )

There is currently no description for this property. Please help us by contributing one!

bool sub_emitter_keep_velocity = false

  • void set_sub_emitter_keep_velocity ( bool value )

  • bool get_sub_emitter_keep_velocity ( )

There is currently no description for this property. Please help us by contributing one!

SubEmitterMode sub_emitter_mode = 0

There is currently no description for this property. Please help us by contributing one!

Texture2D tangential_accel_curve

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

float tangential_accel_max = 0.0

Maximum tangential acceleration applied to each particle. Tangential acceleration is perpendicular to the particle's velocity giving the particles a swirling motion.

float tangential_accel_min = 0.0

Minimum equivalent of tangential_accel_max.

bool turbulence_enabled = false

  • void set_turbulence_enabled ( bool value )

  • bool get_turbulence_enabled ( )

If true, enables turbulence for the particle system. Turbulence can be used to vary particle movement according to its position (based on a 3D noise pattern).

Note: Enabling turbulence has a high performance cost on the GPU. Only enable turbulence on a few particle systems at once at most, and consider disabling it when targeting mobile/web platforms.

float turbulence_influence_max = 0.1

Maximum turbulence influence on each particle.

The actual amount of turbulence influence on each particle is calculated as a random value between turbulence_influence_min and turbulence_influence_max and multiplied by the amount of turbulence influence from turbulence_influence_over_life.

float turbulence_influence_min = 0.1

Minimum turbulence influence on each particle.

The actual amount of turbulence influence on each particle is calculated as a random value between turbulence_influence_min and turbulence_influence_max and multiplied by the amount of turbulence influence from turbulence_influence_over_life.

Texture2D turbulence_influence_over_life

Each particle's amount of turbulence will be influenced along this CurveTexture over its life time.

float turbulence_initial_displacement_max = 0.0

Maximum displacement of each particle's spawn position by the turbulence.

The actual amount of displacement will be a factor of the underlying turbulence multiplied by a random value between turbulence_initial_displacement_min and turbulence_initial_displacement_max.

float turbulence_initial_displacement_min = 0.0

Minimum displacement of each particle's spawn position by the turbulence.

The actual amount of displacement will be a factor of the underlying turbulence multiplied by a random value between turbulence_initial_displacement_min and turbulence_initial_displacement_max.

float turbulence_noise_scale = 9.0

  • void set_turbulence_noise_scale ( float value )

  • float get_turbulence_noise_scale ( )

This value controls the overall scale/frequency of the turbulence noise pattern.

A small scale will result in smaller features with more detail while a high scale will result in smoother noise with larger features.

Vector3 turbulence_noise_speed = Vector3(0.5, 0.5, 0.5)

  • void set_turbulence_noise_speed ( Vector3 value )

  • Vector3 get_turbulence_noise_speed ( )

The movement speed of the turbulence pattern. This changes how quickly the noise changes over time.

A value of Vector3(0.0, 0.0, 0.0) will freeze the turbulence pattern in place.

float turbulence_noise_speed_random = 0.0

  • void set_turbulence_noise_speed_random ( float value )

  • float get_turbulence_noise_speed_random ( )

Use to influence the noise speed in a random pattern. This helps break up visible movement patterns.

float turbulence_noise_strength = 1.0

  • void set_turbulence_noise_strength ( float value )

  • float get_turbulence_noise_strength ( )

The turbulence noise strength. Increasing this will result in a stronger, more contrasting noise pattern.

Method Descriptions

float get_param_max ( Parameter param ) const

Returns the maximum value range for the given parameter.

float get_param_min ( Parameter param ) const

Returns the minimum value range for the given parameter.

Texture2D get_param_texture ( Parameter param ) const

Returns the Texture2D used by the specified parameter.

bool get_particle_flag ( ParticleFlags particle_flag ) const

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

void set_param_max ( Parameter param, float value )

Sets the maximum value range for the given parameter.

void set_param_min ( Parameter param, float value )

Sets the minimum value range for the given parameter.

void set_param_texture ( Parameter param, Texture2D texture )

Sets the Texture2D for the specified Parameter.

void set_particle_flag ( ParticleFlags particle_flag, bool enable )

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