
# Expandable Solid Particle System

## Create an expandable SPS

Until now, the SPS that you've created has a fixed number of particles once for all because it's the most performant way to use it.  
In some cases, it may be useful to add or to remove some particles from the SPS after its creation, because they are newly needed or not needed any longer for the rest of the time.  
In this case, you can create an expandable SPS with the optional parameter `expandable: true` (default `false`).

```javascript
var sps = new BABYLON.SolidParticleSystem("sps", scene, { expandable: true });
```

### Adding particles

If you want to add some more particles to the existing ones, then just use again the method `addShape()` as many times as necessary. Then call `buildMesh()` to rebuild the SPS geometry with these newly added particles.

```javascript
var sps = new BABYLON.SolidParticleSystem("sps", scene, { expandable: true });
sps.addShape(model1, 100); // adds 100 particles from model1
sps.buildMesh();

// ... further in the code, when needed
sps.addShape(model2, 100); // adds 100 new particles from model2
sps.addShape(model3, 200); // and 200 particles from model3
sps.buildMesh(); // updates the SPS mesh geometry from the last particle additions
sps.setParticles();
```

Example: <Playground id="#X1T859" title="Adding Particles To A Solid Particle System" description="Simple example of adding particles to a solid particle system."/>
Each mouse click adds 20 new depth sorted particles.

### Removing particles

If you want to remove some particles from the SPS, then use the method `removeParticles(start, end)` where `start` and `end` are the starting and ending indexes of the particles.  
This method returns an array populated with the removed particles.

```javascript
var sps = new BABYLON.SolidParticleSystem("sps", scene, { expandable: true });
sps.addShape(model1, 1000); // adds 1000 particles from model1
sps.buildMesh();

// ... further in the code, when needed
var removed1 = sps.removeParticles(700, 999); // removes the last 300 particles
var removed2 = sps.removeParticles(0, 9); // removes the first 10
sps.buildMesh(); // update the SPS mesh geometry from the last particle additions
sps.setParticles();
```

Example: <Playground id="#0MXVDK" title="Removing Particles From A Solid Particle System" description="Simple example of removing particles from a solid particle system"/>
Each click removes the 2 first and last 100 particles.  
**Important note :** the SPS must contain at least one particle to work, so never empty it completely !

### Storable particles

You may want to create new particles and not to insert them in the SPS on its creation but later. You may also want to keep aside removed particles to put them back in the system later.  
So when creating new particles, you can specify to store them aside from the SPS with the optional parameter `storage: []` of the method `addShape()`.

```javascript
var stock = []; // the array to store the particles
var sps = new BABYLON.SolidParticleSystem("sps", scene, { expandable: true });
sps.addShape(model1, 1); // the SPS needs at least one particle
sps.addShape(model1, 100, { storage: stock }); // stores 100 particles from model1 in the stock array
sps.buildMesh();
```

This SPS contains only one particle. The 100 others are stored in an external array.

If you want now to restore these particles, or some previously removed ones, just use the method `insertParticlesFromArray(array)`.

```javascript
var stock = []; // the array to store the particles in
var sps = new BABYLON.SolidParticleSystem("sps", scene, { expandable: true });
sps.addShape(model1, 1000); // the SPS contains 1000 particles
sps.addShape(model1, 100, { storage: stock }); // 100 others are stored aside
sps.buildMesh();

// ... later in the code
var removed = sps.removeParticles(0, 99); // the 100 first particles are removed and stored in another array
sps.buildMesh();

// ... later again in the code : let's restore the misssing particles
sps.insertParticlesFromArray(removed); // restores the previously removed particles
sps.insertParticlesFromArray(stock); // restores the previously created particles
sps.buildMesh();
sps.setParticles();
```

Each time that you call `insertParticlesFromArray()`, the stored particle objects aren't just referenced in the SPS, they are cloned and the clones are reindexed and given a new identifier.  
This means that you can modify or get rid of the storage array or their contained particle objects with no effect and no risk for the SPS working.  
Example: <Playground id="#HL9PPA" title="Storable Particles Example" description="Simple example of making particles storable."/>
Each click removes 100 particles of a given shape and restore 100 particles of another shape in turn.  
100 particles are stored aside at the SPS creation.

### Notes :

- When you remove particles, the remaining ones are reindexed, meaning that their `particle.idx` value can change. The particle identifier `particle.id` keeps unchanged. If a particle is given a parent and if this parent is removed, then the particle `parent` property value is set to `null`.
- Adding or removing particles will create a new VertexData object, so a new VBO buffer, each time `buildMesh()` is called.  
  This can trigger the Garbage Collector activity at some unwanted moment, so it's not a good idea to add or remove particles each frame.  
  Moreover, using an expandable SPS uses more memory than a fixed one because all the dynamic extensible arrays are saved under the hood along the SPS life.

  In a standard SPS, the particle index `particle.idx` and the particle identifier `particle.id` have the same value.  
In an expandable SPS (see below), when particles are removed only the particle identifier `particle.id` keeps unchanged whereas the particle index may change.  
So, when using an expandable SPS, make sure to set a particle parent with the parent identifier and make sure that this parent still exists.

```javascript
if (otherParticle) {
  particle.parentId = otherParticle.id; // not otherParticle.idx
}
```


# Immutable Solid Particle System

An immutable SPS is one where particle properties will not change. This is one way to optimize your scene when it needs many similar objects that won't change afterwards, such as buildings in the distance or asteroids. Placing multiple copies of a model into one mesh means only one draw call for each frame rendering. Besides SPS there are other methods of forming a single mesh from multiple copies of one mesh; these are merge meshes, instances and thin instances.

You can create an immutable SPS in two different ways.

1. Build your SPS as explained earlier in this section and call _initParticles_ and _setParticles()_ just once, before and outside the render loop, to set your particles where and how you need. This method is quite simple However the SPS mesh is still built as updatable so that particle properties can be initiated and because of this particle data is cached, waiting for a hypothetical further change. This is the only way to do it when using billboard mode and in this case you still need to call _setParticles_ in the render loop also even if the particles don't move.
2. Set the SPS to updatable on construction using a third options parameter _SolidParticleSystem(name, scene, \{ updatable: false \})_

It is the second method that we describe here.

To construct an immutable SPS you use

```javascript
var SPS = new BABYLON.SolidParticleSystem(name, scene, { updatable: false });
```

As the mesh can't be updated you cannot initiate the particles with _initParticles()_ and calling _setParticles()_ has no effect; don't call it, you'll spare some CPU. For now the _particles_ array is not even populated! In fact no particle management function called **after** _SPS.buildMesh()_ will have any effect.

How do you set the initial particle properties when the SPS mesh can't be updated? You pass a custom function to an options object with the property _positionFunction_ when you add a model as a shape like this

```javascript
SPS.addShape(model, number_of_particles, { positionFunction: myCustomFunction });
```

Your custom function will be called as many times as the _number_of_particles_ for the added shape. It needs up to three parameters; a particle object, an index, i, which is a counter to the total number of shapes that have been added by all calls to _addShape_ and, s, which is a counter to the number of models added by calling _addShape_.

For example, a custom function has this form

```javascript
const myBuilder = function (particle, i, s) {
  // set properties of particle
};
```

When using it on two models

```javascript
SPS.addShape(model1, 1000, { positionFunction: myBuilder });
SPS.addShape(model2, 500, { positionFunction: myBuilder });
```

While model1 is added i runs from 0 to 999 and s runs from 0 to 999.
When model2 is added i runs from 1000 to 1499 and s runs from 0 to 499

The _particle_ object has the following properties that you can set

| property           | type       | default                                                     |
| ------------------ | ---------- | ----------------------------------------------------------- |
| position           | Vector3    | (0,0,0)                                                     |
| rotation           | Vector3    | (0,0,0)                                                     |
| rotationQuaternion | Quaternion | null, if _rotationQuaternion_ is set, _rotation_ is ignored |
| scaling            | Vector3    | (1,1,1)                                                     |
| pivot              | Vector3    | (0,0,0)                                                     |
| color              | Color4     | null                                                        |
| uvs                | Vector4    | (0,0,1,1)                                                   |

An example of code to build an immutable mesh

```javascript
const myBuilder = (particle, i, s) => {
  // particle is the current particle
  // i is its global index in the SPS
  // s is its index in its shape, so here from 0 to 149
  particle.rotation.y = s / 150;
  particle.position.x = s - 150;
  particle.uvs = new BABYLON.Vector4(0, 0, 0.33, 0.33); // first image from an atlas
  particle.scaling.y = Math.random() + 1;
};
const box = BABYLON.MeshBuilder.CreateBox("b", {}, scene);
const SPS = new BABYLON.SolidParticleSystem("SPS", scene, { updatable: false });
SPS.addShape(box, 150, { positionFunction: myBuilder }); // myBuilder will be called for each of the 150 boxes
const mesh = SPS.buildMesh();
```

Immutable color cube of triangle particles: <Playground id="#2FPT1A#5" title="Immutable Color Cube of Triangle Particles" description="Simple example of immutable color cube of triangle particles."/>
Immutable town with 80,000 buildings: <Playground id="#2FPT1A#36" title="Immutable Town With 80,000 Buildings" description="Simple example of an immutable town with 80,000 buildings"/>

