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)

Param	Type	Description
options	array	HexGrid options.
[options.width]	number	The width of the map.
[options.height]	number	The height of the map.
[options.tileFactory]	tileFactory	A tileFactory object. A tileFactory is an object that has a newTile function property that when called returns a tile object. The tile objects returned by tileFactory.newTile() must have an id property which is unique across all tiles generated by the tileFactory.
[options.orientation]	string	The orientation of the map. Must be one of: flat-topped, pointy-topped.
[options.layout]	string	The layout of the map. Must be one of: odd-q, even-q, odd-r, even-r.

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.

Param	Type	Description
x	number	The X coordinate.
y	number	The Y coordinate.

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.

Param	Type	Description
x	number	The X coordinate.
y	number	The Y 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.

Param	Type	Description
tileId	string	The ID of the tile.

hexGrid.getTileById(tileId) ⇒ object | null

Gets a tile given its ID.

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

Param	Type	Description
tileId	string	The ID of 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.

Param	Type	Description
x	number	The X coordinate of the tile.
y	number	The Y coordinate of the tile.
dir	string	A direction. One of: north, northeast, east, southeast, south, southwest, west, northwest.

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.

Param	Type	Description
tileId	string	The tile's ID.
dir	string	A direction. One of: north, northeast, east, southeast, south, southwest, west, northwest.

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.

Param	Type	Description
tileId	string	The tile's ID.

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.

Param	Type	Description
x	number	The X coordinate of the tile.
y	number	The Y coordinate of the tile.

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.

Param	Type	Description
tileId	string	The tile's ID.

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.

Param	Type	Description
tileId	string	The tile's ID.
options	object	An options object.
options.maxCost	number	The maximum allowed cost of a path, or POSITIVE_INFINITY if not specified. If specified, a pathCost function must be provided.
options.moveCost	number | function	The cost of moving from one tile to another. If a function is provided, it is called like options.pathCost(fromTile, toTile) and it should return the cost of moving from fromTile to toTile. Defaults to 1.