Classes

Particle

What game does not have some sort of particle effect? Even sprite-based games, with spritesheet animation systems, can benefit from a particle system. There are essentially three components to a particle system: particle, emitter, and system. A Particle is the graphic element which changes size, speed, color, etc.. over time, and ultimately fades away and destroys itself. An Emitter is responsible for the type of emission of particles; ie a continuous stream or a one-time burst, and can control multiple types of particles at once. A System is the container which is in charge of the positioning, movement, and state of any number of emitters.

Particles are first class objects! They share all the same properties and events with Sprites, which means quite a bit of flexibility for some robust effects. Creating your own custom particle effects is easy because the process is identical to creating Sprites. Consider the following example:


	GAME.initParticles(function(){
	
		var p1 = GAME.Particle.createParticle('circle', {
			name: 'ps-pt1',
			tint: '#0000ff',
			scaleX: 0.1,
			scaleY: 0.1,
			alpha: 0.5,
			blend: GAME.cons.BLEND.ADD
		});
		
		GAME.Particle.createEmitter({
			name: 'ps-em1',
			type: 'stream',
			x: -32,
			y: -8,
			particleName: 'ps-pt1',
			particleDelay: 60
		});

		GAME.Particle.createSystem({
			name: 'ps1',
			emitters: ['ps-em1']
		});	

		p1.onCreate(function(obj){
			obj.vspeed = -2;
			obj.angle = GAME.Util.randomInteger(0, 360);
			obj.spin({degrees:32});	
			obj.scale({scaleX:2, scaleY:2, time:2000});
			obj.fade({type:'out', time:1000});
		});
		
	});

TIP: try to use particle effects sparingly especially when considering mobile platforms, as all those extra objects on screen can really slow down performance (especially if they each have multiple effects). Whenever possible, if a simple effect can be achieved with a Sprite animation, it is best to do that instead.

Properties (static)

Name Type Description
countNumberthe number of active (not destroyed) particles on screen. **read-only**
limitNumberthe limit of active (not destroyed) particles on screen. This variable can be changed in GAME.vars.PARTICLE_LIMIT. (default: 100) **read-only**

Methods (static)

Name Type Parameter Description
createParticlecreates a particle entity for use in an emitter. Particles are basically a special kind of Sprite; therefore, they have the same properties, methods, and events. See Classes > Sprite for more information.
* assetNameStringan existing Sprite asset. (TIP: can have animation frames!)
* options.nameStringname of the particle entity.
options.???Mixedsee Core > Entity : Properties for available properties.
createEmittercreates an emitter entity for use in a system.
* options.nameStringname of the emitter entity.
options.typeStringtype of emitter; stream or burst. (default: 'burst')
* options.particleNameStringexisting particle entity name.
options.particleCountNumbernumber of particles. (default: 1)
NOTE: only applies when type is 'burst'.
options.particleDelayNumberdelay (in milliseconds) between each particle. (default: 100)
createSystemcreates a system entity for instantiation in a Room.
* options.nameStringname of particle system.
* options.emittersArrayemitter entity names.
addSysteminstantiates a particle system into the current Room.
* nameStringexisting particle system name.
* options.xStringx coordinate of particle system. If the follow property is set, then this x value is relative. (if not specified, will be 0)
* options.yStringy coordinate of particle system. If the follow property is set, then this y value is relative. (if not specified, will be 0)
options.foregroundBooleanif set to TRUE, will render in front of all other non-foreground entities. (default: FALSE)
options.persistentBooleanif set to TRUE, will automatically be created in every Room (create event is only executed when first instantiated).
options.followBooleanname of an entity to follow. If followed entity has more than one instance, will follow nearest instance. If followed instance no longer exists, will stop.
destroySystemdestroys a particle system (including all associated emitters and particles) with given name.

NOTE: when a particle system's followed object no longer exists, the corresponding particle system is also automatically destroyed.
* nameStringexisting particle system name.

Properties (object)

See Core > Entity : Properties for available properties.

Events (object)

See Core > Entity : Events for available events.