ParticlesMaterial

Inherits: Material < Resource < Reference < Object

Particle properties for Particles and Particles2D nodes.

Description

ParticlesMaterial defines particle properties and behavior. It is used in the process_material of Particles and Particles2D 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.

When a randomness ratio is applied to a property it is used to scale that property by a random amount. The random ratio is used to interpolate between 1.0 and a random number less than one, the result is multiplied by the property to obtain the randomized property. For example a random ratio of 0.4 would scale the original property between 0.4-1.0 of its original value.

Properties

float	angle	0.0
Texture	angle_curve
float	angle_random	0.0
float	angular_velocity	0.0
Texture	angular_velocity_curve
float	angular_velocity_random	0.0
float	anim_offset	0.0
Texture	anim_offset_curve
float	anim_offset_random	0.0
float	anim_speed	0.0
Texture	anim_speed_curve
float	anim_speed_random	0.0
Color	color	Color( 1, 1, 1, 1 )
Texture	color_ramp
float	damping	0.0
Texture	damping_curve
float	damping_random	0.0
Vector3	direction	Vector3( 1, 0, 0 )
Vector3	emission_box_extents
Texture	emission_color_texture
Texture	emission_normal_texture
int	emission_point_count
Texture	emission_point_texture
EmissionShape	emission_shape	0
float	emission_sphere_radius
bool	flag_align_y	false
bool	flag_disable_z	false
bool	flag_rotate_y	false
float	flatness	0.0
Vector3	gravity	Vector3( 0, -9.8, 0 )
float	hue_variation	0.0
Texture	hue_variation_curve
float	hue_variation_random	0.0
float	initial_velocity	0.0
float	initial_velocity_random	0.0
float	lifetime_randomness	0.0
float	linear_accel	0.0
Texture	linear_accel_curve
float	linear_accel_random	0.0
float	orbit_velocity
Texture	orbit_velocity_curve
float	orbit_velocity_random
float	radial_accel	0.0
Texture	radial_accel_curve
float	radial_accel_random	0.0
float	scale	1.0
Texture	scale_curve
float	scale_random	0.0
float	spread	45.0
float	tangential_accel	0.0
Texture	tangential_accel_curve
float	tangential_accel_random	0.0
GradientTexture	trail_color_modifier
int	trail_divisor	1
CurveTexture	trail_size_modifier

Methods

bool	get_flag ( Flags flag ) const
float	get_param ( Parameter param ) const
float	get_param_randomness ( Parameter param ) const
Texture	get_param_texture ( Parameter param ) const
void	set_flag ( Flags flag, bool enable )
void	set_param ( Parameter param, float value )
void	set_param_randomness ( Parameter param, float randomness )
void	set_param_texture ( Parameter param, Texture texture )

Enumerations

enum Parameter:

• PARAM_INITIAL_LINEAR_VELOCITY = 0 --- Use with set_param, set_param_randomness, and set_param_texture to set initial velocity properties.
• PARAM_ANGULAR_VELOCITY = 1 --- Use with set_param, set_param_randomness, and set_param_texture to set angular velocity properties.
• PARAM_ORBIT_VELOCITY = 2 --- Use with set_param, set_param_randomness, and set_param_texture to set orbital velocity properties.
• PARAM_LINEAR_ACCEL = 3 --- Use with set_param, set_param_randomness, and set_param_texture to set linear acceleration properties.
• PARAM_RADIAL_ACCEL = 4 --- Use with set_param, set_param_randomness, and set_param_texture to set radial acceleration properties.
• PARAM_TANGENTIAL_ACCEL = 5 --- Use with set_param, set_param_randomness, and set_param_texture to set tangential acceleration properties.
• PARAM_DAMPING = 6 --- Use with set_param, set_param_randomness, and set_param_texture to set damping properties.
• PARAM_ANGLE = 7 --- Use with set_param, set_param_randomness, and set_param_texture to set angle properties.
• PARAM_SCALE = 8 --- Use with set_param, set_param_randomness, and set_param_texture to set scale properties.
• PARAM_HUE_VARIATION = 9 --- Use with set_param, set_param_randomness, and set_param_texture to set hue variation properties.
• PARAM_ANIM_SPEED = 10 --- Use with set_param, set_param_randomness, and set_param_texture to set animation speed properties.
• PARAM_ANIM_OFFSET = 11 --- Use with set_param, set_param_randomness, and set_param_texture to set animation offset properties.
• PARAM_MAX = 12 --- Represents the size of the Parameter enum.

enum Flags:

• FLAG_ALIGN_Y_TO_VELOCITY = 0 --- Use with set_flag to set flag_align_y.
• FLAG_ROTATE_Y = 1 --- Use with set_flag to set flag_rotate_y.
• FLAG_DISABLE_Z = 2 --- Use with set_flag to set flag_disable_z.
• FLAG_MAX = 3 --- Represents the size of the Flags enum.

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_BOX = 2 --- Particles will be emitted in the volume of a box.
• EMISSION_SHAPE_POINTS = 3 --- 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 = 4 --- 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_MAX = 5 --- Represents the size of the EmissionShape enum.

Property Descriptions

float angle

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial rotation applied to each particle, in degrees.

Only applied when flag_disable_z or flag_rotate_y are true or the SpatialMaterial being used to draw the particle is using SpatialMaterial.BILLBOARD_PARTICLES.

Texture angle_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float angle_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Rotation randomness ratio.

