
## Creating Animated Particles

Here we are talking about the animation of the texture of a particle rather than any movement of the particle itself. This feature uses a similar system to that of sprite animation and was added to Babylon.js v3.1. As with sprite animation, it requires a uniform spritesheet.

You must set the property *isAnimationSheetEnabled* to true for animated particles either on or after construction (fourth parameter):

```javascript
particleSystem = new BABYLON.ParticleSystem("particles", capacity, scene, null, true); // on construction

particleSystem = new BABYLON.ParticleSystem("particles", capacity);
particleSystem.isAnimationSheetEnabled = true; // after construction
```

As an example, we use the same spritesheet as in the sprite manager section of the documentation.

![sheet](/img/how_to/sprites/08-2.webp)

This spritesheet is used as the *particleTexture*:

```javascript
particleSystem.particleTexture = new BABYLON.Texture("textures/player.png", scene, true, false);
```

In this case, the third parameter *noMipMaps* is set to true and the fourth, *invertY*, to false to read the texture data from top to bottom.

```javascript
particleSystem.spriteCellHeight = 64;
particleSystem.spriteCellWidth = 64;
particleSystem.startSpriteCellID = 0;
particleSystem.endSpriteCellID = 9;
particleSystem.spriteCellChangeSpeed = 4; // default is one
```

The *spriteCellHeight* and *spriteCellWidth* are the cell height and width for each sprite in the animation sheet.

![Cell Dimensions](/img/how_to/sprites/08-1.webp)

We are only going to use the first 10 cells of the spritesheet, and so *startSpriteCellID* is 0 and *endSpriteCellID* is 9. The top-left sprite is in cell 0, and you count from left to right from the top row downwards.

Starting with Babylon.js v3.3, you can also use

```javascript
particleSystem.spriteRandomStartCell = true;
```

to randomly pick the start cell ID of each particle between *startSpriteCellID* and *endSpriteCellID*.

To control the speed of animation, you can experiment with adjusting direction, emitPower, and updateSpeed, though doing so adjusts the whole particle animation and not just the sprite animation frame rate.

To adjust the sprite animation frame rate, you set the property *spriteCellChangeSpeed*. A value of 1 matches the animation rate to the lifetime of a particle. The particle will be emitted with the sprite at *startSpriteCellID* and will die displaying the sprite at *endSpriteCellID*. As values increase above 1, the animation frame rate speeds up. Although the particle will be emitted with the sprite at *startSpriteCellID*, the sprite on display when the particle dies will depend on the value of the speed and the lifetime of the particle.

## Examples

Adjust emit power and update speed: <Playground id="#0K3AQ2#3939" title="Adjust Emit Power And Update Speed" description="Simple example of adjusting emit power and update speed."/>  
Cell Change Speed: <Playground id="#0K3AQ2#3941" title="Cell Change Speed" description="Simple example of adjusting the cell change speed."/>



## How To Customize Particles

Beyond the many built-in properties for controlling particle behavior, Babylon.js allows further customization through **Custom Functions** and **Custom Effects**.

## Custom Functions

There are three methods you can customize:

- `startDirectionFunction`: specifies the direction for each new particle;
- `startPositionFunction`: specifies the start position for each new particle;
- `updateFunction`: provides an update to each particle on each frame and can affect position, color, age, size, etc. Try to keep it simple and fast.

You can directly attach all these functions to the `particleSystem`.

Since Babylon.js v3.2, you can use `startDirectionFunction` and `startPositionFunction` when creating a new particle emitter type, as is done with the [box, sphere, and cone emitters](/features/featuresDeepDive/particles/particle_system/shape_emitters).

### Direct

The start direction function has the default form:

```javascript
particleSystem.startDirectionFunction = (worldMatrix: Matrix, directionToUpdate: Vector3, particle: Particle, isLocal: boolean) {
    var randX = randomNumber(this.direction1.x, this.direction2.x);
    var randY = randomNumber(this.direction1.y, this.direction2.y);
    var randZ = randomNumber(this.direction1.z, this.direction2.z);

    Vector3.TransformNormalFromFloatsToRef(randX, randY, randZ, worldMatrix, directionToUpdate);
}
```

The start position function has the default form:

```javascript
particleSystem.startPositionFunction = (worldMatrix: Matrix, positionToUpdate: Vector3, particle: Particle, isLocal: boolean): void => {
  var randX = randomNumber(this.minEmitBox.x, this.maxEmitBox.x);
  var randY = randomNumber(this.minEmitBox.y, this.maxEmitBox.y);
  var randZ = randomNumber(this.minEmitBox.z, this.maxEmitBox.z);

  Vector3.TransformCoordinatesFromFloatsToRef(randX, randY, randZ, worldMatrix, positionToUpdate);
};
```

