Recursive AI

Snapshot and restore navmesh state in C#

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

Save navigation mesh state for rollback, including tile slots and runtime edits.

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.Mesh;
 
var mesh = NavMesh.Build2D(
    Grid.FromText("....")); // '.' = walkable cell
var tiles = mesh.Tiles;
byte[] saved = tiles.Snapshot(
    SnapshotMode.Full);
var polygon = tiles.GetSlotRef(0).Poly(0);
tiles.SetPolyArea(polygon, 3);
tiles.Restore(saved);
Console.WriteLine(saved.AsSpan()
    .SequenceEqual(tiles.Snapshot()));
Text
True

Slots and generations are part of polygon references, so restoring them preserves which references are valid.

Unzip the example, then dotnet run.

Full program

C#
using RecursiveAI.OnePath;
using RecursiveAI.OnePath.Mesh;
 
var mesh = NavMesh.Build2D(Grid.FromText("....\n....")); // '.' = walkable cell
var tiles = mesh.Tiles;
var polygon = tiles.GetSlotRef(0).Poly(0);
tiles.SetPolyArea(polygon, 3);
tiles.SetPolyFlags(polygon, 7);
byte[] saved = tiles.Snapshot(SnapshotMode.Full);
Console.WriteLine($"Saved area: {tiles.GetTileBySlot(0)!.PolyAreas[0]}");
tiles.SetPolyArea(polygon, 5);
tiles.SetPolyFlags(polygon, 0);
Console.WriteLine($"Changed area: {tiles.GetTileBySlot(0)!.PolyAreas[0]}");
tiles.Restore(saved);
Console.WriteLine($"Restored area: {tiles.GetTileBySlot(0)!.PolyAreas[0]}");
Console.WriteLine($"Restored flags: {tiles.GetTileBySlot(0)!.PolyFlags[0]}");
Console.WriteLine($"Reference valid: {tiles.IsValid(polygon)}");
Console.WriteLine($"Same bytes: {saved.AsSpan().SequenceEqual(tiles.Snapshot())}");
var restored = NavMeshSnapshot.Restore(saved);
Console.WriteLine($"New mesh same bytes: {saved.AsSpan().SequenceEqual(restored.Snapshot())}");

dotnet run prints:

Text
Saved area: 3
Changed area: 5
Restored area: 3
Restored flags: 7
Reference valid: True
Same bytes: True
New mesh same bytes: True

The full program builds a two-row, four-column walkable grid from "....\n....", saves area 3 and flags 7, changes them, then restores both in place and into a new mesh. Invalid snapshot bytes throw NavMeshFormatException; an incompatible build fingerprint throws NavMeshFingerprintException, without partially replacing the existing mesh.

Variations

After the full program, use a tile library for a referenced snapshot:

C#
var library = new TileLibrary();
for (int slot = 0; slot < tiles.SlotCount; slot++)
    if (tiles.GetTileBySlot(slot) is { } tile)
        library.Add(tile);
byte[] referenced = tiles.Snapshot(SnapshotMode.Referenced);
var fromLibrary = NavMeshSnapshot.Restore(referenced, library);
Console.WriteLine(referenced.AsSpan().SequenceEqual(
    fromLibrary.Snapshot(SnapshotMode.Referenced)));
Text
True

Query a navmesh · Roll back a crowd

The short answer

Call TiledNavMesh.Snapshot(SnapshotMode.Full) to capture self-contained navigation mesh state, then call Restore on that mesh to roll back later mutations. Use NavMeshSnapshot.Restore(saved) when you want a new tiled mesh rather than replacing the state of an existing one.

A snapshot includes tile slots and generations, runtime polygon areas and flags, and off-mesh link switches. It is different from saving geometry for later loading: rollback must preserve reference validity and dynamic edits, not just produce a similar walkable surface.

How do I snapshot and restore a navmesh in C#?

The example builds a small walkable grid in memory. NavMesh.Tiles exposes the underlying TiledNavMesh; no mesh file or editor export is required. The full program sets an area and flags on its first polygon, snapshots that state, changes both values, and restores the snapshot.

The result restores the saved area and flags. The polygon reference obtained before the snapshot is valid after restoration, and a second snapshot equals the original bytes. The state covered by snapshots is defined in the snapshot documentation.

Slots and generations matter because polygon references contain them. Rebuilding equivalent geometry alone is not the same operation as restoring these values. Query buffers and query objects are not snapshot state. Stitched links and bounding-volume trees are derived data and are rebuilt during restoration rather than stored as independent state.

Can I restore a navmesh snapshot without the original tiles?

Use Full mode for a self-contained snapshot. It stores the tiles’ as-built bytes as well as their runtime edits. Restoring it into a new mesh needs no tile library. It is also the default mode when Snapshot() is called without an argument.

Referenced mode stores tile content IDs instead of inline tile bytes. Restoration requires a TileLibrary containing every named tile. The variation adds the fixture’s tiles to a library and restores using it. A library missing a required tile cannot restore that snapshot. Keep the tile library available for as long as you retain referenced snapshots.

A tile’s content ID describes its as-built data, not its current polygon edits. Runtime edits are represented separately in the snapshot. This lets the same underlying tile content support different saved runtime states without treating every area change as new geometry.

Is a navmesh snapshot the same as saving a mesh?

No. NavMeshSerializer.WriteMesh stores current tile areas and flags as content and does not store link switches. Reading that content back makes those values the new as-built values. That is useful for shipping mesh data, but it is not a substitute for rollback state.

Snapshots instead preserve the state needed to return to a particular moment. Restoring in place requires matching mesh parameters, including the build fingerprint. The reader parses and checks the snapshot, constructs replacement state separately and swaps it into the mesh only after the earlier steps succeed. A malformed snapshot therefore does not leave a partially restored mesh.

Crowd movement and the tile cache are separate concerns. A mesh snapshot does not capture a crowd’s positions or velocities. For a 3D-built world with runtime obstacles, area volumes and a pending rebuild queue, use the tile cache snapshot described in the same documentation: it wraps a mesh snapshot with the cache’s own state.

All onepath recipes