API

Particle System Intro

An Introduction to the Particle System

The creation of a particle system requires a name and its capacity and the number of particles in the system (capacity). The system is designed to produce particles that emit at a given rate, move and last for a set lifetime before they are re-cycled and re-emitted.

const myParticleSystem = new BABYLON.ParticleSystem("particles", capacity, scene); //scene is optional and defaults to the current scene

Before you can start the system running you need to provide a texture so that the particles can be seen. Also you need to set the point of origin for the particle emissions. You set this as an emitter, i.e. a mesh, whose position provides the emission origin or it can be just a vector3. Particles are emitted from random points inside a region of given size about the emission point of origin.

myParticleSystem.particleTexture = new BABYLON.Texture("path to texture");


myParticleSystem.emitter = mesh;
myParticleSystem.emitter = point; //a Vector3


myParticleSystem.start(); //features/starts the emission of particles

To stop the emission use

myParticleSystem.stop();

While this stops the emission of new particles the ones already emitted will continue to exist up to their time limit. To stop and clear particles at the same time use

myParticleSystem.stop();
myParticleSystem.reset(); //Reset to empty system

Minimal particle system Minimal Particle System

You can do this all in one line using the ParticleHelper to create a default configured particle system.

Default particle system using the helper: Default Particle System Using The Helper

Emit particles from a box position: Emit Particles From a Box Position

By fixing the size of the emission region you can constrain the emission region. The values used will depend on the size of the emitted particles and the size of the region. The center of an emitted particle could be inside a box, say close to the edge, yet the particle could be big enough for its perimeter to be outside the box.

Emit particles from wholly inside the box: Emit Particles From Completely Inside a Box When you want the particle system to start after 3 seconds for example you use one of the following

myParticleSystem.start(3000); //time in milliseconds


myParticleSystem.startDelay = 3000;

Delayed start particle system: Particle System With a Delayed Start

To run the particle system for a limited time you use

myParticleSystem.targetStopDuration = 5;

The target duration before the system stops is dependent of the how fast the particles system updates the particles frames. The faster the update speed the shorter time before the system stops. You set the update speed using

myParticleSystem.updateSpeed = 0.01;

Once stopped you can dispose of the particle system. Very useful if you want to create a one shot particle system with a specific targetStopDuration.

myParticleSystem.disposeOnStop = true;

Pre-warming

Starting with Babylon.js v3.3, you can now specify a pre-warming period to make sure your system is in a correct state before rendering.

To do so, you need to setup two properties:

  • system.preWarmCycles: Gets or sets a value indicating how many cycles (or frames) must be executed before first rendering (this value has to be set before starting the system). Default is 0 (ie. no pre-warming)
  • system.preWarmStepOffset: Gets or sets a value indicating the time step multiplier to use in pre-warm mode (default is 1)

So if you set your system like this:

system.preWarmCycles = 100;
system.preWarmStepOffset = 5;
system.start();

It will execute the particle animation loop 100 times with a time step set to 5 times faster than real time. The more cycles you want, the slower the system will be to start. So it could be interesting to increase the time step to have less cycles to run. But keep in mind that a too big time step will introduce issues if the lifetime of a particle is smaller than the time step.

Here is an example of pre-warming: Particle Pre-Warming Example

Particle Texture

To apply a texture to the particles, such as
Flare

set the particleTexture

myParticleSystem.particleTexture = new BABYLON.Texture("PATH TO IMAGE", scene);

You can also apply a mask to a texture to filter some colors, or filter a part of the alpha channel.

myParticleSystem.textureMask = new BABYLON.Color4(0.1, 0.8, 0.8, 1.0);

This example produces the following
TextureMask

To use multiple textures in the scene use multiple particle systems all of which can use the same emitter object.

Noise texture

Starting with Babylon.js v3.3, you can now use noise texture to "perturbate" the position of particles. The noise texture is technically used to apply change to the direction of the particles:

var noiseTexture = new BABYLON.NoiseProceduralTexture("perlin", 256, scene);
noiseTexture.animationSpeedFactor = 5;
noiseTexture.persistence = 2;
noiseTexture.brightness = 0.5;
noiseTexture.octaves = 2;


particleSystem.noiseTexture = noiseTexture;
particleSystem.noiseStrength = new BABYLON.Vector3(100, 100, 100);

Alongside setting the noiseTexture you can also control the strength applied on each axis with particleSystem.noiseStrength.

Adjustable noise: Changing Particle Direction With Noise

Local space

If the emitter is a mesh and you set particleSystem.isLocal = true then all particles will be generated into the mesh local space (so rotation or transforming the mesh will transform the entire particle system).

Demo: Particles In Local Space

World offset

Starting with Babylon.js v4.0, you can set up a world offset to your particles with:

particleSystem.worldOffset = new BABYLON.Vector3(100, 20, -453);

This command will shift the particles using the offset (Mostly used when you need to keep the camera at the center of the world to increase precision and then move the world instead).

So far we have barely touched the surface of the particle system. There is a wide range of properties to find out about to further tune the particle system.