API
API|
@babylonjs/core|
ParticleSystem

Class ParticleSystem

This represents a particle system in Babylon. Particles are often small sprites used to simulate hard-to-reproduce phenomena like fire, smoke, water, or abstract visual effects like magic glitter and faery dust. Particles can take different shapes while emitted like box, sphere, cone or you can write your custom function.

https://doc.babylonjs.com/features/featuresDeepDive/particles/particle_system/particle_system_intro

Hierarchy

  • ThinParticleSystem
    • ParticleSystem
Index
constructor
activeSubSystems animations applyFog beginAnimationFrom beginAnimationLoop beginAnimationOnStart beginAnimationTo blendMode clipPlane clipPlane2 clipPlane3 clipPlane4 clipPlane5 clipPlane6 color1 color2 colorDead customShader defaultProjectionMatrix defaultViewMatrix disposeOnStop doNotSerialize emitRate emitter endSpriteCellID flowMapStrength forceDepthWrite gravity id isGPU layerMask limitVelocityDamping manualEmitCount maxAngularSpeed maxEmitPower maxInitialRotation maxLifeTime maxScaleX maxScaleY maxSize metadata minAngularSpeed minEmitPower minInitialRotation minLifeTime minScaleX minScaleY minSize name noiseStrength onAnimationEnd onDisposeObservable onStartedObservable onStoppedObservable particleEmitterType particleTexture paused preventAutoStart preWarmCycles preWarmStepOffset recycleParticle renderingGroupId snippetId spriteCellChangeSpeed spriteCellHeight spriteCellLoop spriteCellWidth spriteRandomStartCell startDelay startSpriteCellID subEmitters textureMask translationPivot uniqueId updateFunction updateInAnimate updateSpeed worldOffset BILLBOARDMODE_ALL BILLBOARDMODE_STRETCHED BILLBOARDMODE_STRETCHED_LOCAL BILLBOARDMODE_Y BLENDMODE_ADD BLENDMODE_MULTIPLY BLENDMODE_MULTIPLYADD BLENDMODE_ONEONE BLENDMODE_STANDARD BLENDMODE_SUBTRACT ForceGLSL
attractors billboardMode direction1 direction2 flowMap imageProcessingConfiguration indexBuffer isAnimationSheetEnabled isBillboardBased isDisposed isLocal isNodeGenerated maxEmitBox minEmitBox noiseTexture onBeforeDrawParticlesObservable onDispose particles shaderLanguage source startDirectionFunction startPositionFunction targetStopDuration useLogarithmicDepth useRampGradients vertexBuffers vertexShaderName
addAlphaRemapGradient addAngularSpeedGradient addAttractor addColorGradient addColorRemapGradient addDragGradient addEmitRateGradient addLifeTimeGradient addLimitVelocityGradient addRampGradient addSizeGradient addStartSizeGradient addVelocityGradient animate canStart clone createBoxEmitter createConeEmitter createCylinderEmitter createDirectedConeEmitter createDirectedCylinderEmitter createDirectedSphereEmitter createHemisphericEmitter createMeshEmitter createPointEmitter createSphereEmitter dispose fillDefines fillUniformsAttributesAndSamplerNames forceRefreshGradients getActiveCount getAlphaRemapGradients getAngularSpeedGradients getCapacity getClassName getColorGradients getColorRemapGradients getCustomEffect getDragGradients getEmitRateGradients getLifeTimeGradients getLimitVelocityGradients getRampGradients getScene getSizeGradients getStartSizeGradients getVelocityGradients isAlive isReady isStarted isStopping rebuild removeAlphaRemapGradient removeAngularSpeedGradient removeAttractor removeColorGradient removeColorRemapGradient removeDragGradient removeEmitRateGradient removeLifeTimeGradient removeLimitVelocityGradient removeRampGradient removeSizeGradient removeStartSizeGradient removeVelocityGradient render reset resetDrawCache serialize setCustomEffect start stop Parse

  • Instantiates a particle system. Particles are often small sprites used to simulate hard-to-reproduce phenomena like fire, smoke, water, or abstract visual effects like magic glitter and faery dust.

    Parameters

    • name: string

      The name of the particle system

    • capacity: number

      The max number of particles alive at the same time

    • sceneOrEngine: Scene | AbstractEngine

      The scene the particle system belongs to or the engine to use if no scene

    • customEffect: Nullable<Effect> = null

      a custom effect used to change the way particles are rendered by default

    • isAnimationSheetEnabled: boolean = false

      Must be true if using a spritesheet to animate the particles texture

    • epsilon: number = 0.01

      Offset used to render the particles

    • noUpdateQueue: boolean = false

      If true, the particle system will start with an empty update queue

    Returns ParticleSystem

