repository·master·Indexed 23 days ago
https://github.com/prettymuchbryce/easystarjsAn asynchronous A* pathfinding library for HTML5 games and interactive projects. Version 0.4.4 provides an API to define walkable grids, set tile and point costs, and configure movement rules such as diagonal movement and corner cutting. It prevents main-thread blocking by calculating paths in chunks via a manual calculate() loop, though it also supports a synchronous mode.
To use the library, you must first create an instance of EasyStar.js. The initialization method differs based on your runtime.
Web (Browser):
var easystar = new EasyStar.js();Node.js:
var easystarjs = require('easystarjs');
var easystar = new easystarjs.js();// for node.js
var easystarjs = require('easystarjs');
var easystar = new easystarjs.js();To find a path, you must follow these steps:
findPath(startX, startY, endX, endY, callback). The callback receives the path (an array of points) or null if no path is found.easystar.calculate() (ideally on a ticker or setInterval) to process the pathfinding asynchronously.To prevent performance issues on large grids, you can limit the work done per tick using setIterationsPerCalculation(value).
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]];
easystar.setGrid(grid);
easystar.setAcceptableTiles([0]);
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);
}
});
// You must call this to start the asynchronous calculation
easystar.calculate();You can install easystarjs depending on your environment:
bin/ directory.bower install easystarjs.npm install easystarjsBy default, findPath() schedules a calculation that runs in chunks to avoid freezing the browser/environment. To actually process the pathfinding queue, you must call calculate() manually in your application loop (e.g., inside a requestAnimationFrame or a setInterval).
Each call to calculate() performs a set number of iterations. You can control this workload using setIterationsPerCalculation(n).
Workflow:
findPath(...) to add a request to the queue.calculate() repeatedly in your game/app loop.callback provided to findPath will trigger once the path is found or impossible.EasyStar constructor. This object will act as your pathfinding engine, where you configure the grid, tile costs, and movement rules before requesting paths.To use EasyStar, you must first define which tiles in your grid are considered "walkable" and provide the grid itself.
setAcceptableTiles() to specify which tile values are walkable. You can pass a single number or an array of numbers.setGrid() to provide a 2D array of numbers representing your map.If you do not call these methods before calling findPath(), the library will throw an error.
The following are the primary methods available on an EasyStar.js instance:
new EasyStar.js(): Constructor.setGrid(twoDimensionalArray): Sets the map grid.setAcceptableTiles(arrayOfAcceptableTiles): Defines walkable tiles.findPath(startX, startY, endX, endY, callback): Requests a path. Returns an instanceId if used with the ID-based signature.calculate(): Starts/continues the asynchronous calculation process.cancelPath(instanceId): Cancels a specific pathfinding task.EasyStar is a pathfinding library that uses the A* algorithm to find paths through a grid. To use it, you must first define the grid and the acceptable tiles (walkable areas).
setGrid(grid). The grid should be a 2D array.setAcceptableTiles(tiles) to specify which tile values are passable. You can pass a single number or an array of numbers.setTileCost(tile, cost) to assign specific weights to certain tiles, making some paths moreEasyStar provides several methods to customize how paths are calculated and how the environment is treated:
Movement Rules:
enableDiagonals(): Allows diagonal movement.enableCornerCutting(): Allows cutting through corners.setDirectionalCondition(x, y, [EasyStar.TOP, EasyStar.LEFT]): Restricts access to a tile to specific directions.Cost and Obstacles:
setTileCost(tileType, multiplicativeCost): Adjusts the cost of moving through specific tile types.setAdditionalPointCost(x, y, cost): Sets a specific cost for a single coordinate.avoidAdditionalPoint(x, y): Treats a specific coordinate as an obstacle.Performance and Execution:
setIterationsPerCalculation(someValue): Limits the number of iterations per calculate() call to prevent frame drops.enableSync(): Switches from asynchronous to synchronous calculation.cancelPath(instanceId): Cancels a pathfinding request using the ID returned by findPath.Force the pathfinder to avoid specific coordinates, even if they are marked as acceptable tiles.
avoidAdditionalPoint(x, y): Marks a coordinate as an obstacle.stopAvoidingAdditionalPoint(x, y): Removes the avoidance rule for a coordinate.stopAvoidingAllAdditionalPoints(): Clears all avoidance rules.You can restrict movement into or out of specific tiles by defining allowed directions. Use the constants exported by EasyStar to specify directions.
setDirectionalCondition(x, y, allowedDirections): Takes an array of direction strings (e.g., ['TOP', 'BOTTOM']).removeAllDirectionalConditions(): Clears all directional restrictions.If you want to prevent the pathfinder from ever stepping on a specific coordinate, regardless of whether that tile is marked as "acceptable," use the avoidance methods.
avoidAdditionalPoint(x, y): Adds a point to the avoidance list.stopAvoidingAdditionalPoint(x, y): Removes a point from the avoidance list.stopAvoidingAllAdditionalPoints(): Clears the entire avoidance list.