Recursive AI

Build a tiled 2D navmesh in C#

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

A navmesh divides walkable ground into polygons. Tiles meet at shared edges called portals, which let a route cross between tiles.

Terminal
dotnet add package RecursiveAI.OnePath

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

C#
using RecursiveAI.OnePath;
 
bool[] floor = [true, true];
var settings = new NavSettings {
    TileSize = 4, AgentRadius = 0
};
var mesh = NavMesh.Build2D(floor, 2, 1,
    4, new(0, 0), settings);
// Y is height; Z follows the map rows.
var path = mesh.FindPath(
    new(1, 0, 2), new(7, 0, 2));
Console.WriteLine(path.Status);
var slots = path.Corridor
    .Select(poly => poly.TileSlot);
Console.WriteLine(string.Join(" -> ", slots));

The corridor visits tile slots 0 and 1, crossing the seam at X = 4.

Unzip the example, then dotnet run.

Text
Found
0 -> 1

The full program

The input is two walkable map cells in one row, each four units square. The program also reads the portal from the first corridor polygon to the last. The portal range measures the shared part of the edge in steps of 1/255 of the edge’s length, so 0..255 covers the whole edge.

C#
using RecursiveAI.OnePath;
using RecursiveAI.OnePath.Mesh;
 
bool[] floor = [true, true];
var settings = new NavSettings {
    TileSize = 4, AgentRadius = 0
};
var mesh = NavMesh.Build2D(floor, 2, 1,
    4, new(0, 0), settings);
// Y is height; Z follows the map rows.
var path = mesh.FindPath(
    new(1, 0, 2), new(7, 0, 2));
Console.WriteLine(path.Status);
var slots = path.Corridor
    .Select(poly => poly.TileSlot);
Console.WriteLine(string.Join(" -> ", slots));
 
if (!path.Found)
    return;
 
Console.WriteLine($"Tiles: {mesh.Tiles.TileCount}");
var from = path.Corridor[0];
var to = path.Corridor[^1];
foreach (var link in mesh.Tiles.GetLinks(from))
{
    if (link.Kind == NavLinkKind.Portal && link.Target == to)
        Console.WriteLine($"Shared edge: {link.Kind}, {link.RangeMin}..{link.RangeMax}/255");
}

dotnet run prints:

Text
Found
0 -> 1
Tiles: 2
Shared edge: Portal, 0..255/255

If a tile line falls too far off the snap grid, the builder throws ArgumentException; align your tile origin and size with the grid.

Variations

To keep the same floor in one navigation tile, use this setting in place of the TileSize line.

C#
TileSize = 8, AgentRadius = 0
Text
Found
0
Tiles: 1

The short answer

Pass your walkable tilemap and a NavSettings.TileSize to NavMesh.Build2D in one call. The builder slices the whole walkable region and stitches neighboring tiles. Ask for a route with endpoints on opposite sides of a seam, then check Found and the polygon references in Corridor. A successful route whose corridor changes tile slots crossed at least one seam. The sample also reads the link itself to show it is a surface portal, not a jump or other off-mesh connection.

How do you generate a 2D navmesh from a tilemap?

Flatten the map into a row-major Boolean array: true is walkable, and false contributes no floor. Pass the map width and height, the world size of a map cell, and the map’s origin. In the sample, the two true cells form one rectangle from X = 0 to 8 and Z = 0 to 4. The geometry’s X and Y become world X and Z; world Y is the constant FloorY. This overload builds a flat floor, not stacked floors.

A tilemap cell is input geometry, while a navigation tile is a chunk of the output. TileSize is in world units, so it need not equal the map cell size. Here it is four units, placing a vertical seam through the middle of the floor at X = 4. At eight units, the two source cells still describe the same walkable rectangle, but the route fits inside one navigation tile; the variation prints only slot 0. Likewise, the input cell size sets the coverage of the map cells, whereas NavSettings.CellSize is a build setting used in the snap-grid rules.

Why aren’t neighboring navmesh tiles connected?

Two tiles can sit next to each other without a walkable edge between them. In a single 2D build, each cut is part of the same geometry calculation, so overlapping portal edges are cut at the same vertices on both sides. If you build each tile separately, that shared calculation no longer applies. In particular, radius clearance shrinks the walkable region before slicing. Treating an intended seam as the outside boundary of two separate builds may shrink both sides away from it.

If a route stops short, inspect the start and end locations and the corridor before assuming that stitching failed. A blocked map cell or a gap too narrow for the chosen radius can remove the connection from the walkable region. A partial result does not establish that the destination is reachable. The example uses radius zero so the seam runs across the full width of the floor; in a game, choose the clearance for the character whose center the mesh represents.

This is a build from static floor geometry, not a runtime update when an obstacle moves. The 2D tile builder reference describes the tile grid and how the portals are cut.

All onepath recipes