Note that although the particles cannot move but you can still move, scale or rotate the whole SPS mesh. When there is no need for you SPS mesh to move, scale or rotate you can use the standard Babylon.js mesh _freezeXXX()_ methods for further performance gain

```javascript
SPS.mesh.freezeWorldMatrix(); // prevents from re-computing the World Matrix each frame
SPS.mesh.freezeNormals(); // prevents from re-computing the normals each frame
```

You are not restricted to using the _positionFunction_ to just a SPS created with _updatable = true_ although using _initParticles()_ and _setParticles()_ is probably easier and you have a few more particle properties.

## Solid Particle Vertex Position

In addition to the _positionFunction_ to set a particle's property there is also a _vertexFunction_ option to modify the shape of each particle by changing the positions of the vertices of the model forming the particle. The custom function you assign to the _vertexFunction_ is called once by _SPS.buildMesh()_ for each vertex of a particle.

```javascript
var myVertexFunction = function (particle, vertex, i) {
  // particle : the current particle
  // vertex : the current vertex position within the particle
  // i : index of the vertex in the particle shape
  vertex.x *= Math.random() + 1;
};
SPS.addShape(box, 150, { vertexFunction: myVertexFunction }); // the 150 boxes will have their vertices moved randomly
SPS.buildMesh();
```

Of course you can use the both properties together :

```javascript
SPS.addShape(box, 150, {
  vertexFunction: myVertexFunction,
  positionFunction: myPositionFunction,
});
```

Example with asteroids: <Playground id="#2FPT1A#2" title="Solid Particle Vertex Position Example" description="Simple example of updating solid particle vertex positions"/>

Making your SPS immutable is one way to optimize your scene. Next we will consider ways to optimize when using an updatable SPS.

## Rebuild the mesh

if a mesh, changed at creation time with `positionFunction` or `vertexFunction` has been then modified with `setParticles()`, it can be rebuild by reapplying the internally stored `positionFunction` or `vertexFunction` functions.  
Note that only the function are stored, not their results. This means that if one of your function produces different results each call (using `Math.random()` for instance), you won't get back the same SPS mesh shape but another computed shape.

```javascript
SPS.rebuildMesh();
```

Except in some very specific cases, you might not need to use this function.



# Managing the SPS

The SPS mesh when built has all the properties and methods that you can apply to any mesh. In addition there are useful properties you can use with the SPS. Some you should have met already.

Property | Type | Use 
-----|-----|----- 
SPS.particles | particle[] | iterate over this array in *initParticles()*
SPS.nbParticles | number | total number of particles in the SPS
SPS.billboard | Boolean | turns particles towards camera; false by default
SPS.counter | number | for your own usage, its not set by the SPS

When working with JavaScript you can add your own properties like _capacity_ or _rate_ if needed.

When you don't need your SPS any longer, you can dispose it to free the memory with
```javascript
SPS.dispose();
SPS = null; // tells the GC the reference can be cleaned up also
```

When you are not going to use some particle features you can set other properties of the SPS to *false* disable them.  You can always enable them again with *true*. This improve the performance of the scene as no attempt will be made to update these properties.

Property | Type | Default | Use 
----- | ----- | ----- | -----
SPS.computeParticleRotation | Boolean | true | allows or prevents computing particle.rotation
SPS.computeParticleTexture | Boolean | true | allows or prevents computing particle.uvs
SPS.computeParticleColor | Boolean | true | allows or prevents from computing particle.color
SPS.computeParticleVertex | Boolean | false | allows or prevents calling the custom updateParticleVertex() function

These properties affect the *SPS.setParticles()* process only. You can change them between calls to *SPS.setParticles()*.  For example setting *SPS.computeParticleColor* to false after the first call to *SPS.setParticles()* allows particle colors set during *initParticles()* to be applied but prevents any call to updating colors in subsequent calls to *SPS.setParticles()*. When *SPS.setParticles()* is inside the render loop this can be very beneficial.

Tetra fountain color and texture not updated: <Playground id="#GLZ1PX#10" title="Tetrahedron Fountain Color And Texture Not Updated" description="Simple example of creating a particle fountain where color and textures are not updated."/>



# Managing SPS Particles

## Properties

There are many properties you can set on a particle

| Property           | Type       | Default      |
| ------------------ | ---------- | ------------ |
| position           | Vector3    | (0, 0, 0)    |
| rotation           | Vector3    | (0, 0, 0)    |
| rotationQuaternion | Quaternion | undefined    |
| velocity           | Vector3    | (0, 0, 0)    |
| color              | Color4     | (1, 1, 1, 1) |
| scaling            | Vector3    | (1, 1, 1)    |
| pivot              | Vector3    | (0, 0, 0)    |
| uvs                | Vector4    | (0, 0, 1, 1) |
| isVisible          | boolean    | true         |
| alive              | boolean    | true         |
| translateFromPivot | boolean    | false        |
| parentId           | integer,   | null         |
| props              | any        | null         |

and three you can read:

- _idx_ - which allows you to read the index of the particle in the SPS particles array;
- _idxInShape_ - which allows you to read the index of the particle relative to the shape (model mesh) added to the SPS;
- _shapeId_ - a number reference to the model added

For example, after

```javascript
SPS.addShape(model1, 1000);
SPS.addShape(model2, 500);

particle = SPS.particles[1200];
```

In the above example

1. the particle with _particle.idx = 745_ will have _particle.idxInShape = 745_ and _particle.shapeId = 0_.
2. the particle with _particle.idx = 1200_ will have _particle.idxInShape = 200_ and _particle.shapeId = 1_.

These can be useful for applying different properties to different shapes.

When you set a particle rotation quaternion, its rotation property will then be ignored.

All positions are expressed in the SPS mesh's _local space_.

Please note also that, even a particle is invisible (_isVisible_ set to _false_), its other property values can be updated and _updateParticle()_ is called for every particle whether it is visible or not.

### Pivot

Setting the _pivot_ vector value to a particle applies it as a translation to the particle in its local space. Any rotation is always computed around the local space origin. By default, the particle is translated, then rotated, then translated back to its original location unless you set the particle property _translateFromPivot_ to _true_ (default _false_). In this case, it's simply translated, then rotated and left at the translated location.

In the simple case of 1 dimension let a particle be at positionX with a pivot at pivotX. The center of transformation depends whether _translateFromPivot_ is true or not. When false it is at the point = positionX + pivotX, and when true it is the point = positionX. The distance of the point from the pivot is then pivotX.

<Playground id="#GLZ1PX#11" title="Solid Particle Pivot Example" description="Simple example of adjusting the pivot of a solid particle"/>

Illustration of pivot particle, 1D pivot placement; change data on lines 23 - 25 to see effect.

<Playground id="#LXXL6Y#1" title="Scaled Pivot Example" description="Simple example of scaling a pivot on a solid particle"/>

Pivot particle set in 3D, rotation and scaling applied - 1000 tetrahedron satellites orbiting around 1000 rotating boxes.

### Billboard

When you set your SPS in billboard mode, you should only set a _rotation.z_ value. Putting _SPS.billboard = true_ makes all the particles face the camera and their _x_ and _y_ rotation values will be ignored. This is rather useful if you display only plane particles. However, if you deal only with 2D particles you should consider to use the particle system or one of the various sprite managers which are more performant in 2D computation. In order to display the SPS in billboard mode, you need to call _SPS.setParticles()_ within the scene render loop.

<Playground id="#WCDZS#7" title="Solid Particle Plane Billboard Mode" description="Simple example of solid plane particles in billboard mode."/>

Here is an example with plane particles in billboard mode.

<Playground id="#WCDZS#1" title="Solid Plane Particles Rotating" description="Simple example of solid plane particles rotating"/>

The same but with plane particle rotations and no billboard mode.

<Playground id="#WCDZS#2" title="Solid Box and Tetrahedron Particles Rotating" description="Simple example of solid box and tetrahedron particles rotating"/>

The same with solid particles, boxes and tetrahedrons.

<Playground id="#2FPT1A#9" title="Solid Particles With Colors and Rotations" description="Simple example of solid particles with colors and rotations."/>

Another one with colors and rotations.

### Color

When setting a particle color all vertices of the particle are set to that color and will blend nicely with any material colors if applied.

On creation the vertex colors of the particle are the vertex colors of the model added. When the model has vertices using a range of colors, a box with different face colors for example, these colors are preserved by the particle. However setting the color of a particle will result in a single color for that particle. When the model mesh has no colors the the particle color is set to white.

In _initParticle_ and _updateParticle_ you can use, for example

```javascript
particle.color.r = red; //number from 0 to 1
particle.color.g = green; //number from 0 to 1
particle.color.b = blue; //number from 0 to 1
particle.color.a = alpha; //number from 0 to 1
```

Note: There is another way of setting the initial state of the particles that you will learn about when you read the next page on immutable SPS. This is done by an option property _positionFunction_ when adding a shape. When this method is used particle colors are null and so a new Color4 object must be created to set _particle.color_, following this form

