Recursive AI

Hex grid pathfinding in C#

OnePath is a free, open-source pathfinding library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Find a route around blocked hexes, then convert its cells to world positions.

Terminal
dotnet add package RecursiveAI.OnePath

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OnePath;
 
var grid = HexGrid.FromText(
    ".....\n.###.\n.....");
var path = grid.FindPath(
    new Cell(0, 1), new Cell(4, 1));
Console.WriteLine(path.Status);
foreach (var cell in path.Cells)
    Console.WriteLine($"{cell.X},{cell.Y}");

In the map string, . is walkable and # is a wall.

Prints:

Text
Found
0,1
1,0
2,0
3,0
4,0
4,1

Unzip the example, then dotnet run.

Full program

The map below is built in memory. Cell.X is the column and Cell.Y is the row. The default layout is pointy-topped with odd rows shifted right.

C#
using RecursiveAI.OnePath;
 
var grid = HexGrid.FromText(".....\n.###.\n.....");
var path = grid.FindPath(new Cell(0, 1), new Cell(4, 1));
Console.WriteLine($"{path.Status}: cost {path.Cost}");
foreach (var cell in path.Cells)
{
    var axial = grid.ToAxial(cell);
    var world = grid.CellCenter(cell);
    Console.WriteLine(FormattableString.Invariant(
        $"({cell.X},{cell.Y}) axial ({axial.Q},{axial.R}) world ({world.X:F2},{world.Y:F2})"));
}

dotnet run prints:

Text
Found: cost 5
(0,1) axial (0,1) world (0.50,0.87)
(1,0) axial (1,0) world (1.00,0.00)
(2,0) axial (2,0) world (2.00,0.00)
(3,0) axial (3,0) world (3.00,0.00)
(4,0) axial (4,0) world (4.00,0.00)
(4,1) axial (4,1) world (4.50,0.87)

If the destination is disconnected, FindPath returns NoPath; check the status before using the cells.

Variations

Flat-topped hexes with a custom origin and spacing. This is a complete replacement program. Cell size is the distance between adjacent centers, not the hex’s corner radius.

C#
using RecursiveAI.OnePath;
 
var grid = new HexGrid(3, 3, HexLayout.FlatOddColumn);
grid.Space = new GridSpace(10, 20, 2);
var cell = new Cell(1, 1);
var axial = grid.ToAxial(cell);
var world = grid.CellCenter(cell);
Console.WriteLine($"Axial: {axial.Q},{axial.R}");
Console.WriteLine(FormattableString.Invariant(
    $"World: {world.X:F2},{world.Y:F2}"));
Text
Axial: 1,1
World: 11.73,23.00

The short answer

Use HexGrid, not a square Grid with diagonal moves enabled. Construct the map in offset coordinates, call FindPath with start and goal cells, and read path.Cells when the status is Found. OnePath supplies the six-neighbor topology and the hex-distance heuristic. You do not need to write a separate A* implementation for each hex orientation.

The example deliberately blocks the middle row. Its route leaves that row and comes back to the goal, so the output shows actual hex adjacency rather than a straight list of columns. The cost counts movement through the map; the world positions are coordinates for drawing or moving along the resulting route.

Which coordinate system should I use for a hexagonal grid?

OnePath stores a rectangular array of offset cells. A Cell(2, 1) means column two, row one; it is not axial q=2, r=1 unless the chosen layout’s conversion happens to give that result. Use ToAxial when your gameplay logic needs axial coordinates and CellCenter when your renderer needs positions. The full program prints all three representations next to each other.

There are four layouts: PointyOddRow, PointyEvenRow, FlatOddColumn and FlatEvenColumn. Choose the one matching your map’s alternating rows or columns before loading the map. Changing the layout changes adjacency and placement, not merely how the result is labeled. The grid documentation defines their conversions.

The general distinction between offset storage and axial arithmetic is illustrated in Red Blob Games’ coordinate-system guide. Its size convention is a corner radius; OnePath’s GridSpace.CellSize is center spacing. Keep those conventions separate when adapting drawing formulas.

How do I calculate distance on a hex grid?

Convert the endpoints to axial coordinates. For differences dq and dr, the third cube-coordinate difference is ds = −dq − dr. The empty-grid distance is (abs(dq) + abs(dr) + abs(ds)) / 2. This counts neighbor steps, not straight-line world distance. OnePath’s automatic hex heuristic uses hex distance scaled by the smallest area multiplier, as specified in the A* rules.

Walls can force a longer route than that empty-grid distance. Terrain costs can also make the least-cost route differ from the route with the fewest steps. Walkable area IDs have positive finite multipliers; a hex step charges the mean of the two endpoint multipliers. The wall area is separate from costly terrain: it cannot be crossed. Keep the default heuristic and cost rules when you need their documented optimality guarantees.

All onepath recipes