# Particles

Particle generator optimized to display thousands of instances.

![Particles example](../../../media/examples/particles.png)


## Examples

### Manual generation

```js
import { Particles, Star, Math as M } from "pencil.js";

const count = 5000;
const position = [100, 200];
const base = new Star(undefined, 5, 20);
// Additional parameters after the first one come from the generate method call
const generator = (index, any, additional, params) => {
    // Particles data
    return {
        position: scene.getRandomPosition(),
        rotation: M.random(),
        scale: M.random(0.5, 1.5),
        ttl: 100,
        // And whatever value you want to define for each individual particle, for example
        speed: new Position(1, 0).rotate(M.random()),
    };
};
const updater = (data, index) => {
    data.position.add(data.speed);
};

const particles = new Particles(position, base, generator, updater);
// Any parameters after the first one are passed to the generator function
particles.generate(count, any, additional, params);
```

### Automatic generation

```js
import { Particles, Star, Math as M } from "pencil.js";

const count = 5000;
const position = [100, 200];
const base = new Star(undefined, 5, 20);
// Additional parameters after the first one come from the generate method call
const generator = (index, any, additional, params) => {
    // Particles data
    return {
        position: scene.cursorPosition,
        rotation: M.random(),
        scale: M.random(0.5, 1.5),
        ttl: 100,
        // And whatever value you want to define for each individual particle, for example
        speed: new Position(1, 0).rotate(M.random()),
    };
};
const updater = (data, index) => {
    data.position.add(data.speed);
};

const particles = new Particles(position, base, generator, updater, {
    emit: [10, 20], // Between 10 and 20 particles
    frequency: 0.5, // about every 2 frames
    args: [any, additional, params], // parameters for the generator function
});
```


## ParticlesOptions

Inherit from [ComponentOptions](../component/readme.md#componentoptions).

| Name        | Type                        | Default | Comment                                                                                           |
|-------------|-----------------------------|---------|---------------------------------------------------------------------------------------------------|
| `frequency` | `Number`                    | `1`     | Frequency of emission per frame (randomized, 1 mean every frame, 0.1 mean about 1 each 10 frames) |
| `emit`      | `Number` or `Array<Number>` |         | Number or range of number of particles emitted                                                    |
| `args`      | `Array`                     |         | Arguments passed to the generator function                                                        |


## ParticlesData

`ParticlesData` stores individuals information about each particle.
It supports a limited number of properties.

| Name       | Type                      | Default          | Comment                                                                                                                                                                    |
|------------|---------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `position` | [`Position`](../position) | `new Position()` | Position of the particle                                                                                                                                                   |
| `rotation` | `Number`                  | `0`              | Rotation applied to the particle                                                                                                                                           |
| `scale`    | `Number` or `Array`       | `1`              | Scaling ratio or a pair of value for horizontal and vertical scaling                                                                                                       |
| `ttl`      | `Number`                  | `undefined`      | Time to live, number of frames the particle is displayed. This number will be decremented and the data removed when it reach 0. Any falsy value will prevent this behavior |

The data object can also be used to store any other individual values for each particle.