Path queries: endpoints, filters and metadata

NavigationPathQueryParameters2D holds query options; NavigationPathQueryResult2D receives points and metadata. NavigationServer2D.QueryPath(parameters, result) executes the query. Results do not update themselves when the target moves. The corresponding 3D types use the 3D suffix and Vector3.

Preconditions

Use an active navigation map with prepared regions. Obtain the intended NavigationRegion2D map through GetNavigationMap(). Supply start and target in that map's global coordinates, rather than a child Entity's local coordinates. The query mask must overlap region layers: see navigation layers.

Wait for navigation publication after creating or changing regions. MapGetIterationId(map) == 0 means the first version is missing; a larger value does not establish freshness of all later changes. The RID must belong to a live map: do not reuse it after FreeRid.

Reusable 2D query

Save PathQuery2D.cs in a Reckfell 1.0.0 C# project:

using Reckfell;
using System;

public sealed class PathQuery2D : IDisposable
{
    public NavigationPathQueryParameters2D Parameters { get; } = new();
    public NavigationPathQueryResult2D Result { get; } = new();

    public bool ConnectsEndpoints(Rid map, Vector2 start, Vector2 target,
        uint layers, float tolerance = 0.1f)
    {
        Result.Reset();
        Result.PathLength = 0;
        if (!map.IsValid || layers == 0 || tolerance < 0
            || NavigationServer2D.MapGetIterationId(map) == 0)
            return false;

        Parameters.Map = map;
        Parameters.StartPosition = start;
        Parameters.TargetPosition = target;
        Parameters.NavigationLayers = layers;
        NavigationServer2D.QueryPath(Parameters, Result);
        Vector2[] path = Result.Path;
        return path.Length > 0 && path[0].DistanceTo(start) <= tolerance
            && path[^1].DistanceTo(target) <= tolerance;
    }

    public void Dispose()
    {
        Parameters.Dispose();
        Result.Dispose();
    }
}

Keep one helper per query owner and call ConnectsEndpoints(map, start, target, layers) again when needed. Read Result.Path after the call. Call Dispose() when its owner no longer needs queries. Do not share one instance across concurrently executing independent queries.

true means that the first and last points are within tolerance of the requested start and target. false can mean an unready map, no path or a partial/projected path. In the latter case, points remain in Result.Path; your game decides whether to follow a partial route. This method does not establish that a physical body has reached the target or fits through the passage.

For adjacent regions on layers 1 and 2, the fixture returns a complete route with mask 3. Mask 1 produces a path to the first region boundary; mask 2 projects the start onto the second region. In both cases the helper returns false even though points exist.

Filters and metadata

Set additional options through Parameters before calling. The helper replaces map, start, target and mask; other parameters persist between calls.

Do not resolve a zero owner ID to an Entity. A region RID and an Entity ID are distinct identifiers. Metadata does not execute link transitions or move a character.

Before filtering routes through NavigationLink, check the navigation link limitations.

Processing and limits

PathPostprocessing controls the found corridor: Corridorfunnel shortens the path inside it, Edgecentered uses the centers of crossed edges, and None leaves the raw variant. This does not search for a globally shortest route outside the selected corridor.

SimplifyPath with SimplifyEpsilon removes less relevant points; check the result on your geometry. All three modes and simplification preserved endpoints in the simple rectangular fixture, which does not establish quality on a complex level.

PathReturnMaxLength and PathReturnMaxRadius clip the returned path after searching; zero disables the corresponding limit. They can intentionally leave the endpoint far from the target. PathSearchMaxDistance and PathSearchMaxPolygons limit the search itself: low values can produce an incomplete or poor route. Do not promise performance gains without measurements on your level.

In SDK 1.0.0, Reset() clears arrays but retains PathLength, so the helper explicitly resets the length too. A completed new query replaces the data; after rejecting a request before execution, do not treat an old length as evidence of a path.

Executed checks cover the exact helper, masks, both endpoints, reuse, region filters, metadata, length/radius clipping, processing modes and the Reset() behavior. Basic masks and Reset() were also checked in 3D. NavigationLink, movement, avoidance, search-limit quality, callbacks and complex meshes are outside this suite's coverage.