Moscrif API Docs for: 2012q3
Show:

Emitter Class

include "lib://game2d/particle/emitter.ms";
Library: game2d

A particle system is a collection of independent objects, often represented by a simple shape or dot. It can be used to model many irregular types of natural phenomena, such as explosions, fire, smoke, sparks, waterfalls, clouds, fog, petals, grass, bubbles, and so on. Emitter manages the creation and ongoing state of particles. Emitter uses Initializers to customise the initial state of particles that it creates; their position, velocity etc. These are added to the emitter using the addParticle method. To ensure the proper functioning of emitter it is needed to call emiter's process function from game onProcess event.

Methods

addParticle

(
  • options
)
protected

Method to add particle. Options adjust the particle. This method is usually called automatically from Emitter.process method.

Parameters:

  • options Object

draw

(
  • canvas
)
protected

Method draw defines action whithin onDraw. It draws all particles from this emitter. Is is usally no need to overweite this method.

Parameters:

  • canvas Canvas

    Current game canvas

init

() protected

Init instance. The init method sets all needed emiter properties acording to developer requirements or to default values. This method is called when emiter object is constructed.

moveTo

(
  • point
)

Move emiter to new position.

Parameters:

  • point Vector

    position of emitter

process

(
  • fields
)

Process method makes time step for emitter. It creates new particles and destroys old particles.

Parameters:

  • fields Array

    Array of fields.

Properties

count

Integer

Number of particles

Example:

//process emitters
for (var emitter in emitters) {
    emitter.process(fields);
    console<<"current count of particles "<<emitter.count<<"\n";
}

emissionRate

Integer

Defines emission rate, default is set to 4. Emision rate is number of particles emited during one call of Emitter.process method.

Example:

new Emitter({
    emissionRate    : 5,
    ...
})

maxParticles

Integer

Maximum number of particles. If there are more particles, emitter does not emitt new particles. Value less then 1 means an infinite number of particles.

particleClass

Class

Class used to create particles - enables to create custom particles. This property accepts all classes extended from Particle class.

Example:

// custom paricle class
class MyParticle : Particle
{
    // static variables
    // static paint used by all instances to draw bitmap
    var paint = null;
    // static bitmap used by all instances
    var img = Bitmap.fromFile("app://fire.png");

    function init()
    {
        super.init();

        ...
    }

    // owerwrite ancestor's draw function
    function draw(canvas)
    {
        // set bitmap translate acording to actual particle position
        this._matrix.translateX = this._position.x;
        this._matrix.translateY = this._position.y;
        // draw custom particle bitmap
        canvas.drawBitmapMatrix(MyParticle.img, this._matrix, MyParticle.paint);
    }
}
...
new Emitter({
   ...
   particleClass   : MyParticle
})

particleLife

Integer

Time of the particle's existence in milliseconds, default is set to -1 (forever);

Example:

new Emitter({
    particleLife    : 100, // milliseconds
    ...
});

position

Vector

Vector of the emitter center in pixels.

Example:

new Emitter({
    // place emiter to the center of the screen
    position        : new Vector({x:System.width/2, y:System.height/2}),
    ...
)}

size

Integer

How large the particle is for rendering (doesn't affect particle dynamics or collision). Default size is 8.

spread

Float

Spread angle definition. Default is set to Math.PI / 32

Example:

new Emitter({
    spread          : Math.PI/10,
    ...
})

velocity

Vector

Velocity vector (direction and speed). The vector's direction is a direction of the center of particles stream. The particles variance can be customized by Emitter.spread property. The velocity also affects particles' speed. Positive values on x-axis are right and on the y-axis down from the emitter's center.

Example:

new Emitter({
    velocity        : new Vector({x:2, y:0}),
    ...
)};

Events

onParticleCreated

Event onParticleCreated, defines action after particle is created

Event Payload:

  • particle Object

    new particle

Example:

var emitter = new Emitter({
    position        : new Vector({x:System.width/2, y:System.height/2}),
    velocity        : new Vector({x:2, y:0}),
    size            : 8,
    particleLife    : 100,
    spread          : 2*Math.PI,
    emissionRate    : 1,
    maxParticles    : 1000;
})
emitter.onParticleCreated = function(particle)
{
  console<<"New particle created "<<particle<<"\n";
}

onParticleDestroyed

Event onParticleDestroyed, defines action after particle is destroyed

Event Payload:

  • particle Object

    destroyed particle

Example:

var emitter = new Emitter({
    position        : new Vector({x:System.width/2, y:System.height/2}),
    velocity        : new Vector({x:2, y:0}),
    size            : 8,
    particleLife    : 100,
    spread          : 2*Math.PI,
    emissionRate    : 1,
    maxParticles    : 1000;
})
emitter.onParticleDestroyed = function(particle)
{
    console<<"A particle destroyed "<<particle<<"\n";
}