Skip to content


Repository files navigation

Build Status Gem Version Code Climate Test Coverage


This repository contain a library for using a grid of hexagons with ruby.

  • It is a partial ruby implementation of the huge work of Amit Patel (
  • The hexagons are pointy topped.
  • The coordinate system is axial.
  • Only required methods are implemented in the cube object.


This gem has been tested with ruby 2.4, 2.5, 2.6


gem install rhex

Or in your gemfile :

gem 'rhex'

Then in your code :

require 'rhex'



# Create a new hexagon (q = 10, r = 10 )
# To understand what q and r mean, please have a look at
hexa = 10, 10 )
# => #<AxialHex @q=10, @r=10>

# Get hexes surrounding it
# => [#<AxialHex @q=10, @r=9>, #<AxialHex @q=11, @r=9>, ... ]

# Get distance between two hexagons
hexb = 20, 20 )
# => 20

# Check if a hex is adjacent to another hex
# => false

# Get the nearset hex from a hexes list
hexc = 20, 13 )
hlist = [ hexb, hexc ]
# => #<AxialHex @q=20, @r=13>

Hexagons grid

Hexagons by themselves are not really useful. What we need is an hexagon grid.

# Create an hexagon grid
g =
# => #<AxialGrid @hexes={}, @element_to_color_hash={}, @hex_ray=16, @hex_height=32.0, @hex_width=27.712812921102035, @half_width=13.856406460551018, @quarter_height=8.0>

# Add an hexagon to the grid
g.cset( 5, 8 )
# => #<AxialHex @q=5, @r=8, @border=false>

# Get an hexagon from the grid
g.cget( 5, 8 )
# => #<AxialHex @q=5, @r=8, @border=false>

g.cget( 5, 4 )
# => nil

Reading a grid from an ascii file

It will be far more fun to create your hex map from an ascii map. For example, if you have the following map :

m m g g m m m m m
 m g g g m m m m g
m g w w g m m m m
 m g w w w g m g g
g w w w w g g g w
 g w w w w w g g g
g g w w w g g g m
 g g g w w g g m m
g g g g w g g g g
 g g g g w g g g g
g g g g g w g g g
 g g g g w g g g g
g g g g w g g g g

Where m = mountains, g = grass and w = water. If this map is in a file called for instance : ascii_map.txt then :

# CAUTION : don't use an axial grid for that, your asciimap is square
g =

# Load it with 
g.read_ascii_file( 'test/ascii_map.txt' )

# Get an hex 
g.cget( 5, 5 )
# => <AxialHex @q=5, @r=5, @color="w", @data=nil>

# Get an hex value
g.cget( 5, 5 ).color
# => "w"

# Borders don't work, will be fixed
# Check if the hex is at the border of the map or not 
# g.cget( 5, 5 ).border
# => nil
# g.cget( 0, 0 ).border
# => true

Dumping an hex map (require rmagick - see

You can dump a grid to a bitmap file. In order to have different colors for your hex map, you need to specify them when creating the grid.

  element_to_color_hash: {
    m: :brown, g: :green, w: :blue, u: '#e3e3e3'

Where m = brown, g = green and w = blue (the colors for mountains, grass and water - u mean unused, its only to show an example of RGB notation). I used rmagick to create the bitmap, so all rmagick color syntax are available :

# Create a grid with a correspondence array from val to color
g =
  element_to_color_hash: {
    m: :brown, g: :green, w: :blue

# Load the same map we used before
g.read_ascii_file( 'test/ascii_map.txt' )

# Create the pic
g.to_pic( 'test2.png' )

You should get your map as an hex bitmap grid :

test picture


A library designed to provide hexagonal grids with ruby







No releases published


No packages published