# hex-grid.js

> A library for working with hexagonal grids.

Latest version **1.3.1** (published 2015-09-06) · ISC license · 0 weekly downloads

## Install

```sh
npm install hex-grid.js
pnpm add hex-grid.js
yarn add hex-grid.js
bun add hex-grid.js
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.1 |
| Published | 2015-09-06 |
| First published | 2015-02-21 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 64 |
| Author | James Pickard |
| Maintainers | euoia |
| Keywords | hex, hexagonal, grid, grids, hex grid, map, maps, library |

## Links

- npm: https://www.npmjs.com/package/hex-grid.js
- Repository: https://github.com/euoia/hex-grid
- Homepage: https://github.com/euoia/hex-grid.js
- Issues: https://github.com/euoia/hex-grid.js/issues
- npm.io page: https://npm.io/package/hex-grid.js

## Alternatives

- [@lexical/table](https://npm.io/package/@lexical/table.md) — 3.0M weekly downloads
- [mantine-datatable](https://npm.io/package/mantine-datatable.md) — 98.2K weekly downloads
- [react-native-collapsible-tab-view](https://npm.io/package/react-native-collapsible-tab-view.md) — 70.6K weekly downloads
- [@handsontable/vue3](https://npm.io/package/@handsontable/vue3.md) — 16.1K weekly downloads
- [vuewordcloud](https://npm.io/package/vuewordcloud.md) — 7.2K weekly downloads

## Recent versions

- 1.3.1 (latest) — 2015-09-06
- 1.3.0 — 2015-09-06
- 1.2.2 — 2015-06-17
- 1.2.0 — 2015-04-26
- 1.1.0 — 2015-04-26
- 1.0.0 — 2015-02-24
- 0.9.2 — 2015-02-21
- 0.9.1 — 2015-02-21
- 0.9.0 — 2015-02-21

## README

hex-grid.js
===========
A JavaScript library for working with hexagonal grids.

With inspiration from
[http://www.redblobgames.com/grids/hexagons](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
-------
  <a name="module_hex-grid"></a>
## hex-grid
Exports a constructor taking an options object.

**Example**  
```js
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](#module_hex-grid)
  * [HexGrid](#exp_module_hex-grid--HexGrid) ⏏
    * [new HexGrid(options)](#new_module_hex-grid--HexGrid_new)
    * [.getWidth()](#module_hex-grid--HexGrid+getWidth) ⇒ <code>number</code>
    * [.getHeight()](#module_hex-grid--HexGrid+getHeight) ⇒ <code>number</code>
    * [.isWithinBoundaries(x, y)](#module_hex-grid--HexGrid+isWithinBoundaries) ⇒ <code>bool</code>
    * [.getTileByCoords(x, y)](#module_hex-grid--HexGrid+getTileByCoords) ⇒ <code>tile</code> &#124; <code>null</code>
    * [.getTileIterator()](#module_hex-grid--HexGrid+getTileIterator) ⇒ <code>object</code>
    * [.isValidDirection()](#module_hex-grid--HexGrid+isValidDirection) ⇒ <code>bool</code>
    * [.getCoordsById(tileId)](#module_hex-grid--HexGrid+getCoordsById) ⇒ <code>object</code> &#124; <code>null</code>
    * [.getTileById(tileId)](#module_hex-grid--HexGrid+getTileById) ⇒ <code>object</code> &#124; <code>null</code>
    * [.getNeighbourByCoords(x, y, dir)](#module_hex-grid--HexGrid+getNeighbourByCoords) ⇒ <code>object</code> &#124; <code>null</code>
    * [.getNeighbourById(tileId, dir)](#module_hex-grid--HexGrid+getNeighbourById) ⇒ <code>object</code> &#124; <code>null</code>
    * [.getNeighboursById(tileId)](#module_hex-grid--HexGrid+getNeighboursById) ⇒ <code>Array.&lt;object&gt;</code>
    * [.getPositionByCoords(x, y)](#module_hex-grid--HexGrid+getPositionByCoords) ⇒ <code>object</code>
    * [.getPositionById(tileId)](#module_hex-grid--HexGrid+getPositionById) ⇒ <code>object</code>
    * [.getShortestPathsFromTileId(tileId, options)](#module_hex-grid--HexGrid+getShortestPathsFromTileId) ⇒ <code>object</code>

<a name="exp_module_hex-grid--HexGrid"></a>
### HexGrid ⏏
A hexagonal grid.

**Kind**: Exported class  
**See**: [http://redblobgames.com/grids/hexagons](http://redblobgames.com/grids/hexagons) for explanations of
`options.orientation` and `options.layout`.  
<a name="new_module_hex-grid--HexGrid_new"></a>
#### new HexGrid(options)

| Param | Type | Description |
| --- | --- | --- |
| options | <code>array</code> | HexGrid options. |
| [options.width] | <code>number</code> | The width of the map. |
| [options.height] | <code>number</code> | The height of the map. |
| [options.tileFactory] | <code>tileFactory</code> | 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] | <code>string</code> | The orientation of the map. Must be one of: flat-topped, pointy-topped. |
| [options.layout] | <code>string</code> | The layout of the map. Must be one of: odd-q, even-q, odd-r, even-r. |

<a name="module_hex-grid--HexGrid+getWidth"></a>
#### hexGrid.getWidth() ⇒ <code>number</code>
Gets the width of the grid.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>number</code> - The width of the grid.  
<a name="module_hex-grid--HexGrid+getHeight"></a>
#### hexGrid.getHeight() ⇒ <code>number</code>
Gets the height of the grid.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>number</code> - The height of the grid.  
<a name="module_hex-grid--HexGrid+isWithinBoundaries"></a>
#### hexGrid.isWithinBoundaries(x, y) ⇒ <code>bool</code>
Returns whether a coordinate is within the grid boundaries.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>bool</code> - Whether the coordinate is within the boundaries of the
grid.  

| Param | Type | Description |
| --- | --- | --- |
| x | <code>number</code> | The X coordinate. |
| y | <code>number</code> | The Y coordinate. |

<a name="module_hex-grid--HexGrid+getTileByCoords"></a>
#### hexGrid.getTileByCoords(x, y) ⇒ <code>tile</code> &#124; <code>null</code>
Gets a specific tile by its x and y coordinates.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>tile</code> &#124; <code>null</code> - The tile. Null if not a valid coordinate.  

| Param | Type | Description |
| --- | --- | --- |
| x | <code>number</code> | The X coordinate. |
| y | <code>number</code> | The Y coordinate. |

<a name="module_hex-grid--HexGrid+getTileIterator"></a>
#### hexGrid.getTileIterator() ⇒ <code>object</code>
Returns an iterator with a next() function that iterates through the
tiles in the grid.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> - The iterator object.  
<a name="module_hex-grid--HexGrid+isValidDirection"></a>
#### hexGrid.isValidDirection() ⇒ <code>bool</code>
Whether a given direction is valid for this map layout.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>bool</code> - Whether the direction is valid.  
<a name="module_hex-grid--HexGrid+getCoordsById"></a>
#### hexGrid.getCoordsById(tileId) ⇒ <code>object</code> &#124; <code>null</code>
Gets the coordinates of a tile given its ID.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> &#124; <code>null</code> - An object with x and y properties.  

| Param | Type | Description |
| --- | --- | --- |
| tileId | <code>string</code> | The ID of the tile. |

<a name="module_hex-grid--HexGrid+getTileById"></a>
#### hexGrid.getTileById(tileId) ⇒ <code>object</code> &#124; <code>null</code>
Gets a tile given its ID.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> &#124; <code>null</code> - The tile.  

| Param | Type | Description |
| --- | --- | --- |
| tileId | <code>string</code> | The ID of the tile. |

<a name="module_hex-grid--HexGrid+getNeighbourByCoords"></a>
#### hexGrid.getNeighbourByCoords(x, y, dir) ⇒ <code>object</code> &#124; <code>null</code>
Gets a tile's neighbour given its coordinates and a direction.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> &#124; <code>null</code> - The neighbouring tile.  

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

<a name="module_hex-grid--HexGrid+getNeighbourById"></a>
#### hexGrid.getNeighbourById(tileId, dir) ⇒ <code>object</code> &#124; <code>null</code>
Gets a tile's neighbour given the tile's ID and a direction.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> &#124; <code>null</code> - The neighbouring tile.  

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

<a name="module_hex-grid--HexGrid+getNeighboursById"></a>
#### hexGrid.getNeighboursById(tileId) ⇒ <code>Array.&lt;object&gt;</code>
Gets all neighbours of a tile given the tile's ID.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>Array.&lt;object&gt;</code> - The neighbouring tiles.  

| Param | Type | Description |
| --- | --- | --- |
| tileId | <code>string</code> | The tile's ID. |

<a name="module_hex-grid--HexGrid+getPositionByCoords"></a>
#### hexGrid.getPositionByCoords(x, y) ⇒ <code>object</code>
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 <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> - An object with x and y properties.  

| Param | Type | Description |
| --- | --- | --- |
| x | <code>number</code> | The X coordinate of the tile. |
| y | <code>number</code> | The Y coordinate of the tile. |

<a name="module_hex-grid--HexGrid+getPositionById"></a>
#### hexGrid.getPositionById(tileId) ⇒ <code>object</code>
Gets the position of a tile by its ID.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> - An object with x and y properties.  

| Param | Type | Description |
| --- | --- | --- |
| tileId | <code>string</code> | The tile's ID. |

<a name="module_hex-grid--HexGrid+getShortestPathsFromTileId"></a>
#### hexGrid.getShortestPathsFromTileId(tileId, options) ⇒ <code>object</code>
Gets all shortest paths from a given starting tile.

**Kind**: instance method of <code>[HexGrid](#exp_module_hex-grid--HexGrid)</code>  
**Returns**: <code>object</code> - 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 | <code>string</code> | The tile's ID. |
| options | <code>object</code> | An options object. |
| options.maxCost | <code>number</code> | The maximum allowed cost of a path, or POSITIVE_INFINITY if not specified. If specified, a pathCost function must be provided. |
| options.moveCost | <code>number</code> &#124; <code>function</code> | 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. |

---
_Source: https://npm.io/package/hex-grid.js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._