API

Changing Particle Properties Over Time

Some properties of a particle, size or color for example, can be changed over their lifetime. Others, such as emit rate, start size or lifetime, can be changed over the duration of the particle system.

Changing relevant properties over the duration of the particle system is available from Babylon.js V3.3 onwards, provided, of course, you set the targetStopDuration, When the duration is set you can alter appropriate properties from the start, 0, to the end, 1, by adding a gradient method related to the property.

Whether it is over a particle lifetime or the system duration the general form to change a specific property value is

particleSystem.add < PROPERTY > Gradient(fraction_of_time_period_elapsed, property_value); //set a value at given time point

and for a range of property values

particleSystem.add < PROPERTY > Gradient(fraction_of_time_period_elapsed, minimum_property_value, maximum_property_value); //set a range of values at given time point

In both cases we recommend that you add gradients for the start, 0, and end, 1, even when setting other time points between 0 and 1.

To remove a gradient you use

particleSystem.remove < PROPERTY > Gradient(fraction_of_time_period_elapsed);

There are two time periods used - one for a particle lifetime and the other for the system duration. Both are running from 0 (start) to 1 (stop).

Change Size Over Lifetime

To change size over the lifetime of the particle use

particleSystem.addSizeGradient(0, 0.5); //size at start of particle lifetime
particleSystem.addSizeGradient(1, 3); //size at end of particle lifetime

For a range of values use

particleSystem.addSizeGradient(0, 0.5, 0.8); //size range at start of particle lifetime
particleSystem.addSizeGradient(0.4, 1, 2); //size range at 2/5 of duration of particle system
particleSystem.addSizeGradient(1.0, 3, 4); //size range at end of particle lifetime

To remove a size gradient you use

particleSystem.removeSizeGradient(0.4);

Size increases over lifetime: Particle Size Increases Over Liftime Size increases then decreases over lifetime: Particle Size Increases Then Decreases Over Liftime

Change Color Over Lifetime

To change size over the lifetime of the particle use

particleSystem.addColorGradient(0, new BABYLON.Color4(1, 1, 1, 0)); //color at start of particle lifetime
particleSystem.addColorGradient(1, new BABYLON.Color4(1, 1, 1, 1)); //color at end of particle lifetime

For a range of values use

particleSystem.addColorGradient(0, new BABYLON.Color4(1, 1, 1, 0), new BABYLON.Color4(1, 0, 1, 0)); //color range at start of particle lifetime
particleSystem.addColorGradient(0.4, new BABYLON.Color4(1, 1, 1, 0.5), new BABYLON.Color4(1, 0, 1, 0.5)); //color range at 2/5 of particle lifetime
particleSystem.addColorGradient(1.0, new BABYLON.Color4(1, 1, 1, 1), new BABYLON.Color4(1, 0, 1, 1)); //color range at end of particle lifetime

To remove a color gradient you use

particleSystem.removeColorGradient(0.4);

color change over lifetime: Particle Color Change Over Liftime color change with ranges over lifetime: Particle Color Change With Ranges Over Liftime

Change Speed Over Lifetime

To change the speed (magnitude of velocity) over the lifetime of the particle use

particleSystem.addVelocityGradient(0, 0.5); //applied power at start of particle lifetime
particleSystem.addVelocityGradient(1, 3); //applied power at end of particle lifetime

For a range of values use

particleSystem.addVelocityGradient(0, 0.5, 0.8); //applied power range at start of particle lifetime
particleSystem.addVelocityGradient(0.4, 1, 2); //applied power range at 2/5 of duration of particle system
particleSystem.addVelocityGradient(1.0, 3, 4); //applied power range at end of particle lifetime

To remove a velocity gradient you use

particleSystem.removeVelocityGradient(0.4);

Speed increases over lifetime: Particle Speed Increases Over Liftime Speed increases then decreases over lifetime: Particle Speed Increases Then Decreases Over Liftime

Limit Speed Over Lifetime

You can define by how much to limit the speed of a particle with

particleSystem.limitVelocityDamping = 0.1; //damping factor

A limit will be used to check the current speed of the particle over its lifetime. And if the limit is reached, then the damping factor is applied as speed * damping factor.

To set the speed limit use

particleSystem.addLimitVelocityGradient(0, 10); //speed limit at start of particle lifetime
particleSystem.addLimitVelocityGradient(1, 0.1); //speed limit at end of particle lifetime

For a range of values use

particleSystem.addLimitVelocityGradient(0, 9, 10); //speed limit range at start of particle lifetime
particleSystem.addLimitVelocityGradient(0.4, 2, 3); //speed limit range at 2/5 of duration of particle system
particleSystem.addLimitVelocityGradient(1.0, 0.1, 0.2); //speed limit range at end of particle lifetime

To remove a speed limit gradient you use

particleSystem.removeLimitVelocityGradient(0.4);

