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_initial_ramp

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

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

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:

Parameter PARAM_INITIAL_LINEAR_VELOCITY = 0

Use with set_param, set_param_randomness, and set_param_texture to set initial velocity properties.

Parameter PARAM_ANGULAR_VELOCITY = 1

Use with set_param, set_param_randomness, and set_param_texture to set angular velocity properties.

Parameter PARAM_ORBIT_VELOCITY = 2

Use with set_param, set_param_randomness, and set_param_texture to set orbital velocity properties.

Parameter PARAM_LINEAR_ACCEL = 3

Use with set_param, set_param_randomness, and set_param_texture to set linear acceleration properties.

Parameter PARAM_RADIAL_ACCEL = 4

Use with set_param, set_param_randomness, and set_param_texture to set radial acceleration properties.

Parameter PARAM_TANGENTIAL_ACCEL = 5

Use with set_param, set_param_randomness, and set_param_texture to set tangential acceleration properties.

Parameter PARAM_DAMPING = 6

Use with set_param, set_param_randomness, and set_param_texture to set damping properties.

Parameter PARAM_ANGLE = 7

Use with set_param, set_param_randomness, and set_param_texture to set angle properties.

Parameter PARAM_SCALE = 8

Use with set_param, set_param_randomness, and set_param_texture to set scale properties.

Parameter PARAM_HUE_VARIATION = 9

Use with set_param, set_param_randomness, and set_param_texture to set hue variation properties.

Parameter PARAM_ANIM_SPEED = 10

Use with set_param, set_param_randomness, and set_param_texture to set animation speed properties.

Parameter PARAM_ANIM_OFFSET = 11

Use with set_param, set_param_randomness, and set_param_texture to set animation offset properties.

Parameter PARAM_MAX = 12

Represents the size of the Parameter enum.


enum Flags:

Flags FLAG_ALIGN_Y_TO_VELOCITY = 0

Use with set_flag to set flag_align_y.

Flags FLAG_ROTATE_Y = 1

Use with set_flag to set flag_rotate_y.

Flags FLAG_DISABLE_Z = 2

Use with set_flag to set flag_disable_z.

Flags FLAG_MAX = 3

Represents the size of the Flags 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_BOX = 2

Particles will be emitted in the volume of a box.

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

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

EmissionShape EMISSION_SHAPE_RING = 5

Particles will be emitted in a ring or cylinder.

EmissionShape EMISSION_SHAPE_MAX = 6

Represents the size of the EmissionShape enum.


Property Descriptions

float angle = 0.0

Initial rotation applied to each particle, in degrees.

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


Texture angle_curve

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


float angle_random = 0.0

Rotation randomness ratio.


float angular_velocity = 0.0

Initial angular velocity applied to each particle in degrees per second. Sets the speed of rotation of the particle.

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


Texture angular_velocity_curve

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


float angular_velocity_random = 0.0

Angular velocity randomness ratio.


float anim_offset = 0.0

Particle animation offset.


Texture anim_offset_curve

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


float anim_offset_random = 0.0

Animation offset randomness ratio.


float anim_speed = 0.0

Particle animation speed.


Texture anim_speed_curve

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


float anim_speed_random = 0.0

Animation speed randomness ratio.


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

  • void set_color ( Color value )

  • Color get_color ( )

Each particle's initial color. If the Particles2D's or Particles'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 Material3D, Material3D.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.


Texture color_initial_ramp

  • void set_color_initial_ramp ( Texture value )

  • Texture get_color_initial_ramp ( )

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

Note: color_initial_ramp multiplies the particle mesh's vertex colors. To have a visible effect on a Material3D, Material3D.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.


Texture color_ramp

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

Note: color_ramp multiplies the particle mesh's vertex colors. To have a visible effect on a Material3D, Material3D.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.


float damping = 0.0

The rate at which particles lose velocity.


Texture damping_curve

Damping will vary along this CurveTexture.


float damping_random = 0.0

Damping randomness ratio.


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.


Texture emission_color_texture

  • void set_emission_color_texture ( Texture value )

  • Texture 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 Material3D, Material3D.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.


Texture emission_normal_texture

  • void set_emission_normal_texture ( Texture value )

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


Texture emission_point_texture

  • void set_emission_point_texture ( Texture value )

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


bool flag_align_y = false

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


bool flag_disable_z = false

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


bool flag_rotate_y = false

If true, particles rotate around Y axis by angle.


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.


float hue_variation = 0.0

Initial hue variation applied to each particle.


Texture hue_variation_curve

Each particle's hue will vary along this CurveTexture.


float hue_variation_random = 0.0

Hue variation randomness ratio.


float initial_velocity = 0.0

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


float initial_velocity_random = 0.0

Initial velocity randomness ratio.


float lifetime_randomness = 0.0

  • void set_lifetime_randomness ( float value )

  • float get_lifetime_randomness ( )

Particle lifetime randomness ratio.


float linear_accel = 0.0

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


Texture linear_accel_curve

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


float linear_accel_random = 0.0

Linear acceleration randomness ratio.


float orbit_velocity

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

Note: Only available when flag_disable_z is true.


Texture orbit_velocity_curve

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


float orbit_velocity_random

Orbital velocity randomness ratio.


float radial_accel = 0.0

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


Texture radial_accel_curve

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


float radial_accel_random = 0.0

Radial acceleration randomness ratio.


float scale = 1.0

Initial scale applied to each particle. This can be set to a negative value to flip the particle on all axes.


Texture scale_curve

Each particle's scale will vary along this CurveTexture.


float scale_random = 0.0

Scale randomness ratio.


float spread = 45.0

  • void set_spread ( float value )

  • float get_spread ( )

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


float tangential_accel = 0.0

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

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


float tangential_accel_random = 0.0

Tangential acceleration randomness ratio.


GradientTexture trail_color_modifier

Trail particles' color will vary along this GradientTexture.


int trail_divisor = 1

  • void set_trail_divisor ( int value )

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

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.