float angular_velocity

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial angular velocity applied to each particle. Sets the speed of rotation of the particle.

Only applied when flag_disable_z or flag_rotate_y are true or the SpatialMaterial being used to draw the particle is using SpatialMaterial.BILLBOARD_PARTICLES.

Texture angular_velocity_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float angular_velocity_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Angular velocity randomness ratio.

float anim_offset

Default	0.0
Setter	set_param(value)
Getter	get_param()

Particle animation offset.

Texture anim_offset_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float anim_offset_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Animation offset randomness ratio.

float anim_speed

Default	0.0
Setter	set_param(value)
Getter	get_param()

Particle animation speed.

Texture anim_speed_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float anim_speed_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Animation speed randomness ratio.

Color color

Default	Color( 1, 1, 1, 1 )
Setter	set_color(value)
Getter	get_color()

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

Texture color_ramp

Setter	set_color_ramp(value)
Getter	get_color_ramp()

Each particle's color will vary along this GradientTexture.

float damping

Default	0.0
Setter	set_param(value)
Getter	get_param()

The rate at which particles lose velocity.

Texture damping_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

Damping will vary along this CurveTexture.

float damping_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Damping randomness ratio.

Vector3 direction

Default	Vector3( 1, 0, 0 )
Setter	set_direction(value)
Getter	get_direction()

Unit vector specifying the particles' emission direction.

Vector3 emission_box_extents

Setter	set_emission_box_extents(value)
Getter	get_emission_box_extents()

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

Texture emission_color_texture

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.

Texture emission_normal_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.

Texture emission_point_texture

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.

EmissionShape emission_shape

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.

bool flag_align_y

Default	false
Setter	set_flag(value)
Getter	get_flag()

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

bool flag_disable_z

Default	false
Setter	set_flag(value)
Getter	get_flag()

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

bool flag_rotate_y

Default	false
Setter	set_flag(value)
Getter	get_flag()

If true, particles rotate around Y axis by angle.

float flatness

Default	0.0
Setter	set_flatness(value)
Getter	get_flatness()

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

Vector3 gravity

Default	Vector3( 0, -9.8, 0 )
Setter	set_gravity(value)
Getter	get_gravity()

Gravity applied to every particle.

float hue_variation

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial hue variation applied to each particle.

Texture hue_variation_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

Each particle's hue will vary along this CurveTexture.

float hue_variation_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Hue variation randomness ratio.

float initial_velocity

Default	0.0
Setter	set_param(value)
Getter	get_param()

Initial velocity magnitude for each particle. Direction comes from spread and the node's orientation.

float initial_velocity_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Initial velocity randomness ratio.

float lifetime_randomness

Default	0.0
Setter	set_lifetime_randomness(value)
Getter	get_lifetime_randomness()

Particle lifetime randomness ratio.

float linear_accel

Default	0.0
Setter	set_param(value)
Getter	get_param()

Linear acceleration applied to each particle in the direction of motion.

Texture linear_accel_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float linear_accel_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Linear acceleration randomness ratio.

float orbit_velocity

Setter	set_param(value)
Getter	get_param()

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 flag_disable_z is true.

Texture orbit_velocity_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float orbit_velocity_random

Setter	set_param_randomness(value)
Getter	get_param_randomness()

Orbital velocity randomness ratio.

float radial_accel

Default	0.0
Setter	set_param(value)
Getter	get_param()

Radial acceleration applied to each particle. Makes particle accelerate away from origin.

Texture radial_accel_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float radial_accel_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Radial acceleration randomness ratio.

float scale

Default	1.0
Setter	set_param(value)
Getter	get_param()

Initial scale applied to each particle.

Texture scale_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

Each particle's scale will vary along this CurveTexture.

float scale_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Scale randomness ratio.

float spread

Default	45.0
Setter	set_spread(value)
Getter	get_spread()

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

float tangential_accel

Default	0.0
Setter	set_param(value)
Getter	get_param()

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

Texture tangential_accel_curve

Setter	set_param_texture(value)
Getter	get_param_texture()

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

float tangential_accel_random

Default	0.0
Setter	set_param_randomness(value)
Getter	get_param_randomness()

Tangential acceleration randomness ratio.

GradientTexture trail_color_modifier

Setter	set_trail_color_modifier(value)
Getter	get_trail_color_modifier()

Trail particles' color will vary along this GradientTexture.

int trail_divisor

Default	1
Setter	set_trail_divisor(value)
Getter	get_trail_divisor()

Emitter will emit amount divided by trail_divisor particles. The remaining particles will be used as trail(s).

CurveTexture trail_size_modifier

Setter	set_trail_size_modifier(value)
Getter	get_trail_size_modifier()

Trail particles' size will vary along this CurveTexture.

Method Descriptions

bool get_flag ( Flags flag ) const

Returns true if the specified flag is enabled.

float get_param ( Parameter param ) const

Returns the value of the specified parameter.

float get_param_randomness ( Parameter param ) const

Returns the randomness ratio associated with the specified parameter.

Texture get_param_texture ( Parameter param ) const

Returns the Texture used by the specified parameter.

void set_flag ( Flags flag, bool enable )

If true, enables the specified flag. See Flags for options.

void set_param ( Parameter param, float value )

Sets the specified Parameter.

void set_param_randomness ( Parameter param, float randomness )

Sets the randomness ratio for the specified Parameter.

void set_param_texture ( Parameter param, Texture texture )

Sets the Texture for the specified Parameter.