# HexGrid
[](https://travis-ci.org/rayalex/hexgrid)
Create hexagonal grids in Elixir. Provides basic computational and mapping support.
Work is based on [this excellent article](http://www.redblobgames.com/grids/hexagons/implementation.html) from [redblobgames](http://www.redblobgames.com/).
_See [hex package](https://hex.pm/packages/hexgrid/2.1.0) and [docs](https://hexdocs.pm/hexgrid/2.1.0) for more details._
## Installation
The package can be installed by listing it as a `hex` dependency:
```elixir
def deps do
[{:hexgrid, "~> 2.1"}]
end
```
## Usage
```elixir
alias HexGrid.Map, as: HexMap
alias HexGrid.Hex, as: Hex
```
## API
### Hex Tile
#### new(q, r, s)
Create a tile in a cube coordinate system.
Example:
```elixir
Hex.new(0, 0, 0)
```
#### neighbour(hex, direction)
Gets the neighbuoring hex. Neighbours are just offsets on the given hex:
```elixir
0 -> Hex.new(+1, -1, 0)
1 -> Hex.new(+1, 0, -1)
2 -> Hex.new(0, +1, -1)
3 -> Hex.new(-1, +1, 0)
4 -> Hex.new(-1, 0, +1)
5 -> Hex.new(0, -1, +1)
```
Example:
```elixir
Hex.neighbours(Hex.new(0, 0, 0))
```
#### neighbours(hex)
For a given hex tile, get all adjacent tiles.
Example:
```elixir
Hex.neighbours(Hex.new(0, 0, 0))
```
### Map
Provides support for creating and maintaining tile structures, as well as containing tile data.
_Note: Examples alias `HexGrid.Map` as `Map`_
#### new()
Creates an empty map.
Example:
```elixir
Map.new()
```
#### new_hex(radius)
Utility to create a hexagonal-shaped map with a given radius.
Example:
```elixir
Map.new_hex(5)
```
#### insert(map, tile)
Adds tile to the map.
Example:
```elixir
{:ok, map} = HexMap.new()
{result, map} = HexMap.insert(map, Hex.new(0, 0, 0))
```
#### set(map, tile, key, value)
Sets an arbitrary value on a map, for a given tile.
Example:
```elixir
hex = Hex.new(0, 0, 0)
{_, map} = HexMap.new()
{_, map} = HexMap.insert(map, hex)
{_, map} = HexMap.set(map, hex, :hello, :world)
```
#### get(map, tile, key)
Gets the value from the map, for a given tile.
Example:
```elixir
hex = Hex.new(0, 0, 0)
{_, map} = HexMap.new()
{_, map} = HexMap.insert(map, hex)
{_, map} = HexMap.set(map, hex, :hello, :world)
assert HexMap.get(map, hex, :hello) == {:ok, :world}
```
