Recursive AI

Traverse navmesh off-mesh links in C#

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

An off-mesh link connects walkable surfaces across a gap, for a jump, ladder or other special movement.

Terminal
dotnet add package RecursiveAI.OnePath

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

C#
using RecursiveAI.OnePath;
using RecursiveAI.OnePath.Crowds.Corridors;
using RecursiveAI.OnePath.Mesh.Queries;
 
var grid = Grid.FromText("...#...\n...#...");
var mesh = NavMesh.Build2D(grid, new()
{
    AgentRadius = 0.1f,
    OffMeshLinks = [OffMeshLinkDefinition.Create(
        new(2.5, 0, 0.5), new(4.5, 0, 0.5))]
});
var query = new NavMeshQuery(mesh.Tiles);
var follower = new PathFollower();
if (!follower.Place(query, new(1.5, 0, 0.5)))
    throw new InvalidOperationException();
follower.SetDestination(query, new(5.5, 0, 0.5));
for (int i = 0; i < 200 && follower.HasPath; i++)
    follower.Step(query, 0.1);
Console.WriteLine(follower.State);

Prints:

Text
Arrived

Unzip the example, then dotnet run.

The snippet at the top crosses automatically. The full program below pauses at the link so your movement code can complete the crossing explicitly.

Full program

RecursiveAI.OneMath is installed automatically as a dependency of OnePath; no separate install is needed for using RecursiveAI.OneMath;.

The in-memory map has two walkable islands separated by the # column. The authored link joins their inner cells. No engine or input file is required.

C#
using RecursiveAI.OneMath;
using RecursiveAI.OnePath;
using RecursiveAI.OnePath.Crowds.Corridors;
using RecursiveAI.OnePath.Mesh.Queries;
 
var grid = Grid.FromText("...#...\n...#...\n...#...");
var settings = new NavSettings
{
    AgentRadius = 0.1f,
    OffMeshLinks = [OffMeshLinkDefinition.Create(
        new(2.5, 0, 1.5), new(4.5, 0, 1.5))]
};
var mesh = NavMesh.Build2D(grid, settings);
var query = new NavMeshQuery(mesh.Tiles);
var follower = new PathFollower(FollowerOptions.Humanoid with
{
    OffMeshMode = OffMeshMode.Host
});
Console.WriteLine($"Placed: {follower.Place(query, new(1.5, 0, 1.5))}");
Console.WriteLine($"Destination: {follower.SetDestination(query, new(5.5, 0, 1.5))}");
for (int tick = 0; tick < 200 && follower.HasPath; tick++)
{
    follower.Step(query, 0.1);
    if (follower.State == FollowerState.OffMeshLink)
    {
        Console.WriteLine($"Link: {follower.State}");
        Console.WriteLine($"Entry X: {follower.OffMeshStart.X}; exit X: {follower.OffMeshEnd.X}");
        follower.Step(query, 0.1);
        Console.WriteLine($"Waiting: {follower.State}");
        follower.CompleteOffMeshLink(query);
        Console.WriteLine($"Completed: {follower.State}");
    }
}
Console.WriteLine($"Final: {follower.State}; reached: {follower.ReachedTarget}");

dotnet run prints:

Text
Placed: True
Destination: Success
Link: OffMeshLink
Entry X: 2.5; exit X: 4.5
Waiting: OffMeshLink
Completed: Moving
Final: Arrived; reached: True

Call CompleteOffMeshLink only while the follower is in OffMeshLink; otherwise it throws InvalidOperationException.

Variations

Automatic crossing at a chosen speed. After creating query in the full program, use this instead of its follower setup and loop. OffMeshSpeed sets the speed along the link.

C#
var automatic = new PathFollower(
    FollowerOptions.Humanoid with { OffMeshSpeed = 2 });
automatic.Place(query, new(1.5, 0, 1.5));
automatic.SetDestination(query, new(5.5, 0, 1.5));
for (int i = 0; i < 200 && automatic.HasPath; i++)
    automatic.Step(query, 0.1);
Console.WriteLine(automatic.State);
Text
Arrived

The short answer

Add an OffMeshLinkDefinition to the mesh’s build settings and follow a route with PathFollower. When the follower reaches the link entry, it enters FollowerState.OffMeshLink. Automatic mode advances along the link using the time step you supply. Host mode waits for your movement or animation code to call CompleteOffMeshLink.

These are separate jobs: the link makes the connection available to route search; the follower decides how to traverse it. A successful path query alone does not animate a jump. The sample builds disconnected islands specifically so reaching the other side requires the authored connection rather than an ordinary surface route.

How do I make a navmesh path cross a jump?

Place the start and end of the link near the surfaces they should connect, set its direction and radius, then include it when building the mesh. OnePath supports authored links in both its 2D and 3D builders. The small example uses a 2D floor with world X and Z as the map plane, but the endpoints are still three-dimensional positions.

For host-controlled movement, wait for OffMeshLink, read OffMeshStart and OffMeshEnd, and run your movement between those points. Call completion when that movement ends, not merely when the state first appears. The console example completes immediately after demonstrating that another Step still leaves it waiting. A game would instead wait for its animation or movement callback.

Automatic traversal is linear between the endpoints; it does not create a jump arc. Its duration is the three-dimensional link length divided by OffMeshSpeed. Choose host mode when you need a curved trajectory, a ladder animation or synchronization with another object. The follower rules define these transitions.

First separate route discovery from traversal. Check that placement and destination setup succeed, then inspect whether the follower ever enters OffMeshLink. A route that does not contain the connection cannot trigger a crossing, even if the endpoints look close in your renderer.

Next check the build and filter. The builder assigns the link to the tile containing its start; it drops the link if no tile was built there. Attachment depends on radius and vertical reach. Direction matters for a one-way link, and the filter must accept the connection’s flags and area as well as the polygons on either side. The authored-link rules explain tile assignment and validation.

Finally, check the traversal mode. In host mode, remaining at the entry is expected behavior, not a stalled search. Continue rendering your own movement and call completion once it finishes. In automatic mode, continue stepping with positive finite dt. The follower does not consult a clock on its own, so stopping calls to Step also stops automatic progress.

All onepath recipes