```javascript
particle.color = new BABYLON.Color4(0.25, 0.333, 0.67, 0.88);
```

When you want to set an alpha value, don't forget to enable the alpha channel for vertex colors

```javascript
SPS.mesh.hasVertexAlpha = true;
```

### UVS

On the next page we will look at how SPS can be configured to use multi-materials. For now we just consider the use of one material with one texture. The image file you use should contain all the textures you want to apply to the particles as a texture atlas.

To apply a texture from a region of the image file you specify its lower left (x, y) and upper right (z, w) coordinates as fractions of the whole image in the form of a UV vector4 (x, y, z, w). Taking the lower left coordinates of (0, 0) and the upper left as (1, 1) will apply the whole image as a material. The _uvs_ property of a particle is a vector4 and for the whole image you would use a uv of (0, 0, 1, 1).

When you want apply a smaller region given by lower left (0.2, 0.1) and upper right as (0.6, 0.3) you just set the _uvs_ property like this

```javascript
particle.uvs.x = 0.2; //the coordinate of lower left corner given by 20% of image width
particle.uvs.y = 0.1; //the coordinate of lower left corner given by 10% of image height
particle.uvs.z = 0.6; //the coordinate of upper right corner given by 60% of image width
particle.uvs.w = 0.3; //the coordinate of upper right corner given by 30% of image height
```

![sps.paricle.uv](/img/how_to/Particles/sps2.png)

This can be used both by all the custom functions the _positionFunction_ and _updateParticle()_, whichever you are using. It is most usefult when the image is a texture atlas.

 <Playground id="#GLZ1PX#312" title="Solid Particles With UVs set" description="Simple example of creating solid particles with differing areas of a textrure."/>

Each particle has a different area of the texture set

#### Face Material

When the model mesh you are adding to the SPS is one that is using the [material per face technique](/features/featuresDeepDive/materials/using/texturePerBoxFace) then the correct uv values will be applied automatically when the model is added as a shape. Unlike for the colors, the model UVs are saved whether the model had per face UVs or not. This allows to use not only a texture atlas for the particles, but also a texture atlas for the model then inside the particle atlas because you use only one texture in final.

![Sprite Altlas](/img/how_to/apply-material-to-faces/spriteAtlas2.png)

<Playground id="#GLZ1PX#313" title="Solid Particles With Material Per Face" description="Simple example of creating solid particle copies of a mesh with unique materials per face."/>

Model is a box with per face material, scaling the FaceUVs by 2 groups the 24 individual characters into 6 groups of 4. The particles' material are direct copies of those of the model.

<Playground id="#GLZ1PX#314" title="Solid Particles With Material Per Face With UVs Changed" description="Simple example of creating solid particle copies of a mesh with unique materials per face, but changed UVs."/>

Model is a box with per face material applied as before with a group of four per face. An area of the texture for each face is then chosen using the particles _uvs_, in this case by halving in both the width and height for all particles as in image below.

![Sprite Altlas](/img/how_to/apply-material-to-faces/spriteAtlas3.png)

Transparency

Like for any other mesh, you can also enable the texture transparency with :

```javascript
SPS.mesh.material.diffuseTexture.hasAlpha = true;
```

Or even use the alpha channel of the texture image :

```javascript
SPS.mesh.material.useAlphaFromDiffuseTexture = true;
```

<Playground id="#WCDZS#8" title="Solid Particle Color and UVs Example" description="Simple example of adjusting the color and UVs of a solid particle system."/>

Color and UVs example.

<Playground id="#GLZ1PX#14" title="Solid Particles With Textures and Alpha" description="Simple example of solid particles with textures and alpha."/>

Texture with alpha.

### Parenting

Each particle can be given another particle as a parent. The parent must be created before the current particle, this means the parent has to have a lower index Id (`particle.idx`) than the current particle. So the first particle in the pool (`idx = 0`) cannot have a parent. To give a parent to a particle, just set its property `.parentId` to the parent index Id value.

```javascript
if (particle.idx > 0) {
  particle.parentId = particle.idx - 1; // the previous particle becomes the parent of the current one
}
```

To un-parent a particle, just set `.parentId` back to `null`, the default value.  
When a particle has got a parent, its position and rotation are then expressed in its parent local space.

In the following code the previous particle becomes the parent of the current one. The particle position and rotation are expressed in the previous particle space, this one being already rotated and translated from the yet previous particle. Etc.

```javascript
if (particle.idx > 0) {
  particle.parentId = particle.idx - 1;
  particle.rotation.z = 0.01;
  particle.position.x = 1.0;
}
```

<Playground id="#GLZ1PX#16" title="Box Rotating Around A Parent Box" description="Simple example of a bluish box rotating around its pivot parented to a sliding red box."/>

A bluish box rotating around its pivot parented to a sliding red box.

<Playground id="#GLZ1PX#15" title="Adding A Third Box" description="Simple example of a third box added to the last two, rotating about the previous one"/>

A third box added the last two rotating about the previous one.

<Playground id="#GLZ1PX#17" title="7 Box Parenting Chain" description="Simple example of a chain of 7 boxes each parented to the previous one."/>

A chain of 7 boxes each parented to the previous one.

<Playground id="#V7V1RS" title="Parenting Craziness" description="Simple example of 2000 boxes parented per 20 segment stems."/>  
2000 boxes parented per 20 segment stems.

### Custom Properties

In JavaScript, you can obviously also create your own properties like _acceleration: Vector3_ or _age_, in _initParticles()_ for instance.

```javascript
SPS.initParticles = function () {
  for (let p = 0; p < SPS.nbParticles; p++) {
    particles[p].age = Math.random() * 20;
  }
};
```

Using TypeScript (or JavaScript), you can associate your own properties to each particle with the property _props_ typed _any_ and _null_ by default :

```javascript
particle.props = { myProp1: val1, myProp2: val2 };
```

## Methods

To manage the behavior of particles you use the mandatory method _setParticles_ along with some non mandatory custom functions. The _setParticles_ method is necessary to update and display the mesh built by the SPS.

The non mandatory custom functions

- **_initParticles()_** : lets you set all the initial particle properties. You must iterate over all the particles by using the _SPS.nbParticles_ property.
- **_recycleParticle(particle)_** : lets you set a particle to be recycled. It is called per particle.
- **_updateParticle(particle)_** : lets you set the particle properties. This function is called per particle by _SPS.setParticles()_.
- **_beforeUpdateParticles()_** : lets you make things within the call to _SPS.setParticles()_ just before iterating over all the particles.
- **_afterUpdateParticles()_** : lets you make things within the call to _SPS.setParticles()_ just after the iteration over all the particles is done.

The following pseudo-code schema will show you their application.

```javascript
var particles: SolidParticles[] = [array of SolidParticle objects];
function setParticles() {
    beforeUpdateParticles();
    for (let p = 0; p < nbParticles; p++) {
        updateParticles(particles[p]);
    }
    updateTheWholeMesh();
    afterUpdateParticles();
}
```

When needed you would call _recycleParticle(particle)_ in your own _updateParticle(particle)_ function for instance

```javascript
SPS.updateParticle = function (particle) {
  particle.velocity--;
  if (particle.velocity < 0) {
    particle.alive = false;
    SPS.recycleParticle(particle); // call to your own recycle function
  }
};
```



# Optimize a Solid Particle System
Previously we saw how to use a SPS to optimize a scene containing multiple copies of a model mesh provided the model properties remained fixed. Now we will look at ways of optimizing when the particles are animated.

1. Only update some particles on each render frame;
2. Use the SPS *vars* property to re-use variables and limit garbage collection.

## Restrict the Number of Particles Updated

For any solid particle animation *setParticles()* is called on every render frame. When you have a large big SPS with dozens of thousands particles to improve performance you can restrict the number of particles to update each frame. There are three parameters you can use with *setParticles* to enable you to do this. They are

| parameter | definition                                                                        | default value   |
| --------- | --------------------------------------------------------------------------------- | --------------- |
| start     | _(number)_ the index from where to start to iterate in the `particles` array      | 0               |
| stop      | _(number)_ the index (included) where to stop to iterate in the `particles` array | nbParticles - 1 |
| update    | _(boolean)_ to force the SPS mesh vertex buffer to be updated                     | true            |

If you pass a *stop** value greater than *nbParticles - 1*, the iteration will stop anyway at *nbParticles - 1* to prevent access to undefined elements.

Example 1 : you may want to update your 10K particle mesh only every three frames

- frame 1 : `setParticles(0, 3300, false)` computes everything for particles from 0 to 3300 and doesn't update the mesh.
- frame 2 : `setParticles(3301, 6600, false)` computes everything for particles from 3301 to 6600 and doesn't update the mesh.
- frame 3 : `setParticles(6601, 9999, true)` computes everything for particles from 6601 to 9999 and finally updates the mesh.

10,000 boxes updated per bunch of 3500 here: <Playground id="#2V1C4Z#12" title="10,000 Boxes Updated Per Bunch of 3500" description="Example of optimizing a scene to render 10,000 boxes updated per bunch of 3500."/>

