
# Shape Emitters
Starting from Babylonjs 3.2 you can shape the region the particles are emitted from as a

* Point
* Box
* Sphere
* Hemisphere
* Cylinder
* Cone
* Mesh
* Custom

by the addition of specific emitter function.

## 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 four 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="#08YT34" 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="#MRRGXL#1" title="Box Emitter" description="Simple example of a particle box emitter."/>

## Sphere Emitter

You can create a sphere emitter with a given radius, 1.2 for example,  using

```javascript
var sphereEmitter = particleSystem.createSphereEmitter(1.2);
```
The returned `sphereEmitter` object can be used to change the value of the radius.

The particles are emitted in the direction of the surface normals, ie the lines from the center of the sphere through a surface point.

<Playground id="#MRRGXL#2" 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 first parameter is the radius the second is direction1 and third is direction2. (The direction will be generated randomly between direction1 and direction2)

<Playground id="#MRRGXL#3" 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, 1.2 for example,  using

```javascript
var hemisphericEmitter = particleSystem.createHemisphericEmitter(1.2);
```
The returned `hemisphericEmitter` object can be used to change the value of the radius.

The particles are emitted in the direction of the surface normals, ie the lines from the center of the hemisphere through a surface point.

<Playground id="#FHIQYC" 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, directionRandomizer with the following:

```javascript
var cylinderEmitter = particleSystem.createCylinderEmitter(1,1,0,0);
```
The returned `cylinderEmitter` object can be used to change the value of the radius, height, etc.

The particles are emitted in the direction of the surface normals, ie outward from the cylinder

<Playground id="#UL4WC0" 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` can change how much to randomize the particles direction.

The `createDirectedCylinderEmitter` method takes three 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 first parameter is the radius the second is direction1 and third is direction2. (The direction will be generated randomly between direction1 and direction2)

<Playground id="#UL4WC0#5" title="Cylinder Emitter With Directions" description="Simple example of a particle cylinder emitter with directions."/>

## Cone Emitter

To create a cone emitter you use, for example

```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.

Here is an example of a particle system emitted only from the outside of a flat cone: <Playground id="#B9HKG0#1" title="Emitter From Outside A Cone" description="Simple example of a particle system emitting from outside of a flat cone."/>

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="#MRRGXL#4" title="Cone Emitter" description="Simple example of a particle cone emitter."/>
<Playground id="#MRRGXL#5" title="Cone Emitter Rotating" description="Simple example of a particle cone emitter rotating."/>


## Mesh Emitter

You can use the MeshParticleEmitter to emit your particles from the surface of a mesh:

```javascript
 var meshEmitter = new BABYLON.MeshParticleEmitter(sphere);
```

By default the direction of the particles will be the normal of the surface of the mesh but you can turn it off and then use a custom direction:

```
meshEmitter.useMeshNormalsForDirection = false;
meshEmitter.direction1 = new BABYLON.Vector3(0, 1, 0);
meshEmitter.direction2 = new BABYLON.Vector3(0, -1, 0);
```

**Please note that the MeshParticleEmitter is not supported by GPU Particle**

Here is an example of a mesh particle emitter: <Playground id="#N775HF" title="Mesh Emitter" description="Simple example of a particle mesh emitter."/>

## Custom Emitter

To create a custom emitter you need to provide 2 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;
 }
```

A custom emitter will let you define the position and the destination of each particle.

When used with a GPU Particle system the generators(`particlePositionGenerator` and `particleDestinationGenerator`) will provide a particle index whereas when used with a CPU Particle system they will provide the actual particle to update.

Here is an example of a custom particle emitter: <Playground id="#77BKY4" title="Custom Emitter" description="Simple example of a particle custom emitter."/>



## Creating Animated Particles
Here we are talking about the animation of the texture of a particle rather than any movement or the particle itself. This feature uses a similar system to that of sprite animation and was added to Babylon.js v3.1. As for sprite animation it requires a uniform spritesheet.


You must set the property *isAnimationSheetEnabled* as 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 are using the same spritesheet as for the sprite manager section of the documentstion.

![sheet](/img/how_to/sprites/08-2.png)

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 *noMinMaps* 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 width and height for each sprite in the animation sheet. 

![Cell Dimensions](/img/how_to/sprites/08-1.png)

We are only going to use the first 10 cells of the spritesheets and so *startSpriteCellID* is 0 and *endSpriteCellID* is 9. The top, left most 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 play around with adjusting direction, emitPower and updateSpeed though doing this 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 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#47" title="Adjust Emit Power And Update Speed" description="Simple example of adjusting emit power and update speed."/>
Cell Change Speed: <Playground id="#0K3AQ2#48" title="Cell Change Speed" description="Simple example of adjusting the cell change speed."/>



# Change Particle Behaviors 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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
particleSystem.removeSizeGradient(0.4);
```