activeSubSystems: ParticleSystem[]

The current active Sub-systems, this property is used by the root particle system only.

animations: Animation[] = []

List of animations used by the particle system.

applyFog: boolean = false

Gets or sets a boolean indicating that this particle system will allow fog to be rendered on it (false by default)

beginAnimationFrom: number = 0

Gets or sets the frame to start the animation from when beginAnimationOnStart is true

beginAnimationLoop: boolean = false

Gets or sets a boolean indicating if animations must loop when beginAnimationOnStart is true

beginAnimationOnStart: boolean = false

Gets or sets a boolean indicating that hosted animations (in the system.animations array) must be started when system.start() is called

beginAnimationTo: number = 60

Gets or sets the frame to end the animation on when beginAnimationOnStart is true

blendMode: number = BaseParticleSystem.BLENDMODE_ONEONE

Blend mode use to render the particle For original blend modes which are exposed from ParticleSystem (OneOne, Standard, Add, Multiply, MultiplyAdd, and Subtract), use ParticleSystem.BLENDMODE_FOO For all other blend modes, use Engine Constants.ALPHA_FOO blend modes

clipPlane: Nullable<Plane>

Gets or sets the active clipplane 1

clipPlane2: Nullable<Plane>

Gets or sets the active clipplane 2

clipPlane3: Nullable<Plane>

Gets or sets the active clipplane 3

clipPlane4: Nullable<Plane>

Gets or sets the active clipplane 4

clipPlane5: Nullable<Plane>

Gets or sets the active clipplane 5

clipPlane6: Nullable<Plane>

Gets or sets the active clipplane 6

color1: Color4 = ...

Random color of each particle after it has been emitted, between color1 and color2 vectors

color2: Color4 = ...

Random color of each particle after it has been emitted, between color1 and color2 vectors

colorDead: Color4 = ...

Color the particle will have at the end of its lifetime

customShader: any = null

This can help using your own shader to render the particle system. The according effect will be created

defaultProjectionMatrix: Matrix

Gets or sets a matrix to use to compute projection

defaultViewMatrix: Matrix

Gets or sets a matrix to use to compute view

disposeOnStop: boolean = false

Specifies whether the particle system will be disposed once it reaches the end of the animation.

doNotSerialize: boolean = false

Specifies if the particle system should be serialized

emitRate: number = 10

The maximum number of particles to emit per frame

emitter: Nullable<AbstractMesh | Vector3> = ...

The emitter represents the Mesh or position we are attaching the particle system to.

endSpriteCellID: number = 0

If using a spritesheet (isAnimationSheetEnabled) defines the last sprite cell to display

flowMapStrength: number = 1.0

The strength of the flow map

forceDepthWrite: boolean = false

Forces the particle to write their depth information to the depth buffer. This can help preventing other draw calls to override the particles.

gravity: Vector3 = ...

You can use gravity if you want to give an orientation to your particles.

id: string

The id of the Particle system.

isGPU: false

Indicates that the particle system is CPU based

layerMask: number = 0x0fffffff

The layer mask we are rendering the particles through.

limitVelocityDamping: number = 0.4

Gets or sets a value indicating the damping to apply if the limit velocity factor is reached

manualEmitCount: number = -1

If you want to launch only a few particles at once, that can be done, as well.

maxAngularSpeed: number = 0

Maximum angular speed of emitting particles (Z-axis rotation for each particle).

maxEmitPower: number = 1

Maximum power of emitting particles.

maxInitialRotation: number = 0

Gets or sets the maximal initial rotation in radians.

maxLifeTime: number = 1

Maximum life time of emitting particles.

maxScaleX: number = 1

Maximum scale of emitting particles on X axis.

maxScaleY: number = 1

Maximum scale of emitting particles on Y axis.

maxSize: number = 1

Maximum Size of emitting particles.

metadata: any = null

Gets or sets an object used to store user defined information for the particle system

minAngularSpeed: number = 0

Minimum angular speed of emitting particles (Z-axis rotation for each particle).

minEmitPower: number = 1

Minimum power of emitting particles.

minInitialRotation: number = 0

Gets or sets the minimal initial rotation in radians.

minLifeTime: number = 1

Minimum life time of emitting particles.

minScaleX: number = 1

Minimum scale of emitting particles on X axis.

minScaleY: number = 1

