API Reference

Class List

pc.ParticleSystemComponent

Extends: pc.Component

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.

Summary

Properties

alignToMotionOrient particles in their direction of motion.
alphaGraphAlpha over lifetime.
alphaGraph2If not null, particles pick random values between alphaGraph and alphaGraph2.
animLoopControls whether the sprite sheet animation plays once or loops continuously.
animNumFramesNumber of sprite sheet frames to play.
animSpeedSprite sheet animation speed.
animTilesXNumber of horizontal tiles in the sprite sheet.
animTilesYNumber of vertical tiles in the sprite sheet.
blendBlending mode.
colorGraphColor over lifetime.
colorMapThe color map texture to apply to all particles in the system.
depthSofteningControls fading of particles near their intersections with scene geometry.
depthWriteIf enabled, the particles will write to the depth buffer.
emitterExtents(Only for EMITTERSHAPE_BOX) The extents of a local space bounding box within which particles are spawned at random positions.
emitterRadius(Only for EMITTERSHAPE_SPHERE) The radius within which particles are spawned at random positions.
emitterShapeShape of the emitter.
halfLambertEnabling Half Lambert lighting avoids particles looking too flat in shadowed areas.
initialVelocityDefines magnitude of the initial emitter velocity.
intensityColor multiplier.
lifetimeThe length of time in seconds between a particle's birth and its death.
lightingIf enabled, particles will be lit by ambient and directional lights.
localVelocityGraphVelocity relative to emitter over lifetime.
localVelocityGraph2If not null, particles pick random values between localVelocityGraph and localVelocityGraph2.
loopEnables or disables respawning of particles.
meshTriangular mesh to be used as a particle.
noFogDisable fogging
normalMapThe normal map texture to apply to all particles in the system.
numParticlesMaximum number of simulated particles.
pausedPauses or unpauses the simulation.
preWarmIf enabled, the particle system will be initialized as though it had already completed a full cycle.
rateMinimal interval in seconds between particle births.
rate2Maximal interval in seconds between particle births.
rotationSpeedGraphRotation speed over lifetime.
rotationSpeedGraph2If not null, particles pick random values between rotationSpeedGraph and rotationSpeedGraph2.
scaleGraphScale over lifetime.
scaleGraph2If not null, particles pick random values between scaleGraph and scaleGraph2.
sortSorting mode.
startAngleMinimal inital Euler angle of a particle.
startAngle2Maximal inital Euler angle of a particle.
stretchA value in world units that controls the amount by which particles are stretched based on their velocity.
velocityGraphWorld-space velocity over lifetime.
velocityGraph2If not null, particles pick random values between velocityGraph and velocityGraph2.
wrapBoundsThe half extents of a world space box volume centered on the owner entity's position.

Methods

isPlayingChecks if simulation is in progress.
pauseFreezes the simulation.
playEnables/unfreezes the simulation.
resetResets particle state, doesn't affect playing.
stopDisables the emission of new particles, lets existing to finish their simulation.
unpauseUnfreezes the simulation.

Inherited

Properties

enabledEnables or disables the component.

Details

Constructor

ParticleSystemComponent(system, entity)

Create a new ParticleSystemComponent

Parameters

systempc.ParticleSystemComponentThe ComponentSystem that created this Component
entitypc.EntityThe Entity this Component is attached to

Properties

BooleanalignToMotion

Orient particles in their direction of motion.

pc.CurvealphaGraph

Alpha over lifetime.

pc.CurvealphaGraph2

If not null, particles pick random values between alphaGraph and alphaGraph2.

BooleananimLoop

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

NumberanimNumFrames

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.

NumberanimSpeed

Sprite sheet animation speed. 1 = particle lifetime, 2 = twice during lifetime etc...

NumberanimTilesX

Number of horizontal tiles in the sprite sheet.

NumberanimTilesY

Number of vertical tiles in the sprite sheet.

pc.BLENDblend

Blending mode.

pc.CurveSetcolorGraph

Color over lifetime.

pc.TexturecolorMap

The color map texture to apply to all particles in the system. If no texture is assigned, a default spot texture is used.

NumberdepthSoftening

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.

BooleandepthWrite

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.

pc.Vec3emitterExtents

(Only for EMITTERSHAPE_BOX) The extents of a local space bounding box within which particles are spawned at random positions.

NumberemitterRadius

(Only for EMITTERSHAPE_SPHERE) The radius within which particles are spawned at random positions.

pc.EMITTERSHAPEemitterShape

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.

BooleanhalfLambert

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.

NumberinitialVelocity

Defines magnitude of the initial emitter velocity. Direction is given by emitter shape.

Numberintensity

Color multiplier.

Numberlifetime

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

Booleanlighting

If enabled, particles will be lit by ambient and directional lights.

pc.CurveSetlocalVelocityGraph

Velocity relative to emitter over lifetime.

pc.CurveSetlocalVelocityGraph2

If not null, particles pick random values between localVelocityGraph and localVelocityGraph2.

Booleanloop

Enables or disables respawning of particles.

pc.Meshmesh

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.

BooleannoFog

Disable fogging

pc.TexturenormalMap

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.

NumbernumParticles

Maximum number of simulated particles.

Booleanpaused

Pauses or unpauses the simulation.

BooleanpreWarm

If enabled, the particle system will be initialized as though it had already completed a full cycle. This only works with looping particle systems.

Numberrate

Minimal interval in seconds between particle births.

Numberrate2

Maximal interval in seconds between particle births.

pc.CurverotationSpeedGraph

Rotation speed over lifetime.

pc.CurverotationSpeedGraph2

If not null, particles pick random values between rotationSpeedGraph and rotationSpeedGraph2.

pc.CurvescaleGraph

Scale over lifetime.

pc.CurvescaleGraph2

If not null, particles pick random values between scaleGraph and scaleGraph2.

pc.PARTICLESORTsort

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.

NumberstartAngle

Minimal inital Euler angle of a particle.

NumberstartAngle2

Maximal inital Euler angle of a particle.

Numberstretch

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.

pc.CurveSetvelocityGraph

World-space velocity over lifetime.

pc.CurveSetvelocityGraph2

If not null, particles pick random values between velocityGraph and velocityGraph2.

pc.Vec3wrapBounds

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.

Methods

isPlaying()

Checks if simulation is in progress.

pause()

Freezes the simulation.

play()

Enables/unfreezes the simulation.

reset()

Resets particle state, doesn't affect playing.

stop()

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

unpause()

Unfreezes the simulation.

Inherited

Properties

Booleanenabled

Enables or disables the component.