---
title: "Traverse navmesh off-mesh links in C#"
url: https://recursiveai.org/onepath/cookbook/traverse-off-mesh-links/
description: "Traverse an off-mesh link in C# with OnePath. Build two disconnected walkable areas, follow a route and complete a host-controlled crossing."
version: "1.2.0"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OnePath) · [GitHub](https://github.com/recursive-ai-oss/onepath-csharp) · [Docs](https://recursiveai.org/onepath/docs/) · [Download example (.zip)](https://recursiveai.org/onepath/cookbook/traverse-off-mesh-links/traverse-off-mesh-links.zip)

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

```shell
dotnet add package RecursiveAI.OnePath
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onepath/cookbook/traverse-off-mesh-links/traverse-off-mesh-links.zip), 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.

```csharp
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.

```csharp
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
```

## Related recipes

- [Navmesh path and raycast queries](https://recursiveai.org/onepath/cookbook/navmesh-queries/)
- [Build a navmesh from polygon obstacles](https://recursiveai.org/onepath/cookbook/build-navmesh-from-polygon-obstacles/)

---

## 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](https://recursiveai.org/onepath/docs/crowds/) define these transitions.

## Why is my navmesh link not working?

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](https://recursiveai.org/onepath/docs/navmesh-format/#authoring-off-mesh-links-agent-classes-streaming) 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.
