API
API|
@babylonjs/core|
GPUParticleSystem

Class GPUParticleSystem

This represents a GPU particle system in Babylon This is the fastest particle system in Babylon as it uses the GPU to update the individual particle data

https://www.babylonjs-playground.com/#PU4WYI#4

Hierarchy (View Summary)

Implements

Index
constructor
animations applyFog beginAnimationFrom beginAnimationLoop beginAnimationOnStart beginAnimationTo blendMode clipPlane clipPlane2 clipPlane3 clipPlane4 clipPlane5 clipPlane6 color1 color2 colorDead customShader defaultProjectionMatrix disposeOnStop doNotSerialize emitRate emitRateControl emitter endSpriteCellID flowMapStrength forceDepthWrite gravity id isGPU isLocal layerMask limitVelocityDamping manualEmitCount maxAngularSpeed maxAttractors maxEmitPower maxInitialRotation maxLifeTime maxScaleX maxScaleY maxSize metadata minAngularSpeed minEmitPower minInitialRotation minLifeTime minScaleX minScaleY minSize name noiseStrength onAnimationEnd onDisposeObservable onStartedObservable onStoppedObservable particleEmitterType particleTexture preventAutoStart preWarmCycles preWarmStepOffset renderingGroupId snippetId spriteCellChangeSpeed spriteCellHeight spriteCellLoop spriteCellWidth spriteRandomStartCell startDelay startSpriteCellID textureMask translationPivot uniqueId updateInAnimate updateSpeed worldOffset BLENDMODE_ADD BLENDMODE_MULTIPLY BLENDMODE_MULTIPLYADD BLENDMODE_ONEONE BLENDMODE_STANDARD BLENDMODE_SUBTRACT
_isAnimationSheetEnabled activeParticleCount attractors billboardMode direction1 direction2 flowMap imageProcessingConfiguration indexBuffer isAnimationSheetEnabled isBillboardBased isNodeGenerated maxActiveParticleCount maxEmitBox minEmitBox noiseTexture onBeforeDrawParticlesObservable targetStopDuration useLogarithmicDepth useRampGradients vertexBuffers vertexShaderName IsSupported
addAlphaRemapGradient addAngularSpeedGradient addAttractor addColorGradient addColorRemapGradient addDragGradient addEmitRateGradient addLifeTimeGradient addLimitVelocityGradient addRampGradient addSizeGradient addStartSizeGradient addVelocityGradient animate 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 isReady isStarted isStopped isStopping rebuild removeAlphaRemapGradient removeAngularSpeedGradient removeAttractor removeColorGradient removeColorRemapGradient removeDragGradient removeEmitRateGradient removeLifeTimeGradient removeLimitVelocityGradient removeRampGradient removeSizeGradient removeStartSizeGradient removeVelocityGradient render reset resetDrawCache serialize setCustomEffect start stop fromParticleSystem Parse

  • Instantiates a GPU 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

    • options: Partial<
          {
              capacity: number;
              emitRateControl: boolean;
              maxAttractors: number;
              randomTextureSize: number;
          },
      >

      The options used to create the system

    • 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

    Returns GPUParticleSystem

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

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

emitRateControl: boolean = false

Gets or sets whether emit rate control is enabled. When true, the GPU particle system limits the number of active particles to approximately emitRate * maxLifeTime (matching CPU particle behavior) and uses a circular buffer to recycle particle slots. When false (default), all dead particles are recycled immediately, which is the legacy GPU particle behavior. Changing the value takes effect on the next frame (the update and render effects are rebuilt automatically when their shader defines change; buffer allocation does not depend on it).

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: true

Indicates that the particle system is GPU based

isLocal: boolean = false

Specifies if the particles are updated in emitter local space or world space.

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

maxAttractors: number

Maximum number of attractors for this GPU particle system instance. Determined at construction time via the maxAttractors option (default 8). Limited by the fixed-size uniform arrays in the update shaders.

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)

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)

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

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

updateInAnimate: boolean = false

Indicates that the update of particles is done in the animate function (and not in render). Default: false

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

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)

_isAnimationSheetEnabled

  • 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 (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 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 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 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

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

    Parameters

    • defines: string[]

      Array to be updated

    • blendMode: number = 0

      blend mode to take into account when updating the array

    • fillImageProcessing: boolean = true

      fills the image processing defines

    Returns void

  • Force the system to rebuild all gradients that need to be resync.

    This is the live-edit entry point both Inspectors call from their gradient onChange handlers, so a value-only edit must preserve the running simulation: every family whose lookup texture can be re-baked in place is updated without touching the particle buffers. Only a STRUCTURAL change — a family that has no texture to re-bake yet, one that was emptied, or a color2 row-layout flip — rebuilds the pool.

    An ABSENT family is not a structural change: it has nothing to resync, and counting it as one would reset the pool on every call (the destruction this method exists to avoid). Absence has two spellings — see _gradientFamilyNeedsResync.

    Returns void

  • Renders the particle system in its current state

    Parameters

    • preWarm: boolean = false

      defines if the system should only update the particles but not render them

    • forceUpdateOnly: boolean = false

      if true, force to only update the particles and never display them (meaning, even if preWarm=false, when forceUpdateOnly=true the particles won't be displayed)

    Returns number

    the current number of particles

  • Creates a new GPUParticleSystem from an existing CPU ParticleSystem, copying all shared properties. Features that are not supported on the GPU (sub-emitters, custom startDirectionFunction / startPositionFunction, customShader, ramp/remap gradients) are logged as warnings and skipped. Flow maps are converted: the CPU FlowMap image data is uploaded to a new RawTexture which is assigned to the result.

    Note: a custom updateFunction on the source cannot be detected (the property is always assigned to a default) and has no equivalent on the GPU path, so any custom per-frame update logic will be silently dropped.

    Textures (particleTexture, noiseTexture) are shared by reference between the source and the result. All other mutable state (colors, vectors, emitter type, gradients, attractors) is cloned so that the two systems can be modified independently after the call.

    Note: unlike the GPUParticleSystem constructor, emitRateControl defaults to true here so that changes to emitRate on the converted system behave the same as on the CPU source. Pass { emitRateControl: false } explicitly to opt out.

    Parameters

    • source: ParticleSystem

      The CPU ParticleSystem to convert

    • sceneOrEngine: Scene | AbstractEngine

      The scene or engine the new GPU particle system belongs to

    • Optionaloptions: Partial<
          {
              capacity: number;
              emitRateControl: boolean;
              maxAttractors: number;
              randomTextureSize: number;
          },
      >

      Optional options forwarded to the new GPU particle system (capacity, randomTextureSize, emitRateControl, maxAttractors). capacity defaults to the source capacity and emitRateControl defaults to true.

    Returns GPUParticleSystem

    A new GPUParticleSystem with shared properties copied from the source

  • Parses a JSON object to create a GPU 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 GPUParticleSystem

    the parsed GPU particle system