API Reference

Class List

ParticleSystemComponent

Extends: 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 Curve or 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

alignToMotion

Orient particles in their direction of motion.

alphaGraph

Alpha over lifetime.

alphaGraph2

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

animIndex

When animNumAnimations is greater than 1, the sprite sheet animation index determines which animation the particle system should play.

animLoop

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

animNumAnimations

Number of sprite sheet animations contained within the current sprite sheet.

animNumFrames

Number of sprite sheet frames in the current sprite sheet animation.

animSpeed

Sprite sheet animation speed.

animStartFrame

The sprite sheet frame that the animation should begin playing from.

animTilesX

Number of horizontal tiles in the sprite sheet.

animTilesY

Number of vertical tiles in the sprite sheet.

autoPlay

Controls whether the particle system plays automatically on creation.

blend

Controls how particles are blended when being written to the currently active render target.

colorGraph

Color over lifetime.

colorMap

The color map texture to apply to all particles in the system.

colorMapAsset

The Asset used to set the colorMap.

depthSoftening

Controls fading of particles near their intersections with scene geometry.

depthWrite

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

emitterExtentsInner

(Only for EMITTERSHAPE_BOX) The exception of extents of a local space bounding box within which particles are not spawned.

emitterRadius

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

emitterRadiusInner

(Only for EMITTERSHAPE_SPHERE) The inner radius within which particles are not spawned.

emitterShape

Shape of the emitter.

halfLambert

Enabling Half Lambert lighting avoids particles looking too flat in shadowed areas.

initialVelocity

Defines magnitude of the initial emitter velocity.

intensity

Color multiplier.

layers

An array of layer IDs (Layer#id) to which this particle system should belong.

lifetime

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

lighting

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

localSpace

Binds particles to emitter transformation rather then world space.

localVelocityGraph

Velocity relative to emitter over lifetime.

localVelocityGraph2

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

loop

Enables or disables respawning of particles.

mesh

Triangular mesh to be used as a particle.

meshAsset

The Asset used to set the mesh.

noFog

Disable fogging.

normalMap

The normal map texture to apply to all particles in the system.

normalMapAsset

The Asset used to set the normalMap.

numParticles

Maximum number of simulated particles.

orientation

Sorting mode.

particleNormal

(Only for PARTICLEORIENTATION_WORLD and PARTICLEORIENTATION_EMITTER) The exception of extents of a local space bounding box within which particles are not spawned.

preWarm

If enabled, the particle system will be initialized as though it had already completed a full cycle.

radialSpeedGraph

Radial speed over lifetime, velocity vector points from emitter origin to particle pos.

radialSpeedGraph2

If not null, particles pick random values between radialSpeedGraph and radialSpeedGraph2.

randomizeAnimIndex

Each particle emitted by the system will play a random animation from the sprite sheet, up to animNumAnimations.

rate

Minimal interval in seconds between particle births.

rate2

Maximal interval in seconds between particle births.

renderAsset

The Render Asset used to set the mesh.

rotationSpeedGraph

Rotation speed over lifetime.

rotationSpeedGraph2

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

scaleGraph

Scale over lifetime.

scaleGraph2

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

screenSpace

Renders particles in 2D screen space.

sort

Sorting mode.

startAngle

Minimal initial Euler angle of a particle.

startAngle2

Maximal initial Euler angle of a particle.

stretch

A value in world units that controls the amount by which particles are stretched based on their velocity.

velocityGraph

World-space velocity over lifetime.

velocityGraph2

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

wrapBounds

The half extents of a world space box volume centered on the owner entity's position.

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

enabled

Enables or disables the component.

entity

The Entity that this Component is attached to.

system

The ComponentSystem used to create this Component.

Methods

fire

Fire an event, all additional arguments are passed on to the event listener.

hasEvent

Test if there are any handlers bound to an event name.

off

Detach an event handler from an event.

on

Attach an event handler to an event.

once

Attach an event handler to an event.

Details

Constructor

ParticleSystemComponent(system, entity)

Create a new ParticleSystemComponent.

Parameters

systemParticleSystemComponentSystem

The ComponentSystem that created this Component.

entityEntity

The Entity this Component is attached to.

Properties

booleanalignToMotion

Orient particles in their direction of motion.

CurvealphaGraph

Alpha over lifetime.

CurvealphaGraph2

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

numberanimIndex

When animNumAnimations is greater than 1, the sprite sheet animation index determines which animation the particle system should play.

booleananimLoop

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

numberanimNumAnimations

Number of sprite sheet animations contained within the current sprite sheet. The number of animations multiplied by number of frames should be a value less than animTilesX multiplied by animTilesY.

numberanimNumFrames

Number of sprite sheet frames in the current sprite sheet animation. The number of animations multiplied by number of frames should be a value less than animTilesX multiplied by animTilesY.

numberanimSpeed

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

numberanimStartFrame

The sprite sheet frame that the animation should begin playing from. Indexed from the start of the current animation.

numberanimTilesX

Number of horizontal tiles in the sprite sheet.

numberanimTilesY

Number of vertical tiles in the sprite sheet.

booleanautoPlay

Controls whether the particle system plays automatically on creation. If set to false, it is necessary to call ParticleSystemComponent#play for the particle system to play. Defaults to true.

numberblend

Controls how particles are blended when being written to the currently active render target. Can be:

CurveSetcolorGraph

Color over lifetime.

TexturecolorMap

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

AssetcolorMapAsset

The Asset used to set the colorMap.

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.

Vec3emitterExtents

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

Vec3emitterExtentsInner

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

numberemitterRadius

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

numberemitterRadiusInner

(Only for EMITTERSHAPE_SPHERE) The inner radius within which particles are not spawned.

numberemitterShape

Shape of the emitter. Defines the bounds inside which particles are spawned. Also affects the direction of initial velocity.

  • EMITTERSHAPE_BOX: Box shape parameterized by emitterExtents. Initial velocity is directed towards local Z axis.
  • 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.

number[]layers

An array of layer IDs (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.

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.

booleanlocalSpace

Binds particles to emitter transformation rather then world space.

CurveSetlocalVelocityGraph

Velocity relative to emitter over lifetime.

CurveSetlocalVelocityGraph2

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

booleanloop

Enables or disables respawning of particles.

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.

AssetmeshAsset

The Asset used to set the mesh.

booleannoFog

Disable fogging.

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.

AssetnormalMapAsset

The Asset used to set the normalMap.

numbernumParticles

Maximum number of simulated particles.

numberorientation

Sorting mode. Forces CPU simulation, so be careful.

Vec3particleNormal

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

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.

CurveradialSpeedGraph

Radial speed over lifetime, velocity vector points from emitter origin to particle pos.

CurveradialSpeedGraph2

If not null, particles pick random values between radialSpeedGraph and radialSpeedGraph2.

numberrandomizeAnimIndex

Each particle emitted by the system will play a random animation from the sprite sheet, up to animNumAnimations.

numberrate

Minimal interval in seconds between particle births.

numberrate2

Maximal interval in seconds between particle births.

AssetrenderAsset

The Render Asset used to set the mesh.

CurverotationSpeedGraph

Rotation speed over lifetime.

CurverotationSpeedGraph2

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

CurvescaleGraph

Scale over lifetime.

CurvescaleGraph2

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

booleanscreenSpace

Renders particles in 2D screen space. This needs to be set when particle system is part of hierarchy with ScreenComponent as its ancestor, and allows particle system to integrate with the rendering of ElementComponents. Note that an entity with ParticleSystem component cannot be parented directly to ScreenComponent, but has to be a child of a ElementComponent, for example LayoutGroupComponent.

numbersort

Sorting mode. Forces CPU simulation, so be careful.

numberstartAngle

Minimal initial Euler angle of a particle.

numberstartAngle2

Maximal initial 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.

CurveSetvelocityGraph

World-space velocity over lifetime.

CurveSetvelocityGraph2

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

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.

Returns

boolean

True if the particle system is currently playing and false otherwise.

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.

Entityentity

The Entity that this Component is attached to.

ComponentSystemsystem

The ComponentSystem used to create this Component.

Methods

fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])