Example 2 : you could keep, say, the first 5000 particles as unused ones and compute the particle behavior only for the last 5000 lasts in your global pool.

### Limit Garbage Collection

In Javascript, the Garbage Collector is usually your friend : it takes care about cleaning up all the not any longer needed variables you could have declared and thus it sets the memory free.  
However, it can sometimes become an awkward friend because it can start its cleaning just while you are displaying a very smooth animation, so it takes the CPU for itself and leaves to you only those nice lags on the screen.  
In order to avoid unpredictable GC pauses, it's best to avoid allocating new objects in loops that execute often, where particles are created or updated.  
For example, *updateParticle()* is often called each frame for each particle or each particle vertex. Now imagine that you have a SPS with 30 000 particles. Suppose you write code like this to add a particle acceleration :

```javascript
SPS.updateParticle = function(particle) {
  const accel = new BABYLON.Vector3(0, 0.5, 0);
  particle.velocity = particle.velocity.add(accel);
  // ...
};
```

Code like the above would create two new `Vector3` objects each call, or 60 000 new objects over the course of the update. And although modern JS engines are quite good at cleaning up short-lived objects, it's best not to unnecessarily strain the GC this way.  
Instead, make your update loops reuse variables that were declared outside the loop, and don't call any methods inside the loop that create new objects:

```javascript
let accel = new BABYLON.Vector3(0, 0.5, 0);
SPS.updateParticle = function(particle) {
  particle.velocity.addInPlace(accel);
  // ...
};
```

SPS also has a *vars* property, which is an object that you can use to store any variables you want to reuse. Any variables you store there will share the SPS' lifecycle, and get cleaned up when you dispose it:

```javascript
SPS.vars.tempVector = new BABYLON.Vector3(0, 0, 0);
// ...
SPS.dispose(); // cleans explicitly all your SPS.vars !
```

A good JS practice for the compiler is to **never** change the variable type once it has been set :

```javascript
SPS.vars.myFloat = 0.01; // just keep setting float values to myFloat afterwards
SPS.vars.myInt = 5; // just keep setting integer values to myInt afterwards
SPS.vars.myString = "foo"; // just keep setting string values to myString afterwards
```

Here is an implementation of a simple particle IA called "flocking" what a behavior of association, then cohesion and separation. This example uses *SPS.vars* to allocate the memory used for results only once instead of in-function temporary variables.  
 <Playground id="#2FPT1A#35" title="Solid Particle System Optimization" description="Simple example of a flocking behavior in an optimized solid particle system."/>


## Pickable Particles

You can set your particles as pickable with the parameter `isPickable` (default _false_) when creating your SPS :

```javascript
var SPS = new BABYLON.SolidParticleSystem("SPS", scene, { isPickable: true });
```

This will set the underlying mesh as pickable and populate two arrays called `SPS.pickedParticles` and `SPS.pickebBySubMesh`. So, don't set your SPS as pickable if you don't need it to be, this will save much memory.  
In order to retrieve the particle picking data from these arrays, use the method `SPS.pickedParticle(pickingInfo)` that returns an object with these properties :

- `idx` : the picked particle idx
- `faceId` : the face index of the picked particle (counted within this particle)

Example :

```javascript
var SPS = new BABYLON.SolidParticleSystem("SPS", scene, { isPickable: true });
// add shapes, build the mesh, init particles, etc
SPS.setParticles(); // initial SPS draw
SPS.refreshVisibleSize(); // force the BBox recomputation
scene.onPointerDown = function(evt, pickResult) {
  var meshFaceId = pickResult.faceId; // get the mesh picked face
  if (meshFaceId == -1) {
    return;
  } // return if nothing picked
  var picked = SPS.pickedParticle(pickResult); // get the picked particle data : idx and faceId
  var idx = picked.idx;                         
  var p = SPS.particles[idx];                   // get the actual picked particle
  p.color.r = 1; // turn it red
  p.color.b = 0;
  p.color.g = 0;
  p.velocity.y = -1; // drop it
  SPS.setParticles();
};
```

The SPS pickability is directly related to the size of its bounding box (please read 'SPS Visibility' part). So, in order to make sure your particles will be pickable, don't forget to force, at least once, the bounding box size recomputation once the particles are set in the space with `setParticles()`.  
Pickable particle example (no SPS update in the render loop): <Playground id="#2FPT1A#352" title="Pickable Solid Particles Example" description="Simple example showing how to make solid particles pickable."/>
Pickable particle example (particle rotation): <Playground id="#2FPT1A#351" title="Pickable Solid Particles That Rotate" description="Simple example of picking solid particles that then rotate in the render loop."/>



# Solid Particle Animation

To animate the particles you need to reset and draw them on each render cycle, for example with

```javascript
scene.onBeforeRenderObservable.add(() => {
    SPS.setParticles();
})
```

As said previously all behaviors of solid particles have to be implemented by yourself. This includes using a billboard mode. You set this using

```javascript
SPS.billboard = true; //false by default
```
The required rotation for the mesh to face the camera has to be calculated each render frame so the above render loop needs to be added.

Billboard set to true, comment line 35 for false: <Playground id="#GLZ1PX#6" title="Solid Particle Billboards" description="Simple example of solid particle billboards"/>

To achieve an animation of solid particles their properties have to be updated render frame by render frame. To do this you need to code a custom *myUpdateParticle(particle)*. You can then set 

```javascript
SPS.updateParticle = myUpdateParticle
```

This is sufficient since *setParticles* calls *updateParticle*.

Let's make some tetrahedrons bounce up and down. We just use a cos function to produce varying heights.

```javascript
let y = h * (1 + Math.cos(angle))
```

will give y from 0 to 2h as the angle varies.

Bouncing tetrahedrons: <Playground id="#GLZ1PX#7" title="Bouncing Tetrahedrons" description="Simple example of bouncing tetrahedrons."/>
Bouncing tetrahedrons SPS mesh rotating: <Playground id="#GLZ1PX#8" title="Bouncing Tetrahedrons With Meshes Rotating" description="Simple example of bouncing tetrahedrons with meshes rotating."/>

Another very useful custom function to create is *recycle(particle)* and call this from *updateParticle* on some condition, for example

```javascript
const updateParticle = (particle) => {
    if (particle condition) {
        recycleParticle(particle)
    }
    doUpdate(particle);
}
```

A fountain of recycled tetrahedra: <Playground id="#GLZ1PX#9" title="A Fountain Of Recycled Tetrahedra" description="Simple example of a fountain of recycled tetrahedra."/>

Before moving on much further it is time to pull together in one place all the features of managing the SPS and its particles.


## Digest a Mesh

There is another way than adding shapes of meshes used as models to populate the SPS : you can directly "digest" a mesh.  
To digest a mesh means that the SPS will decompose this mesh geometry and use all its facets to generate the particles. So, by default, a digested mesh generates as many particles as the mesh number of facets.

```javascript
var model = BABYLON.MeshBuilder.CreateTorusKnot(
  "s",
  { radius: 20, tube: 6, tubularSegments: 64, radialSegments: 128 },
  scene
);
SPS.digest(model);
model.dispose();
SPS.buildMesh();
```

Note that in this case, all the generated particles have their property "position" set with some values and no more to (0, 0, 0).  
This method is obviously compatible with `addShape()` and you can even call it several times with the same model, or different models, in the same SPS.

```javascript
var model = BABYLON.MeshBuilder.CreateTorusKnot(
  "s",
  { radius: 20, tube: 6, tubularSegments: 64, radialSegments: 128 },
  scene
);
SPS.addShape(boxModel, 50);
SPS.digest(model);
SPS.addShape(sphereModel, 20);
SPS.digest(model, { number: 10 });
model.dispose();
sphereModel.dispose();
boxModel.dispose();
SPS.buildMesh();
```

This method accepts three optional parameters : `facetNb`, `delta` and `number`

- `facetNb` is the number of the mesh facets required to build each particle. By default, the value is set to 1, this means each particle will just be a triangle (a mesh facet). Set to 2 and you'll probably get quads instead.  
  The number of generated particles depends then on the mesh initial number of facets and on the `faceNb` value.  
  This parameter is overriden if the parameter `number` is set.
- `delta` (default 0), used with `facetNb`, allows to generate each particle with a random size between _facetNb_ and _facetNb + delta_ facets.
- `number` is the wanted number of particles. `digest()` divides then the mesh into `number` particles of the same size in term of the number of facets used per particle.  
  If `number` is greater than the total number of mesh facets, then this total number is used for the value of `number`.

```javascript
var model = BABYLON.MeshBuilder.CreateTorusKnot(
  "s",
  { radius: 20, tube: 6, tubularSegments: 64, radialSegments: 128 },
  scene
);
SPS.digest(model, { facetNb: 10 }); // 10 facets per particle whatever their final number
SPS.digest(model, { number: 200 }); // 200 particles whatever their final size
SPS.digest(model, { facetNb: 10, delta: 30 }); // between 10 and 40 facets per particle, randomly, whatever their final number
model.dispose();
SPS.buildMesh();
```

Example (click on the torus knot): <Playground id="#HDHQN" title="Solid Particle From Mesh Facets Example" description="Simple example of solid particles from mesh facets (click on the torus knot)"/>


