JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Easystar.js

    An asynchronous A* pathfinding API written in Javascript.
    Filed under 

    • 🔾48%Overall
    • 1,883
    • 38.1 days
    • 🕩166
    • 👥14

    HTML5/Javascript Pathfinding Library

    Click here for a demonstration

    Installation

    • Web: Find the minified file in the /bin directory
    • node.js: npm install easystarjs
    • Phaser: see Phaser Plugin
    • Bower: bower install easystarjs

    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. ~7kb
    • Use it with any existing Javascript Framework
    • TypeScript support

    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.enableCornerCutting();
    
    easystar.setAdditionalPointCost(x, y, cost);
    
    easystar.setTileCost(tileType, multiplicativeCost);
    
    easystar.enableSync();
    
    easystar.setDirectionalCondition(x, y, [EasyStar.TOP, EasyStar.LEFT]); // only accessible from the top and left
    
    var instanceId = easystar.findPath(startX, startY, endX, endY, callback);
    // ...
    easystar.cancelPath(instanceId);
    

    Usage

    First create EasyStar.

    // for web
    var easystar = new EasyStar.js();
    
    // for node.js
    var easystarjs = require('easystarjs');
    var easystar = new easystarjs.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

    npm run test

    Support

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

    Show All