Class: ParticleSystemComponent

pc.ParticleSystemComponent

Used to simulate particles and produce 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 to support reasonable uniform count, reading from multiple textures in vertex shader and 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. 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 camera facing axis, while mesh particles rotate around 2 different view-independent axes. Most of the simulation parameters are specified with pc.Curve or pc.CurveSet. Curves are interpolated based on each particle's lifetime, therefore parameters are able to change over time. Most of the curve parameters can also be specified by 2 minimum/maximum curves, this way each particle will pick a random value in-between.

Constructor

new ParticleSystemComponent(system, entity)

Create a new ParticleSystemComponent
Parameters:
Name Type Description
system pc.ParticleSystemComponentSystem The ComponentSystem that created this Component
entity pc.Entity The Entity this Component is attached to
Properties:
Name Type Description
autoPlay Boolean Controls whether the particle system plays automatically on creation. If set to false, it is necessary to call pc.ParticleSystemComponent#play for the particle system to play. Defaults to true.
loop Boolean Enables or disables respawning of particles.
preWarm Boolean If enabled, the particle system will be initialized as though it had already completed a full cycle. This only works with looping particle systems.
lighting Boolean If enabled, particles will be lit by ambient and directional lights.
halfLambert Boolean Enabling Half Lambert lighting avoids particles looking too flat in shadowed areas. It is a completely non-physical lighting model but can give more pleasing visual results.
alignToMotion Boolean Orient particles in their direction of motion.
depthWrite Boolean If enabled, the particles will write to the depth buffer. If disabled, the depth buffer is left unchanged and particles will be guaranteed to overwrite one another in the order in which they are rendered.
noFog Boolean Disable fogging
localSpace Boolean Binds particles to emitter transformation rather then world space.
numParticles Number Maximum number of simulated particles.
rate Number Minimal interval in seconds between particle births.
rate2 Number Maximal interval in seconds between particle births.
startAngle Number Minimal initial Euler angle of a particle.
startAngle2 Number Maximal initial Euler angle of a particle.
lifetime Number The length of time in seconds between a particle's birth and its death.
stretch Number A value in world units that controls the amount by which particles are stretched based on their velocity. Particles are stretched from their center towards their previous position.
intensity Number Color multiplier.
animLoop Boolean Controls whether the sprite sheet animation plays once or loops continuously.
animTilesX Number Number of horizontal tiles in the sprite sheet.
animTilesY Number Number of vertical tiles in the sprite sheet.
animNumFrames Number Number of sprite sheet frames to play. It is valid to set the number of frames to a value less than animTilesX multiplied by animTilesY.
animSpeed Number Sprite sheet animation speed. 1 = particle lifetime, 2 = twice during lifetime etc...
depthSoftening Number Controls fading of particles near their intersections with scene geometry. This effect, when it's non-zero, requires scene depth map to be rendered. Multiple depth-dependent effects can share the same map, but if you only use it for particles, bear in mind that it can double engine draw calls.
initialVelocity Number Defines magnitude of the initial emitter velocity. Direction is given by emitter shape.
emitterExtents pc.Vec3 (Only for EMITTERSHAPE_BOX) The extents of a local space bounding box within which particles are spawned at random positions.
emitterExtentsInner pc.Vec3 (Only for EMITTERSHAPE_BOX) The exception of extents of a local space bounding box within which particles are not spawned. Aligned to the center of EmitterExtents.
emitterRadius Number (Only for EMITTERSHAPE_SPHERE) The radius within which particles are spawned at random positions.
emitterRadiusInner Number (Only for EMITTERSHAPE_SPHERE) The inner radius within which particles are not spawned.
wrapBounds pc.Vec3 The half extents of a world space box volume centered on the owner entity's position. If a particle crosses the boundary of one side of the volume, it teleports to the opposite side.
colorMapAsset pc.Asset The pc.Asset used to set the colorMap.
normalMapAsset pc.Asset The pc.Asset used to set the normalMap.
meshAsset pc.Asset The pc.Asset used to set the mesh.
colorMap pc.Texture The color map texture to apply to all particles in the system. If no texture is assigned, a default spot texture is used.
normalMap pc.Texture The normal map texture to apply to all particles in the system. If no texture is assigned, an approximate spherical normal is calculated for each vertex.
emitterShape pc.EMITTERSHAPE Shape of the emitter. Defines the bounds inside which particles are spawned. Also affects the direction of initial velocity.
  • pc.EMITTERSHAPE_BOX: Box shape parameterized by emitterExtents. Initial velocity is directed towards local Z axis.
  • pc.EMITTERSHAPE_SPHERE: Sphere shape parameterized by emitterRadius. Initial velocity is directed outwards from the center.