# An Introduction to The Solid Particle System

The Solid Particle System, SPS, is a single updatable mesh rendered with one draw call. It is built by combining multiple copies of one or more model meshes which become the particles of the system. Once the SPS is built, it has the same properties as any other Babylon.js mesh - no more, no less. It can be scaled, rotated, translated, lit, textured, etc.

As a system of particles, it provides some methods to manage the particles. However, unlike the standard particle system, it provides no built-in behaviors. It has no emitters, no particle physics, no particle recycler nor particle movement. You have to implement your own behaviors. 

Once you have a mesh model, or models, as a basis for the particles you follow these steps

- First, create your SPS with `new SolidParticleSystem(name, scene)`;
- then, add a number of particles to the SPS from a mesh model with `addShape(model, number)`;
- redo this as many times as needed with any model;
- When done, build the SPS mesh with `buildMesh()`.

Your SPS is then ready to manage its particles by 

- initiating their positions, colors etc. with `initParticles()`;
- update the SPS and draw it with `setParticles()`.

When you want to animate the particles by changing their properties over time you need to
- define their individual behavior with`updateParticle(particle)`;
- call `setParticles()` within the render loop.

Let's create an example

```javascript
const SPS = new SolidParticleSystem("SPS", scene); // scene is required
const sphere = BABYLON.MeshBuilder.CreateSphere("s", {});
const poly = BABYLON.MeshBuilder.CreatePolyhedron("p", { type: 2 }, scene);
SPS.addShape(sphere, 20); // 20 spheres
SPS.addShape(poly, 120); // 120 polyhedrons
SPS.addShape(sphere, 80); // 80 other spheres
sphere.dispose(); //free memory
poly.dispose(); //free memory

const mesh = SPS.buildMesh(); // finally builds and displays the SPS mesh
```
At this stage, all the particles are displayed at the origin. So to separate them, we need to initiate some properties. Access to the individual particles is through the *particles array*, and the length of which is given by *nbParticles*.

We setup the function to initiate the particles

```javascript
// initiate particles function
SPS.initParticles = () => {
    for (let p = 0; p < SPS.nbParticles; p++) {
        const particle = SPS.particles[p];
        //Place particles at random positions with a cube
      	particle.position.x = BABYLON.Scalar.RandomRange(-50, 50);
        particle.position.y = BABYLON.Scalar.RandomRange(-50, 50);
        particle.position.z = BABYLON.Scalar.RandomRange(-50, 50);
    }
};
```

then call it to apply the initiation, followed by *setParticles* to actually reconfigure the SPS mesh geometry and vertex data

```javascript
//Update SPS mesh
SPS.initParticles();
SPS.setParticles();
```

A basic SPS: <Playground id="#GLZ1PX#1" title="A Basic Solid Particle System" description="Simple example of a basic solid particle system."/>
Colored Green: <Playground id="#GLZ1PX#2" title="Green Colored Solid Particle System" description="Simple example of a green colored solid particle system."/>
With Texture: <Playground id="#GLZ1PX#3" title="Solid Particle System With Textures" description="Simple example of a solid particle system with textures."/>

As well as position you can also set properties such as color or uv values. More on managing particles later in this section

Color individual particles: <Playground id="#GLZ1PX#4" title="Individually Colored Solid Particles" description="Simple example of individually colored solid particles."/>
Texture individual particles: <Playground id="#GLZ1PX#5" title="Individually Textured Solid Particles" description="Simple example of individually textured solid particles"/>

While it can be useful to have an SPS that will not change, for example to represent an asteroid field or city buildings

![Immutable](/img/how_to/Particles/sps1.png)  

there is much more you can do with an SPS.



## Different Materials

The SPS renders all the particles in a single draw call because you've used only one material, or none what means a default material under the hood, so far.  
Sometimes yet, you may want to use several materials in order to render some glowing particles with the glow layer, some others with a bump texture and some others with a colored standard material for instance. In this case, you may accept that the draw call number is higher but you wish it keeps at its possible minimum.  
The SPS supports the MultiMaterials and provides a mechanism to keep the draw call number to a minimum value. You can use them by different ways.

### Simple way

The simplest way to set different materials to the particles is to set a different material to each model used to create the particles and to ask the SPS to use these materials at construction time with the optional paramater `useModelMaterial` set to `true` (default `false`).

```javascript
// model1, model2 and model3 are meshes with already set materials at this step
var sps = new BABYLON.SolidParticleSystem("sps", scene, {
  useModelMaterial: true
});
sps.addShape(model1, 300);
sps.addShape(model2, 300);
sps.addShape(model3, 300);
sps.buildMesh();
```

This enables the multimaterial support, then copies the model geometries and creates automatically the SPS multimaterial from the model materials, with the following rule :

- if several models share the same material, this material is used only once in the SPS : particles are sorted in this purpose to minimize the draw call numbers,
- if a model has no material, a standard material is created,
- if another following model has also no material, the first rule applies : the newly created standard material is shared among the particles depicting all the models with no material.  
  Example: <Playground id="#RCUHJA" title="Materials In SPS" description="Simple example of applying materials to solid particles."/>

You can obviously notice that this method associates the model materials to the particles on the particle shape basis : all the particles of a given shape share the same material.  
You can still change this behavior by assignig some materials on the particle basis by setting the particle property `.materialIndex` value to the wanted material index. The material index is simply the index of the shape material in the order the shape are created : 0 for the first shape, 1 for the second one, and so on. If set, it overwrites the assigned shape material index.  
This can be done at creation time in a `positionFunction` of an immutable SPS for instance.

```javascript
var initParticle = function(particle, i) {
  particle.position.x = areaSize * (Math.random() - 0.5);
  particle.position.y = areaSize * (Math.random() - 0.5);
  particle.position.z = areaSize * (Math.random() - 0.5);
  // above a given altitude, it's given the material 1
  // whatever the initial shape material
  if (particle.position.y > areaSize * 0.1) {
    particle.materialIndex = 1;
  }
};
var sps = new BABYLON.SolidParticleSystem("sps", scene, {
  useModelMaterial: true,
  updatable: false
});
sps.addShape(model1, 300, { positionFunction: initFunction });
sps.addShape(model2, 300, { positionFunction: initFunction });
sps.addShape(model3, 300, { positionFunction: initFunction });
sps.buildMesh();
```

Example: <Playground id="#RCUHJA#2" title="Solid Particle Material Assignment" description="Simple example of assigning materials to solid particles."/>

This method can be used to build non-updatable meshes with MultiMaterials by assembling shapes of different materials even when knowing nothing about indices nor vertices as it's required to define a MultiMaterial object by hands : https://doc.babylonjs.com/how_to/multi_materials

### Intermediate way

When you set the SPS `useModelMaterial` property to `true`, this enables the support for MultiMaterial.  
You can also enable this support by just setting the property `enableMultiMaterial` to `true`.  
In this case, the difference is that the support is enabled but the model materials aren't copied at construction time.

You may want then to use your own set of materials instead of the model ones.
So, whatever the SPS is immutable or not and whatever you're using `enableMultiMaterial` or `useModelMaterial`, you can pass your own materials to the SPS once it's build with the method `sps.setMultiMaterials(arrayOfMaterials)`.

```javascript
var sps = new BABYLON.SolidParticleSystem("sps", scene, {
  enableMultiMaterial: true,
  updatable: false
});
sps.addShape(model1, 300, { positionFunction: initFunction });
sps.addShape(model2, 300, { positionFunction: initFunction });
sps.addShape(model3, 300, { positionFunction: initFunction });
sps.buildMesh();

// mat0, mat1, mat2 are Material objects
sps.setMultiMaterial([mat0, mat1, mat2]);

// ... later in the code, swap mat0 and mat1
sps.setMultiMaterial([mat1, mat0, mat2]);
```

This method can be called as many times as needed once the SPS mesh is built.  
It recomputes the underlying MultiMaterial object and the SPS geometry in order to group the particles by materials, so it's probably not a good idea to call it each frame in the render loop.  
Example: <Playground id="#RCUHJA#3" title="Intermediate Solid Particle Material Assignment" description="Intermediate example of assigning materials to solid particles."/>

### Advanced way

Until now, you've essentially set the particle `materialIndex` values at construction time and they haven't changed then, only the materials themselves have changed.  
You can still change the particle `materialIndex` values at any time, for instance in a call to `sps.updateParticle()` from `sps.setParticles()` like you would do to change the particle positions or rotations, or in a call to any other function of your own at some moment.  
The difference with the other particle properties (positon, rotation, etc) is that `setParticles()` doesn't compute the materials at all.  
Indeed `setParticles()` is designed to be called each frame in the render loop and to make sure to keep the garbage collector activity to its minimum by allocating nothing.  
Applying the changes of `materialIndex` values requires to sort again all the particles, to recompute the whole SPS geometry and moreover to recreate new SubMesh objects from the SPS mesh.  
Therefore a dedicated method is provided `sps.computeSubMeshes()`. This method is to be called manually after each change of particle `materialIndex` values for them to be taken in account at once.  
Like `setMultiMaterials()`, it's probably not a good idea to call it each frame in the render loop.