Speed limit increases over lifetime: Particle Speed Limit Increases Over Liftime

Change Rotation Speed Over Lifetime

To change the rotation or angular speed over the lifetime of the particle use

particleSystem.addAngularSpeedGradient(0, 0.5); //angular speed at start of particle lifetime
particleSystem.addAngularSpeedGradient(1, 3); //angular speed at end of particle lifetime

For a range of values use

particleSystem.addAngularSpeedGradient(0, 0.5, 0.8); //angular speed range at start of particle lifetime
particleSystem.addAngularSpeedGradient(0.4, 1, 2); //angular speed range at 2/5 of duration of particle system
particleSystem.addAngularSpeedGradient(1.0, 3, 4); //angular speed range at end of particle lifetime

To remove a angular speed gradient you use

particleSystem.removeAngularSpeedGradient(0.4);

AngularSpeed increases over lifetime: Particle AngularSpeed Increases Over Liftime AngularSpeed increases then decreases over lifetime: Particle AngularSpeed Increasing and Decreasing Over Liftime

Change Drag Over Lifetime

You can simulate air friction by applying a drag to the particle, and you can change the amount of drag the particle experiences over its lifetime. Drag is applied in the direction of the particle's velocity. A drag of 0.8 will reduce the velocity to 20% of its value. When the drag is > 1, the particle's direction will reverse.

To change drag over the lifetime of the particle use

particleSystem.addDragGradient(0, 0.1); //drag at start of particle lifetime
particleSystem.addDragGradient(1, 0.8); //drag at end of particle lifetime

For a range of values use

particleSystem.addDragGradient(0, 0.1, 0.2); //drag range at start of particle lifetime
particleSystem.addDragGradient(0.4, 0.5, 0.6); //drag range at 2/5 of duration of particle system
particleSystem.addDragGradient(1.0, 0.8, 0.9); //drag range at end of particle lifetime

To remove a drag gradient you use

particleSystem.removeDragGradient(0.4);

Drag ≤ 1: Particle Drag Changing Over Liftime 1 Drag > 1: Particle Drag Changing Over Liftime 2

Change Emit Rate Over Duration

For example as energy builds over the duration of the particle system and increases the emit rate you might use,

particleSystem.targetStopDuration = 8;


particleSystem.addEmitRateGradient(0, 10); //emit rate at start of particle system
particleSystem.addEmitRateGradient(1.0, 500); //emit rate at end of particle system

Setting a range of lifetimes

particleSystem.targetStopDuration = 8;


particleSystem.addEmitRateGradient(0, 10, 20); //emit rate range at start of particle system
particleSystem.addEmitRateGradient(0.4, 200, 250); //emit rate range at 2/5 of duration of particle system
particleSystem.addEmitRateGradient(1, 500, 600); //emit rate range at end of particle system

remove gradient at 0.4

particleSystem.removeEmitRateGradient(0.4);

Faster emit rate over duration: Particle Faster Emission Rate Over Duration

Increasing and then decreasing emit rates over duration: Increasing Then Decreasing Emission Rates Over Duration

Change Lifetime Over Duration

For example to shorten lifetime as energy is used up over the duration of the particle system you might use,

particleSystem.targetStopDuration = 8;


particleSystem.addLifeTimeGradient(0, 0.5); //lifetime at start of particle system
particleSystem.addLifeTimeGradient(1, 0); //lifetime at end of particle system

Setting a range of lifetimes

particleSystem.targetStopDuration = 8;


particleSystem.addLifeTimeGradient(0, 0.5, 0.75); //lifetime range at start of particle system
particleSystem.addLifeTimeGradient(0.4, 0.25, 0.5); //lifetime range at 2/5 of duration of particle system
particleSystem.addLifeTimeGradient(1, 0, 0.1); //lifetime range at end of particle system

remove gradient at 0.4

particleSystem.removeLifeTimeGradient(0.4);

Shorter lifetimes over duration: Shorter Lifetimes Over Duration Increasing and then decreasing lifetimes over duration: Increasing and Decreasing Lifetimes Over Duration

Change Start Size Over Duration

To change the size of a particle on emission over the duration of the particle system use

particleSystem.targetStopDuration = 8;


particleSystem.addStartSizeGradient(0, 0.25); //start size at start of particle system
particleSystem.addStartSizeGradient(1, 1.5); //start size at end of particle system

Setting a range of start sizes

particleSystem.targetStopDuration = 8;


particleSystem.addStartSizeGradient(0, 0.5, 0.75); //start size range at start of particle system
particleSystem.addStartSizeGradient(0.4, 0.25, 0.5); //start size range at 2/5 of duration of particle system
particleSystem.addStartSizeGradient(1, 0, 0.1); //start size range at end of particle system

remove gradient at 0.4

particleSystem.removeStartSizeGradient(0.4);

Increasing start sizes over duration: Increasing Particle Start Sizes Over Duration