HTML5/Javascript Pathfinding Library

Find the minified file in the /bin folder.

Click here for a demonstration

Description

easystar.js is an asynchronous A* pathfinding API written in Javascript for use in your HTML5 games and interactive projects. The goal of this project is to make it easy and fast to implement performance conscious pathfinding.

Features

• Calculates asynchronously for better overall performance
• Simple API
• Small. ~5kb
• Use it with any existing Javascript Framework

API

Main Methods

var easystar = new EasyStar.js();

easystar.setGrid(twoDimensionalArray);

easystar.setAcceptableTiles(arrayOfAcceptableTiles);

easystar.findPath(startX, startY, endX, endY, callback);

easystar.calculate();

Additional Features

easystar.setIterationsPerCalculation(someValue);

easystar.avoidAdditionalPoint(x, y);

easystar.enableDiagonals();

easystar.setTileCost(tileType, multiplicativeCost);

Usage

First create EasyStar.

var easystar = new EasyStar.js();

Create a grid, or tilemap. You may have made this with a level editor, or procedurally. Let's keep it simple for this example.

var grid = [[0,0,1,0,0],
	   	    [0,0,1,0,0],
	        [0,0,1,0,0],
	        [0,0,1,0,0],
	        [0,0,0,0,0]];

Set our grid.

easystar.setGrid(grid);

Set tiles which are "walkable".

easystar.setAcceptableTiles([0]);

Find a path.

easystar.findPath(0, 0, 4, 0, function( path ) {
	if (path === null) {
		alert("Path was not found.");
	} else {
		alert("Path was found. The first Point is " + path[0].x + " " + path[0].y);
	}
});

EasyStar will not yet start calculating my path.

In order for EasyStar to actually start calculating, I must call the calculate() method.

You should call easystar.calculate() on a ticker, or setInterval.

If you have a large grid, then it is possible that these calculations could slow down the browser. For this reason, it might be a good idea to give EasyStar a smaller iterationsPerCalculation value via

easystar.setIterationsPerCalculation(1000); 

It may take longer for you to find a path this way, but you won't completely halt your game trying to find one. The only thing left to do now is to calculate the path.

easystar.calculate();

License

easystar.js is licensed under the MIT license. You may use it for commercial use.

Running the demo locally

In order to run the demo you will need node.js, and npm installed.

git clone https://github.com/prettymuchbryce/easystarjs.git

cd easystarjs/demo

npm install

node app.js

Open your browser to 127.0.0.1:3000 to see the example.

Testing

This project is setup to use the karma test runner.

Development Testing

run grunt karma:dev to start the karma test runner in dev mode. Once the karma server is up and running open http://localhost:9876 in your web browser. The tests will run automatically. View the results in your terminal window where you started the karma server. Editing any of the source or spec files will cause the tests to run again.

Coverage Testing

run grunt karma:coverage to run the karma server in test coverage mode. Once the test run is complete open coverage/Phantom**/index.html in your web browser to view the test coverage report.

once the karma server is running in test coverage mode you can visit http://localhost:9876 with any web browser to get a test coverage report for the connected browser.

Roadmap

• Better test coverage
• Performance and API improvements

Support

If you have any questions, comments, or suggestions please open an issue.