---
title: "3D voxel pathfinding in C#"
url: https://recursiveai.org/onepath/cookbook/find-path-in-3d-voxel-grid/
description: "3D voxel pathfinding in C# with OnePath: runnable grid setup, obstacle rules and a downloadable .NET example with its actual output."
version: "1.2.0"
---

# 3D voxel 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-in-3d-voxel-grid/find-path-in-3d-voxel-grid.zip)

Search free cells in a 3D volume, including movement above and below obstacles. Voxel search does not model an agent’s physical radius.

```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 = new VoxelGrid(5, 5, 5);
grid.SetWalkable(2, 2, 2, false);
var path = grid.FindPath(
    new VoxelCell(0, 2, 2),
    new VoxelCell(4, 2, 2));
Console.WriteLine(path.Status);
Console.WriteLine(path.Cells.Length);
```

Prints:

```text
Found
5
```

Unzip [the example](https://recursiveai.org/onepath/cookbook/find-path-in-3d-voxel-grid/find-path-in-3d-voxel-grid.zip), then `dotnet run`.

## The full program

The full program blocks the plane at x=2 except for layer z=4. It checks the endpoints, each neighbor transition and every swept voxel before printing a route over the wall. Coordinates are `(x,y,z)`.

```csharp
using RecursiveAI.OnePath;

var grid = new VoxelGrid(5, 5, 5);
// A wall at x=2, except for the top layer z=4.
for (int z = 0; z < 4; z++)
    for (int y = 0; y < 5; y++)
        grid.SetWalkable(2, y, z, false);
var start = new VoxelCell(0, 2, 2);
var goal = new VoxelCell(4, 2, 2);
var path = grid.FindPath(start, goal);
if (!path.Found) throw new InvalidOperationException(path.Status.ToString());
if (path.Cells[0] != start || path.Cells[^1] != goal)
    throw new InvalidOperationException("Wrong endpoints");
for (int i = 0; i < path.Cells.Length; i++)
{
    var cell = path.Cells[i];
    if (!grid.Contains(cell.X, cell.Y, cell.Z) ||
        !grid.IsWalkable(cell.X, cell.Y, cell.Z))
        throw new InvalidOperationException("Blocked cell");
    if (i == 0) continue;
    var previous = path.Cells[i - 1];
    int dx = Math.Abs(cell.X - previous.X);
    int dy = Math.Abs(cell.Y - previous.Y);
    int dz = Math.Abs(cell.Z - previous.Z);
    if (Math.Max(dx, Math.Max(dy, dz)) != 1)
        throw new InvalidOperationException("Not a neighbor");
    // Default NoCornerCutting: every voxel in the move's cube is open.
    for (int z = Math.Min(previous.Z, cell.Z); z <= Math.Max(previous.Z, cell.Z); z++)
        for (int y = Math.Min(previous.Y, cell.Y); y <= Math.Max(previous.Y, cell.Y); y++)
            for (int x = Math.Min(previous.X, cell.X); x <= Math.Max(previous.X, cell.X); x++)
                if (!grid.IsWalkable(x, y, z))
                    throw new InvalidOperationException("Blocked swept voxel");
}
Console.WriteLine($"{path.Status}: {path.Cells.Length} voxels");
Console.WriteLine(string.Join(" -> ", path.Cells.ToArray()
    .Select(cell => $"({cell.X},{cell.Y},{cell.Z})")));
```

`dotnet run` prints:

```text
Found: 7 voxels
(0,2,2) -> (1,2,3) -> (1,2,4) -> (2,2,4) -> (3,2,4) -> (4,2,3) -> (4,2,2)
```

An unreachable goal returns `NoPath`; a blocked or out-of-range endpoint returns `StartInvalid` or `GoalInvalid`.

## Variations

Restrict movement to the six face neighbors. This is a complete replacement for `Program.cs`.

```csharp
using RecursiveAI.OnePath;

var grid = new VoxelGrid(5, 5, 5);
grid.SetWalkable(2, 2, 2, false);
var path = grid.FindPath(
    new VoxelCell(0, 2, 2),
    new VoxelCell(4, 2, 2),
    VoxelOptions.SixConnected);
Console.WriteLine(path.Status);
Console.WriteLine(path.Cells.Length);
```

```text
Found
7
```

## Related recipes

- [A* pathfinding in C#](https://recursiveai.org/onepath/cookbook/a-star-pathfinding/)
- [Theta* any-angle pathfinding in C#](https://recursiveai.org/onepath/cookbook/any-angle-grid-pathfinding/)
- [Hierarchical pathfinding with HPA* in C#](https://recursiveai.org/onepath/cookbook/hierarchical-grid-pathfinding/)

## The short answer

For 3D voxel pathfinding in C#, create a `VoxelGrid`, mark solid cells with `SetWalkable(x, y, z, false)`, and call `FindPath` with two `VoxelCell` endpoints. The released OnePath API searches with A*. A successful `VoxelPath.Cells` lists neighboring free voxels; `Points` gives their world-space centers.

This is volume navigation: the example travels above a wall because those voxels are free. It does not infer floors, gravity, climbing ability or a character’s body size. An empty cell is traversable whether or not there is a floor below it. For a walking character, those constraints need to be represented in your occupancy or movement model.

## How do I implement pathfinding in a voxel game?

Supply the occupancy data first. The full program creates a five-by-five-by-five volume and blocks x=2 in every row below z=4. Its start and goal lie on opposite sides of that plane. The result goes to the open top layer, crosses it and descends to the goal.

The grid starts open by default. Area 255 is solid; other area IDs are traversable and can have different cost multipliers. You can instead construct a solid grid and carve free cells by choosing a solid default area. Occupancy storage is chunked, but the search still operates on individual voxels.

Handle `Status` before reading a route. An in-range endpoint in a solid voxel is invalid, just as an endpoint outside the volume is invalid. A valid goal can still be unreachable. Reusing the grid after `SetWalkable` edits is supported; a new query reads the edited contents. Do not continue following an old path without accounting for changes that block it.

## How do waypoints work in 3D voxel pathfinding?

The returned cells are neighboring search nodes, not a smoothed spline. Default connectivity permits 26 moves: six through faces, twelve across edges and eight across corners. Face moves have unit length; edge and corner moves have square-root-of-two and square-root-of-three lengths. Area multipliers affect the final move costs.

The default `NoCornerCutting` rule requires every swept voxel inside a move’s cube to be open. For an edge move, that includes the two beside face cells; for a corner move, three face and three edge cells. The full program checks the entire small cube for each returned transition. The six-connected variation allows face steps only, so it cannot take edge or corner shortcuts.

Do not connect nonadjacent returned cells with a new straight line unless your own collision test supports that shortcut. A route of legal neighboring moves is not permission to skip the obstacle checks between distant points. See the [voxel grid specification](https://recursiveai.org/onepath/docs/grids/#3d-voxel-grids) for movement and coordinate rules.

## How do I map a C# 3D voxel path to world coordinates?

Set `grid.Space` to a `VoxelSpace` containing origin coordinates and a positive cell size. Cell `(i,j,k)` occupies the box starting at `origin + (i,j,k) * cellSize`; its center adds half a cell on each axis. `CellCenter` converts an integer cell to that center. `TryGetCell` maps a world point to its containing cell and reports whether it lies inside the volume. `FindPath` also accepts `VoxelPoint` endpoints directly.

World mapping does not create clearance. `VoxelOptions` has connectivity and corner rules but no square-grid-style `AgentSize` property. Build occupancy for the positions your actor can safely occupy, including its full body and a suitable margin. A point-valid route through a one-voxel opening is not, by itself, a collision-free route for an arbitrarily large actor.
