NavigationServer3D in Godot – Complete Guide

Navigating the digital landscapes of our creations plays a pivotal role in bringing life to games and virtual environments. Whether guiding a character through a maze or directing a drone over an alien terrain, understanding the mechanics of virtual movement is a cornerstone of game development. Today, we delve into the world of 3D navigation in Godot 4, a powerful game engine beloved by developers for its open-source nature and robust features.

One of Godot 4’s tools for handling navigation in three-dimensional spaces is the NavigationServer3D class. This tutorial aims not only to illuminate the capabilities and functions of NavigationServer3D but also to equip you with the knowledge to implement advanced navigation features into your projects. So, let the journey begin, and let’s explore the realms of 3D navigation together!

What Is NavigationServer3D?

NavigationServer3D is a powerful class in Godot 4 designed to provide low-level access to 3D navigation capabilities. Unlike AStar3D, which provides A* pathfinding algorithms, NavigationServer3D manages navigation maps, regions, agents, and meshes. These components collectively form the navigational blueprint of a game’s 3D world.

What Is It For?

At its core, NavigationServer3D serves to:

  • Create navigable areas within a 3D environment through regions and navigation meshes.
  • Define pathways and control spatial relationships, ensuring regions are seamlessly connected for smooth navigation.
  • Incorporate layers, aiding in the fine-tuning of path requests to manage accessibility across various game entities.
  • Enable dynamic collision avoidance among agents via a sophisticated avoidance system.

Why Should I Learn It?

Understanding and mastering NavigationServer3D is essential for several reasons:

  • Creating Immersive Experiences: Sophisticated navigation enhances gameplay by enabling realistic movements and interactions in a 3D world.
  • Performance Optimizations: Leveraging the server’s efficient pathfinding and avoidance algorithms can significantly boost a game’s performance.
  • Multi-threaded Support: The server facilitates any navigation updates in a thread-safe manner, allowing for smooth gameplay without framerate hiccups.
  • Customization and Flexibility: With an array of methods and signals to work with, you can tailor navigation to fit any scenario or gaming mechanic.

Learning to work with NavigationServer3D will enhance your skillset, allowing you to construct more dynamic, responsive, and engaging 3D environments. Let’s dive deeper into this essential tool and see how it can transform your gaming projects!

CTA Small Image

Setting Up a Navigation Mesh Instance

To start utilizing the NavigationServer3D in Godot 4, we must first set up a navigation mesh instance. This mesh will act as the foundation for the areas that can be navigated by your agents.

var navmesh_instance =
var map_id = NavigationServer3d.map_create()
NavigationServer3D.region_set_map(navmesh_instance.get_rid(), map_id)

In this example, we initialize a new NavigationMeshInstance, which is a specialized node for navigation meshes. Then, we use the create_from_mesh method to build it from your custom mesh. Following that, we create a new map using NavigationServer3D.map_create() and associate our navigation mesh instance with this map.

Defining and Connecting Navigation Regions

In complex environments, you may have several interconnected regions that need to be navigated between. Here’s how you define and connect these regions:

var navmesh_instance1 =
var navmesh_instance2 =

var map_id = NavigationServer3D.map_create()
NavigationServer3D.region_set_map(navmesh_instance1.get_rid(), map_id)
NavigationServer3D.region_set_map(navmesh_instance2.get_rid(), map_id)


This snippet demonstrates how to connect two separate navigation mesh instances. After creating and setting up each instance with their respective meshes, we enable a connection between them using NavigationServer3D.region_set_connection, allowing agents to travel across the mesh boundaries seamlessly.

Creating and Managing Navigation Agents

Navigation agents represent entities that navigate the mesh, such as players or AI characters. Here’s how you can create an agent and adjust its parameters:

var agent_id = NavigationServer3D.agent_create()
NavigationServer3D.agent_set_map(agent_id, map_id)

NavigationServer3D.agent_set_position(agent_id, Vector3(0, 0, 0))
NavigationServer3D.agent_set_velocity(agent_id, Vector3(2, 0, 0))
NavigationServer3D.agent_set_max_speed(agent_id, 5.0)
NavigationServer3D.agent_set_radius(agent_id, 1.0)

We start by creating a navigation agent using NavigationServer3D.agent_create() and setting it to our map with agent_set_map. Next, we set its initial position, desired velocity, maximum speed, and radius for its collision shape.

Basic Pathfinding with NavigationServer3D

Once our agents are set up, we can use NavigationServer3D to find paths from one point to another. Below is a simple pathfinding example:

var start_position = Vector3(0, 0, 0)
var end_position = Vector3(10, 0, 10)
var path = NavigationServer3D.map_get_path(map_id, start_position, end_position, true)

for point in path:
  print("Path point: ", point)

