Byakugan-js NPM

Byakugan-js

Description

Byakugan-js is an array-based, super simple and lightweight implementation of A* pathfinding algorithm written in Typescript.

It's then compiled into JavaScript with ES 5 syntax.

The name Byakugan (白眼) was influenced by the manga series Naruto.

Demo: https://byakugan.js.org/ (please visit using either tablet or pc to see the demo).

Installation:

Node: npm install --save byakugan-js

Web: Use packages inside build/ or use one of the following CDNs:

Minified build:

<script src="https://cdn.jsdelivr.net/gh/rockmanvnx6/byakugan-js@master/dist/byakugan.min.js"></script>

Development build:

<script src="https://cdn.jsdelivr.net/gh/rockmanvnx6/byakugan-js@master/dist/byakugan.js"></script>

Quick start

Make sure Byakugan-js is installed via npm or included using CDN.

const Byakugan = require('byakugan-js'); // ignore if using CDN

const settings = {
        grid: [
            [1, 0, 0, 0],
            [1, 0, 0, 0],
            [0, 0, 0, 0],
            [0, 1, 0, 0],
            [0, 1, 1, 1],
            [0, 0, 0, 1],
        ],
        obstacles: [1,3], // Obstacle tiles
        diagonal: true, // Move diagonally, default false
}
const byakugan = new Byakugan(settings);
const paths = byakugan.search(0,1,3,3);

Methods:

search(row1, col1, row2, col2)

Return a 2D array which contains the coordinates of path.

Example:

let byakugan = new Byakugan(settings)
byakugan.search(0,1,3,3); // Find path from grid[0][1] to grid[3][3]

Return:

[ [1,1], [2,1], [2,2], [3,2], [3,3] ]

Settings Object

These are the available keys of the settings object

Key	Value
grid: `Array<Array<Number>>`	A 2D array describe the grid. Required
obstacles: `Array`	Array of obstacles value. `Default = [1]`
diagonal: `boolean`	`true/false` value to determine if the algorithm can go diagonally. `Default = false`
callbacks: `Object`	An object contain list of callbacks functions.
heuristics: `Object`	Select heuristic distance functions for type `normal` and `diagonal`. Use `override` to override the heuristic functions.

Callbacks

These are the list of available callback functions:

functions	description
`nodeConstructions(node)`	The function will be called after a node is constructed. It will pass a `object` type as the parameter the object will have the following values: `{ row: number, col: number, isObstacle: boolean}`

Heuristics

The available heuristic functions are:

Eucludian
Manhattan (default for normal (4 directions) movement)
Octile (default for diagonal (8 directions) movement)

The default settings were used based on this suggestions. Where for diagonal distance, Octile distance was chosen with D = 1 and D2 = sqrt(2).

To re-select/override a distance function, simply define in the settings object:

let settings = {
    grid: grid,
    heuristics: {
        normal: 'eucludian', // default Manhattan
        override: {
        	diagonal: function (a,b) {
                let dx = Math.abs(a.col - b.col);
                let dy = Math.abs(a.row - b.row);
                return 0.5 * (dx + dy)
            }
    	}
    }
}

The above configuration will use eucludian distance for normal movement and a custom function for diagonal movement.