Recursive AI

Query a local navmesh neighborhood in C#

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

A local navmesh neighborhood finds connected walkable polygons without overlaps in the top-down view. The API uses the British spelling: FindLocalNeighbourhood.

Terminal
dotnet add package RecursiveAI.OnePath

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

C#
using RecursiveAI.OneMath;
using RecursiveAI.OnePath.Mesh;
using RecursiveAI.OnePath.Mesh.Queries;
 
var bytes = File.ReadAllBytes("floors.nav");
var mesh = NavMeshSnapshot.Restore(bytes);
var query = new NavMeshQuery(mesh);
var center = new Vector3D(2, 0, 2);
var start = query.FindNearestPoly(center,
    new Vector3D(1, 0.5, 1)).Poly;
var polys = new PolyRef[8];
var status = query.FindLocalNeighbourhood(
    start, center, 5, null, polys, default,
    out int count, out bool truncated);
if (status != AreaQueryStatus.Success ||
    truncated || query.AreaNodeLimitReached)
    throw new InvalidOperationException(
        $"Neighborhood query: {status}");
foreach (var poly in polys.AsSpan(0, count))
    Console.WriteLine(poly.PolyIndex);

Unzip the example, then dotnet run.

floors.nav comes in the zip. The snippet prints the indices of the polygons kept.

Text
0
1
2
3
4
5

The full program

floors.nav is a single synthetic tile. The polygons connect in order from 0 to 6 around a bend, so there is a route to the upper floor. These are the polygon footprints in the snapshot:

  • 0 (start): X 1–3, Z 1–3, Y 0.
  • 1: X 3–5, Z 1–3, Y 0.
  • 2 (ramp): X 3–5, Z 3–5, Y 0 to 1.
  • 3: X 3–5, Z 5–7, Y 1.
  • 4: X 1–3, Z 5–7, Y 1.
  • 5: X 1–3, Z 3–5, Y 1.
  • 6 (upper floor): X 1–3, Z 1–3, Y 1.
C#
using RecursiveAI.OneMath;
using RecursiveAI.OnePath.Mesh;
using RecursiveAI.OnePath.Mesh.Queries;
 
var bytes = File.ReadAllBytes("floors.nav");
var mesh = NavMeshSnapshot.Restore(bytes);
var query = new NavMeshQuery(mesh);
var center = new Vector3D(2, 0, 2);
var start = query.FindNearestPoly(center,
    new Vector3D(1, 0.5, 1)).Poly;
var polys = new PolyRef[8];
var status = query.FindLocalNeighbourhood(
    start, center, 5, null, polys, default,
    out int count, out bool truncated);
if (status != AreaQueryStatus.Success ||
    truncated || query.AreaNodeLimitReached)
    throw new InvalidOperationException(
        $"Neighborhood query: {status}");
foreach (var poly in polys.AsSpan(0, count))
    Console.WriteLine(poly.PolyIndex);
 
var circle = new PolyRef[8];
var circleStatus = query.FindPolysInCircle(
    start, center, 5, null, circle, default, default,
    out int reached, out bool circleTruncated);
if (circleStatus != AreaQueryStatus.Success || circleTruncated ||
    query.AreaNodeLimitReached)
    throw new InvalidOperationException($"Incomplete circle: {circleStatus}");
Console.WriteLine("Circle: " + string.Join(", ",
    circle.Take(reached).Select(poly => poly.PolyIndex)));

dotnet run prints:

Text
0
1
2
3
4
5
Circle: 0, 1, 2, 3, 4, 5, 6

Polygon 6 doesn’t appear in the local list: its footprint overlaps polygon 0, even though it’s one unit higher. Polygon 5 shares an edge with 6 but only touches 0 in plan view, so 5 is kept. If the starting reference is missing, stale, or rejected by the filter, the query returns InvalidStartPoly.

The short answer

Use NavMeshQuery.FindLocalNeighbourhood with a starting polygon, a world position, a radius, and a buffer for polygon references. The method walks through connections that touch the search circle in X/Z and skips any new polygon whose projected interior overlaps a polygon it has already accepted. Use it when you want a nearby patch of walkable surface with no double coverage in a top-down view. For a reachability check that can include both levels, call FindPolysInCircle instead.

How do you query nearby polygons on a navmesh?

Start with the polygon the character is on. If you only have a position, FindNearestPoly searches a box centered on that position. Its halfExtents are how far that box extends from the center on each axis. Set the Y half-extent to match how far you’re willing to look up or down; it’s independent of the neighborhood’s horizontal radius. In the example, a Y half-extent of 0.5 excludes the upper floor from the starting lookup.

The local query then checks the shared edges or tile-border connections between polygons. An edge connection that touches the circle is enough to reach the next polygon, provided the filter accepts it and its footprint passes the overlap rule. The method returns polygon references, not clipped outlines. Use the full PolyRef across tiles: the example prints PolyIndex only because it has one tile.

How does a local navmesh query handle overlapping floors?

The area-query docs define overlap by intersecting interiors in X/Z; polygons that merely touch at an edge or corner can both be kept. The first polygon admitted wins. The query doesn’t compare floor heights to choose the closest floor, and it won’t walk through a skipped polygon to reach something beyond it. In the example, the lower floor wins because it’s where the search starts, not because it’s lower.

That distinction matters when deciding what to draw or inspect. A top-down preview can use the local result to avoid drawing the same patch twice. A movement rule that needs to know whether the ramp actually reaches the upper floor should use the circle result, which includes polygon 6. Neither query follows off-mesh links such as jumps.

All onepath recipes