```javascript
// updatable SPS creation
var sps = new BABYLON.SolidParticleSystem("sps", scene, {
  enableMultiMaterial: true
});
sps.addShape(model1, 300);
sps.addShape(model2, 300);
sps.addShape(model3, 300);
sps.buildMesh();

// mat0, mat1, mat2 are Material objects
sps.setMultiMaterial([mat0, mat1, mat2]);

// the particle materialIndex are set in the call to updateParticle
// while the mesh and the multimaterial are already built
sps.updateParticle = initFunction;
sps.setParticles(); // updates the particle positions
sps.computeSubMeshes(); // actually computes the submeshes and materials
```

Examples: <Playground id="#RCUHJA#4" title="Advanced Solid Particle Material Assignment 1" description="Advanced example of assigning materials to solid particles."/>
In this second example the particles above a given altitude are given the next material in turn every 15 frames. <Playground id="#RCUHJA#7" title="Advanced Solid Particle Material Assignment 2" description="Advanced example of assigning materials to solid particles where the particles above a given altitude are given the next material in turn every 15 frames."/>

If you still really want to call `computeSubMeshes()` each time you call `setParticles()` because your particle materials are updated at this same frequency, you can then set the property `sps.autoUpdateSubMeshes` to `true` (default `false`). In this case, no more need for calling `sps.computeSubMeshes()` by hands as `setParticles()` will do it for you internally.

```javascript
sps.autoUpdateSubMeshes = true;
sps.setParticles(); // updates the particle material indexes AND recomputes the subMeshes
```

Example: <Playground id="#RCUHJA#8" title="Advanced Solid Particle Material Assignment 3" description="Advanced example of material assignment to solid particles with computeSubMeshes()."/>

In the case you want to make your own MultiMaterial object by hands, then set it to the SPS mesh material property and call `sps.computeSubMeshes()` to internally build the needed SubMesh objects.

```javascript
var multimat = new BABYLON.MultiMaterial("multi", scene);
multimat.subMaterials.push(material0);
multimat.subMaterials.push(material1);
multimat.subMaterials.push(material2);

sps.mesh.material = multimat;
sps.computeSubMeshes();
```

**Note 1 :** By default, the particle `materialIndex` value is `null`.  
When enabling the MultiMaterial in the SPS, this value is set to zero for every particle until it's overwritten by the user or automatically set to some model material index by `useModelMaterial`.  
**Note 2 :** The particle depth sort doesn't work with the MultiMaterial support because particles can't be sorted by their distances to the camera and by materials in the same time. So if you enable both modes, it won't crash but it will get to some weird visible results.  
**Note 3 :** The SPS MultiMaterial support works also with an expandable SPS, meaning you can add/store/remove particles with different materials. When calling `sps.buildMesh()` again, everything is then recomputed automatically.

## Solid Particle Systems and Node Materials
As was mentioned above, setting `useModelMaterial` to true on the SPS constructor will allow the material assigned to an added mesh to be used with the SPS mesh's `multimaterial`. This material can be any type of material defined in the engine, including a node material. Using a node material can give added flexibility to the SPS mesh as it can be authored to work in concert with the `initParticles` and `updateParticle` methods to create a striking render. 

![Example of node material on SPS showing a series of spheres emitted into a cylindrical area with varying metallic values, random roughness values and colors that range from blue and yellow-orange at the top to purple and red at the bottom](/img/how_to/Particles/sps_nme_render.jpg)

This render shows a solid particle system using a node material employing `PBRMetallicRoughness` nodes, random metallic and roughness values, world postion-based base color gradients, and randomized color pairings. Normally, setting `useModelMaterial` in the SPS constructor is all that is needed but there are a couple of considerations to keep in mind. 

