Classes

Path

Paths allow you to set any entity in motion onto a predefined path of x,y coordinates. There are two types of Paths: absolute and relative. An entity on an absolute path will follow the x,y coordinates exactly, no matter where its starting point was. An entity on a relative path will follow the x,y coordinates in a relative fashion, regardless of where its starting point is. Consider the following examples:


	GAME.initPaths(function(){
		// this is an absolute path
		var path1 = GAME.Path.create({
			name: 'path1',

			points: [	
				{x:32, y:32, callback:function(obj){
					obj.spin({degrees:16});
				}},

				{x:GAME.width-32, y:32, callback:function(obj){
					obj.blink();
				}},

				{x:GAME.width-32, y:GAME.height-32, callback:function(obj){
					obj.pulse({scaleX:0.5, scaleY:0.5}); 
				}}
			],

			speed: 1
			relative: false,
			loop: false
		});

		// this is a relative path
		var pathrel = GAME.Path.create({
			name: 'path-rel',

			points: [	
				{x:0, y:-32, callback:function(obj){
					console.log('rel checkpoint 1');
				}},

				{x:32, y:-32, callback:function(obj){
					console.log('rel checkpoint 2'); 
				}},

				{x:32, y:0, callback:function(obj){
					console.log('rel checkpoint 3');
				}}
			],

			speed: 1,
			relative: true,
			loop: true
		});	
	});

The main difference between the two paths in the example above is the manner in which the x,y point coordinates are set. In a relative path the coordinates are set like a +/- vector, which is interpreted as "this point is plus or minus this many pixels from the entity's starting point".

TIP: you have to set the path object's relative flag to TRUE if creating a relative path; the default is FALSE.

Once your paths have been initialized in the GAME.initPaths() function, you attach them to entity objects in either the GAME.initEntities() or GAME.initEntitiesChildren() init functions via an entity object's setPath() method. The following example builds on the previous example up top to show you how this is done:


	GAME.initEntities(function(){
		var enemy = GAME.Sprite.create('enemy', {x:32, y:GAME.height-32});
		
		enemy.onCreate(function(obj){
			obj.setPath('path1', {speed:4, loop:true, collide:true});
		});
		
		enemy.onUpdate(function(obj){
			if (obj.placeMeeting(obj.x, obj.y, {name:'player'})){
				obj.path.reverse();
			}
		});
	});

As you can see in the above example, once a path has been attached to an entity, you can access its properties and events via its parent entity's path property.

Methods (static)

Name Type Parameter Description
create* options.nameStringname of path, used for attaching to entity via obj.setPath()
* options.pointsArrayan array of objects, each containing the following properties:

- * x: x coordinate of this point, for attached entity to move to.
- * y: y coordinate of this point, for attached entity to move to.
- speed: speed at this point, of attached entity.
- callback: a function to execute when this point has been reached.
options.speedNumberspeed of attached entity object. (default: 1)
options.loopBooleanloops the path when end is reached, if set to TRUE. (default: FALSE)
options.relativeBooleanmakes path coordinates relative, if set to TRUE. (default: FALSE)
options.collideBooleanattached entity will collide with other objects, if set to TRUE; otherwise will go through objects. (default: FALSE)

Properties (object)

Name Type Description
nameStringthe name of the Path reference. **read-only**
speedNumbergets/sets the global speed. (default: 1)
loopBooleangets/sets whether the path is looped. (default: FALSE)
relativeBooleangets/sets whether the path is relative. (default: FALSE)
collideBooleangets/sets whether the path can collide with other entities. (default: FALSE)
startedBooleanis TRUE if path has already started. **read-only**
endedBooleanis TRUE if path has ended. **read-only**
reversedBooleanis TRUE if path has reversed. **read-only**
pausedBooleanis TRUE if path has been paused. **read-only**

Methods (object)

Name Type Parameter Description
pausecallbackFunctiona function to execute after path is paused.
resumecallbackFunctiona function to execute after path is resumed.
reversecallbackFunctiona function to execute after path is reversed.

TIP: to destroy an entity object's path, simply do the following: obj.setPath(false), where 'obj' is the entity instance you are dealing with.

Events (object)

Name Type Parameter Description
onStartcallbackFunctiona function execute when the path starts.
onEndcallbackFunctiona function to execute when the path ends.