Minimum scale of emitting particles on Y axis.

minSize: number = 1

Minimum Size of emitting particles.

name: string

The friendly name of the Particle system.

noiseStrength: Vector3 = ...

Gets or sets the strength to apply to the noise value (default is (10, 10, 10))

onAnimationEnd: Nullable<() => void> = null

Callback triggered when the particle animation is ending.

onDisposeObservable: Observable<IParticleSystem> = ...

An event triggered when the system is disposed

onStartedObservable: Observable<IParticleSystem> = ...

An event triggered when the system is started

onStoppedObservable: Observable<IParticleSystem> = ...

An event triggered when the system is stopped

particleEmitterType: IParticleEmitterType

The particle emitter type defines the emitter used by the particle system. It can be for example box, sphere, or cone...

particleTexture: Nullable<BaseTexture>

The texture used to render each particle. (this can be a spritesheet)

paused: boolean = false

Gets or sets a boolean indicating that the particle system is paused (no animation will be done).

preventAutoStart: boolean = false

By default particle system starts as soon as they are created. This prevents the automatic start to happen and let you decide when to start emitting particles.

preWarmCycles: number = 0

Gets or sets a value indicating how many cycles (or frames) must be executed before first rendering (this value has to be set before starting the system). Default is 0

preWarmStepOffset: number = 1

Gets or sets a value indicating the time step multiplier to use in pre-warm mode (default is 1)

recycleParticle: (particle: Particle) => void = ...

"Recycles" one of the particle by copying it back to the "stock" of particles and removing it from the active list. Its lifetime will start back at 0.

renderingGroupId: number = 0

The rendering group used by the Particle system to chose when to render.

snippetId: string

Snippet ID if the particle system was created from the snippet server

spriteCellChangeSpeed: number = 1

If using a spritesheet (isAnimationSheetEnabled) defines the speed of the sprite loop (default is 1 meaning the animation will play once during the entire particle lifetime)

spriteCellHeight: number = 0

If using a spritesheet (isAnimationSheetEnabled), defines the sprite cell height to use

spriteCellLoop: boolean = true

If using a spritesheet (isAnimationSheetEnabled), defines wether the sprite animation is looping

spriteCellWidth: number = 0

If using a spritesheet (isAnimationSheetEnabled), defines the sprite cell width to use

spriteRandomStartCell: boolean = false

This allows the system to random pick the start cell ID between startSpriteCellID and endSpriteCellID

startDelay: number = 0

Defines the delay in milliseconds before starting the system (0 by default)

startSpriteCellID: number = 0

If using a spritesheet (isAnimationSheetEnabled) defines the first sprite cell to display

subEmitters: (ParticleSystem | SubEmitter | SubEmitter[])[]

The Sub-emitters templates that will be used to generate the sub particle system to be associated with the system, this property is used by the root particle system only. When a particle is spawned, an array will be chosen at random and all the emitters in that array will be attached to the particle. (Default: [])

textureMask: Color4 = ...

An optional mask to filter some colors out of the texture, or filter a part of the alpha channel

translationPivot: Vector2 = ...

Gets or sets a Vector2 used to move the pivot (by default (0,0))

uniqueId: number

Gets or sets the unique id of the particle system

updateFunction: (particles: Particle[]) => void

This function can be defined to provide custom update for active particles. This function will be called instead of regular update (age, position, color, etc.). Do not forget that this function will be called on every frame so try to keep it simple and fast :)

updateInAnimate: true

Indicates that the update of particles is done in the animate function

updateSpeed: number = 0.01

The overall motion speed (0.01 is default update speed, faster updates = faster animation)

worldOffset: Vector3 = ...

Gets or sets a world offset applied to all particles

BILLBOARDMODE_ALL: 7 = Constants.PARTICLES_BILLBOARDMODE_ALL

Billboard mode will apply to all axes

BILLBOARDMODE_STRETCHED: 8 = Constants.PARTICLES_BILLBOARDMODE_STRETCHED

Special billboard mode where the particle will be biilboard to the camera but rotated to align with direction

BILLBOARDMODE_STRETCHED_LOCAL: 9 = Constants.PARTICLES_BILLBOARDMODE_STRETCHED_LOCAL

Special billboard mode where the particle will be billboard to the camera but only around the axis of the direction of particle emission

BILLBOARDMODE_Y: 2 = Constants.PARTICLES_BILLBOARDMODE_Y

Billboard mode will only apply to Y axis

BLENDMODE_ADD: number = 2

Add current color and particle color multiplied by particle’s alpha

