> Learn how to manage solid particles in Babylon.js.

Source: https://doc.babylonjs.com/features/featuresDeepDive/particles/solid_particle_system/manage_sps_particles

# 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         |

There are also three properties 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 also note that even when 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 one-dimensional case, let a particle be at `positionX` with a pivot at `pivotX`. The center of transformation depends on whether _translateFromPivot_ is true. When false, it is at the point `positionX + pivotX`, and when true, it is at the point `positionX`. The distance of the point from the pivot is then `pivotX`.

- [Playground: Solid Particle Pivot Example](https://playground.babylonjs.com/#GLZ1PX#11) - Simple example of adjusting the pivot of a solid particle

Illustration of a pivot particle with 1D pivot placement; change the data on lines 23 - 25 to see the effect.

- [Playground: Scaled Pivot Example](https://playground.babylonjs.com/#LXXL6Y#1) - Simple example of scaling a pivot on a solid particle

Pivot particle set in 3D, with 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. Setting _SPS.billboard = true_ makes all the particles face the camera, and their _x_ and _y_ rotation values will be ignored. This is useful if you display only plane particles. However, if you work only with 2D particles, you should consider using the particle system or one of the various sprite managers, which are more performant for 2D computation. To display the SPS in billboard mode, you need to call _SPS.setParticles()_ within the scene render loop.

- [Playground: Solid Particle Plane Billboard Mode](https://playground.babylonjs.com/#WCDZS#523) - Simple example of solid plane particles in billboard mode.

Here is an example with plane particles in billboard mode.

- [Playground: Solid Plane Particles Rotating](https://playground.babylonjs.com/#WCDZS#521) - Simple example of solid plane particles rotating

The same but with plane particle rotations and no billboard mode.

- [Playground: Solid Box and Tetrahedron Particles Rotating](https://playground.babylonjs.com/#WCDZS#522) - Simple example of solid box and tetrahedron particles rotating

The same with solid particles, boxes and tetrahedrons.

- [Playground: Solid Particles With Colors and Rotations](https://playground.babylonjs.com/#2FPT1A#9) - Simple example of solid particles with colors and rotations.

Another one with colors and rotations.

### Color

When you set 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 added model. When the model has vertices that use 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 results in a single color for that particle. When the model mesh has no colors, 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 to set the initial state of the particles, which you will learn about on the next page about immutable SPS. This is done by using the _positionFunction_ option property when adding a shape. When this method is used, particle colors are null, 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, do not 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 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 as (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 to 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.particle.uv](https://doc.babylonjs.com/img/how_to/Particles/sps2.webp)

This can be used by either of the custom functions, _positionFunction_ or _updateParticle()_, whichever you are using. It is most useful when the image is a texture atlas.

 - [Playground: Solid Particles With UVs set](https://playground.babylonjs.com/#GLZ1PX#312) - Simple example of creating solid particles with differing areas of a texture.

Each particle has a different area of the texture set.

#### Face Material

When the model mesh you are adding to the SPS uses the [material per face technique](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/texturePerBoxFace), the correct uv values are applied automatically when the model is added as a shape. Unlike colors, the model UVs are preserved whether or not the model had per-face UVs. This lets you use not only a texture atlas for the particles, but also a texture atlas for the model within the particle atlas, because you use only one final texture.

![Sprite Altlas](https://doc.babylonjs.com/img/how_to/apply-material-to-faces/spriteAtlas2.webp)

- [Playground: Solid Particles With Material Per Face](https://playground.babylonjs.com/#GLZ1PX#313) - Simple example of creating solid particle copies of a mesh with unique materials per face.

The 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' materials are direct copies of those of the model.

- [Playground: Solid Particles With Material Per Face With UVs Changed](https://playground.babylonjs.com/#GLZ1PX#314) - Simple example of creating solid particle copies of a mesh with unique materials per face, but changed UVs.

The 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 both the width and height for all particles as in the image below.

![Sprite Altlas](https://doc.babylonjs.com/img/how_to/apply-material-to-faces/spriteAtlas3.webp)

Transparency

Like any other mesh, you can also enable 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: Solid Particle Color and UVs Example](https://playground.babylonjs.com/#WCDZS#520) - Simple example of adjusting the color and UVs of a solid particle system.

Color and UVs example.

- [Playground: Solid Particles With Textures and Alpha](https://playground.babylonjs.com/#GLZ1PX#14) - 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, which means it must 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 a parent, its position and rotation are then expressed in its parent's 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's space, which is already rotated and translated from the particle before it, and so on.

```javascript
if (particle.idx > 0) {
  particle.parentId = particle.idx - 1;
  particle.rotation.z = 0.01;
  particle.position.x = 1.0;
}
```

- [Playground: Box Rotating Around A Parent Box](https://playground.babylonjs.com/#GLZ1PX#16) - 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: Adding A Third Box](https://playground.babylonjs.com/#GLZ1PX#15) - Simple example of a third box added to the last two, rotating about the previous one

A third box is added to the last two, rotating about the previous one.

- [Playground: 7 Box Parenting Chain](https://playground.babylonjs.com/#GLZ1PX#17) - 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: Parenting Craziness](https://playground.babylonjs.com/#V7V1RS) - 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 with each particle through the _props_ property, typed _any_ and set to _null_ by default:

```javascript
particle.props = { myProp1: val1, myProp2: val2 };
```

## Methods

To manage particle behavior, 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 are:

- **_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 shows how they are applied.

```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
  }
};
```
