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
count	Number	the number of active (not destroyed) particles on screen. read-only
limit	Number	the 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
createParticle	creates 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.
	* assetName	String	an existing Sprite asset. (TIP: can have animation frames!)
	* options.name	String	name of the particle entity.
	options.???	Mixed	see Core > Entity : Properties for available properties.
createEmitter	creates an emitter entity for use in a system.
	* options.name	String	name of the emitter entity.
	options.type	String	type of emitter; stream or burst. (default: 'burst')
	* options.particleName	String	existing particle entity name.
	options.particleCount	Number	number of particles. (default: 1) NOTE: only applies when type* is 'burst'*.
	options.particleDelay	Number	delay (in milliseconds) between each particle. (default: 100)
createSystem	creates a system entity for instantiation in a Room.
	* options.name	String	name of particle system.
	* options.emitters	Array	emitter entity names.
addSystem	instantiates a particle system into the current Room.
	* name	String	existing particle system name.
	* options.x	String	x coordinate of particle system. If the follow property is set, then this x value is relative. (if not specified, will be 0)
	* options.y	String	y coordinate of particle system. If the follow property is set, then this y value is relative. (if not specified, will be 0)
	options.foreground	Boolean	if set to TRUE, will render in front of all other non-foreground entities. (default: FALSE)
	options.persistent	Boolean	if set to TRUE, will automatically be created in every Room (create event is only executed when first instantiated).
	options.follow	Boolean	name 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.
destroySystem	destroys 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.
	* name	String	existing particle system name.

Properties (object)

See Core > Entity : Properties for available properties.

Events (object)

See Core > Entity : Events for available events.