mig38m / hexagonal.js

Hexagon and Hexagonal Map library in JS

Hexagonal Map for JS

Hexagon and Hexagonal Maps management library written in Javascript.

• Post on the dev blog about Hexagonal.js
• Demos

API

The Hexagon object

An hexagon can be inscribed in a circle, so you can create one passing the circumference radius and, optionally, the circumference center:

// Regular hexagon inscribed in a circle with center in 5,5 and a radius of 10
hexagon = Hexagonal.Hexagon.byRadius 10, center: { x: 5, y: 5 }

You can create an hexagon with a given size:

// Regular hexagon with a height of 10 and width of 10 * sqrt(3)/2
hexagon = Hexagonal.Hexagon.bySize { height: 10 }
// Hexagon with a width of 10 and a height of 5
hexagon = Hexagonal.Hexagon.bySize { width: 10, height: 5 }

Both the methods above will create the vertices collections. But if you want you can create an hexagon passing your custom vertices:

// A weird hexagonal polygon
vertices = (new Hexagonal.Vertex(i*5, i*10) for i in [0...6])
hexagon = Hexagonal.Hexagon.byVertices vertices

To each of the methods described above you can pass additional options to customize the hexagon:

• flatTopped (default: false) By default the hexagon is treated as pointly topped. If you want to have a flat topped hexagon, set this value to true.
• position (default: new Hexagonal.Point(0, 0)) Set this if you want to place the hexagon in a specific position

Hexagonal Map

// map of 10x10 composed by regular hexagons with a width of 10
new Hexagonal.Map({cols: 10, rows: 10, hexagon: { width: 10 }})
// map of 10x10 composed by hexagons with a size of 2x3
new Hexagonal.Map({cols: 10, rows: 10, hexagon: { width: 2, height: 3 }})
// map of 10x10 composed by regular hexagons inscribed in a circumference with
// a radius of 10
new Hexagonal.Map({cols: 10, rows: 10, hexagon: { radius: 10 }})
// map of 10x10 with a total width of 500. The total width will be divided by
// cols to obtain each hexagon width
new Hexagonal.Map({cols: 10, rows: 10, width: 500})
// map of 10x10 with a total width of 500 and a total height of 500. The total
// width and height will be divided by cols and rows to obtain each hexagon size
new Hexagonal.Map({cols: 10, rows: 10, width: 500, height: 500})

In addition you can use the following options when building a new map:

• flatTopped (default: false) By default the map will be composed by pointly topped hexagons. Set it to true if you want to use flat topped hexagons.
• offsetLayout (default: 'odd') Set it to 'even' you want to change the layout (shifting even rows/cols instead of odd rows/cols).

Once you have the map, you can choose which Cursor you want to use to navigate it:

Offset Cursor

map = new Hexagonal.Map({rows: 5, cols: 5, hexagon: { radius: 5 }})
cursor = new Hexagonal.Cursors.Offset(map, 0, 0) // offset cursor, set in 0,0 (first hexagon)
cursor.moveTo(2, 2) // move to the center and returns the current hexagon
cursor.hexagon // => returns the current hexagon

Axial Cursor

map = new Hexagonal.Map({rows: 5, cols: 5, hexagon: { radius: 5 }})
cursor = new Hexagonal.Cursors.Axial(map, 0, 0) // offset cursor, set in 0,0 (map center)
cursor.moveTo(2, 2) // move to the last hexagon of the map and returns the current hexagon
cursor.hexagon // => returns the current hexagon

Cursors can be easily converted back and forth passing the current cursor to the new one's constructor:

map = new Hexagonal.Map({rows: 5, cols: 5, hexagon: { radius: 5 }})
offset = new Hexagonal.Cursors.Offset(map, 0, 0)
axial = new Hexagonal.Cursors.Axial(offset)

Precision

To arginate floating point rounding errors each calculation in Hexagonal will be rounded to 1 decimal digit. If you want to change it, you can set how many decimal digits to use:

Hexagonal.precision() // => 1
Hexagonal.Util.round(3.123) // => 3.1
Hexagonal.precision(2)
Hexagonal.Util.round(3.12) // => 3.12
Hexagonal.precision(null) // => disable rounding

Tests

Use grunt to run tests and compile into javascript. Running grunt will:

1. compile src/hexagonal/index.coffee into build/hexagonal.js (via browserify)
2. compile specs/**/*_spec.coffee into build/specs.js and specs/spec_helper.coffee into build/spec_helper.js
3. run the test suite using jasmine + phantomjs
4. clean build/specs.js and build/spec_helper.js