@babylonjs/core
Version:
Getting started? Play directly with the Babylon.js API using our [playground](https://playground.babylonjs.com/). It also contains a lot of samples to learn how to use it.
688 lines (687 loc) • 29.7 kB
TypeScript
import type { Immutable, Nullable } from "../types.js";
import type { Vector2, Vector3, Matrix } from "../Maths/math.vector.js";
import type { Color3, Color4 } from "../Maths/math.color.js";
import type { BaseTexture } from "../Materials/Textures/baseTexture.js";
import type { BoxParticleEmitter, IParticleEmitterType, PointParticleEmitter, HemisphericParticleEmitter, SphereParticleEmitter, SphereDirectedParticleEmitter, CylinderParticleEmitter, CylinderDirectedParticleEmitter, ConeParticleEmitter, ConeDirectedParticleEmitter } from "../Particles/EmitterTypes/index.js";
import type { Scene } from "../scene.js";
import type { ColorGradient, FactorGradient, Color3Gradient } from "../Misc/gradients.js";
import type { Effect } from "../Materials/effect.js";
import type { Observable } from "../Misc/observable.js";
import type { VertexBuffer } from "../Buffers/buffer.js";
import type { DataBuffer } from "../Buffers/dataBuffer.js";
import type { Animation } from "../Animations/animation.js";
import type { AbstractMesh } from "../Meshes/abstractMesh.js";
/**
* Interface representing a particle system in Babylon.js.
* This groups the common functionalities that needs to be implemented in order to create a particle system.
* A particle system represents a way to manage particles from their emission to their animation and rendering.
*/
export interface IParticleSystem {
/**
* Gets or sets the unique id of the particle system.
*/
uniqueId: number;
/**
* List of animations used by the particle system.
*/
animations: Animation[];
/**
* The id of the Particle system.
*/
id: string;
/**
* The name of the Particle system.
*/
name: string;
/**
* The emitter represents the Mesh or position we are attaching the particle system to.
*/
emitter: Nullable<AbstractMesh | Vector3>;
/**
* Gets or sets a boolean indicating if the particles must be rendered as billboard or aligned with the direction
*/
isBillboardBased: boolean;
/**
* The rendering group used by the Particle system to chose when to render.
*/
renderingGroupId: number;
/**
* The layer mask we are rendering the particles through.
*/
layerMask: number;
/**
* The overall motion speed (0.01 is default update speed, faster updates = faster animation)
*/
updateSpeed: number;
/**
* The amount of time the particle system is running (depends of the overall update speed).
*/
targetStopDuration: number;
/**
* The texture used to render each particle. (this can be a spritesheet)
*/
particleTexture: Nullable<BaseTexture>;
/**
* Blend mode use to render the particle. It can be any of the ParticleSystem.BLENDMODE_* constants
*/
blendMode: number;
/**
* Minimum life time of emitting particles.
*/
minLifeTime: number;
/**
* Maximum life time of emitting particles.
*/
maxLifeTime: number;
/**
* Minimum Size of emitting particles.
*/
minSize: number;
/**
* Maximum Size of emitting particles.
*/
maxSize: number;
/**
* Minimum scale of emitting particles on X axis.
*/
minScaleX: number;
/**
* Maximum scale of emitting particles on X axis.
*/
maxScaleX: number;
/**
* Minimum scale of emitting particles on Y axis.
*/
minScaleY: number;
/**
* Maximum scale of emitting particles on Y axis.
*/
maxScaleY: number;
/**
* Random color of each particle after it has been emitted, between color1 and color2 vectors.
*/
color1: Color4;
/**
* Random color of each particle after it has been emitted, between color1 and color2 vectors.
*/
color2: Color4;
/**
* Color the particle will have at the end of its lifetime.
*/
colorDead: Color4;
/**
* The maximum number of particles to emit per frame until we reach the activeParticleCount value
*/
emitRate: number;
/**
* You can use gravity if you want to give an orientation to your particles.
*/
gravity: Vector3;
/**
* Minimum power of emitting particles.
*/
minEmitPower: number;
/**
* Maximum power of emitting particles.
*/
maxEmitPower: number;
/**
* Minimum angular speed of emitting particles (Z-axis rotation for each particle).
*/
minAngularSpeed: number;
/**
* Maximum angular speed of emitting particles (Z-axis rotation for each particle).
*/
maxAngularSpeed: number;
/**
* Gets or sets the minimal initial rotation in radians.
*/
minInitialRotation: number;
/**
* Gets or sets the maximal initial rotation in radians.
*/
maxInitialRotation: number;
/**
* The particle emitter type defines the emitter used by the particle system.
* It can be for example box, sphere, or cone...
*/
particleEmitterType: Nullable<IParticleEmitterType>;
/**
* Defines the delay in milliseconds before starting the system (0 by default)
*/
startDelay: number;
/**
* 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
*/
preWarmCycles: number;
/**
* Gets or sets a value indicating the time step multiplier to use in pre-warm mode (default is 1)
*/
preWarmStepOffset: number;
/**
* 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)
*/
spriteCellChangeSpeed: number;
/**
* If using a spritesheet (isAnimationSheetEnabled) defines the first sprite cell to display
*/
startSpriteCellID: number;
/**
* If using a spritesheet (isAnimationSheetEnabled) defines the last sprite cell to display
*/
endSpriteCellID: number;
/**
* If using a spritesheet (isAnimationSheetEnabled), defines whether the sprite animation is looping
*/
spriteCellLoop: boolean;
/**
* If using a spritesheet (isAnimationSheetEnabled), defines the sprite cell width to use
*/
spriteCellWidth: number;
/**
* If using a spritesheet (isAnimationSheetEnabled), defines the sprite cell height to use
*/
spriteCellHeight: number;
/**
* This allows the system to random pick the start cell ID between startSpriteCellID and endSpriteCellID
*/
spriteRandomStartCell: boolean;
/**
* Gets or sets a boolean indicating if a spritesheet is used to animate the particles texture
*/
isAnimationSheetEnabled: boolean;
/** Gets or sets a Vector2 used to move the pivot (by default (0,0)) */
translationPivot: Vector2;
/**
* Gets or sets a texture used to add random noise to particle positions
*/
noiseTexture: Nullable<BaseTexture>;
/** Gets or sets the strength to apply to the noise value (default is (10, 10, 10)) */
noiseStrength: Vector3;
/**
* Gets or sets the billboard mode to use when isBillboardBased = true.
* Value can be: ParticleSystem.BILLBOARDMODE_ALL, ParticleSystem.BILLBOARDMODE_Y, ParticleSystem.BILLBOARDMODE_STRETCHED
*/
billboardMode: number;
/**
* Gets or sets a boolean enabling the use of logarithmic depth buffers, which is good for wide depth buffers.
*/
useLogarithmicDepth: boolean;
/** Gets or sets a value indicating the damping to apply if the limit velocity factor is reached */
limitVelocityDamping: number;
/**
* Gets or sets a boolean indicating that hosted animations (in the system.animations array) must be started when system.start() is called
*/
beginAnimationOnStart: boolean;
/**
* Gets or sets the frame to start the animation from when beginAnimationOnStart is true
*/
beginAnimationFrom: number;
/**
* Gets or sets the frame to end the animation on when beginAnimationOnStart is true
*/
beginAnimationTo: number;
/**
* Gets or sets a boolean indicating if animations must loop when beginAnimationOnStart is true
*/
beginAnimationLoop: boolean;
/**
* Specifies whether the particle system will be disposed once it reaches the end of the animation.
*/
disposeOnStop: boolean;
/**
* If you want to launch only a few particles at once, that can be done, as well.
*/
manualEmitCount: number;
/**
* Specifies if the particles are updated in emitter local space or world space
*/
isLocal: boolean;
/** Snippet ID if the particle system was created from the snippet server */
snippetId: string;
/** Gets or sets a matrix to use to compute projection */
defaultProjectionMatrix: Matrix;
/** Indicates that the update of particles is done in the animate function (and not in render) */
updateInAnimate: boolean;
/** @internal */
_wasDispatched: boolean;
/**
* Returns true if the particle system was generated by a node particle system set
*/
isNodeGenerated: boolean;
/**
* Gets the maximum number of particles active at the same time.
* @returns The max number of active particles.
*/
getCapacity(): number;
/**
* Gets the number of particles active at the same time.
* @returns The number of active particles.
*/
getActiveCount(): number;
/**
* Gets if the system has been started. (Note: this will still be true after stop is called)
* @returns True if it has been started, otherwise false.
*/
isStarted(): boolean;
/**
* Animates the particle system for this frame.
*/
animate(): void;
/**
* Renders the particle system in its current state.
* @returns the current number of particles
*/
render(): number;
/**
* Dispose the particle system and frees its associated resources.
* @param disposeTexture defines if the particle texture must be disposed as well (true by default)
* @param disposeAttachedSubEmitters defines if the attached sub-emitters must be disposed as well (false by default)
* @param disposeEndSubEmitters defines if the end type sub-emitters must be disposed as well (false by default)
*/
dispose(disposeTexture?: boolean, disposeAttachedSubEmitters?: boolean, disposeEndSubEmitters?: boolean): void;
/**
* An event triggered when the system is disposed
*/
onDisposeObservable: Observable<IParticleSystem>;
/**
* An event triggered when the system is stopped
*/
onStoppedObservable: Observable<IParticleSystem>;
/**
* An event triggered when the system is started
*/
onStartedObservable: Observable<IParticleSystem>;
/**
* Clones the particle system.
* @param name The name of the cloned object
* @param newEmitter The new emitter to use
* @returns the cloned particle system
*/
clone(name: string, newEmitter: any): Nullable<IParticleSystem>;
/**
* Serializes the particle system to a JSON object
* @param serializeTexture defines if the texture must be serialized as well
* @returns the JSON object
*/
serialize(serializeTexture: boolean): any;
/**
* Rebuild the particle system
*/
rebuild(): void;
/** Force the system to rebuild all gradients that need to be resync */
forceRefreshGradients(): void;
/**
* Starts the particle system and begins to emit
* @param delay defines the delay in milliseconds before starting the system (0 by default)
*/
start(delay?: number): void;
/**
* Stops the particle system.
*/
stop(): void;
/**
* Remove all active particles
*/
reset(): void;
/**
* Gets a boolean indicating that the system is stopping
* @returns true if the system is currently stopping
*/
isStopping(): boolean;
/**
* Is this system ready to be used/rendered
* @returns true if the system is ready
*/
isReady(): boolean;
/**
* Returns the string "ParticleSystem"
* @returns a string containing the class name
*/
getClassName(): string;
/**
* Gets the custom effect used to render the particles
* @param blendMode Blend mode for which the effect should be retrieved
* @returns The effect
*/
getCustomEffect(blendMode: number): Nullable<Effect>;
/**
* Sets the custom effect used to render the particles
* @param effect The effect to set
* @param blendMode Blend mode for which the effect should be set
*/
setCustomEffect(effect: Nullable<Effect>, blendMode: number): void;
/**
* Fill the defines array according to the current settings of the particle system
* @param defines Array to be updated
* @param blendMode blend mode to take into account when updating the array
* @param fillImageProcessing fills the image processing defines
*/
fillDefines(defines: Array<string>, blendMode: number, fillImageProcessing?: boolean): void;
/**
* Fill the uniforms, attributes and samplers arrays according to the current settings of the particle system
* @param uniforms Uniforms array to fill
* @param attributes Attributes array to fill
* @param samplers Samplers array to fill
*/
fillUniformsAttributesAndSamplerNames(uniforms: Array<string>, attributes: Array<string>, samplers: Array<string>): void;
/**
* Observable that will be called just before the particles are drawn
*/
onBeforeDrawParticlesObservable: Observable<Nullable<Effect>>;
/**
* Gets the name of the particle vertex shader
*/
vertexShaderName: string;
/**
* Gets the vertex buffers used by the particle system
*/
vertexBuffers: Immutable<{
[key: string]: VertexBuffer;
}>;
/**
* Gets the index buffer used by the particle system (or null if no index buffer is used)
*/
indexBuffer: Nullable<DataBuffer>;
/**
* Adds a new color gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param color1 defines the color to affect to the specified gradient
* @param color2 defines an additional color used to define a range ([color, color2]) with main color to pick the final color from
* @returns the current particle system
*/
addColorGradient(gradient: number, color1: Color4, color2?: Color4): IParticleSystem;
/**
* Remove a specific color gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeColorGradient(gradient: number): IParticleSystem;
/**
* Adds a new size gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the size factor to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addSizeGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific size gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeSizeGradient(gradient: number): IParticleSystem;
/**
* Gets the current list of color gradients.
* You must use addColorGradient and removeColorGradient to update this list
* @returns the list of color gradients
*/
getColorGradients(): Nullable<Array<ColorGradient>>;
/**
* Gets the current list of size gradients.
* You must use addSizeGradient and removeSizeGradient to update this list
* @returns the list of size gradients
*/
getSizeGradients(): Nullable<Array<FactorGradient>>;
/**
* Gets the current list of angular speed gradients.
* You must use addAngularSpeedGradient and removeAngularSpeedGradient to update this list
* @returns the list of angular speed gradients
*/
getAngularSpeedGradients(): Nullable<Array<FactorGradient>>;
/**
* Adds a new angular speed gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the angular speed to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addAngularSpeedGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific angular speed gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeAngularSpeedGradient(gradient: number): IParticleSystem;
/**
* Gets the current list of velocity gradients.
* You must use addVelocityGradient and removeVelocityGradient to update this list
* @returns the list of velocity gradients
*/
getVelocityGradients(): Nullable<Array<FactorGradient>>;
/**
* Adds a new velocity gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the velocity to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addVelocityGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific velocity gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeVelocityGradient(gradient: number): IParticleSystem;
/**
* Gets the current list of limit velocity gradients.
* You must use addLimitVelocityGradient and removeLimitVelocityGradient to update this list
* @returns the list of limit velocity gradients
*/
getLimitVelocityGradients(): Nullable<Array<FactorGradient>>;
/**
* Adds a new limit velocity gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the limit velocity to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addLimitVelocityGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific limit velocity gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeLimitVelocityGradient(gradient: number): IParticleSystem;
/**
* Adds a new drag gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the drag to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addDragGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific drag gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeDragGradient(gradient: number): IParticleSystem;
/**
* Gets the current list of drag gradients.
* You must use addDragGradient and removeDragGradient to update this list
* @returns the list of drag gradients
*/
getDragGradients(): Nullable<Array<FactorGradient>>;
/**
* Adds a new emit rate gradient (please note that this will only work if you set the targetStopDuration property)
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the emit rate to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addEmitRateGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific emit rate gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeEmitRateGradient(gradient: number): IParticleSystem;
/**
* Gets the current list of emit rate gradients.
* You must use addEmitRateGradient and removeEmitRateGradient to update this list
* @returns the list of emit rate gradients
*/
getEmitRateGradients(): Nullable<Array<FactorGradient>>;
/**
* Adds a new start size gradient (please note that this will only work if you set the targetStopDuration property)
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the start size to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addStartSizeGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific start size gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeStartSizeGradient(gradient: number): IParticleSystem;
/**
* Gets the current list of start size gradients.
* You must use addStartSizeGradient and removeStartSizeGradient to update this list
* @returns the list of start size gradients
*/
getStartSizeGradients(): Nullable<Array<FactorGradient>>;
/**
* Adds a new life time gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param factor defines the life time factor to affect to the specified gradient
* @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
* @returns the current particle system
*/
addLifeTimeGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
/**
* Remove a specific life time gradient
* @param gradient defines the gradient to remove
* @returns the current particle system
*/
removeLifeTimeGradient(gradient: number): IParticleSystem;
/**
* Gets the current list of life time gradients.
* You must use addLifeTimeGradient and removeLifeTimeGradient to update this list
* @returns the list of life time gradients
*/
getLifeTimeGradients(): Nullable<Array<FactorGradient>>;
/**
* Gets the current list of color gradients.
* You must use addColorGradient and removeColorGradient to update this list
* @returns the list of color gradients
*/
getColorGradients(): Nullable<Array<ColorGradient>>;
/**
* Adds a new ramp gradient used to remap particle colors
* @param gradient defines the gradient to use (between 0 and 1)
* @param color defines the color to affect to the specified gradient
* @returns the current particle system
*/
addRampGradient(gradient: number, color: Color3): IParticleSystem;
/**
* Gets the current list of ramp gradients.
* You must use addRampGradient and removeRampGradient to update this list
* @returns the list of ramp gradients
*/
getRampGradients(): Nullable<Array<Color3Gradient>>;
/** Gets or sets a boolean indicating that ramp gradients must be used
* @see https://doc.babylonjs.com/features/featuresDeepDive/particles/particle_system/ramps_and_blends
*/
useRampGradients: boolean;
/**
* Adds a new color remap gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param min defines the color remap minimal range
* @param max defines the color remap maximal range
* @returns the current particle system
*/
addColorRemapGradient(gradient: number, min: number, max: number): IParticleSystem;
/**
* Gets the current list of color remap gradients.
* You must use addColorRemapGradient and removeColorRemapGradient to update this list
* @returns the list of color remap gradients
*/
getColorRemapGradients(): Nullable<Array<FactorGradient>>;
/**
* Adds a new alpha remap gradient
* @param gradient defines the gradient to use (between 0 and 1)
* @param min defines the alpha remap minimal range
* @param max defines the alpha remap maximal range
* @returns the current particle system
*/
addAlphaRemapGradient(gradient: number, min: number, max: number): IParticleSystem;
/**
* Gets the current list of alpha remap gradients.
* You must use addAlphaRemapGradient and removeAlphaRemapGradient to update this list
* @returns the list of alpha remap gradients
*/
getAlphaRemapGradients(): Nullable<Array<FactorGradient>>;
/**
* Creates a Point Emitter for the particle system (emits directly from the emitter position)
* @param direction1 Particles are emitted between the direction1 and direction2 from within the box
* @param direction2 Particles are emitted between the direction1 and direction2 from within the box
* @returns the emitter
*/
createPointEmitter(direction1: Vector3, direction2: Vector3): PointParticleEmitter;
/**
* Creates a Hemisphere Emitter for the particle system (emits along the hemisphere radius)
* @param radius The radius of the hemisphere to emit from
* @param radiusRange The range of the hemisphere to emit from [0-1] 0 Surface Only, 1 Entire Radius
* @returns the emitter
*/
createHemisphericEmitter(radius: number, radiusRange: number): HemisphericParticleEmitter;
/**
* Creates a Sphere Emitter for the particle system (emits along the sphere radius)
* @param radius The radius of the sphere to emit from
* @param radiusRange The range of the sphere to emit from [0-1] 0 Surface Only, 1 Entire Radius
* @returns the emitter
*/
createSphereEmitter(radius: number, radiusRange: number): SphereParticleEmitter;
/**
* Creates a Directed Sphere Emitter for the particle system (emits between direction1 and direction2)
* @param radius The radius of the sphere to emit from
* @param direction1 Particles are emitted between the direction1 and direction2 from within the sphere
* @param direction2 Particles are emitted between the direction1 and direction2 from within the sphere
* @returns the emitter
*/
createDirectedSphereEmitter(radius: number, direction1: Vector3, direction2: Vector3): SphereDirectedParticleEmitter;
/**
* Creates a Cylinder Emitter for the particle system (emits from the cylinder to the particle position)
* @param radius The radius of the emission cylinder
* @param height The height of the emission cylinder
* @param radiusRange The range of emission [0-1] 0 Surface only, 1 Entire Radius
* @param directionRandomizer How much to randomize the particle direction [0-1]
* @returns the emitter
*/
createCylinderEmitter(radius: number, height: number, radiusRange: number, directionRandomizer: number): CylinderParticleEmitter;
/**
* Creates a Directed Cylinder Emitter for the particle system (emits between direction1 and direction2)
* @param radius The radius of the cylinder to emit from
* @param height The height of the emission cylinder
* @param radiusRange the range of the emission cylinder [0-1] 0 Surface only, 1 Entire Radius (1 by default)
* @param direction1 Particles are emitted between the direction1 and direction2 from within the cylinder
* @param direction2 Particles are emitted between the direction1 and direction2 from within the cylinder
* @returns the emitter
*/
createDirectedCylinderEmitter(radius: number, height: number, radiusRange: number, direction1: Vector3, direction2: Vector3): CylinderDirectedParticleEmitter;
/**
* Creates a Cone Emitter for the particle system (emits from the cone to the particle position)
* @param radius The radius of the cone to emit from
* @param angle The base angle of the cone
* @returns the emitter
*/
createConeEmitter(radius: number, angle: number): ConeParticleEmitter;
createDirectedConeEmitter(radius: number, angle: number, direction1: Vector3, direction2: Vector3): ConeDirectedParticleEmitter;
/**
* Creates a Box Emitter for the particle system. (emits between direction1 and direction2 from withing the box defined by minEmitBox and maxEmitBox)
* @param direction1 Particles are emitted between the direction1 and direction2 from within the box
* @param direction2 Particles are emitted between the direction1 and direction2 from within the box
* @param minEmitBox Particles are emitted from the box between minEmitBox and maxEmitBox
* @param maxEmitBox Particles are emitted from the box between minEmitBox and maxEmitBox
* @returns the emitter
*/
createBoxEmitter(direction1: Vector3, direction2: Vector3, minEmitBox: Vector3, maxEmitBox: Vector3): BoxParticleEmitter;
/**
* Get hosting scene
* @returns the scene
*/
getScene(): Nullable<Scene>;
}