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. |
blendType | 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
system | ParticleSystemComponentSystem | The ComponentSystem that created this Component. |
entity | Entity | The Entity this Component is attached to. |
Properties
When animNumAnimations is greater than 1, the sprite sheet animation index determines which animation the particle system should play.
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.
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.
Sprite sheet animation speed. 1 = particle lifetime, 2 = twice during lifetime etc...
The sprite sheet frame that the animation should begin playing from. Indexed from the start of the current animation.
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.
Controls how particles are blended when being written to the currently active render target. Can be:
- BLEND_SUBTRACTIVE: Subtract the color of the source fragment from the destination fragment and write the result to the frame buffer.
- BLEND_ADDITIVE: Add the color of the source fragment to the destination fragment and write the result to the frame buffer.
- BLEND_NORMAL: Enable simple translucency for materials such as glass. This is equivalent to enabling a source blend mode of BLENDMODE_SRC_ALPHA and a destination blend mode of BLENDMODE_ONE_MINUS_SRC_ALPHA.
- BLEND_NONE: Disable blending.
- BLEND_PREMULTIPLIED: Similar to BLEND_NORMAL expect the source fragment is assumed to have already been multiplied by the source alpha value.
- BLEND_MULTIPLICATIVE: Multiply the color of the source fragment by the color of the destination fragment and write the result to the frame buffer.
- BLEND_ADDITIVEALPHA: Same as BLEND_ADDITIVE except the source RGB is multiplied by the source alpha.
The color map texture to apply to all particles in the system. If no texture is assigned, a default spot texture is used.
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.
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.
(Only for EMITTERSHAPE_BOX) The extents of a local space bounding box within which particles are spawned at random positions.
(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.
(Only for EMITTERSHAPE_SPHERE) The radius within which particles are spawned at random positions.
(Only for EMITTERSHAPE_SPHERE) The inner radius within which particles are not spawned.
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.
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.
Defines magnitude of the initial emitter velocity. Direction is given by emitter shape.
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.
If not null, particles pick random values between localVelocityGraph and localVelocityGraph2.
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.
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.
Sorting mode. Forces CPU simulation, so be careful.
- PARTICLEORIENTATION_SCREEN: Particles are facing camera.
- PARTICLEORIENTATION_WORLD: User defines world space normal (particleNormal) to set planes orientation.
- PARTICLEORIENTATION_EMITTER: Similar to previous, but the normal is affected by emitter (entity) transformation.
(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.
If enabled, the particle system will be initialized as though it had already completed a full cycle. This only works with looping particle systems.
Radial speed over lifetime, velocity vector points from emitter origin to particle pos.
If not null, particles pick random values between radialSpeedGraph and radialSpeedGraph2.
Each particle emitted by the system will play a random animation from the sprite sheet, up to animNumAnimations.
If not null, particles pick random values between rotationSpeedGraph and rotationSpeedGraph2.
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.
Sorting mode. Forces CPU simulation, so be careful.
- PARTICLESORT_NONE: No sorting, particles are drawn in arbitrary order. Can be simulated on GPU.
- PARTICLESORT_DISTANCE: Sorting based on distance to the camera. CPU only.
- PARTICLESORT_NEWER_FIRST: Newer particles are drawn first. CPU only.
- PARTICLESORT_OLDER_FIRST: Older particles are drawn first. CPU only.
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.
If not null, particles pick random values between velocityGraph and velocityGraph2.
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
booleanTrue 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
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
name | string | 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
EventHandlerSelf 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
name | string | The name of the event to test. |
Returns
booleanTrue 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.
const 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 handler functions, called 'test' with scope this
Parameters
name | string | Name of the event to unbind. |
callback | HandleEventCallback | Function to be unbound. |
scope | object | Scope that was used as the this when the event is fired. |
Returns
EventHandlerSelf 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
name | string | Name of the event to bind the callback to. |
callback | HandleEventCallback | Function that is called when event is fired. Note the callback is limited to 8 arguments. |
scope | object | Object to use as 'this' when the event is fired, defaults to current this. |
Returns
EventHandlerSelf 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
name | string | Name of the event to bind the callback to. |
callback | HandleEventCallback | Function that is called when event is fired. Note the callback is limited to 8 arguments. |
scope | object | Object to use as 'this' when the event is fired, defaults to current this. |
Returns
EventHandlerSelf for chaining.