Recursive AI

Find reachable navmesh polygons in a circle 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 circle query follows connections between walkable polygons, so it leaves out disconnected islands.

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("rooms.nav");
var query = new NavMeshQuery(
    NavMeshSnapshot.Restore(bytes));
var center = new Vector3D(2, 0, 3);
var start = query.FindNearestPoly(center,
    new Vector3D(1, 1, 1)).Poly;
var polys = new PolyRef[4];
var entrySq = new double[polys.Length];
var status = query.FindPolysInCircle(
    startPoly: start, center: center, radius: 2,
    filter: null, polys: polys,
    parents: default,
    distancesSquared: entrySq,
    count: out int count,
    truncated: out bool truncated);
if (status != AreaQueryStatus.Success ||
    truncated || query.AreaNodeLimitReached)
    throw new InvalidOperationException(
        $"Circle query: {status}");
for (int i = 0; i < count; i++)
{
    var poly = polys[i];
    Console.WriteLine(
        $"{poly.PolyIndex}: {entrySq[i]}");
}

Unzip the example, then dotnet run.

rooms.nav comes in the zip. For your own .nav file, save a snapshot of your OnePath navmesh. Each line shows a polygon index and the squared distance to the edge used to enter it (zero for the start).

Text
0: 0
1: 1

The full program

rooms.nav contains three flat rectangles in one tile. Polygon 0 covers X=1–3, Z=2–4; polygon 1 covers X=3–5, Z=2–4 and shares the edge at X=3 with polygon 0. Polygon 2 covers X=1–2, Z=0.5–1.5. It touches the search circle but has no connection to either of the other polygons. The program also runs the query with one output slot, then retries with two when truncated is true.

C#
using RecursiveAI.OneMath;
using RecursiveAI.OnePath.Mesh;
using RecursiveAI.OnePath.Mesh.Queries;
 
var bytes = File.ReadAllBytes("rooms.nav");
var query = new NavMeshQuery(
    NavMeshSnapshot.Restore(bytes));
var center = new Vector3D(2, 0, 3);
var start = query.FindNearestPoly(center,
    new Vector3D(1, 1, 1)).Poly;
var polys = new PolyRef[4];
var entrySq = new double[polys.Length];
var status = query.FindPolysInCircle(
    startPoly: start, center: center, radius: 2,
    filter: null, polys: polys,
    parents: default,
    distancesSquared: entrySq,
    count: out int count,
    truncated: out bool truncated);
if (status != AreaQueryStatus.Success ||
    truncated || query.AreaNodeLimitReached)
    throw new InvalidOperationException(
        $"Circle query: {status}");
for (int i = 0; i < count; i++)
{
    var poly = polys[i];
    Console.WriteLine(
        $"{poly.PolyIndex}: {entrySq[i]}");
}
 
var small = new PolyRef[1];
var smallStatus = query.FindPolysInCircle(
    start, center, 2, null, small, default, default,
    out int written, out bool more);
Console.WriteLine($"{smallStatus}: {written} written, truncated={more}");
if (smallStatus != AreaQueryStatus.Success || query.AreaNodeLimitReached)
    throw new InvalidOperationException($"Incomplete search: {smallStatus}");
if (more)
{
    Array.Resize(ref small, small.Length * 2);
    var retry = query.FindPolysInCircle(
        start, center, 2, null, small, default, default,
        out written, out more);
    if (retry != AreaQueryStatus.Success || more || query.AreaNodeLimitReached)
        throw new InvalidOperationException($"Incomplete retry: {retry}");
    Console.WriteLine($"Retry: {written} written, truncated={more}");
}

dotnet run prints:

Text
0: 0
1: 1
Success: 1 written, truncated=True
Retry: 2 written, truncated=False

The circle is centered at X=2, Z=3, one unit from the shared edge. Polygon 1 appears with a squared entry distance of 1; polygon 2 never appears. If the starting polygon doesn’t exist or fails the filter, FindPolysInCircle returns InvalidStartPoly.

The short answer

Call NavMeshQuery.FindPolysInCircle with a starting polygon, a center, a radius, and an output span. It returns polygons reachable through a chain of connections that touch the horizontal circle. Pass a double span for the squared entry distances and, optionally, a PolyRef span for the parents. Read only the entries below count; check truncated and AreaNodeLimitReached before treating the result as complete.

How do you find all reachable navmesh polygons within a radius?

The radius applies to portals, the shared edges or linked edge segments you cross to enter another polygon. If the closest point on a portal in X/Z is at most the radius from the center, the search can follow it, provided the destination passes the filter. The radius is measured in world units and must be finite, from 0 to 2²². The search ignores height and doesn’t follow off-mesh links, such as jumps.

That’s a connectivity test, not an overlap test. A disconnected island can sit partly inside the circle and still be absent. A connected polygon can extend past the circle and still be present. The accepted starting polygon is always listed first, even if the circle doesn’t touch it. The output doesn’t describe a clipped walkable region or the area of each polygon inside the circle.

What do the distances from a navmesh circle query measure?

distancesSquared[i] is the squared X/Z distance from the center to the portal used to enter polys[i], not the distance to the polygon center. It’s also the search’s priority key, not a running sum or a path cost with terrain weights. A route might turn several times to reach a portal a unit away from the center. Its key would still be 1. If you request parents, the corresponding entry tells you which polygon the search entered from; the start has no parent (PolyRef.Invalid).

What happens if the navmesh result buffer is too small?

The area-query docs describe two separate limits. truncated means that more polygons were reached than the output span can hold. A status of Success can accompany that flag, and count tells you how many were actually written. If you need all the results, grow the polygon array and run the query again. Grow the distance and parent arrays too if you need a value for every result; those arrays may be shorter without setting truncated.

AreaNodeLimitReached means the search itself ran out of room to track more polygons. Growing only the output arrays won’t fix that. Use a query with a larger maxNodes or narrow the search, depending on whether you need the original radius.

All onepath recipes