Hexagonal Grids

Angles

add(center, polar(size, 2 * PI / 6 * i)

angle = 2 * PI / 6 * i;
x_i = center_x + size * cos(angle);
y_i = center_y + size * sin(angle);

for (i = 0; i <= 6; i++) {
 angle = 2 * PI / 6 * i;
 x_i = center_x + size * cos(angle);
 y_i = center_y + size * sin(angle);
 if (i == 0) {
 moveTo(x_i, y_i);
 } else {
 lineTo(x_i, y_i);
 }
}

Now let’s assemble hexagons into a grid. With square grids, there’s one obvious way to do it. With hexagons, there are multiple approaches. I recommend axial coordinates for most situations.

Offset coordinates

The most common approach is to offset every other column or row. I’m going to call the columns q and the rows r. You can either offset the odd or the even column/rows, so the horizontal and vertical hexagons each have two variants.

Cube coordinates

The cube coordinates are a reasonable choice for a hex grid coordinate system. The constraint is that x + y + z = 0 so the algorithms must preserve that. The constraint also ensures that there’s a canonical coordinate for each hex.

“But Amit!” you say, “I don’t want to store 3 numbers for coordinates. I don’t know how to store a map that way.”

It is likely that you will use axial or offset coordinates in your project, but many algorithms are simpler to express in cube coordinates. Therefore we need to be able to convert back and forth.

# convert cube to axial
q = x
r = z
# convert axial to cube
x = q
z = r
y = -x-z
# convert cube to even-q offset
q = x
r = z + (x + x&1) / 2
# convert even-q offset to cube
x = q
z = r - (q + q&1) / 2
y = -x-z
# convert cube to odd-q offset
q = x
r = z + (x - x&1) / 2
# convert odd-q offset to cube
x = q
z = r - (q - q&1) / 2
y = -x-z
# convert cube to even-r offset
q = x + (z + z&1) / 2
r = z
# convert even-r offset to cube
x = q - (r + r&1) / 2
z = r
y = -x-z
# convert cube to odd-r offset
q = x + (z - z&1) / 2
r = z
# convert odd-r offset to cube
x = q - (r - r&1) / 2
z = r
y = -x-z

Note that I use &1 instead of %2. Why? Because -1 % 2 == -1 in some languages (this annoys me!), but I always want 0 or 1.

In addition to these transforms, your grid numbering scheme may be offset by Δq, Δr. Subtract these before applying the conversion to cubes and add them after converting back from cubes to hex.

Given a hex, which 6 hexes are neighboring it? As you might expect, the answer is simplest with cube coordinates, still pretty simple with axial coordinates, and slightly trickier with offset coordinates. We might also want to calculate the 6 “diagonal” hexes.

neighbors = [[+1, -1, 0], [+1, 0, -1], [ 0, +1, -1],[-1, +1, 0], [-1, 0, +1], [ 0, -1, +1]
];
d = neighbors[direction];
return Cube(x + d[0], y + d[1], z + d[2]);

neighbors = [, , ,, , 
];
d = neighbors[direction];
return Hex(q + d[0], r + d[1]);

Offset coordinates

With offset coordinates, the change depends on where in the grid we are. If we’re on an offset column/row then the rule is different than if we’re on a non-offset column/row.

As above, we’ll build a table of Δq and Δr. However this time there will be two arrays, one for odd columns/rows and one for even columns/rows. Each array with contain six elements [Δq, Δr]. Look at (1,1) on the grid map above and see how q and r change as you move in each of the six directions. Then do this again for (2,2).

neighbors = [
 [ , , ,, ,  ],
 [ , , ,, ,  ]
];
parity = q& 1;
d = neighbors[parity][direction];
return Hex(q + d[0], r + d[1]);

However, for those of you who are curious, I’m going to show you how to derive a formula, from first principles. Feel free to skip the rest of this section.

First, be sure you understand the cube neighbor section above. There are six neighbors, and each increments one axis by 1 and decrements a different axis by 1, thus preserving the x + y + z = 0 constraint.

For each of the six directions, we have Δx, Δy, Δz. The key idea here is that we’ll start with q, r coordinates from the offset grid, convert them into cube coordinates x, y, z, then add  Δx, Δy, Δz, then convert back into offset coordinates q, r. This general principle works for all the algorithms on the page.

I’ll show how this works for a single offset grid type, “even-q”: These are the coordinate conversions for “even-q”, from the above section:

# convert cube to even-q offset
q = x
r = z + (x + x&1) / 2
# convert even-q offset to cube
x = q
z = r - (q + q&1) / 2
y = -x - z

I’m only going to show this for a single direction, northeast, with Δx = +1, Δy = 0, Δz = -1:

# (1) convert even-q offset to cube coords:
x = q
y = -x - z
z = r - (q - q&1) / 2
# (2) apply Δx, Δy, Δz:
x' = x + 1
y' = y
z' = z - 1
# (3) substitute eq (1) into eq (2):
x' = q + 1
y' = -x - z
z' = r - (q - q&1) / 2 - 1
# (4) convert back into even-q coords:
q' = x'
r' = z' + (x' + x'&1) / 2
# (5) substitute eq (3) into eq (4)
q' = q + 1
r' = r - (q - q&1) / 2 - 1 + (q + 1 + (q + 1)&1) / 2
 = r - 1 + (-q + q&1 + q + 1 + (q + 1)&1) / 2
 = r - 1 + ( q&1 + 1 + (1 - q&1) ) / 2
 = r - 1 + ( q&1 + 1 + 1 - q&1) / 2
 = r - 1 + (2 + 2*q&1) / 2
 = r - 1 + 1 + q&1
 = r + q&1

So that’s it! We’ve worked through some math and it simplifies down to q' = q + 1 and r' = r + q&1. (For this case, y doesn’t play a role, but it does in other situations.) That’s just for one direction, and only for even-q offset grids, but that’s how it works. For those of you who are compiler/language enthusiasts, this is defining evenQ_neighbors(H) as map(cube_to_evenQ, cube_neighbors(evenQ_to_cube(H))), then inlining all that code and greatly simplifying. It’s the type of work an compiler optimizer would do for you.

You can either work through all the cases, or you can perform the conversions at runtime (which likely will be optimized out by your compiler), or you can precalculate everything and put the results into lookup tables. I used lookup tables for my last game.

Diagonals

diagonals = [[+2, -1, -1], [+1, +1, -2], [-1, +2, -1],[-2, +1, +1], [-1, -1, +2], [+1, -2, +1]];
d = diagonals[direction];
return Cube(x + d[0], y + d[1], z + d[2]);

Cube coordinates

function hex_distance(x1, y1, z2, x2, y2, z2) {
 return (abs(x1 - x2) + abs(y1 - y2) + abs(z1 - z2)) / 2;
}

function hex_distance(x1, y1, z2, x2, y2, z2) {
 return max(abs(x1 - x2), abs(y1 - y2), abs(z1 - z2));
}

Axial coordinates

In the 2-axis system, the third coordinate is implicit. Let’s convert 2-axis to cube (3-axis) to calculate distance. We do this by filling in the third coordinate, which can easily be calculated given the constraint x + y + z = 0 (I’m using x = q and z = r here but many configurations are possible):

function hex_distance(q1, r1, q2, r2) {
 var x1 = q1;
 var z1 = r1;
 var x2 = q2;
 var z2 = r2;
 var y1 = -(x1 + z1);
 var y2 = -(x2 + z2);
 return (abs(x1 - x2) + abs(y1 - y2) + abs(z1 - z2)) / 2;
}

This can be greatly simplified, to this:

function hex_distance(q1, r1, q2, r2) {
 return (abs(q1 - q2) + abs(r1 - r2)
 + abs(q1 + r1 - q2 - r2)) / 2;
}

If you write q1 + r1 - q2 - r2 as q1 - q2 + r1 - r2, and if you use the “max” form instead of the “divide by two” form, you get the “difference of differences” approach described here. No matter which way you write it, 2-axis hex distance is derived from the Mahattan distance on cubes.

Offset coordinates

This is trickier. The simplest way to do this is to convert offset coordinates to cube coordinates, then use cube distance. This pattern will repeat for several of the algorithms; sometimes the code can be simplified, as shown above for axial neighbors and distances.

Putting these together, to draw a line from A to B:

# Adjust one endpoint to break ties, make lines look better
ɛ = 1e-6
A.x += ɛ; A.y += ɛ; A.z -= 2*ɛ;
Δx = A.x - B.x
Δy = A.y - B.y
Δz = A.z - B.z
N = max(abs(Δx - Δy), abs(Δy - Δz), abs(Δz - Δx))
prev = null
for each 0 ≤ i ≤ N:
 p = hex_round(A * (i/N) + B * (1 - i/N))
 if p ≠ prev:
 draw hex at p
 prev = p

The above algorithm is simple but it’s not the fastest. The standard line-drawing algorithms on square grids are Bresenham’s and DDA. In none of my hex-game projects has line drawing been such a critical routine that I need something optimized as much as possible, so I’ve not bothered to implement these faster but more complicated algorithms. If you need an alternative to the simple algorithm I presented, take a look at:

Clark Verbrugge’s guide describes a “start at center and move outwards” algorithm to calculate field of view. However I suggest using the brute force method and only use a clever algorithm if the brute force version is too slow for you. The brute force method combines two existing algorithms (hex ring and line drawing).

For hex to pixel, it’s useful to review the size and spacing diagram at the top of the page. For axial and cube coordinates, the way to think about hex to pixel conversion is to look at the basis vectors. In the diagram, the arrow A→Q is the q basis vector and A→R is the r basis vector. The pixel coordinate is q_basis * q + r_basis * r. For example, B at (1, 1) is the sum of the q and r basis vectors.

If you have a matrix library, this is a simple matrix multiplication; however I’ll write the code out without matrices here. For the x = q, z = r axial grid I use in this guide, the conversion is:

x = size * sqrt(3) * (q + r/2)
y = size * 3/2 * rx = size * 3/2 * q
y = size * sqrt(3) * (r + q/2)

Axial coordinates: flat top or pointy top

For offset coordinates, we need to offset either the column or row number (it will no longer be an integer). After that you can use a q and r basis vector, aligned with the x and y axes:

x = size * sqrt(3) * (q + 0.5 * (r&1))
y = size * 3/2 * rx = size * sqrt(3) * (q - 0.5 * (r&1))
y = size * 3/2 * rx = size * 3/2 * q
y = size * sqrt(3) * (r + 0.5 * (q&1))x = size * 3/2 * q
y = size * sqrt(3) * (r - 0.5 * (q&1))

Offset coordinates: odd-Reven-Rodd-QevenQ

Another approach is to convert the offset coordinates into cube coordinates, then use the cube to pixel conversion. By inlining the conversion code then optimizing, it will end up being the same as above.

Note that the above conversions are for hex q=0, r=0 being centered at x=0.0, y=0.0. If you want to center that hex elsewhere, add the desired center to the x, y you get.

Given a cube coordinate x, y, z, round each to the nearest integer, rx, ry, rz, and then discard the largest component, resetting it based on the x+y+z = 0 constraint.

function hex_round(x, y, z):
 rx = round(x)
 ry = round(y)
 rz = round(z)
 x_err = abs(rx - x)
 y_err = abs(ry - y)
 z_err = abs(rz - z)
 if x_err > y_err and x_err > z_err:
 rx = -ry-rz
 else if y_err > z_err:
 ry = -rx-rz
 else:
 rz = -rx-ry
 return Cube(rx, ry, rz)

For non-cube coordinates, the simplest thing to do is to convert to cube coordinates, use the rounding algorithm, then convert back.

This algorithm is based on Charles Fu’s article. His code contains the additional optimization that if rx + ry + rz = 0 then there’s no need to look at the error values and reset the largest component.

One of the most common questions is, how do I take a pixel location (such as a mouse click) and convert it into a hex grid coordinate? All of these approaches have two parts: first we make a guess, then we fix it.

[x = size * [ sqrt(3) sqrt(3)/2 * [q
 y] 0 3/2 ] r]

[q = [ 1/3 * sqrt(3) -1/3 * [x
 r] 0 2/3 ] y] / size

q = (1/3*sqrt(3) * x - 1/3 * y) / size
r = 2/3 * y / size

Note that the above conversions are for hex q=0, r=0 being centered at x=0.0, y=0.0. If you want to center that hex elsewhere, subtract the desired center from the x, y before converting.

1: Using hex rounding

Use hex rounding to convert the fractional coordinate above into an integer cube coordinate.

2: Guess and test

Use regular rounding to get a first guess to the hexagon. Scan its neighbors and itself, and pick the one closest with Euclidean distance. This works because a regular hex grid also happens to satisfy the Voronoi property: the hexagon contains all points that are closer to its center than to any other hexagon center.

This approach is easy but I think it’s even easier to use hex rounding, which is also useful for other algorithms.

3: Pixel map

Instead of scanning the neighbors each time, note that the answer is always the same relative to the position you’re given. You can store the answer in a 2D array or bitmap. Given a screen location x, y, make an initial guess q0, r0. If that hexagon is centered at x0, y0, so you can store dq, dr for each x - x0, y - y0. Then the answer will be q0 + dq, r0 + dr. I’ve used this in a previous project but for future projects I’ll use hex rounding.

4: Geometry

By looking at the geometry of hexagons you can narrow down a pixel location to either one, two, or three hexagons, typically by dividing hexagons into smaller shapes. You can then use the edges between hexes to determine which subshape the pixel coordinate is on. There are a variety of shapes you can use. Here are some articles to read with details:

These are natural ways to approach the problem but I find that hex rounding is more elegant and conceptually simple.

5: Branchless Method

All the pixel to hex conversions I’ve seen use branches or a lookup table. I was mystified when Charles Chambers sent me pixel to hex conversion code that uses floor() five times, but no branches. First, divide x and y by size * sqrt(3); then find q, r with:

temp = floor(x + sqrt(3) * y + 1)
q = floor((floor(2*x+1) + temp) / 3);
r = floor((temp + floor(-x + sqrt(3) * y + 1))/3);

How does it work? I admit I don’t yet fully understand this one. Charles uses the floor() function to divide space into rhombuses which make up hexagonal rows. If you look at subexpressions in the “inner” calls to floor(), 2 * x, x + sqrt(3) * y, and -x + sqrt(3) * y, you’ll notice that they’re dot products of (x, y) with the three basis vectors aligned with the hex grid. Each “outer” call to floor() combines two of the dot products.

If you’re using this for your own project, note that the q, r here are for a different axial form than the one I use in this guide.

I suspect that extending this to work with cube coordinates directly will help me understand how it works.

One of the common complaints about the 2-axis coordinate system is that it leads to wasted space when using a rectangular map; that’s one reason to favor an offset coordinate system. However all the hex coordinate systems lead to wasted space when using a triangular or hexagonal map. We can use the same strategies for storing all of them.

Notice in the diagram that the wasted space is on the left and right sides of each row. This gives us three strategies for storing the map:

If you’re using graph-based pathfinding such as A* or Dijkstra’s algorithm or Floyd-Warshall, pathfinding on hex grids isn’t different from pathfinding on square grids. For A*, you need:

For more on pathfinding in general (mostly A*), read my pathfinding pages. I wanted to have an interactive HTML5 demo here for you to play with, but I haven’t implemented it yet. For now, check out the Flash version I wrote in 2008.

• The best early guide I saw to the 2-axis coordinate system was Clark Verbrugge’s guide, written in 1996.
• The first time I saw the cube (3-axis) coordinate system was from Charles Fu’s posting to rec.games.programmer in 1994.
• James McNeill has a nice visual explanation of grid transformations.
• Overview of hex coordinate types: staggered (offset), interlaced, 3d (3-axis), and trapezoidal (2-axis).
• Range for cube coordinates: given a distance, which hexagons are that distance from the given one?
• Distances on hex grids using cube coordinates.
• This guide explains the basics of measuring and drawing hexagons, using an offset grid.
• Convert cube hex coordinates to pixel coordinates.
• This thread explains how to generate rings.
• The HexPart system uses both hexes and rectangles to make some of the algorithms easier to work with.
• Are there pros and cons of “pointy topped” and “flat topped” hexagons?
• Line of sight in a hex grid with offset coordinates, splitting hexes into triangles
• I used the PDF hex grids from this page while working out some of the algorithms.
• Generalized Balanced Ternary for hex coordinates seems interesting; I haven’t studied it.
• Hex-Grid Utilities is a C# library for hex grid math, with neighbors, grids, range finding, path finding, field of view. Open source, MIT license.

My code isn’t great but if you want to take a look, the core algorithms and data structures are in Haxe and compiled down to Javascript: Cube.hx, Hex.hx, Grid.hx, ScreenCoordinate.hx; the UI code is in Javascript and uses D3.js for visualization: ui.js and cubegrid.js (for the cube/hex animation).

There are lots more things I wanted to do for this guide but didn’t have time. I’m keeping a list on Trello. Do you have suggestions for things to change or add? Comment below.