Fire an event, all additional arguments are passed on to the event listener.

obj.fire('test', 'This is the message');

Parameters

nameobject

Name of event to fire.

arg1*

First argument that is passed to the event handler.

arg2*

Second argument that is passed to the event handler.

arg3*

Third argument that is passed to the event handler.

arg4*

Fourth argument that is passed to the event handler.

arg5*

Fifth argument that is passed to the event handler.

arg6*

Sixth argument that is passed to the event handler.

arg7*

Seventh argument that is passed to the event handler.

arg8*

Eighth argument that is passed to the event handler.

Returns

EventHandler

Self for chaining.

hasEvent(name)

Test if there are any handlers bound to an event name.

obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false

Parameters

namestring

The name of the event to test.

Returns

boolean

True if the object has handlers bound to the specified event name.

off([name], [callback], [scope])

Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

var handler = function () {
};
obj.on('test', handler);

obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all hander functions, called 'test' with scope this

Parameters

namestring

Name of the event to unbind.

callbackcallbacks.HandleEvent

Function to be unbound.

scopeobject

Scope that was used as the this when the event is fired.

Returns

EventHandler

Self for chaining.

on(name, callback, [scope])

Attach an event handler to an event.

obj.on('test', function (a, b) {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console

Parameters

namestring

Name of the event to bind the callback to.

callbackcallbacks.HandleEvent

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scopeobject

Object to use as 'this' when the event is fired, defaults to current this.

Returns

EventHandler

Self for chaining.

once(name, callback, [scope])

Attach an event handler to an event. This handler will be removed after being fired once.

obj.once('test', function (a, b) {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
obj.fire('test', 1, 2); // not going to get handled

Parameters

namestring

Name of the event to bind the callback to.

callbackcallbacks.HandleEvent

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scopeobject

Object to use as 'this' when the event is fired, defaults to current this.

Returns

EventHandler

Self for chaining.