Assigning `updateFunction` replaces Babylon.js's built-in particle update, so your function is responsible for advancing particle age, recycling particles, and applying any movement or color changes you still want. Use public properties and methods in custom update functions; properties starting with `_` are internal and can change between releases.

A custom update function can take this form:

```javascript
var scaledColorStep = new BABYLON.Color4(0, 0, 0, 0);
var scaledDirection = BABYLON.Vector3.Zero();
var scaledGravity = BABYLON.Vector3.Zero();

particleSystem.updateFunction = function (particles) {
  var scene = this.getScene();
  var delta = this.updateSpeed * (scene ? scene.getAnimationRatio() : 1);

  for (let index = 0; index < particles.length; index++) {
    var particle = particles[index];
    particle.age += delta;

    if (particle.age >= particle.lifeTime) {
      this.recycleParticle(particle);
      index--;
      continue;
    }

    particle.colorStep.scaleToRef(delta, scaledColorStep);
    particle.color.addInPlace(scaledColorStep);

    if (particle.color.a < 0) {
      particle.color.a = 0;
    }

    particle.angle += particle.angularSpeed * delta;

    particle.direction.scaleToRef(delta, scaledDirection);
    particle.position.addInPlace(scaledDirection);

    this.gravity.scaleToRef(delta, scaledGravity);
    particle.direction.addInPlace(scaledGravity);
  }
};
```

Two simple examples of customizing the update function:

### Randomize the Particle's Color per Frame

Add the following line after the recycle check:

```javascript
particle.color = new BABYLON.Color4(Math.random(), Math.random(), Math.random(), 1);
```

<Playground id="#MRRGXL#956" image="/img/playgroundsAndNMEs/pg-MRRGXL-950.webp" title="Random Colored Particles" description="Simple example of creating random colored particles."/>

### Grow Particles from Size 0 to a Final Size

This is a little trickier, since the particles start from size 0 — both `minSize` and `maxSize` must be set to 0, and a new property is added to store the final size.

Add in the main body of code:

```javascript
particleSystem.minSize = 0;
particleSystem.maxSize = 0;

particleSystem.finalSize = 1;
```

After the recycle check, to grow the particle to its final size by 35% of its lifetime, add:

```javascript
if (particle.age < particle.lifeTime * 0.35) {
  particle.size = (particleSystem.finalSize * particle.age) / (particle.lifeTime * 0.35);
}
```

<Playground id="#WJBZQH#109" image="/img/playgroundsAndNMEs/pg-WJBZQH-104.webp" title="Growing Particles" description="Simple example of creating growing particles."/>

### Particle Emitter Type

Starting from Babylon.js v3.2, you can create a new object of type `IParticleEmitterType` for the particle system. [Examples](/features/featuresDeepDive/particles/particle_system/shape_emitters) of this type include `SphereParticleEmitter` and `ConeParticleEmitter`, which are produced by `createSphereEmitter` and `createConeEmitter`.

These objects are assigned to the `particleEmitterType` property of the particle system.

You use `startDirectionFunction` and `startPositionFunction` as methods on objects of this type to determine the region of space that the particles are emitted from and their direction of travel.

You can create your own particle emitter type by implementing `IParticleEmitterType` and assigning it to `particleEmitterType`, overriding the default `startDirectionFunction` and `startPositionFunction` methods.

Below is an example that creates a new spray emitter, which sends streams of particles out of the top, bottom, and sides of a cylindrical region.

#### Create Spray Emitter

To determine where a particle is emitted from, the cylinder is divided into two regions, as shown in the diagram below.

![cylinder emitter](/img/how_to/particles/cyl_particles.webp)

Any particle with a start position inside the red region is emitted in the direction from the center to the particle. Any particle with a start position inside the blue region is emitted horizontally.

The `createSprayEmitter` method sets the radius and height of the cylinder and creates a new `SprayParticleEmitter` object, which is assigned to the `particleEmitterType` property.

```javascript no-code-variants
BABYLON.ParticleSystem.prototype.createSprayEmitter = function (radius, height) {
  if (radius === void 0) {
    radius = 0.5;
  }
  if (height === void 0) {
    height = 1;
  }
  var particleEmitter = new BABYLON.SprayParticleEmitter(radius, height);
  this.particleEmitterType = particleEmitter;
  return particleEmitter;
};
```

The `SprayParticleEmitter` class implements two methods — `startDirectionFunction` and `startPositionFunction` — and Babylon.js takes care of the rest.