Size increases over lifetime: <Playground id="#0K3AQ2#18" title="Particle Size Increases Over Liftime" description="Simple example of particle size increasing over the lifteime of a particle."/>
Size increases then decreases over lifetime: <Playground id="#0K3AQ2#19" title="Particle Size Increases Then Decreases Over Liftime" description="Simple example of particle size increasing then decreasing over the lifteime of a particle."/>

## Change Color Over Lifetime

To change color over the lifetime of the particle use

```javascript
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

```javascript
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

```javascript
particleSystem.removeColorGradient(0.4);
```

color change over lifetime: <Playground id="#0K3AQ2#20" title="Particle Color Change Over Liftime" description="Simple example of particle color changing over the lifteime of a particle."/>
color change with ranges over lifetime: <Playground id="#0K3AQ2#22" title="Particle Color Change With Ranges Over Liftime" description="Simple example of particle color changing with ranges over the lifteime of a particle."/>

## Change Speed Over Lifetime

To change the speed (magnitude of velocity) over the lifetime of the particle use

```javascript
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

```javascript
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

```javascript
particleSystem.removeVelocityGradient(0.4);
```

Speed increases over lifetime: <Playground id="#0K3AQ2#29" title="Particle Speed Increases Over Liftime" description="Simple example of particle speed increasing over the lifteime of a particle."/>
Speed increases then decreases over lifetime: <Playground id="#0K3AQ2#30" title="Particle Speed Increases Then Decreases Over Liftime" description="Simple example of particle speed increasing then decreasing over the lifteime of a particle."/>

## Limit Speed Over Lifetime

You can define by how much to limit the speed of a particle with

```javascript
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

```javascript
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

```javascript
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

```javascript
particleSystem.removeLimitVelocityGradient(0.4);
```

Speed limit increases over lifetime: <Playground id="#0K3AQ2#33" title="Particle Speed Limit Increases Over Liftime" description="Simple example of particle speed limit increasing over the lifteime of a particle."/>

## Change Rotation Speed Over Lifetime

To change the rotation or angular speed over the lifetime of the particle use

```javascript
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

```javascript
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 an angular speed gradient you use

```javascript
particleSystem.removeAngularSpeedGradient(0.4);
```

AngularSpeed increases over lifetime: <Playground id="#0K3AQ2#26" title="Particle AngularSpeed Increases Over Liftime" description="Simple example of particle Angularspeed increasing over the lifteime of a particle."/>
AngularSpeed increases then decreases over lifetime: <Playground id="#0K3AQ2#27" title="Particle AngularSpeed Increasing and Decreasing Over Liftime" description="Simple example of particle Angularspeed increasing and decreasing over the lifteime of a particle."/>

## 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 &gt; 1, the particle's direction will reverse.

To change drag over the lifetime of the particle use

```javascript
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

```javascript
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

```javascript
particleSystem.removeDragGradient(0.4);
```

Drag &le; 1: <Playground id="#0K3AQ2#39" title="Particle Drag Changing Over Liftime 1" description="Simple example of particle drag changing over the lifteime of a particle."/>
Drag &gt; 1: <Playground id="#0K3AQ2#40" title="Particle Drag Changing Over Liftime 2" description="Simple example of particle drag changing over the lifteime of a particle."/>

## 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,

```javascript
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

```javascript
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

```javascript
particleSystem.removeEmitRateGradient(0.4);
```

Faster emit rate over duration: <Playground id="#0K3AQ2#13" title="Particle Faster Emission Rate Over Duration" description="Simple example of faster particle emission rates over the duration."/>

Increasing and then decreasing emit rates over duration: <Playground id="#0K3AQ2#14" title="Increasing Then Decreasing Emission Rates Over Duration" description="Simple example of increasing then decreasing the emission rate over the 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,

```javascript
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

```javascript
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

```javascript
particleSystem.removeLifeTimeGradient(0.4);
```

Shorter lifetimes over duration: <Playground id="#0K3AQ2#9" title="Shorter Lifetimes Over Duration" description="Simple example of shortening lifetimes of particles over duration."/>
Increasing and then decreasing lifetimes over duration: <Playground id="#0K3AQ2#15" title="Increasing and Decreasing Lifetimes Over Duration" description="Simple example of increasing and then 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

```javascript
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

```javascript
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

```javascript
particleSystem.removeStartSizeGradient(0.4);
```

Increasing start sizes over duration: <Playground id="#0K3AQ2#41" title="Increasing Particle Start Sizes Over Duration" description="Simple example of increasing particle start sizes over duration."/>
