3D navigation: character, floor and first route

Surface walking needs navigation data, a physics floor and character movement code. NavigationMesh does not create a floor collider, and NavigationAgent3D does not automatically move its parent. This example targets a flat surface, rather than being a complete stair, jump or platform controller.

Prepare the level

Use a Reckfell 1.0.0 C# project. The fixture uses navigation rectangle x=0–20, z=0–10 at y=0, assigned to a region on an active map. See navigation baking for building a resource from geometry.

Create a physics floor: a StaticBody3D containing CollisionShape3D with BoxShape3D. The checked box has size (40, 1, 20) and center (10, -0.5, 5), so its top lies at y=0 and covers the navigation surface.

Create a CharacterBody3D with its origin at the feet. Give its child CollisionShape3D a capsule of height 1.8 and radius 0.3, offset upward by (0, 0.9, 0). Add a child NavigationAgent3D named exactly NavigationAgent3D.

The origin matters: the agent uses its parent position while path points lie on the map surface. A chest-height body origin can prevent route completion with a small distance tolerance to floor points.

Move with gravity

Attach NavigationWalker3D.cs to the body:

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

Use a positive Speed and nonnegative Gravity. Assign a custom map with walker.Agent.SetNavigationMap(map) when needed. Once the surface is ready, call walker.SetDestination(new Vector3(18, 0, 5)).

The checked body started at (2, 1, 5), settled onto the floor, walked to the goal and stopped. Horizontal velocity is in units per second; delta scales gravity acceleration rather than velocity supplied to MoveAndSlide().

The example deliberately disables avoidance. Enabling it requires a separate VelocityComputed application path; flipping the flag while retaining direct movement does not correctly apply computed velocity.

Check behavior rather than only path points

First verify IsOnFloor(), foot position, XZ movement and goal stopping. Then run two negative scenarios:

1. A goal beyond navigation: (30, 0, 5) produced a partial route. IsNavigationFinished() became true while IsTargetReached() stayed false.
2. A physics wall absent from navigation: it stopped the body despite a straight path. Fix mismatched geometry rather than disabling collisions.

Bake rasterization can place path height above the source floor. Inspect actual points, the body origin and tolerances. Do not hide the mismatch with an enormous TargetDesiredDistance.

Other route models

Use AStar3D for predefined points and connections; it does not automatically analyze a volumetric world. For surface walking, use maps/regions and direct MapGetPath or an agent. Jumps and teleports need a link and transition implementation.

Editor artwork, a camera, models and lights are outside this script. They are needed for a visual project but do not replace physics-floor and navigation checks.

Executed checks cover the exact code, a feet-origin capsule, gravity, flat-floor walking, stopping, a partial path and a physics wall. Slopes, stairs, platforms, avoidance, link traversal, editor UI and graphical output were not tested by this suite.