```javascript no-code-variants
var SprayParticleEmitter = (function () {
  function SprayParticleEmitter(radius, height, directionRandomizer) {
    if (radius === void 0) {
      radius = 0.5;
    }
    if (height === void 0) {
      height = 1;
    }
    if (directionRandomizer === void 0) {
      directionRandomizer = 0;
    }
    this.height = height;
    this.directionRandomizer = directionRandomizer;
    this.radius = radius;
  }

  SprayParticleEmitter.prototype.startDirectionFunction = function (worldMatrix, directionToUpdate, particle) {
    var direction = particle.position.subtract(worldMatrix.getTranslation()).normalize();
    var randX = BABYLON.Scalar.RandomRange(0, this.directionRandomizer);
    var randY = BABYLON.Scalar.RandomRange(0, this.directionRandomizer);
    var randZ = BABYLON.Scalar.RandomRange(0, this.directionRandomizer);
    if (direction.x * direction.x + direction.z * direction.z > 0.1 * this.radius && Math.abs(direction.y) > (0.1 * this.height) / 2) {
      direction.x += randX;
      direction.y = randY;
      direction.z += randZ;
    } else {
      direction.x += randX;
      direction.y += randY;
      direction.z += randZ;
    }
    direction.normalize();
    BABYLON.Vector3.TransformNormalFromFloatsToRef(direction.x, direction.y, direction.z, worldMatrix, directionToUpdate);
  };

  SprayParticleEmitter.prototype.startPositionFunction = function (worldMatrix, positionToUpdate, particle) {
    var s = BABYLON.Scalar.RandomRange(0, Math.PI * 2);
    var h = BABYLON.Scalar.RandomRange(-0.5, 0.5);
    var radius = BABYLON.Scalar.RandomRange(0, this.radius);
    var randX = radius * Math.sin(s);
    var randZ = radius * Math.cos(s);
    var randY = h * this.height;
    BABYLON.Vector3.TransformCoordinatesFromFloatsToRef(randX, randY, randZ, worldMatrix, positionToUpdate);
  };
  return SprayParticleEmitter;
})();
BABYLON.SprayParticleEmitter = SprayParticleEmitter;
```

<Playground id="#V07WF8#10" title="Custom Spray Emitter Showing Container" description="Simple example of a custom spray emitter showing container."/>
<Playground id="#V07WF8#11" title="Custom Spray Emitter Without Container" description="Simple example of a custom spray emitter without container."/>

## Custom Effects

A custom effect is achieved via a fourth parameter when creating a new particle system:

```javascript
var particleSystem = new BABYLON.ParticleSystem("particles", 2000, scene, customEffect);
```

`customEffect` is a `BABYLON.Effect` that targets a valid shader program and is created with the `createEffectForParticles` method on the `engine` object.

This method takes three parameters:

```javascript
var customEffect = engine.createEffectForParticles(fragment, uniforms, samplers);
```

