hex-grid.js v1.3.1

hex-grid.js

A JavaScript library for working with hexagonal grids.

With inspiration from http://www.redblobgames.com/grids/hexagons.

Running the tests

After installing development dependencies using npm install you should be able to run the tests using:

mocha

Library

hex-grid

Exports a constructor taking an options object.

Example

var HexGrid = require('hex-grid.js');

var TileFactory = function () {
  var _id = 0;
  return {
    newTile: function () {
      var tile = {
        id: _id.toString()
      };

      _id += 1;
      return tile;
    }
  };
};

var tileFactory = new TileFactory();
var hexGrid = new HexGrid({
  width: 20,
  height: 10,
  orientation: 'flat-topped',
  layout: 'odd-q',
  tileFactory: tileFactory
});

• hex-grid
  • HexGrid ⏏
    • new HexGrid(options)
    • .getWidth() ⇒ number
    • .getHeight() ⇒ number
    • .isWithinBoundaries(x, y) ⇒ bool
    • .getTileByCoords(x, y) ⇒ tile | null
    • .getTileIterator() ⇒ object
    • .isValidDirection() ⇒ bool
    • .getCoordsById(tileId) ⇒ object | null
    • .getTileById(tileId) ⇒ object | null
    • .getNeighbourByCoords(x, y, dir) ⇒ object | null
    • .getNeighbourById(tileId, dir) ⇒ object | null
    • .getNeighboursById(tileId) ⇒ Array.<object>
    • .getPositionByCoords(x, y) ⇒ object
    • .getPositionById(tileId) ⇒ object
    • .getShortestPathsFromTileId(tileId, options) ⇒ object

HexGrid ⏏

A hexagonal grid.

Kind: Exported class
See: http://redblobgames.com/grids/hexagons for explanations of options.orientation and options.layout.

new HexGrid(options)

hexGrid.getWidth() ⇒ number

Gets the width of the grid.

Kind: instance method of HexGrid
Returns: number - The width of the grid.

hexGrid.getHeight() ⇒ number

Gets the height of the grid.

Kind: instance method of HexGrid
Returns: number - The height of the grid.

hexGrid.isWithinBoundaries(x, y) ⇒ bool

Returns whether a coordinate is within the grid boundaries.

Kind: instance method of HexGrid
Returns: bool - Whether the coordinate is within the boundaries of the grid.

hexGrid.getTileByCoords(x, y) ⇒ tile | null

Gets a specific tile by its x and y coordinates.

Kind: instance method of HexGrid
Returns: tile | null - The tile. Null if not a valid coordinate.

hexGrid.getTileIterator() ⇒ object

Returns an iterator with a next() function that iterates through the tiles in the grid.

Kind: instance method of HexGrid
Returns: object - The iterator object.

hexGrid.isValidDirection() ⇒ bool

Whether a given direction is valid for this map layout.

Kind: instance method of HexGrid
Returns: bool - Whether the direction is valid.

hexGrid.getCoordsById(tileId) ⇒ object | null

Gets the coordinates of a tile given its ID.

Kind: instance method of HexGrid
Returns: object | null - An object with x and y properties.

hexGrid.getTileById(tileId) ⇒ object | null

Gets a tile given its ID.

Kind: instance method of HexGrid
Returns: object | null - The tile.

hexGrid.getNeighbourByCoords(x, y, dir) ⇒ object | null

Gets a tile's neighbour given its coordinates and a direction.

Kind: instance method of HexGrid
Returns: object | null - The neighbouring tile.

hexGrid.getNeighbourById(tileId, dir) ⇒ object | null

Gets a tile's neighbour given the tile's ID and a direction.

Kind: instance method of HexGrid
Returns: object | null - The neighbouring tile.

hexGrid.getNeighboursById(tileId) ⇒ Array.<object>

Gets all neighbours of a tile given the tile's ID.

Kind: instance method of HexGrid
Returns: Array.<object> - The neighbouring tiles.

hexGrid.getPositionByCoords(x, y) ⇒ object

Gets the position of a tile by its coordinates. Due to the way hexagonal grids work, the position of half of the tiles are offset by 0.5.

Kind: instance method of HexGrid
Returns: object - An object with x and y properties.

hexGrid.getPositionById(tileId) ⇒ object

Gets the position of a tile by its ID.

Kind: instance method of HexGrid
Returns: object - An object with x and y properties.

hexGrid.getShortestPathsFromTileId(tileId, options) ⇒ object

Gets all shortest paths from a given starting tile.

Kind: instance method of HexGrid
Returns: object - An object where the keys are the final tileId in a path and the values are Path objects. The Path object looks like this: { tileIds: tileId1, tileId2, ..., tileIdN, cost: 0 }

The tileIds are the tile IDs traversed in order, including the starting and final tile.

The cost it the total cost of traversing the path. The cost of each step of the path is determined by calling options.pathCost(fromTile, toTile), or 0 if options.pathCost is not supplied.

The zero-length path from a tile to itself is not returned.