# ParticleSystemComponent

Class · extends [`Component`](https://api.playcanvas.com/engine/classes/Component.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/components/particle-system/component.js#L137

The ParticleSystemComponent enables an [Entity](https://api.playcanvas.com/engine/classes/Entity.md) to simulate particles and produce a
renderable particle mesh on either CPU or GPU. GPU simulation is generally much faster than
its CPU counterpart, because it avoids slow CPU-GPU synchronization and takes advantage of
many GPU cores. However, it requires client support for reasonable uniform counts, reading
from multiple textures in a vertex shader and the OES_texture_float extension, including
rendering into float textures. Most mobile devices fail to satisfy these requirements, so it's
not recommended to simulate thousands of particles on them. The GPU version also can't sort
particles, so enabling sorting forces CPU mode too.

Particle rotation is specified by a single angle parameter: default billboard particles rotate
around the camera-facing axis, while mesh particles rotate around two different view-independent
axes. Most of the simulation parameters are specified with [Curve](https://api.playcanvas.com/engine/classes/Curve.md) or [CurveSet](https://api.playcanvas.com/engine/classes/CurveSet.md).
Curves are interpolated based on each particle's lifetime, therefore parameters are able to
change over time. Most curve parameters can also be specified by 2 minimum/maximum curves, so
that each particle picks a random value in-between.

You should never need to use the ParticleSystemComponent constructor directly. To add a
ParticleSystemComponent to an [Entity](https://api.playcanvas.com/engine/classes/Entity.md), use [Entity#addComponent](https://api.playcanvas.com/engine/classes/Entity.md#addcomponent):

```javascript
const entity = new Entity();
entity.addComponent('particlesystem', {
    numParticles: 100,
    lifetime: 2,
    rate: 0.1
});
```

Once the ParticleSystemComponent is added to the entity, you can access it via the
[Entity#particlesystem](https://api.playcanvas.com/engine/classes/Entity.md#particlesystem) property:

```javascript
entity.particlesystem.loop = false; // Play the system once then stop

console.log(entity.particlesystem.loop); // Get the loop flag and print it
```

Relevant Engine API examples:

- [Particle Animated Index](https://playcanvas.github.io/#/graphics/particles-anim-index)
- [Particle Mesh](https://playcanvas.github.io/#/graphics/particles-mesh)
- [Particle Random Sprites](https://playcanvas.github.io/#/graphics/particles-random-sprites)
- [Particle Snow](https://playcanvas.github.io/#/graphics/particles-snow)
- [Particle Spark](https://playcanvas.github.io/#/graphics/particles-spark)
- [Particles in a user interface](https://playcanvas.github.io/#/user-interface/particle-system)

## Accessors

### alignToMotion

```ts
get alignToMotion(): boolean
set alignToMotion(arg: boolean)
```

Gets whether particles are oriented in their direction of motion or not.

### alphaGraph

```ts
get alphaGraph(): Curve
set alphaGraph(arg: Curve)
```

Gets the alpha graph.

### alphaGraph2

```ts
get alphaGraph2(): Curve
set alphaGraph2(arg: Curve)
```

Gets the second alpha graph.

### animIndex

```ts
get animIndex(): number
set animIndex(arg: number)
```

Gets the index of the animation to play.

### animLoop

```ts
get animLoop(): boolean
set animLoop(arg: boolean)
```

Gets whether the sprite sheet animation plays once or loops continuously.

### animNumAnimations

```ts
get animNumAnimations(): number
set animNumAnimations(arg: number)
```

Gets the number of sprite sheet animations contained within the current sprite sheet.

### animNumFrames

```ts
get animNumFrames(): number
set animNumFrames(arg: number)
```

Gets the number of sprite sheet frames in the current sprite sheet animation.

### animSpeed

```ts
get animSpeed(): number
set animSpeed(arg: number)
```

Gets the sprite sheet animation speed.

### animStartFrame

```ts
get animStartFrame(): number
set animStartFrame(arg: number)
```

Gets the sprite sheet frame that the animation should begin playing from.

### animTilesX

```ts
get animTilesX(): number
set animTilesX(arg: number)
```

Gets the number of horizontal tiles in the sprite sheet.

### animTilesY

```ts
get animTilesY(): number
set animTilesY(arg: number)
```

Gets the number of vertical tiles in the sprite sheet.

### autoPlay

```ts
get autoPlay(): boolean
set autoPlay(arg: boolean)
```

Gets whether the particle system plays automatically on creation.

### blendType

```ts
get blendType(): number
set blendType(arg: number)
```

Gets how particles are blended when being written to the currently active render target.

### colorGraph

```ts
get colorGraph(): CurveSet
set colorGraph(arg: CurveSet)
```

Gets the color graph.

### colorGraph2

```ts
get colorGraph2(): CurveSet
set colorGraph2(arg: CurveSet)
```

Gets the second color graph.

### colorMap

```ts
get colorMap(): Texture
set colorMap(arg: Texture)
```

Gets the color map texture to apply to all particles in the system.

### colorMapAsset

```ts
get colorMapAsset(): Asset<string> | null
set colorMapAsset(arg: Asset<string> | null)
```

Gets the [Asset](https://api.playcanvas.com/engine/classes/Asset.md) used to set the colorMap.

### depthSoftening

```ts
get depthSoftening(): number
set depthSoftening(arg: number)
```

Gets whether depth softening is enabled.

### depthWrite

```ts
get depthWrite(): boolean
set depthWrite(arg: boolean)
```

Gets whether depth writes is enabled.

### drawOrder

```ts
get drawOrder(): number
set drawOrder(drawOrder: number)
```

Gets the draw order of the component.

### emitterExtents

```ts
get emitterExtents(): Vec3
set emitterExtents(arg: Vec3)
```

Gets the extents of a local space bounding box within which particles are spawned at random
positions.

### emitterExtentsInner

```ts
get emitterExtentsInner(): Vec3
set emitterExtentsInner(arg: Vec3)
```

Gets the exception of extents of a local space bounding box within which particles are not
spawned.

### emitterRadius

```ts
get emitterRadius(): number
set emitterRadius(arg: number)
```

Gets the radius within which particles are spawned at random positions.

### emitterRadiusInner

```ts
get emitterRadiusInner(): number
set emitterRadiusInner(arg: number)
```

Gets the inner radius within which particles are not spawned.

### emitterShape

```ts
get emitterShape(): number
set emitterShape(arg: number)
```

Gets the shape of the emitter.

### halfLambert

```ts
get halfLambert(): boolean
set halfLambert(arg: boolean)
```

Gets whether Half Lambert lighting is enabled.

### initialVelocity

```ts
get initialVelocity(): number
set initialVelocity(arg: number)
```

Gets the magnitude of the initial emitter velocity.

### intensity

```ts
get intensity(): number
set intensity(arg: number)
```

Gets the color multiplier.

### layers

```ts
get layers(): readonly number[]
set layers(arg: readonly number[])
```

Gets the array of layer IDs ([Layer#id](https://api.playcanvas.com/engine/classes/Layer.md#id)) to which this particle system belongs.

### lifetime

```ts
get lifetime(): number
set lifetime(arg: number)
```

Gets the length of time in seconds between a particle's birth and its death.

### lighting

```ts
get lighting(): boolean
set lighting(arg: boolean)
```

Gets whether particles will be lit by ambient and directional lights.

### localSpace

```ts
get localSpace(): boolean
set localSpace(arg: boolean)
```

Gets whether particles move with respect to the emitter's transform rather then world space.

### localVelocityGraph

```ts
get localVelocityGraph(): CurveSet
set localVelocityGraph(arg: CurveSet)
```

Gets the local space velocity graph.

### localVelocityGraph2

```ts
get localVelocityGraph2(): CurveSet
set localVelocityGraph2(arg: CurveSet)
```

Gets the second velocity graph.

### loop

```ts
get loop(): boolean
set loop(arg: boolean)
```

Gets whether the particle system loops.

### mesh

```ts
get mesh(): Mesh
set mesh(arg: Mesh)
```

Gets the polygonal mesh to be used as a particle.

### meshAsset

```ts
get meshAsset(): Asset<string> | null
set meshAsset(arg: Asset<string> | null)
```

Gets the [Asset](https://api.playcanvas.com/engine/classes/Asset.md) used to set the mesh.

### normalMap

```ts
get normalMap(): Texture
set normalMap(arg: Texture)
```

Gets the normal map texture to apply to all particles in the system.

### normalMapAsset

```ts
get normalMapAsset(): Asset<string> | null
set normalMapAsset(arg: Asset<string> | null)
```

Gets the [Asset](https://api.playcanvas.com/engine/classes/Asset.md) used to set the normalMap.

### numParticles

```ts
get numParticles(): number
set numParticles(arg: number)
```

Gets the maximum number of simulated particles.

### orientation

```ts
get orientation(): number
set orientation(arg: number)
```

Gets the particle orientation mode.

### particleNormal

```ts
get particleNormal(): Vec3
set particleNormal(arg: Vec3)
```

Gets the particle normal.

### preWarm

```ts
get preWarm(): boolean
set preWarm(arg: boolean)
```

Gets whether the particle system will be initialized as though it has already completed a
full cycle.

### radialSpeedGraph

```ts
get radialSpeedGraph(): Curve
set radialSpeedGraph(arg: Curve)
```

Gets the radial speed graph.

### radialSpeedGraph2

```ts
get radialSpeedGraph2(): Curve
set radialSpeedGraph2(arg: Curve)
```

Gets the second radial speed graph.

### randomizeAnimIndex

```ts
get randomizeAnimIndex(): boolean
set randomizeAnimIndex(arg: boolean)
```

Gets whether each particle emitted by the system will play a random animation from the
sprite sheet, up to `animNumAnimations`.

### rate

```ts
get rate(): number
set rate(arg: number)
```

Gets the minimal interval in seconds between particle births.

### rate2

```ts
get rate2(): number
set rate2(arg: number)
```

Gets the maximal interval in seconds between particle births.

### renderAsset

```ts
get renderAsset(): Asset<string> | null
set renderAsset(arg: Asset<string> | null)
```

Gets the Render [Asset](https://api.playcanvas.com/engine/classes/Asset.md) used to set the mesh.

### rotationSpeedGraph

```ts
get rotationSpeedGraph(): Curve
set rotationSpeedGraph(arg: Curve)
```

Gets the rotation speed graph.

### rotationSpeedGraph2

```ts
get rotationSpeedGraph2(): Curve
set rotationSpeedGraph2(arg: Curve)
```

Gets the second rotation speed graph.

### scaleGraph

```ts
get scaleGraph(): Curve
set scaleGraph(arg: Curve)
```

Gets the scale graph.

### scaleGraph2

```ts
get scaleGraph2(): Curve
set scaleGraph2(arg: Curve)
```

Gets the second scale graph.

### screenSpace

```ts
get screenSpace(): boolean
set screenSpace(arg: boolean)
```

Gets whether particles are rendered in 2D screen space.

### sort

```ts
get sort(): number
set sort(arg: number)
```

Gets the particle sorting mode.

### startAngle

```ts
get startAngle(): number
set startAngle(arg: number)
```

Gets the minimal initial Euler angle of a particle.

### startAngle2

```ts
get startAngle2(): number
set startAngle2(arg: number)
```

Gets the maximal initial Euler angle of a particle.

### stretch

```ts
get stretch(): number
set stretch(arg: number)
```

Gets how much particles are stretched in their direction of motion.

### useFog

```ts
get useFog(): boolean
set useFog(arg: boolean)
```

Gets whether the camera's fog is applied to the particles.

### useTonemap

```ts
get useTonemap(): boolean
set useTonemap(arg: boolean)
```

Gets whether the camera's tonemapping and the scene exposure are applied to the particles.

### velocityGraph

```ts
get velocityGraph(): CurveSet
set velocityGraph(arg: CurveSet)
```

Gets the world space velocity graph.

### velocityGraph2

```ts
get velocityGraph2(): CurveSet
set velocityGraph2(arg: CurveSet)
```

Gets the second world space velocity graph.

### wrap

```ts
get wrap(): boolean
set wrap(arg: boolean)
```

Gets whether particles wrap based on the set wrap bounds.

### wrapBounds

```ts
get wrapBounds(): Vec3
set wrapBounds(arg: Vec3)
```

Gets the wrap bounds of the particle system.

## Methods

### isPlaying

```ts
isPlaying(): boolean
```

Checks if simulation is in progress.

**Returns** `boolean`: True if the particle system is currently playing and false otherwise.

### pause

```ts
pause(): void
```

Freezes the simulation.

### play

```ts
play(): void
```

Enables/unfreezes the simulation.

### reset

```ts
reset(): void
```

Resets particle state, doesn't affect playing.

### stop

```ts
stop(): void
```

Disables the emission of new particles, lets existing to finish their simulation.

### unpause

```ts
unpause(): void
```

Unfreezes the simulation.

## Inherited from [Component](https://api.playcanvas.com/engine/classes/Component.md)

- `entity: Entity`
- `system: ComponentSystem`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`