arcanis / sparkle

WebGL particle engine

Sparkle

Basic Usage

With Three.js

var emitter;
scene.add( emitter = new SPARKLE.THREE.Emitter( {
    count : 1000,

    frequency : .05, // should be shortest lifetime divided by particle count
    lifeTime : SPARKLE.lineZone( 1, 1.5 ),
    fading : true,

    color : SPARKLE.cuboidZone( .2, 0, 0 ),
    velocity : SPARKLE.sphereZone( 10 )
} ) );

var render = function ( ) {
    window.requestAnimationFrame( render );
    emitter.update( clock.getDelta( ) );
    renderer.render( scene, camera );
};

Without Three.js

var emitter = new SPARKLE.Emitter( );

emitter.initializer( SPARKLE.lifeTimeInitializer( SPARKLE.lineZone( 1, 1.15 ) ) );
emitter.initializer( SPARKLE.velocityInitializer( SPARKLE.SphereZone( 10 ) ) );

emitter.action( SPARKLE.AgeAction( ) );
emitter.action( SPARKLE.MoveAction( ) );
emitter.action( SPARKLE.FadeAction( ) );

emitter.onWakeUp = myCustomRenderer.onWakeUp;
emitter.onUpdate = myCustomRenderer.onUpdate;
emitter.onSleep = myCustomRenderer.onSleep;

emitter.spawn( 1000, 10 );

setInterval( function ( ) {
    emitter.update( 1000 / 60 );
}, 1000 / 60 );

Example (More examples)

Reference

Initializers

An initializer is a function which, when called with some options as parameter, will return another function which takes an array as parameter and will set the three first field of this array to some numeric values of its choice.

SPARKLE.LifeTimeInitializer( zone )

The resulting function will set the particles lifetimes to random values equal to the length of a vector generated by zone.

Note : To use a linear range, which you probably want, you can use SPARKLE.lineZone( min, max ) as zone parameter.

SPARKLE.PositionInitializer( zone )

The resulting function will set the particles positions to random points inside zone.

SPARKLE.VelocityInitializer( zone )

The resulting function will set the particles velocities to random values from zone.

SPARKLE.THREE.ColorInitializer( zone ) (Three.js only)

Will set the particle color to a random value from zone. X, Y and Z values will be respectively mapped on R, G and B.

Actions

An action is a function, when called with some options as parameter, will return another function taking two parameters (a particle object and a delta time) and affecting that particle in some way when requested. Some actions sometimes depend on some initializers (or even other actions).

SPARKLE.accelerateAction( zone )

The resulting function will constantly increase particles velocity. Requires a Velocity initializer.

SPARKLE.ageAction( [ canDie ] )

The resulting function will age particles, then kill it (except if canDie is set to false). Requires a LifeTime initializer.

SPARKLE.moveAction( )

The resulting function will move particles. Requires both Position and Velocity initializers.

SPARKLE.fadeAction( [ fn ] )

The resulting function will change particles change according to their age. fn can be a function taking the particle age as parameter (this age being in a [0 ; 1] range), and returning the particle opacity. Requires a LifeTime initializer.

SPARKLE.pulseAction( [ fn ] )

The resulting function will change particles size according to their age. fn can be a function taking the particle age as parameter (this age being in a [0 ; 1] range), and returning the particle size. Requires a LifeTime initializer.

Zones

An action is a function which, when called with some options as parameter, will return another function taking an array as parameter, and modifying the first three fields of this array to numeric values.

They often represent a random point inside a shape.

Note : A zone can also be a simple vector-compatible array (at least three numeric parameters). In this case, the zone will be considered as having a single point.

SPARKLE.asyncZone( fn [, context] )

Immediately calls fn with the specified context, passing it a function as parameter. This function takes a Zone as parameter, and set it as the 'real' zone.

As long as this callback is not alled, the AsyncZone will always return a null position.

SPARKLE.cuboidZone( sx, sy, sz [, inner ] )

Represents a cuboid.

SPARKLE.lineZone( ex )

SPARKLE.lineZone( bx, ex )

SPARKLE.lineZone( ex, ey, ez )

SPARKLE.lineZone( bx, by, bz, ex, ey, ez )

Represents a line.

Note : bx, by, bz and ex, ey, ez can both be omitted by passing a vector-compatible arrays instead.

SPARKLE.sphereZone( r, inner, uniform )

Represents a sphere.

SPARKLE.arrayZone( points )

Represents an array of coordinates.

SPARKLE.THREE.GeometryZone( geometry ) (Three.js only)

Represents a Three.js geometry.

The points will always be at the surface of the geometry.

Textures (Three.js only)

These functions are utilitary : they allow to easily create base texture for particles.

`SPARKLE.THREE.circle( resolution [, options ] )

Creates a texture with a white circle. Allowed options are :

• stops, an object where keys are stop offsets and values are stop opacities.

License

Copyright (C) 2013 Maël Nison

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.