In this code, we use NavigationServer3D.map_get_path to calculate a path from a start to an end position. The boolean argument, when set to true, ensures that the method takes navigation mesh connectivity into account. The resulting path is an array of points that an agent can follow.Navigating around obstacles is key for a realistic experience. It’s crucial for characters to avoid colliding with items in their path. Godot’s NavigationServer3D provides a method to do just that with avoidance algorithms that will dynamically alter the agent’s path.

To use obstacle avoidance, we set an agent’s target location and update its velocity accordingly:

var desired_position = Vector3(50, 0, 50)
NavigationServer3D.agent_set_target_location(agent_id, desired_position)
var avoidance_force = NavigationServer3D.agent_get_next_velocity(agent_id)
NavigationServer3D.agent_set_velocity(agent_id, avoidance_force)

In this snippet, we update an agent’s target and retrieve the calculated velocity that accounts for obstacle avoidance. We then apply the new velocity to the agent, ensuring a collision-free route.

Frequently, games require agents to make uninterrupted movements, where sudden changes in direction could break immersion. Godot’s NavigationServer3D can help smooth these transitions.

var current_velocity = NavigationServer3D.agent_get_velocity(agent_id)
var new_velocity = lerp(current_velocity, desired_velocity, 0.1)
NavigationServer3D.agent_set_velocity(agent_id, new_velocity)

This example demonstrates using the `lerp` function to interpolate between the current velocity and the desired velocity over time, creating smoother movement transitions.

In a multiplayer setting or where multiple agents are present, synchronization is key. We can manage multiple agents within the same navigation system to ensure coherent movements and behaviors.

var agent_ids = [NavigationServer3D.agent_create(), NavigationServer3D.agent_create()]

for agent_id in agent_ids:
  NavigationServer3D.agent_set_map(agent_id, map_id)
  NavigationServer3D.agent_set_position(agent_id, Vector3(rand_range(-10, 10), 0, rand_range(-10, 10)))
  NavigationServer3D.agent_set_max_speed(agent_id, rand_range(3.0, 6.0))

Above, we create and configure two agents, giving them random start positions and speeds to simulate a dynamic environment.

Sometimes, virtual environments change, and the navigation mesh needs to adapt accordingly. You can update the navigation mesh in real-time with the following method:

var new_mesh = create_dynamic_obstacle_mesh()
var navmesh_instance_id =
NavigationServer3D.region_set_map(navmesh_instance_id.get_rid(), map_id)

This code shows how to create a new navigation mesh instance on-the-fly. It’s perfect for situations where the environment changes due to player interaction or dynamic events.

Agent State Monitoring

Monitoring your agents is essential for debugging and gameplay scripting. For example, we often want to check whether an agent has reached its destination:

var has_reached_target = NavigationServer3D.agent_is_target_reached(agent_id)
if has_reached_target:
  print("Agent has arrived at its target.")

This simple check can trigger events or change behaviors once an agent arrives at its target location.

To further expand your game’s capacity for dynamic environments, you can also bake the navigation mesh during runtime if your terrain changes.

var terrain_mesh = generate_terrain_mesh()  # Assume this is a method that generates a mesh for your changing terrain.
NavigationServer3D.navmesh_add(navmesh_instance.get_rid(), navmesh_instance.global_transform, navmesh_instance.navmesh)

In this example, a new terrain mesh is generated, and we bake a fresh navigation mesh from it, allowing the game world to adapt to new navigable areas whenever terrain alterations take place.

By now, you should have a better grasp of 3D navigation using Godot’s NavigationServer3D. Remember, practice and exploration of these functions will lead to a stronger command of navigating within your game world. Keep experimenting to see what thrilling dynamics you can bring to life in your games!Absolutely, we’ll carry on by diving deeper into the nuances of NavigationServer3D. This powerful class allows for a wide variety of advanced navigation maneuvers, ensuring your agents move in a realistic and engaging manner.

Let’s first look at how you can adjust the properties of the navigation mesh:

var navmesh_settings =
navmesh_settings.agent_height = 2.0
navmesh_settings.agent_radius = 0.5
navmesh_settings.cell_size = 0.3

var navmesh_instance =
navmesh_instance.navmesh = navmesh_settings
NavigationServer3D.region_set_map(navmesh_instance.get_rid(), map_id)

In the snippet above, we customize the navigation mesh properties, such as agent height, agent radius, and cell size—crucial parameters for the navigation algorithms to consider the physical space the entity occupies.

Following up, let’s explore how to handle dynamic obstacles that might block the path of an agent. In games, such dynamic obstacles are common and handling them efficiently is important:

var obstacle =
var obstacle_id = obstacle.get_rid()
var obstacle_transform = Transform()
# Define the obstacle's size and position
obstacle.set_extents(Vector3(1, 1, 1))