BLENDMODE_MULTIPLY: number = 3

Multiply current color with particle color

BLENDMODE_MULTIPLYADD: number = 4

Multiply current color with particle color then add current color and particle color multiplied by particle’s alpha

BLENDMODE_ONEONE: number = 0

Source color is added to the destination color without alpha affecting the result. Great for additive glow effects (fire, magic, lasers)

BLENDMODE_STANDARD: number = 1

Blend current color and particle color using particle’s alpha. Same as Constants.ALPHA_COMBINE, the go-to for transparency. 100% alpha means source, 0% alpha means background. Glass, UI fade, smoke

BLENDMODE_SUBTRACT: number = -1

Subtracts source (particle) from destination (current color), leading to darker results

  • NOTE: Init as -1 so we can properly map all modes to Engine Const's (otherwise ALPHA_SUBTRACT will conflict with BLENDMODE_MULTIPLY since both use 3)
ForceGLSL: boolean = false

Force all the particle systems to compile to glsl even on WebGPU engines. False by default. This is mostly meant for backward compatibility.

  • get startDirectionFunction(): Nullable<
        (
            worldMatrix: Matrix,
            directionToUpdate: Vector3,
            particle: Particle,
            isLocal: boolean,
        ) => void,
    >

    This function can be defined to specify initial direction for every new particle. It by default use the emitterType defined function

    Returns Nullable<
        (
            worldMatrix: Matrix,
            directionToUpdate: Vector3,
            particle: Particle,
            isLocal: boolean,
        ) => void,
    >

  • set startDirectionFunction(
        value: Nullable<
            (
                worldMatrix: Matrix,
                directionToUpdate: Vector3,
                particle: Particle,
                isLocal: boolean,
            ) => void,
        >,
    ): void

    Parameters

    • value: Nullable<
          (
              worldMatrix: Matrix,
              directionToUpdate: Vector3,
              particle: Particle,
              isLocal: boolean,
          ) => void,
      >

    Returns void

  • get startPositionFunction(): Nullable<
        (
            worldMatrix: Matrix,
            positionToUpdate: Vector3,
            particle: Particle,
            isLocal: boolean,
        ) => void,
    >

    This function can be defined to specify initial position for every new particle. It by default use the emitterType defined function

    Returns Nullable<
        (
            worldMatrix: Matrix,
            positionToUpdate: Vector3,
            particle: Particle,
            isLocal: boolean,
        ) => void,
    >

  • set startPositionFunction(
        value: Nullable<
            (
                worldMatrix: Matrix,
                positionToUpdate: Vector3,
                particle: Particle,
                isLocal: boolean,
            ) => void,
        >,
    ): void

    Parameters

    • value: Nullable<
          (
              worldMatrix: Matrix,
              positionToUpdate: Vector3,
              particle: Particle,
              isLocal: boolean,
          ) => void,
      >

    Returns void

  • Adds a new alpha remap gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • min: number

      defines the alpha remap minimal range

    • max: number

      defines the alpha remap maximal range

    Returns IParticleSystem

    the current particle system

  • Adds a new angular speed gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the angular speed to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns IParticleSystem

    the current particle system

  • Adds a new color remap gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • min: number

      defines the color remap minimal range

    • max: number

      defines the color remap maximal range

    Returns IParticleSystem

    the current particle system

  • Adds a new drag gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the drag value to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns IParticleSystem

    the current particle system

  • Adds a new emit rate gradient (please note that this will only work if you set the targetStopDuration property)

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the emit rate value to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns this

    the current particle system

  • Adds a new life time gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the life time factor to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns IParticleSystem

    the current particle system

  • Adds a new limit velocity gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the limit velocity value to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns IParticleSystem

    the current particle system

  • Adds a new ramp gradient used to remap particle colors

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • color: Color3

      defines the color to affect to the specified gradient

    Returns ThinParticleSystem

    the current particle system

  • Adds a new size gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the size factor to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns IParticleSystem

    the current particle system

  • Adds a new start size gradient (please note that this will only work if you set the targetStopDuration property)

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the start size value to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns IParticleSystem

    the current particle system

  • Adds a new velocity gradient

    Parameters

    • gradient: number

      defines the gradient to use (between 0 and 1)

    • factor: number

      defines the velocity to affect to the specified gradient

    • Optionalfactor2: number

      defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from

    Returns IParticleSystem

    the current particle system

  • Animates the particle system for the current frame by emitting new particles and or animating the living ones.

    Parameters

    • preWarmOnly: boolean = false

      will prevent the system from updating the vertex buffer (default is false)

    Returns void

  • Creates a Box Emitter for the particle system. (emits between direction1 and direction2 from within the box defined by minEmitBox and maxEmitBox)

    Parameters

    • direction1: Vector3

      Particles are emitted between the direction1 and direction2 from within the box

    • direction2: Vector3

      Particles are emitted between the direction1 and direction2 from within the box

    • minEmitBox: Vector3

      Particles are emitted from the box between minEmitBox and maxEmitBox

    • maxEmitBox: Vector3

      Particles are emitted from the box between minEmitBox and maxEmitBox

    Returns BoxParticleEmitter

    the emitter

  • Creates a Cylinder Emitter for the particle system (emits from the cylinder to the particle position)

    Parameters

    • radius: number = 1

      The radius of the emission cylinder

    • height: number = 1

      The height of the emission cylinder

    • radiusRange: number = 1

      The range of emission [0-1] 0 Surface only, 1 Entire Radius

    • directionRandomizer: number = 0

      How much to randomize the particle direction [0-1]

    Returns CylinderParticleEmitter

    the emitter

  • Creates a Directed Cone Emitter for the particle system (emits between direction1 and direction2)

    Parameters

    • radius: number = 1

      The radius of the cone to emit from

    • angle: number = ...

      The base angle of the cone

    • direction1: Vector3 = ...

      Particles are emitted between the direction1 and direction2 from within the cone

    • direction2: Vector3 = ...

      Particles are emitted between the direction1 and direction2 from within the cone

    Returns ConeDirectedParticleEmitter

    the emitter

  • Creates a Directed Cylinder Emitter for the particle system (emits between direction1 and direction2)

    Parameters

    • radius: number = 1

      The radius of the cylinder to emit from

    • height: number = 1

      The height of the emission cylinder

    • radiusRange: number = 1

      the range of the emission cylinder [0-1] 0 Surface only, 1 Entire Radius (1 by default)

    • direction1: Vector3 = ...

      Particles are emitted between the direction1 and direction2 from within the cylinder

    • direction2: Vector3 = ...

      Particles are emitted between the direction1 and direction2 from within the cylinder

    Returns CylinderDirectedParticleEmitter

    the emitter

  • Disposes the particle system and free the associated resources

    Parameters

    • disposeTexture: boolean = true

      defines if the particle texture must be disposed as well (true by default)

    • disposeAttachedSubEmitters: boolean = false

      defines if the attached sub-emitters must be disposed as well (false by default)

    • disposeEndSubEmitters: boolean = false

      defines if the end type sub-emitters must be disposed as well (false by default)

    Returns void

  • Fill the defines array according to the current settings of the particle system

    Parameters

    • defines: string[]

      Array to be updated

    • blendMode: number

      blend mode to take into account when updating the array

    • fillImageProcessing: boolean = true

      fills the image processing defines

    Returns void

  • Fill the uniforms, attributes and samplers arrays according to the current settings of the particle system

    Parameters

    • uniforms: string[]

      Uniforms array to fill

    • attributes: string[]

      Attributes array to fill

    • samplers: string[]

      Samplers array to fill

    Returns void

  • Remove a specific emit rate gradient

    Parameters

    • gradient: number

      defines the gradient to remove

    Returns this

    the current particle system

  • Remove a specific ramp gradient

    Parameters

    • gradient: number

      defines the gradient to remove

    Returns ThinParticleSystem

    the current particle system

  • Serializes the particle system to a JSON object

    Parameters

    • serializeTexture: boolean = false

      defines if the texture must be serialized as well

    Returns any

    the JSON object

  • Starts the particle system and begins to emit

    Parameters

    • delay: number = ...

      defines the delay in milliseconds before starting the system (this.startDelay by default)

    Returns void

  • Stops the particle system.

    Parameters

    • stopSubEmitters: boolean = true

      if true it will stop the current system and all created sub-Systems if false it will stop the current root system only, this param is used by the root particle system only. The default value is true.

    Returns void

  • Parses a JSON object to create a particle system.

    Parameters

    • parsedParticleSystem: any

      The JSON object to parse

    • sceneOrEngine: Scene | AbstractEngine

      The scene or the engine to create the particle system in

    • rootUrl: string

      The root url to use to load external dependencies like texture

    • doNotStart: boolean = false

      Ignore the preventAutoStart attribute and does not start

    • Optionalcapacity: number

      defines the system capacity (if null or undefined the sotred capacity will be used)

    Returns ParticleSystem

    the Parsed particle system