---
title: "Hex grid pathfinding in C#"
url: https://recursiveai.org/onepath/cookbook/find-path-on-hex-grid/
description: "Find a hex-cell route in C# with OnePath. Print offset, axial and world coordinates, choose a hex layout and run the downloadable .NET example."
version: "1.2.0"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OnePath) · [GitHub](https://github.com/recursive-ai-oss/onepath-csharp) · [Docs](https://recursiveai.org/onepath/docs/) · [Download example (.zip)](https://recursiveai.org/onepath/cookbook/find-path-on-hex-grid/find-path-on-hex-grid.zip)

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

```shell
dotnet add package RecursiveAI.OnePath
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onepath/cookbook/find-path-on-hex-grid/find-path-on-hex-grid.zip), 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.

```csharp
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.

```csharp
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
```

## Related recipes

- [Square-grid pathfinding](https://recursiveai.org/onepath/cookbook/a-star-pathfinding/)
- [Pathfinding on a 3D voxel grid](https://recursiveai.org/onepath/cookbook/find-path-in-3d-voxel-grid/)

---

## 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](https://recursiveai.org/onepath/docs/grids/#layout) defines their conversions.

The general distinction between offset storage and axial arithmetic is illustrated in [Red Blob Games’ coordinate-system guide](https://www.redblobgames.com/grids/hexagons/#coordinates). 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](https://recursiveai.org/onepath/docs/grids/).

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.
