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. |