- Cleaning up the scene memory by deleting the original mesh added to the SPS is fine, but leaving the original node material in the scene is important. With the node material available, changes can be made to the material's uniforms to update the node material in real time which will be reflected in the SPS Mesh.
- If the SPS Mesh is taking advantage of `particle.color` [the property is a nullable Color4](/typedoc/classes/BABYLON.SolidParticle#color), but can be assigned a `Color3` in code. Node material will be able to access `particle.color` using the mesh color `InputBlock`, but it is important to understand what class, `Color3` or `Color4`, was assigned in code. If the property was assigned a `Color3`, then the `InputBlock` needs to be connected to a `ColorSplitterBlock` and the `Color3` output should be used for calculations. If connecting the `Color4` output to another block is attempted, the type mismatch will cause an unexpected conflict due to the missing channel that will likely result in nothing rendering. Matching the declaration of `particle.color` to the component channels used in the node graph will ensure the node material renders correctly.
- Not all node material blocks will work with an SPS mesh. For example, SPS meshes do not contain bones or morph targets so those blocks will not add any benefit to the node material. 
- Performance is something that needs to be front of mind when using node materials with SPS meshes. It is easy to create an SPS mesh that is very dense depending on the complexity of the original mesh and the number of particles in the SPS mesh. If a node material added to the SPS mesh is doing a lot of calculations per vertex or per pixel on a dense SPS mesh, a drop in frame rate would be expected. Balance is needed if doing something like vertex displacement on an SPS mesh to ensure that the mesh is not too dense either with too many vertices in the original mesh or too many particles added to the SPS mesh.

### SPS and Node Material example
The render above is from the following example which leverages the `particle.color` to randomize PBR parameters while also using world position to drive the color blend of the particles. The `particle.color` could have easily been used as the base color input of the `PBRMetallicRoughnessBlock` or even to combine with a color uniform in the graph, but instead it is leveraged to help us get more contrast in the material by providing up to four random values to work with. 

In this case the `particle.color` value is using the red channel to randomly choose between a blue-purple gradient and an orange-red gradient for the particle color. The green channel is used directly as the roughness value allowing every particle to have a different roughness value. And the blue channel is used with a step node to assign either 0.0 or 1.0 to the metallic factor of the particle so some are metallic and others are dielectric. A fourth value could have been added though the alpha channel if the `particle.color` had been defined as a `Color4`. 

The other calculation that is being done is a normalized world position on each particle to drive the interpolation between the two colors of either gradient. This results in the particles slowly changing colors as they move along the Y-axis. This is a simple example, but is a good launching point to illustrate how leveraging node materials with SPS meshes is a powerful technique available in Babylon.js.

<Playground id="#6LAAR2" title="Combining SPS with Node Material" description="A demonstration of how to leverage a node material with a solid particle system mesh" isMain={true} category="Particles"/>



## Particle Intersections

The SPS is physics agnostic. This means you need to implement your own particle behavior if you want to animate them.  
For this, you may need to check if the solid particles intersect or not other ones or other meshes in the scene. Example : you would know if your particles collide against an obstacle and then make them bounce back.  
The SPS provides a simple way to deal with particle intersections. As this feature consumes more memory and CPU, it's disabled by default.  
Enable it explicitly with the parameter `particleIntersection` when creating your SPS :

```javascript
var SPS = new SolidParticleSystem("sps", scene, { particleIntersection: true });
```

Then you can simply call the method `intersectsMesh(<SolidParticle | AbstractMesh>target)` of any solid particle to check if this particle intersects the _target_.  
It just will return true or false if the particle intersects or not the target.

```javascript
// for instance, in your SPS.updateParticle(p) function : particle / particle
if (p.intersectsMesh(otherParticle)) { // change p velocity vector }
```

You can pass the method `intersectsMesh()` either a solid particle object, either a standard BJS mesh. Both work the same.

```javascript
// for instance, in your SPS.updateParticle(p) function : particle / mesh
if (p.intersectsMesh(anyMesh)) { // change p velocity vector }
```

Beware that invisible solid particles can still intersect, exactly like meshes do. So it's up to you to test the particle visibility (`isVisible`), if you want to exclude it from an intersection computation.

If you prefer, you can even use the `AbstractMesh` method `intersectsMesh()` and pass it a solid particle.

```javascript
// for instance, in your SPS.updateParticle(p) function : mesh / particle
if (someMesh.intersectsMesh(p)) { // change p velocity vector }
```

Under the hood, when creating a SPS with `particleIntersection`, a bounding box and a bouding sphere are given to each solid particle.  
For performance reasons, the particle intersections are always computed the fastest way, it is to say with Axis Aligned Bounding Boxes (AABB). [More Details on Intersection Collisions](/features/featuresDeepDive/mesh/interactions/mesh_intersect)

If you use the `AbstractMesh` `intersectsMesh()` method, what allows to force OBB computation (precise mode), only the mesh bounding box will be rotated, not the particle one, so the intersection detection will be just a bit better than in AABB mode.  
The precise mode has a CPU significant cost, so it's not recommended to use it with solid particles.

```javascript
// for instance, in your SPS.updateParticle(p) function : precise mode, mesh / particle
if (someMesh.intersectsMesh(p, true)) { // change p velocity vector }
```

Example: <Playground id="#10RCC9" title="Physics and Solid Particles Example 1" description="Simple example of adding physics to solid particles."/>

For a SPS having thousands of particles, computing the bounding box for each particle each frame is still a heavy CPU operation. So, if you need more performance and if you don't mind about the intersection accurary, you may choose to limit the computation to the particle bounding sphere only (a bounding box requires 8 iterations per particle, one for each box vertex) by using the optional boolean parameter `boundingSphereOnly` (default _false_) at SPS creation.

```javascript
var SPS = new SolidParticleSystem("sps", scene, {
    particleIntersection: true,
    boundingSphereOnly: true,
});
```

Example: <Playground id="#2BXZC#2" title="Physics and Solid Particles Example 2" description="Simple example of adding physics to solid particles."/>

As you may know, a mesh -so a solid particle- is inside its bounding box and its bounding box is inside its bounding sphere. So the bounding sphere is bigger than the bounding box, what is bigger than the mesh.  
If your particles look like some some tiny spherical objects and if you use the `boundingSphereOnly` mode, you would probably like to tweak the bounding sphere to make it closer to the embedded particle.  
You can then use the parameter `bSphereRadiusFactor`, a float number that is multiplied by the current bounding sphere radius.  
Imagine that your particle is a spherical shape with a radius of R. Its bounding sphere radius is then by default : R \* sqrt(3). So if you multiply the bounding sphere radius by 1 / sqrt(3), the bounding sphere will get the same radius than the particle one and both will exactly match.

```javascript
var SPS = new SolidParticleSystem("sps", scene, {
    particleIntersection: true,
    boundingSphereOnly: true,
    bSphereRadiusFactor: 1 / Math.sqrt(3),
});
```

Example: <Playground id="#29F0EG#2" title="Physics and Solid Particles Example 3" description="Simple example of adding physics to solid particles."/>

At last, in case you are using the `boundingSphereOnly` mode, just remember that the particle bounding box isn't computed, only its bouding sphere, so don't test the intersection from a **mesh** object :

```javascript
// boundingSphereOnly case :
mesh.intersectsMesh(particle); // won't give the right result
particle.intersectsMesh(mesh); // will give the right bounding sphere intersection
```



# Transparency Concerns

As you know, the SPS is a standard mesh.

Applying the transparency to a standard mesh leads to well-known issues, not when visualizing other opaque or transparent meshes through this current transparent mesh, but when visualizing some parts of this transparent mesh through itself.  
Indeed, when passing the mesh geometry to the GPU, this one draws the mesh in the order the mesh facets are sorted in the `indices` array : first triangle, second one then, etc ... whatever the position of the camera.  
The shader only respects the geometry order and this geometry is fixed.

As the SPS is a standard mesh, it has the same issue when dealing with transparent particles (rotate the camera): <Playground id="#EPBTB7#3" title="Understanding SPS Transparency Issues" description="Simple example showing common transparency issues with solid particles."/>

A parameter allows you to sort the internal mesh geometry live according to the current camera position: <Playground id="#EPBTB7#2" title="Sorting Mesh Geometry Based On Camera" description="Simple example of dealing with sorting issues live, based on the camera position."/>

It sorts the SPS particles only, not all the facets, for performance reasons.

To enable it, just create your SPS with the parameter `enableDepthSort` to `true`. By default, each next call to `setParticles()` will then sort the particles according to the camera global position.

If for some reasons (immobile camera and sps), you want to stop (or reactivate) the sort on the next calls to `setParticles()`, just set the property `sps.depthSortParticles` to `false` (or `true` to reactivate it) .

Note well that is better to not enable the particle depth sort and the [facet depth sort](/features/featuresDeepDive/mesh/facetData#facet-depth-sort) in the same time, else the sort process wil be executed twice with no final gain.  
So just choose what kind of sorting you need : at particle level (faster) or at facet level (more accurate).

Note also that the particle sort **can't work** with the MultiMaterials.

```javascript
// create a particle depth sort enabled SPS
var sps = new BABYLON.SolidParticleSystem("sps", scene, {
  enableDepthSort: true
});

// then later, only do ...
sps.setParticles(); // and the particle are depth sorted each call

// We can skip the sorting at any time (or reactive it) : sps and camera not moving anymore
sps.depthSortParticles = false; // true by default when enableDepthSort is set to true
```

**Notes :**

- This feature is CPU intensive, so call `setParticles()` with `depthSortParticles` set to true only when needed.
- This feature requires the SPS to be updatable, so it can't work with an immutable SPS.
- This features needs to sort all the particles from the pool, so it won't lead to weird results if you call `setParticles(start, end)` on some particles only.


# Update a Particle's Shape

- `SPS.updateParticleVertex()` _usage_ :  
  It happens before particle scaling, rotation and translation and it allows to update the vertex coordinates, color and UV of each particle.  
  This function will be called for each vertex of each particle and it will be passed the current particle, the current vertex and its current index in the particle shape.  
  The vertex is a SolidParticleVertex object, so you can access or set its properties :
  ```javascript
  vertex.position: Vector3 (x, y, z)
  vertex.color: Color4 (r, g, b, a)
  vertex.uv: Vector2 (x, y)
  ```

```javascript
SPS.computeParticleVertex = true; // false by default for performance reason
SPS.updateParticleVertex = function(particle, vertex, v) {
  // particle : the current particle object
  // vertex : the current vertex, a solidParticleVertex object
  // the index of the current vertex in the particle shape
  // example :
  if (particle.shapeID == 1) {
    vertex.position.x *= Math.random() + 1;
    vertex.position.y *= Math.random() + 1;
    vertex.position.z *= Math.random() + 1;
    vertex.color.r = Math.abs(Math.sin(v));
    vertex.color.g = 1 - vertex.color.r
    vertex.uv.x = particle.idx + v;
    vertex.uv.y = vertex.uv.x;
  }

};
```

Note well that this vertex update is not stored (the particle shape isn't modified) but just computed in the next call to `setParticles()`. So there is no value accumulation : the vertex coordinates, colors or UVs are always the initial ones when entering this function.  
Note also that the shape reference for each particle is the original shape of the mesh model you passed in `addShape()`, even if you had passed also a custom `vertexFunction` (see in the part : "Going furhter in immutable SPS").  
The good news is that the very same function can be use for `SPS.updateParticleVertex` and for the custom `vertexFunction` expected by `addShape()`.  
So to better understand how it works, here is another global pseudo-code schema :

```javascript
var particles: SolidParticles[] = [array of SolidParticle objects];
function setParticles() {
    beforeUpdateParticles();                 // your custom function
    for (let p = 0; p < nbParticles; p++) {
      var particle = particles[p];
      updateParticles(particle);             // your custom position function
      for(let v = 0; particle.vertices.length; v++) {
        var vertex = particle.vertices[v];
        updateParticleVertex(particle, vertex, v);   // your ustom vertex function
        computeAllTheVertexStuff();
      }
    }
    updateTheWholeMesh();                   // does the WebGL work
    afterUpdateParticles();                 // your ustom function
}
```

Example: <Playground id="#1X7SUN#11" title="Updating Solid Particle Geometry" description="Simple example of manipulating solid particle geometry."/>
or dancing glow-worms: <Playground id="#1X7SUN#12" title="Dancing Glow Worm Solid Particles" description="Fun Glow Worm example of changing solid particle geometry."/>


# SPS Visibility

To render the meshes on the screen, BJS uses their bounding box (BBox): if the BBox is in the frustum, then the mesh is selected to be rendered on the screen. This method is really performant as it avoids to make the GPU compute things that wouldn't be visible. The BBox of each mesh is recomputed when its World Martix is updated. This is called **frustum culling**. In the following example image, the green and orange objects are frustum culled.

![Frustum culling](/img/how_to/Particles/frustum-culling.png)

When you create a SPS, unless you use the `positionFunction` at creation time, all its particles are set by default at the position (0, 0, 0). So the bounding box size of the SPS mesh is initially the size of its biggest particle. In the following example image, the size of the entire SPS is taken as just the size of the first red object.

![SPS and bounding box size](/img/how_to/Particles/frustum-culling-2.png)

If you animate your particles without updating the SPS mesh World Matrix, its BBox may keep far more little than the current space occupied by the moving particles. So, if this little BBox gets out of the screen (cam rotation for instance), the whole SPS can then disappear at once! In the following example, once the first red object's bounding box is out of the frustum, the entire SPS mesh will be culled, even through there are still two objects visible by the camera.

![SPS and culling](/img/how_to/Particles/frustum-culling-3.png)

In order to manage the SPS visibility, you have some ways: the methods `SPS.refreshVisibleSize()` or `SPS.setVisibilityBox(size)` and the properties `SPS.isAlwaysVisible`, `SPS.computeBoundingBox`, `SPS.isVisibilityBoxLocked`, and `SPS.autoUpdateSubMeshes`.

- `SPS.refreshVisibleSize()`: updates the SPS mesh BBox size on demand. This is an intensive computation, so it's better not to use it in the render loop each frame. You could call it once the mesh has reached its maximum size for instance. This the method to use if you have a SPS located its in own space somewhere in your scene, like a particle explosion, a fountain, etc. Remember when using this method that it iterates over each mesh vertices. So if your mesh has 20K vertices what is usual with a SPS, it needs 20K iterations.

- `SPS.isAlwaysVisible` (default _false_): if _true_, forces the SPS mesh to be computed by the GPU even if its BBox is not visible. This property is to use when the player evolves inside the SPS (maze, asteroid field) or if the SPS is always bigger than the visible part on the screen. Note that setting it to _true_ doesn't recompute the BBox size, so if you need for some reason (pickability, collisions, etc) to update the BBox, you have to call also at least once `SPS.refreshVisibleSize()`.

- `SPS.computeBoundingBox` (default _false_): if set to true, the next calls to `setParticles()` will compute the mesh bounding box within the same loop as the particle computations.
  The reason `refreshVisibleSize()` and `SPS.computeBoundingBox` exist together is that `refreshVisibleSize()` can be called at any time and doesn't require to call `setParticles()` whereas `SPS.computeBoundingBox` is taken in account for the BBox computation only from a call of `setParticles()`.  
  Note that `SPS.computeBoundingBox` can be set to _true_ or _false_ at any time and will affect only the next calls of `setParticles()`.

- `SPS.setVisibilityBox(size)`: sets a fixed size to the SPS Mesh BBox whatever its own real size. This may be useful when you know in advance the limits that the visible particles won't overrange. Note that setting a value doesn't prevent any further BBox recomputation.

- `SPS.isVisibilityBoxLocked` (default _false_): if _true_, the SPS mesh BBox won't be computed any longer until it is reset to _false_.

- `SPS.autoUpdateSubMeshes` (default _false_): When a SPS contains multiple materials, it creates a SubMesh for each material. When `autoUpdateSubMeshes` is set to _true_, these SubMeshes will be recomputed, along with their bounding boxes, on the next call to `setParticles`.

So what method to use? It depends on your needs.  
If your SPS is ever everywhere around the camera environment like an asteroid field, you may use `SPS.isAlwaysVisible`.  
If you need a variable visibility or the pickability, you'll need to set at least once the bounding box.  
So if your SPS stays within some fixed bounds that you don't know the values, you may use `SPS.refreshVisibleSize()` at least once when the SPS has reached these limits and then lock the visibility box.  
If the SPS keeps within some known limits, then it is better to use `SPS.setVisibilityBox(size)` with the right value and then to lock the visibility box.  
At last, if you still need pickability or variable visibility, and don't know how your SPS will evolve, then you might set `SPS.computeBoundingBox` to true, and `SPS.autoUpdateSubMeshes` if the SPS has multiple materials.

## Particle In Frustum

When the SPS is enabled to manage particle intersections, each particle is given a bounding box and a bouding sphere.  
You can then check whether a particle intersects the camera frustum with the method `particle.isInFrustum(frustumPlanes, [cullingStrategy])` like you would do with meshes.

```javascript
scene.updateTransformMatrix(); // force the plane computation once
var frustumPlanes = scene.frustumPlanes;
// then in some loop ...
if (!particle.isInFrustum(frustumePlanes)) {
  p.alive = false;
}
```

Contrary to the meshes, you can't use `.isInFrustum()` to cull particles that wouldn't be rendered, because all the particles are always rendered, meaning passed to the GPU (even the invisible ones). You can only use this test to customize the process applied to the particles.  
Example: You would want to not compute the particles outside the frustum to gain some performance.  
The test done by `isInFrustum()` has also its own CPU cost, so it's probably not a good idea to run it on thousand particles each frame.  
Actually, it's up to you to choose if the test is worth it for your own need.  
Let's imagine a case where each particle computation is really intensive (example : when using `computeParticleVertex`). In this case, the frustum test could be faster than the particle computation, so it would be interesting to use it to disable the particle computation for particles outside the frustum.  
In this following example, the computation charge is directly related to the number of vertices and shouldn't change whatever the camera direction. But, as we disable the particles outside the frustum, if you rotate the camera to isolate one or two worms in the camera field, you can check the performance gain  
<Playground id="#BKX11Q#2" title="Dealing With Solid Particle Visbility Issues" description="Simple example of how to manage common visibility issues in Solid Particle Systems."/>
Note: the default culling strategy used in the particle frustum test is the fastest (`BoundingSphereOnly`).  
You can change it at will for each particle by using the same values than the static properties `CULLINGSTRATEGY_XXX` ones of the `AbstractMesh` class.



# Solid Particles System

The solid particle system (SPS) creates a cloud of particles from one or more base meshes. The resulting system is itself a single mesh requiring a single draw call per frame and has the same properties as any mesh. However you have to implement the behaviour of individual particles yourself, through the features and properties made available.

![SPS](/img/features/particle1.png)

Individual particles are pickable with a pointer and there are methods to check if two particles are intersecting. Another feature, digest mesh, is to take an existing mesh and turn its triangular facets into particles, allowing a mesh to be 'blown apart' for example.


## Particle System JSON Files
When using the [particle system editor](/toolsAndResources/inspector/particleEditor) there is an option to save the particle system as a local json file that can be loaded and used in any Babylon.js scene. This is useful in sharing particle systems between different scenes as well as updating a particle system quickly. Changing the parameters for a particle system stored locally as a json file allows any scene using that particle system to be updated immediately without the need to manage the snippet ID referenced by any scene.

## Loading the JSON file
The [Asset Manager](/features/featuresDeepDive/importers/assetManager) offers flexibility and power in loading the multiple files needed for particle systems - such as particle textures and particle system JSON files - at once. Simply add a new [TextFileAssetTask](/features/featuresDeepDive/importers/assetManager#textfileassettask) for each particle system file that needs to be loaded.

```javascript
const assetsManager = new BABYLON.AssetsManager(scene);
const particleFile = assetsManager.addTextFileTask("my particle system", "particleSystem.json");

// load all tasks
assetsManager.load();


```
Create a new `TextFileTask` for each particle system that needs to be loaded. The great thing about the Asset Manager is that it will load each file in sequence and then send a callback once all of the loading is done. Since most effects are made up of several particle systems, the Asset Manager will help quickly and efficiently load each file before parsing. 

```javascript
assetsManager.onFinish = function (task) {
    console.log("task successful", task);

    // prepare to parse particle system files
}
```

## Parsing the Text File as JSON
Once the files are loaded as text, they need to be parsed as JSON objects before they can be used. Simply add a `JSON.parse` for each loaded text file.

```javascript
assetsManager.onFinish = function (task) {
    console.log("task successful", task);

    // prepare to parse particle system files
    const particleJSON = JSON.parse(particleFile.text);
}
```

## Using the JSON with BABYLON.ParticleSystem
The final step is to convert the JSON into a `BABYLON.ParticleSystem` using another parse operation. However, this parse operation has several components worth exploring. 

```javascript
const myParticleSystem = BABYLON.ParticleSystem.Parse(json, scene, rootURL, doNotStart, capacity);
```

- **json**: The json file to parse.
- **scene**: The scene or engine within which to create the particle system.
- **rootURL**: The root URL to load dependencies like the particle texture.
- **doNotStart**: Boolean to determine if the particle system should automatically start. This overrides the autostart parameter contained in the particle system JSON.
- **capacity**: The capacity limit of particles for this system. This is the only way to change the capacity of a particle system created from JSON. If this parameter is undefined or null, the capacity parameter in the JSON will be used.

Adding this last step to our Asset Manager completes the loading and creation of our particle system.

```javascript
assetsManager.onFinish = function (task) {
    console.log("task successful", task);

    // prepare to parse particle system files
    const particleJSON = JSON.parse(particleFile.text);
    const myParticleSystem = BABYLON.ParticleSystem.Parse(particleJSON, scene, "", false, 1000);
}
```

live example: <Playground id="#9Y10LR" title="Loading particle system from file" description="Simple example using Asset Manager to load a particle system and texture before parsing it" isMain={true} category="Particles"/>



Solid Particle System

Coming next

An Introduction To The Solid Particle System

Learn the basics of the solid particle system in Babylon.js.

Solid Particle Animation

Learn all about animating solid particles in Babylon.js.

Managing The Solid Particle System

Learn about solid particle system management in Babylon.js.

Managing Solid Particles

Learn how to manage solid particles in Babylon.js.

Solid Particle System Materials

Learn all about solid particle system materials in Babylon.js.

Immutable Solid Particle Systems

Learn how to create immutable solid particle systems in Babylon.js.

Solid Particles From Mesh Facets

Learn how to create solid particles from mesh facets in Babylon.js.

Updating A Solid Particle's Shape

Learn how to change a solid particles shape in Babylon.js.

Picking Solid Particles

Learn how to pick and interact with solid particles in Babylon.js.

Physics and Solid Particles

Learn how to add physics to solid particle systems in Babylon.js.

Optimizing Solid Particle Systems

Learn best practices for optimizing solid particle systems in Babylon.js.

Expanding Solid Particle Systems

Learn how to expand solid particle systems in Babylon.js.

Troubleshooting Solid Particle System Visibility Issues

Learn some troubleshooting tips for dealing with common SPS visibility issues in Babylon.js.

Troubleshooting Solid Particle System Transparency Issues

Learn some troubleshooting tips for dealing with common SPS transparency issues in Babylon.js.