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
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|
Methods
get_param_max ( Parameter param ) const | |
get_param_min ( Parameter param ) const | |
get_param_texture ( Parameter param ) const | |
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
True if the interaction with particle attractors is enabled.
float 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
The particles’ friction. Values range from 0
(frictionless) to 1
(maximum friction). Only effective if collision_mode is COLLISION_RIGID.
CollisionMode collision_mode = 0
void set_collision_mode ( CollisionMode value )
CollisionMode get_collision_mode ( )
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
Should collision take scale into account.
Color color = Color(1, 1, 1, 1)
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
The box’s extents if emission_shape
is set to EMISSION_SHAPE_BOX.
Texture2D 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
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
The number of emission points if emission_shape
is set to EMISSION_SHAPE_POINTS or EMISSION_SHAPE_DIRECTED_POINTS.
Texture2D 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
The axis of the ring when using the emitter EMISSION_SHAPE_RING.
float emission_ring_height
The height of the ring when using the emitter EMISSION_SHAPE_RING.
float emission_ring_inner_radius
The inner radius of the ring when using the emitter EMISSION_SHAPE_RING.
float emission_ring_radius
The radius of the ring when using the emitter EMISSION_SHAPE_RING.
EmissionShape emission_shape = 0
void set_emission_shape ( EmissionShape value )
EmissionShape get_emission_shape ( )
Particles will be emitted inside this region. Use EmissionShape constants for values.
float emission_sphere_radius
The sphere’s radius if emission_shape
is set to EMISSION_SHAPE_SPHERE.
float flatness = 0.0
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
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
void set_particle_flag ( ParticleFlags particle_flag, bool enable )
bool get_particle_flag ( ParticleFlags particle_flag ) const
Align Y axis of particle with the direction of its velocity.
bool particle_flag_disable_z = false
void set_particle_flag ( ParticleFlags particle_flag, bool enable )
bool get_particle_flag ( ParticleFlags particle_flag ) const
If true
, particles will not move on the z axis.
bool particle_flag_rotate_y = false
void set_particle_flag ( ParticleFlags particle_flag, bool enable )
bool get_particle_flag ( ParticleFlags particle_flag ) const
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
Each particle’s initial direction range from +spread
to -spread
degrees.
int sub_emitter_amount_at_collision
Sub particle amount on collision.
Maximum amount set in the sub particles emitter.
int sub_emitter_amount_at_end
There is currently no description for this property. Please help us by contributing one!
float sub_emitter_frequency
There is currently no description for this property. Please help us by contributing one!
bool sub_emitter_keep_velocity = false
There is currently no description for this property. Please help us by contributing one!
SubEmitterMode sub_emitter_mode = 0
void set_sub_emitter_mode ( SubEmitterMode value )
SubEmitterMode get_sub_emitter_mode ( )
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
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
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)
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
Use to influence the noise speed in a random pattern. This helps break up visible movement patterns.
float turbulence_noise_strength = 1.0
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.