sort pc.PARTICLESORT Sorting mode. Forces CPU simulation, so be careful.
  • pc.PARTICLESORT_NONE: No sorting, particles are drawn in arbitary order. Can be simulated on GPU.
  • pc.PARTICLESORT_DISTANCE: Sorting based on distance to the camera. CPU only.
  • pc.PARTICLESORT_NEWER_FIRST: Newer particles are drawn first. CPU only.
  • pc.PARTICLESORT_OLDER_FIRST: Older particles are drawn first. CPU only.
mesh pc.Mesh Triangular mesh to be used as a particle. Only first vertex/index buffer is used. Vertex buffer must contain local position at first 3 floats of each vertex.
blend pc.BLEND Blending mode.
orientation pc.PARTICLEORIENTATION Sorting mode. Forces CPU simulation, so be careful.
  • pc.PARTICLEORIENTATION_SCREEN: Particles are facing camera.
  • pc.PARTICLEORIENTATION_WORLD: User defines world space normal (particleNormal) to set planes orientation.
  • pc.PARTICLEORIENTATION_EMITTER: Similar to previous, but the normal is affected by emitter(entity) transformation.
particleNormal pc.Vec3 (Only for PARTICLEORIENTATION_WORLD and PARTICLEORIENTATION_EMITTER) The exception of extents of a local space bounding box within which particles are not spawned. Aligned to the center of EmitterExtents.
localVelocityGraph pc.CurveSet Velocity relative to emitter over lifetime.
localVelocityGraph2 pc.CurveSet If not null, particles pick random values between localVelocityGraph and localVelocityGraph2.
velocityGraph pc.CurveSet World-space velocity over lifetime.
velocityGraph2 pc.CurveSet If not null, particles pick random values between velocityGraph and velocityGraph2.
colorGraph pc.CurveSet Color over lifetime.
rotationSpeedGraph pc.Curve Rotation speed over lifetime.
rotationSpeedGraph2 pc.Curve If not null, particles pick random values between rotationSpeedGraph and rotationSpeedGraph2.
radialSpeedGraph pc.Curve Radial speed over lifetime, velocity vector points from emitter origin to particle pos.
radialSpeedGraph2 pc.Curve If not null, particles pick random values between radialSpeedGraph and radialSpeedGraph2.
scaleGraph pc.Curve Scale over lifetime.
scaleGraph2 pc.Curve If not null, particles pick random values between scaleGraph and scaleGraph2.
alphaGraph pc.Curve Alpha over lifetime.
alphaGraph2 pc.Curve If not null, particles pick random values between alphaGraph and alphaGraph2.
layers Array An array of layer IDs (pc.Layer#id) to which this particle system should belong. Don't push/pop/splice or modify this array, if you want to change it - set a new one instead.
Source:

Extends

Methods

isPlaying() → {Boolean}

Checks if simulation is in progress.
Source:
Returns:
true if the particle system is currently playing and false otherwise.
Type
Boolean

pause()

Freezes the simulation.
Source:

play()

Enables/unfreezes the simulation.
Source:

(private) rebuild()

Rebuilds all data used by this particle system.
Source:

reset()

Resets particle state, doesn't affect playing.
Source:

stop()

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

unpause()

Unfreezes the simulation.
Source: