Навигация 3D: персонаж, пол и первый маршрут

Для ходьбы по поверхности нужны навигационные данные, физический пол и код движения персонажа. NavigationMesh не создаёт коллайдер пола, а NavigationAgent3D не двигает родителя автоматически. Пример ниже рассчитан на ровную поверхность; это не готовый контроллер лестниц, прыжков или платформ.

Подготовить уровень

Используйте C#-проект Reckfell 1.0.0. Для проверки подойдёт навигационный прямоугольник x=0–20, z=0–10 на y=0, назначенный региону активной карты. Как получить ресурс из геометрии — запекание навигации.

Создайте физический пол: StaticBody3D с CollisionShape3D и BoxShape3D. В проверке коробка имеет размер (40, 1, 20), центр (10, -0,5, 5), поэтому её верх находится на y=0 и покрывает навигационную поверхность.

Создайте CharacterBody3D с началом координат у стоп. В дочерней CollisionShape3D используйте капсулу высотой 1,8 и радиусом 0,3, смещённую вверх на (0, 0,9, 0). Добавьте дочерний NavigationAgent3D с точным именем NavigationAgent3D.

Положение начала координат важно: агент использует позицию родителя, а путь лежит на поверхности карты. Если начало тела находится на высоте груди, малый допуск до точки на полу может мешать завершению маршрута.

Движение с гравитацией

Прикрепите к телу NavigationWalker3D.cs:

using Reckfell;

public partial class NavigationWalker3D : CharacterBody3D
{
    [Export] public float Speed { get; set; } = 8;
    [Export] public float Gravity { get; set; } = 9.8f;
    public NavigationAgent3D Agent { get; private set; } = null!;

    public override void _Ready()
    {
        Agent = GetEntity<NavigationAgent3D>("NavigationAgent3D");
        Agent.PathDesiredDistance = 0.25f;
        Agent.TargetDesiredDistance = 0.25f;
        Agent.AvoidanceEnabled = false;
    }

    public void SetDestination(Vector3 target) => Agent.TargetPosition = target;

    public override void _PhysicsProcess(double delta)
    {
        Vector3 velocity = Velocity;
        velocity.Y = IsOnFloor() ? 0 : velocity.Y - Gravity * (float)delta;
        velocity.X = 0; velocity.Z = 0;
        if (NavigationServer3D.MapGetIterationId(Agent.GetNavigationMap()) > 0
            && !Agent.IsNavigationFinished())
        {
            Vector3 direction = Agent.GetNextPathPosition() - GlobalPosition;
            direction.Y = 0;
            direction = direction.Normalized();
            velocity.X = direction.X * Speed;
            velocity.Z = direction.Z * Speed;
        }
        Velocity = velocity;
        MoveAndSlide();
    }
}

Задайте положительную Speed и неотрицательную Gravity. Для отдельной карты назначьте walker.Agent.SetNavigationMap(map). После готовности поверхности вызовите walker.SetDestination(new Vector3(18, 0, 5)).

В проверке тело появилось в (2, 1, 5), опустилось на пол, прошло к цели и остановилось. Горизонтальная скорость задаётся в единицах в секунду; на delta умножается ускорение гравитации, а не скорость перед MoveAndSlide().

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

Проверить результат, а не только путь

Сначала проверьте IsOnFloor(), положение стоп, движение по XZ и остановку у цели. Затем выполните два отрицательных сценария:

1. Цель за краем навигации: в проверке (30, 0, 5) дала частичный маршрут. IsNavigationFinished() стал true, а IsTargetReached() остался false.
2. Физическая стена, отсутствующая в навигации: тело упёрлось в неё, хотя найденный путь шёл прямо. Это ошибка согласования геометрии, а не повод отключать коллизию.

Если путь получен после растеризации запекания, его высота может отличаться от исходного пола. Проверьте фактические точки, начало координат тела и допуски. Не скрывайте несогласованность огромным TargetDesiredDistance.

Другие модели маршрута

Для заданных точек и связей есть AStar3D; это не автоматический анализ объёмного мира. Для ходьбы по мешу используйте карту/регионы и прямой MapGetPath либо агента. Для прыжка или телепорта нужна связь и игровое исполнение перехода.

Сборка рисунка уровня в редакторе, камера, модели и свет не входят в этот скрипт. Они нужны для визуального проекта, но не заменяют проверку физического пола и навигации.

Проверены точный код, капсула со стопами у начала координат, гравитация, ходьба по ровному полу, остановка, частичный путь и физическая стена. Склоны, ступени, платформы, избегание, переходы связей, интерфейс редактора и графика этим набором не проверены.