Particle Emitter CreateJS

A CreateJS Container extension to make a Particle Emitter that controls the CreateJS DisplayObjects it emits and specified intervals

ParticleEmitter

Usage

All options for the emitter have default values: See examples folder:

    // The 'display' property below can be a CreateJS DisplayObject
    // an Array of Display Objects
    // or a Function that returns a DisplayObject
    
    // Function that just returns a single square shape
    let createSquare = function () {
        // Create a shape to be the particle
        let square = new createjs.Shape();
        square.graphics.beginFill("Red").drawRect(0, 0, 10, 10);
        square.set({ regX: 5, regY: 5 });
        return square;
    }

    //Function to be called when each particle's `play()` function is called
    let particlePlay = function(particle) {
        console.log(particle);
    }

    // Function to be called when the emitter's `stop()` function is called
    let emitterStop = function(emitter) {
        console.log(emitter);
    }

    // Settings for each particles
    let particleSettings = {
        display: createSquare,
        lifetime: { min: 1, max: 2 }, 
        moveSpeed: { min: 5, max: 10 },
        rotateSpeed: { min: -180, max: 180 },
        scaleEase: createjs.Ease.sineInOut,
        scaleOverTime: { start: 1, end: 0 },
        opacityEase: createjs.Ease.quadInOut,
        opacityOverTime: { start: 1, end: 0 },
        randomStartVelocity: { x: true, y: true },
        randomStartRotation: true,
        force: { x: 0, y: 0 },
        explode: false,
        implode: false,
        gravity: 9.8,
        playCallback: particlePlay
    };

    // Settings for the emitter
    let emitterSettings = {
        particle: particle, // The particleSettings object created above
        particleContainer: null,
        emitterType: {
            type: 'ring',
            size: { radius: 50 }
        },
        count: 30,
        rate: 0.1,
        loop: false,
        burst: false,
        startOn: true,
        prewarm: 0,
        stopCallback: emitterStop
    };

    return new ParticleEmitter(emitterSettings);

Particle Settings

display - The visual DisplayObject for the particle. Can be either a single DisplayObject, an Array of DisplayObjects, or a Function that returns a Display Object

lifetime - The min and max lifetime of each particle (random number between if values are different)

moveSpeed - The min and max movement speed for each particle (random number between if values are different)

rotateSpeed - The min and max rotation speed for each particle (random number between if values are different)

scaleEase - The CreateJS Ease Function to use for scaleOverTime property

scaleOverTime - The start and end value for scaling the particle over it's lifetime

opacityEase - The CreateJS Ease function to use for the opacityOverTime property

opacityOverTime - The start and end value for changing the alpha property of the particle over it's lifetime

randomStartVelocity - Does the particle get a random X and Y start velocity/direction

randomStartRotation - Does the particle get a random start rotation

force - The force to apply in the X and Y direction (wind)

** Note only one option 'explode' or 'implode' can be set to true not both **    
explode - Do the particles 'explode' outwards from the center of the emitter shape - does not work with 'point'

** Note only one option 'explode' or 'implode' can be set to true not both **
implode - Do the particles 'implode' towards the center of the emitter shape - does not work with 'point'

gravity - The Gravity force on the Y axis (pos or neg)

playCallback - Callback function to be called when a Particle's `play()` function is called. The function is passed the Particle that called the function (Optional)

stopCallback - Callback function to be called when a Particle's `stop()` function is called. The function is passed the Particle that called the function (Optional)

Emitter Settings

particle - An object containing some or all the Particle Settings listed above

particleContainer - The Parent container to add all particles too. Default is the ParticleEmitter itself

emitterType - The shape and size for the emitter - see examples folder for more info

count - The number of particles created and controlled in the pool

rate - The rate (speed) at which the particles are spawned over time (ignored if burst is true)

loop - Does the emitter loop or just play once (true / false)

burst - If set to `true` the emitter will spawn all the particles at once (takes precedence over rate)

startOn - Does the particle emitter play immediately or not (`.play()` call is required if false)

prewarm - Number of Frames to simulate - Simulate where the particle emitter would be after X number of frames - Use for emitters such as a waterfall effect that would have been pre-running before being visually loaded

playCallback - Callback function to be called when the emitter's `play()` function is called, called when instantion is complete if `startOn = true`. The function is passed the ParticleEmitter that called the function (Optional)

stopCallback - Callback function to be called when the emitter's `stop()` function is called, called when the last particle spawns if `loop = false`. The function is passed the ParticleEmitter that called the function (Optional)

new ParticleEmitter(settings)

Constructor

Param	Type	Description
settings	`Object`	Settings for the emitter and the particles it controls

particleEmitter.playCallback()

Callback the playCallback function if one was provided

particleEmitter.stopCallback()

Callback the stopCallback function if one was provided

particleEmitter.setSizeDefaults(type)

If we do not have a size for the emitter set some defaults

Param	Type	Description
type	`String`	Emitter Type from constructor settings

particleEmitter.prewarm(frames)

Prewarm, set, or calculate what the particle emitter would look at after jumping a number of frames ahead

Param	Type	Description
frames	`Number`	number of frames to calculate ahead of the particle emitter's starting position

particleEmitter._tick(event)

Update tick called internally - handled by CreateJS

Param	Type
event	`Event`

particleEmitter.spawnParticle()

Spawn a particle and increment the array tracker

particleEmitter.getRandomPos()

Set the particle position based on the emitter type we have

particleEmitter.getRandomBoxPosition()

Get a random position within a box or rectangle shape

particleEmitter.getRandomBorderPosition()

Get a random position position on the border of a box or rectangle shape

particleEmitter.getRandomCornerPosition()

Get a random position of the 4 corners of a box or rectangle shape

particleEmitter.getRandomCirclePosition()

Get a random position within a circle radius shape

particleEmitter.getRandomRingPosition()

Get random ring position

particleEmitter.createPool()

Create all the objects in a pool

particleEmitter.createDisplay(display)

Create a DisplayObject from either a Function, an Array, or a single DisplayObject

Param	Type	Description
display	`*`	DisplayObject / Array of DisplayObjects / Function that returns a DisplayObject

particleEmitter.getRandomDisplay(array)

Return a random display object from the Array

Param	Type	Description
array	`Array`	Array of DisplayObjects

particleEmitter.checkReady()

Check if all the particles are ready to play again - used for checking if we are ready for another Burst

particleEmitter.stopAllParticles()

Stop all the particles and the emitter

particleEmitter.play()

Play the emitter

particleEmitter.pause()

Pause the emitter

particleEmitter.resume()

Resume the playing of our emitter

particleEmitter.stop()

Stop the emitter

particleEmitter.reset()

Stop all the particles and the emitter and then play again

particleEmitter.stopAll()

Stop the particles and the emitter

particleEmitter.change(particleData)

Change the particles being emitted during runtime

Param	Type	Description
particleData	`Object`	new data for the particle settings

particleEmitter.setEmitter(settings)

Set the emitter object settings values

Param	Type	Description
settings	`Object`	Object with settings to change for the emitter Object

particleEmitter.setParticles(settings)

Set the particle object settings values

Param	Type	Description
settings	`Object`	Object with settings to change for the particle Object

@curiousmedia/particle-emitter-createjs