# Add the obstacle to the NavigationServer3D
NavigationServer3D.obstacle_add(obstacle_id, map_id)

The code snippet above creates a new obstacle and adds it to the NavigationServer3D. The navigation server now knows to consider this object when plotting paths.

Next, let’s look at a way to continuously update an agent’s path in a changing environment:

func _process(delta):
    var new_path = NavigationServer3D.map_get_path(map_id, agent_position, desired_target_position, true)
    NavigationServer3D.agent_set_path(agent_id, new_path)

In this function, which would be called each frame, we’re dynamically recalculating the path to the target position and updating the agent’s path. This is especially useful if the target is moving or if the environment changes.

To fine-tune agent behavior for cases such as NPCs following the player, consider incorporating path smoothing:

var path = NavigationServer3D.map_get_path(map_id, npc_position, player_position, false)
var smoothed_path = smooth_path(path)
NavigationServer3D.agent_set_path(agent_id, smoothed_path)

func smooth_path(path):
    # Implement your custom path smoothing algorithm
    # Return the new smoothed path

With the simple function prototype `smooth_path`, developers can inject their custom smoothing algorithms, which could include techniques like cubic splines or bezier curves to create more natural movements.

For more complex scenes where agents may need to change navigation levels, such as going up or down stairs, you can implement off-mesh links:

var offmesh_link_start = Vector3(0, 0, 0)
var offmesh_link_end = Vector3(0, 10, 0)
var offmesh_connection_id = NavigationServer3D.offmesh_connection_create()
NavigationServer3D.offmesh_connection_set_start(offmesh_connection_id, offmesh_link_start)
NavigationServer3D.offmesh_connection_set_end(offmesh_connection_id, offmesh_link_end)
NavigationServer3D.offmesh_connection_set_map(offmesh_connection_id, map_id)

The above snippet creates an off-mesh connection, which agents can use to navigate between disconnected areas of the navigation mesh that represent different elevation levels. This is essential for multi-floor navigation.

Lastly, to optimize navigation performance in your game, especially when having many agents or complex scenes, you might want to stagger your pathfinding updates:

func _process(delta):
    if Engine.get_frames_drawn() % 10 == 0:  # Update every 10 frames
        var new_path = NavigationServer3D.map_get_path(map_id, agent_position, target_position, true)
        NavigationServer3D.agent_set_path(agent_id, new_path)

The `_process` function here uses Godot’s built-in `Engine.get_frames_drawn()` to update the agent’s path periodically instead of every frame. This reduces the computational load, preventing your game’s performance from dipping while still maintaining effective navigation for multiple agents.

With these examples, you should have an array of techniques to tackle different navigational challenges. What makes Godot’s NavigationServer3D special is its flexibility, allowing game developers to craft intricate navigation behaviors that suit the unique needs of their gameplay. Keep experimenting with these tools, and take your game’s navigation to the next level!

Continuing Your Game Development Journey

Embarking on the path of game development with Godot 4 is an exciting adventure filled with endless possibilities. As you’ve started to understand the depth of 3D navigation, it’s natural to wonder, “Where do I go from here?” The journey of learning is continuous, and there is so much more to explore in Godot’s ever-expanding universe.

We at Zenva encourage you to keep the momentum going by delving deeper into our comprehensive Godot Game Development Mini-Degree. With a curriculum crafted to transition you from beginner to building your own games, the mini-degree is a leap towards mastering not just navigation, but all facets of game development in Godot 4. From understanding the intricacies of 2D and 3D assets to controlling gameplay flow and designing engaging combat systems, the mini-degree is your gateway to creating a professional portfolio in the world of games.

For those who thirst for a wider breath of topics, our broader range of Godot courses span across various subjects, ensuring you have all the knowledge at your fingertips. Whether you are starting out or leveling up your skills, Zenva offers over 250 supported courses to keep your learning journey vibrant and fruitful. So, continue to learn, create, and let your passion for game development flourish!


As you’ve dived into the realms of 3D navigation in Godot 4, you’ve unlocked just a glimpse of the boundless potential that awaits in game development. Remember, NavigationServer3D is merely a single piece of the vast puzzle. With each step forward, you acquire another tool for your developer’s toolkit, bringing you closer to crafting the immersive and innovative experiences you envision. Our journey at Zenva continues alongside yours, as we strive to provide engaging and up-to-date content that propels your learning to new heights.

We invite you to keep exploring our extensive Godot Game Development Mini-Degree and take advantage of the curated knowledge within. Each challenge you overcome and every skill you perfect with us not only enhances your game projects but also fortifies your path as a game developer. With the power of Godot 4 and the support of Zenva’s educational resources, your development journey is limited only by your imagination. So keep coding, keep creating, and transform your game development dreams into reality!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.