A Guide to Sparks

Welcome to the sparkseditor wiki!

Sparks.js is a javascript particle engine along the likes of Flint and StarDust particle engines. It uses the awesome javascript libraries Three.js and Tween.js

There isn't much documentation out there at the moment, but feel free to check out the examples and drop any questions.

To create an emitter, var sparksEmitter = new SPARKS.Emitter(new SPARKS.SteadyCounter(160)); SPARKS.SteadyCounter tells the Emitter to produce 160 particles in a second.

Initializers

All particles created in the system would be initialized. sparksEmitter.addInitializer(new SPARKS.Position( new SPARKS.PointZone( new THREE.Vector3(0,0,0) ) ) ); This particle emitter initialize all particles with a position from a zone point, specifically at coordinates (0,0,0)

sparksEmitter.addInitializer(new SPARKS.Lifetime(4,5)); Set a random lifetime each particle, between 4 to 5 seconds

sparksEmitter.addInitializer(new SPARKS.Target(null, callback)); This initializer runs the callback, and sets the return result of the callback to the particle's target.

sparksEmitter.addInitializer(new SPARKS.Velocity(new SPARKS.PointZone(new THREE.Vector3(0,100,00)))); This assigns a velocity to the particle, which moves units of 0 along x, 100 units along y, and 0 along z axis.

Actions

sparksEmitter.addAction(new SPARKS.Age()); Every time the particle engine updates, this ages the particle, and removes it if its dead.

sparksEmitter.addAction(new SPARKS.Move()); This moves the particle based on its velocity and acceleration

sparksEmitter.addAction(new SPARKS.RandomDrift(500,500,0)); This drifts the particle in a random amount of units in a second.

Callbacks

Use callbacks to tap into the particle events sparksEmitter.addCallback("created", onParticleCreated); sparksEmitter.addCallback("initialized", onParticleInitialized); sparksEmitter.addCallback("dead", onParticleDead);

Running

sparksEmitter.start(); Run the engine using its built in timer.

https://barionleg.github.io/sparkseditor/vendor/codemirror/manual.html

Sparks# Is a highly flexible particle system built using THREE.js. Sparks are defined by 3 major relationships Initializers, Actions, and Zones. As you can imagine _Initializers _are used to set up the particles initial state. _Actions _are carried out every frame, and the Sparks internal clock counts the time for each frame. _Zones _are used by both _Actions _and _Initializers _to define where things happen. The brilliant thing about sparks is you can define your own, or use the ones included as standard, heres how:

Particles

Sparks is a particle system, each particle has the following:

Lifetime- how many seconds the particle 'lives' age- how old the particle currenlty is energy- ??? isDead- has the particle died this frame position- where the particle is now velocity - the direction its heading in _oldvelocity- the direction it went in last frame

Emitters

Emitters put it all together, it does this by keeping stacks of objects that it calls in defined ways every frame. When you define your new emitter you need to give it counter to tell it how fast to emit its particles:

example = new SPARKS.Emitter(new SPARKS.SteadyCounter(150));

or you can create a fixed number of particles:

sparksEmitter = new SPARKS.Emitter(new SPARKS.ShotCounter(100));

You can then add 3 types of behaviours using the following methods:

.addInitializer()

.addAction()

.addCallback()

once you have added all your objects (find out more about them bellow) you must start() it all off

example.start()

Initializers## Must have the following method: .initialize = function( emitter, particle ) Defined Initializers### Lifetime(min,max) generates a random life between max and min Position (zone) calls** getLocation()** for the zone class upon Initialization, which usually generates a random location within that zone. Target (target, callback) The target is currently a THREE.Particle and the callback will act upon that target, allowing you access to the THREE.js API.

Action Classes## Must have an update = function(emitter, particle, time) method

Defined Actions### Age() particles will die if they live longer than their life time Move() moves the particle by a constant velocity Death Zone() if a paritcle enters this zone it dies ActionZone() = function(action, zone) { You can define an action with an update function when a particle reaches a zone, which contain() funtion returns true. **Accelerate(x,y,z)**Increases velocity by the vector RandomDrift() Randomises the particle position by +/- 0.5 the vector dimensions

##Zones must have a getLocation() method this returns a random point within that zone, called on Initialization to fill the zone with random points contains(particle) does the zone contain the point - returns true or false

###Defined Zones PointZone() getLocation() returns the point

LineZone()

ParallelogramZone(corner, side1, side2) Rectangle

CubeZone()

SphereCapZone(x, y, z, minr, maxr, angle) not sure how minr, maxr, and angle relate

Callbacks and Events

Further callbacks can be added to enhance actions at specific points in the code:

addCallback: function(name, callback) { this.callbacks[name] = callback; },

##Pre-defined Events

Events are called once after all particles processed.

SPARKS.EVENT_PARTICLE_CREATED = "created" is called after all particles are Initialized.

SPARKS.EVENT_PARTICLE_UPDATED = "updated" is called after each particle is updated

SPARKS.EVENT_PARTICLE_DEAD = "dead"; is called if a particle dies

SPARKS.EVENT_LOOP_UPDATED = "loopUpdated"; is called once all particles have been updated.