Запрос пути: достижимость, фильтры и метаданные

NavigationPathQueryParameters2D задаёт запрос, NavigationPathQueryResult2D получает точки и метаданные. NavigationServer2D.QueryPath(parameters, result) выполняет запрос; результат сам по себе не обновляется при перемещении цели. Для 3D существуют соответствующие типы с суффиксом 3D и Vector3.

Условия перед запросом

Нужна активная навигационная карта с подготовленными регионами. Возьмите карту нужного NavigationRegion2D через GetNavigationMap(). Старт и цель передавайте в глобальных координатах этой карты, а не локальных координатах дочерней Entity. Маска запроса должна пересекаться со слоями регионов: навигационные слои.

Дождитесь опубликованной навигации после создания или изменения регионов. MapGetIterationId(map) == 0 означает отсутствие первой версии; значение больше нуля не подтверждает свежесть всех последующих изменений. RID должен принадлежать живой карте: не используйте его после FreeRid.

Повторно используемый запрос 2D

Сохраните PathQuery2D.cs в C#-проекте Reckfell 1.0.0:

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();
    }
}

Создайте один экземпляр помощника для владельца запроса и повторно вызывайте ConnectsEndpoints(map, start, target, layers). После вызова читайте Result.Path. Освободите помощник через Dispose(), когда владелец больше не будет делать запросы. Не используйте один экземпляр для одновременно выполняемых независимых запросов.

true означает, что первая и последняя точки находятся в пределах tolerance от переданных старта и цели. false может означать неготовую карту, отсутствие пути или частичный/спроецированный путь. В последнем случае точки остаются в Result.Path: решение следовать по частичному маршруту принимает ваша логика. Никакой результат этого метода не гарантирует, что физическое тело уже дошло до цели или поместится в проходе.

Для двух соседних регионов со слоями 1 и 2 проверка получает полный путь при маске 3. При маске 1 возвращается путь к границе первого региона, а при маске 2 старт проецируется на второй. В обоих случаях помощник возвращает false, хотя точки существуют.

Фильтры и метаданные

Дополнительные параметры задавайте через Parameters перед вызовом. Помощник обновляет карту, старт, цель и маску; остальные параметры сохраняются между запросами.

Не пытайтесь получить Entity по нулевому ID. RID региона и ID Entity — разные идентификаторы. Метаданные сами не исполняют переходы через ссылки и не перемещают персонажа.

Для фильтрации маршрутов с NavigationLink сначала проверьте ограничения навигационных связей.

Обработка и ограничения

PathPostprocessing выбирает обработку найденного коридора: Corridorfunnel сокращает путь внутри него, Edgecentered использует середины пересекаемых рёбер, None оставляет исходный вариант. Это не поиск глобально кратчайшего маршрута вне выбранного коридора.

SimplifyPath с SimplifyEpsilon удаляет менее значимые точки; проверяйте результат на своей геометрии. Для простой прямоугольной проверки все три режима и упрощение сохранили концы маршрута — это не доказательство качества на сложном уровне.

PathReturnMaxLength и PathReturnMaxRadius обрезают возвращённый путь после поиска; 0 отключает соответствующий предел. Они могут намеренно оставить конец далеко от цели. PathSearchMaxDistance и PathSearchMaxPolygons ограничивают сам поиск: слишком малые значения могут дать неполный или неудачный маршрут. Не обещайте прирост производительности без измерений на своём уровне.

В SDK 1.0.0 Reset() очищает массивы, но сохраняет PathLength. Поэтому помощник дополнительно обнуляет длину. Успешно выполненный новый запрос заменяет данные; после отказа до запроса нельзя использовать старую длину как признак существования пути.

Проверены точный помощник, маски, оба конца пути, повторное использование, фильтры регионов, метаданные, обрезка длины/радиуса, режимы обработки и особенность Reset(). Отдельно проверены базовые маски и Reset() в 3D. NavigationLink, движение, избегание, качество ограниченного поиска, callback и сложные меши не проверены этим набором.