
# 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.


# 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."/>



# 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.
