Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/arcanis/sparkle

WebGL particle engine
https://github.com/arcanis/sparkle

Last synced: about 2 months ago
JSON representation

WebGL particle engine

Awesome Lists containing this project

README 

        
# Sparkle



## Basic Usage



### With Three.js



```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



```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](http://arcanis.github.io/sparkle/example/) ([More examples](http://imgur.com/a/MMxnT))



[![Example](http://i.imgur.com/TJ7uKyB.png)](http://arcanis.github.io/sparkle/example/)



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