Search free cells in a 3D volume, including movement above and below obstacles. Voxel search does not model an agent’s physical radius.
dotnet add package RecursiveAI.OnePathRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
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:
Found 5
Unzip the example, 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).
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:
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.
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);
Found 7
Related recipes
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 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.