- fragment: string — the name of the fragment shader, which can be in the [shaders store](/features/featuresDeepDive/materials/advanced/custom_procedural_textures#using-a-shaderstore-for-shader-storage) or the [id of a DOM element](/features/featuresDeepDive/materials/shaders/shaderCodeInBjs#shader-code-in-script-tags)
- uniforms: [strings] — array of additional uniforms used in the shader
- samplers: [strings] — array of names of samplers for additional textures

### Fragment Shader Assignment

When assigning a fragment shader to the shader store, the name should have `FragmentShader` appended to it. For example, creating a custom effect with the fragment name `myParticle` requires a `myParticleFragmentShader` entry in the shader store:

```javascript
BABYLON.Effect.ShadersStore["myParticleFragmentShader"] = [...]
```

```javascript
var customEffect = engine.createEffectForParticles("myParticle", [...]);
```

### Uniforms Assignment

By default, Babylon.js provides `vUV` and `vColor` varying parameters and also passes the particle texture.

You can add further uniform variables. For example, to pass a uniform variable such as `time`, include it in the uniforms array:

```javascript
var customEffect = engine.createEffectForParticles("myParticle", [time]);
```

Then pass it using `setFloat` with an `onBind` callback for `customEffect`:

```javascript
var time = 0;
var order = 0.1;

customEffect.onBind = function () {
  customEffect.setFloat("time", time);

  time += order;

  if (time > 100 || time < 0) {
    order *= -1;
  }
};
```

You can see an example of the above in this playground:  
<Playground id="#1ASENS#43" title="Custom Effect Using Shader Store" description="Simple example of a custom effect using the shader store."/>  
You can see a similar example with node-based particles:
<Playground id="#0K3AQ2#3943" title="Custom Effect Using Shader Store With NPE" description="Simple example of a custom effect using the shader store with NPE."/>

### Particle Effect Object

The particle effect object is a slightly modified [Babylon Effect Object](/typedoc/classes/babylon.effect). Also note that the `ShadersStore` is a namespace on this special effect object.



# Shape Emitters

Starting from Babylon.js 3.2, you can shape the region particles are emitted from by using a specific emitter type:

* Point
* Box
* Sphere
* Hemisphere
* Cylinder
* Cone
* Mesh
* Custom

## Point Emitter

To create a point emitter, you can run this code:

```javascript
var pointEmitter = particleSystem.createPointEmitter(new BABYLON.Vector3(-7, 8, 3), new BABYLON.Vector3(7, 8, -3));
```

The `createPointEmitter` method takes two parameters in the following order:

* direction1: Vector3
* direction2: Vector3

The returned `pointEmitter` object can be used to change the values of these properties:

```javascript
pointEmitter.direction1 = new BABYLON.Vector3(-5, 2, 1); 
pointEmitter.direction2 = new BABYLON.Vector3(5, 2, 1);  
```

<Playground id="#0K3AQ2#3933" title="Point Emitter" description="Simple example of a particle point emitter."/>

## Box Emitter

To create a box emitter, you use, for example:

```javascript
var boxEmitter = particleSystem.createBoxEmitter(new BABYLON.Vector3(-7, 8, 3), new BABYLON.Vector3(7, 8, -3), new BABYLON.Vector3(-1, 0, 0), new BABYLON.Vector3(1, 0, 0));
```

The `createBoxEmitter` method takes four parameters in the following order:

* direction1: Vector3
* direction2: Vector3
* minEmitBox: Vector3
* maxEmitBox: Vector3

The returned `boxEmitter` object can be used to change the values of these properties:

```javascript
boxEmitter.direction1 = new BABYLON.Vector3(-5, 2, 1); 
boxEmitter.direction2 = new BABYLON.Vector3(5, 2, 1);  
boxEmitter.minEmitBox = new BABYLON.Vector3(-2, -3, -4);  
boxEmitter.maxEmitBox = new BABYLON.Vector3(2, 3, 4); 
```

<Playground id="#0K3AQ2#3912" title="Box Emitter" description="Simple example of a particle box emitter."/>

## Sphere Emitter

You can create a sphere emitter with a given radius (e.g. 1.2):

```javascript
var sphereEmitter = particleSystem.createSphereEmitter(1.2);
```

The returned `sphereEmitter` object can be used to change the radius.

The particles are emitted in the direction of the surface normals, i.e. the lines from the center of the sphere through a surface point.

<Playground id="#0K3AQ2#3916" title="Sphere Emitter" description="Simple example of a particle sphere emitter."/>

With `sphereEmitter.radiusRange`, you can define where along the radius the particles should be emitted. A value of 0 means only on the surface, while a value of 1 means all along the radius.

If you prefer to choose the emission direction, you can create a directed sphere emitter:

```javascript
var sphereEmitter = particleSystem.createDirectedSphereEmitter(1.2, new BABYLON.Vector3(1, 1, 1), new BABYLON.Vector3(2, 8, 2));
```

The `createDirectedSphereEmitter` method takes three parameters in the following order:

* radius: Number
* direction1: Vector3
* direction2: Vector3

The returned `sphereEmitter` object can be used to change the values of these properties:

```javascript
sphereEmitter.radius = 3.4;
sphereEmitter.direction1 = new BABYLON.Vector3(-5, 2, 1); 
sphereEmitter.direction2 = new BABYLON.Vector3(5, 2, -1);    
```

The particle direction will be generated randomly between `direction1` and `direction2`.

<Playground id="#0K3AQ2#3917" title="Sphere Emitter With Directions" description="Simple example of a particle sphere emitter with directions."/>

## Hemispheric Emitter

You can create a hemispheric emitter with a given radius (e.g. 1.2):

```javascript
var hemisphericEmitter = particleSystem.createHemisphericEmitter(1.2);
```

The returned `hemisphericEmitter` object can be used to change the radius.

The particles are emitted in the direction of the surface normals, i.e. the lines from the center of the hemisphere through a surface point.

<Playground id="#0K3AQ2#3915" title="Hemispheric Emitter" description="Simple example of a particle hemispheric emitter."/>

With `hemisphericEmitter.radiusRange`, you can define where along the radius the particles should be emitted. A value of 0 means only on the surface, while a value of 1 means all along the radius.

## Cylinder Emitter

You can create a cylinder emitter with a given `radius`, `height`, `radiusRange`, and `directionRandomizer`:

```javascript
var cylinderEmitter = particleSystem.createCylinderEmitter(1, 1, 0, 0);
```

The returned `cylinderEmitter` object can be used to change these property values.

The particles are emitted in the direction of the surface normals, i.e. outward from the cylinder.

<Playground id="#0K3AQ2#3921" title="Cylinder Emitter" description="Simple example of a particle cylinder emitter."/>

With `cylinderEmitter.radiusRange`, you can define where along the radius the particles should be emitted. A value of 0 means only on the surface, while a value of 1 means all along the radius.
With `cylinderEmitter.directionRandomizer`, you can change how much to randomize the particle's direction.

If you prefer to choose the emission direction, you can create a directed cylinder emitter. The `createDirectedCylinderEmitter` method takes five parameters in the following order:

* radius: Number
* height: Number
* radiusRange: Number
* direction1: Vector3
* direction2: Vector3

The returned `cylinderEmitter` object can be used to change the values of these properties:

```javascript
cylinderEmitter.radius = 3.4;
cylinderEmitter.direction1 = new BABYLON.Vector3(-5, 2, 1); 
cylinderEmitter.direction2 = new BABYLON.Vector3(5, 2, -1);    
```

The particle direction will be generated randomly between `direction1` and `direction2`.

<Playground id="#0K3AQ2#3922" title="Cylinder Emitter With Directions" description="Simple example of a particle cylinder emitter with directions."/>

## Cone Emitter

To create a cone emitter:

```javascript
var coneEmitter = particleSystem.createConeEmitter(2, Math.PI / 3);
```

The `createConeEmitter` method takes two parameters in the following order:

* radius: Number
* angle: Number — measured in radians; the vertex angle of the cone

The cone is created with its axis along the Y-axis and its vertex at the bottom.

With `coneEmitter.radiusRange`, you can define where along the radius the particles should be emitted. A value of 0 means only on the surface, while a value of 1 means all along the radius.

The same applies to `coneEmitter.heightRange`: you can define where along the height the particles should be emitted. A value of 0 means only on the top surface, while a value of 1 means all along the height.

The returned `coneEmitter` object can be used to change the values of these properties:

```javascript
coneEmitter.radius = 3.4;
coneEmitter.angle = Math.PI / 2;    
```

With `coneEmitter.emitFromSpawnPointOnly = true`, you can force the emitter to only emit particles from the spawn point (the start of the cone).

<Playground id="#0K3AQ2#3925" title="Cone Emitter" description="Simple example of a particle cone emitter."/>
<Playground id="#0K3AQ2#3935" title="Cone Emitter From Spawn Point" description="Simple example of a particle cone emitter from the spawn point."/>

## Mesh Emitter

You can use `MeshParticleEmitter` to emit particles from the surface of a mesh:

```javascript
var meshEmitter = new BABYLON.MeshParticleEmitter(sphere);
```

By default, the direction of the particles follows the surface normal of the mesh. You can disable this and use a custom direction instead:

```javascript
meshEmitter.useMeshNormalsForDirection = false;
meshEmitter.direction1 = new BABYLON.Vector3(0, 1, 0);
meshEmitter.direction2 = new BABYLON.Vector3(0, -1, 0);
```

**Please note that `MeshParticleEmitter` is not supported by GPU particle systems.**

Here is an example of a mesh particle emitter: <Playground id="#0K3AQ2#3929" title="Mesh Emitter" description="Simple example of a particle mesh emitter."/>

## Custom Emitter

A custom emitter lets you define the position and destination of each particle by providing two generator functions:

```javascript
var customEmitter = new BABYLON.CustomParticleEmitter();

var id = 0;
customEmitter.particlePositionGenerator = (index, particle, out) => {
    out.x = Math.cos(id) * 5;
    out.y = Math.sin(id) * 5;
    out.z = 0;
    id += 0.01;
}

customEmitter.particleDestinationGenerator = (index, particle, out) => {
    out.x = 0;
    out.y = 0;
    out.z = 0;
}
```

When used with a GPU particle system, the generators (`particlePositionGenerator` and `particleDestinationGenerator`) receive a particle index. When used with a CPU particle system, they receive the actual particle object to update.

Here is an example of a custom particle emitter: <Playground id="#0K3AQ2#3932" title="Custom Emitter" description="Simple example of a particle custom emitter."/>


Animating Particles

Creating Animated Particles

Examples