NavigationAgent3D in Godot – Complete Guide

Welcome to our comprehensive tutorial on the NavigationAgent3D class in Godot 4, a vital piece of the puzzle for creating dynamic, intelligent movement in 3D games. Navigating a virtual world effortlessly and avoiding obstacles with realism is foundational to an immersive gaming experience. Throughout this tutorial, we will explore the ins and outs of the NavigationAgent3D class, demonstrating how it can be utilized to add sophisticated pathfinding capabilities to your 3D characters or objects in Godot Engine. So, gear up for an exciting journey into the realm of AI-driven navigation where the possibilities are as vast as the worlds you wish to create!

What Is NavigationAgent3D?

NavigationAgent3D is a node class in the Godot Engine that enables objects to find paths through a scene while circumventing both static and dynamic barriers. This class employs pathfinding algorithms to calculate routes and RVO (Reciprocal Velocity Obstacles) collision avoidance to seamlessly navigate around other agents or obstacles. It’s designed to be simple to work with but powerful enough to handle common navigation challenges in 3D environments with ease.

What Is It For?

The functionality of NavigationAgent3D is critical for game development in scenarios where you need characters or objects to move intelligently in a 3D space. Whether it’s NPCs wandering around, enemies chasing the player, or simply moving items from point A to B, this class ensures they can reach their destination without bumping into walls or each other, providing a natural and convincing behavior.

Why Should I Learn It?

Understanding how to work with NavigationAgent3D can take your game’s interactivity and realism to the next level. Here’s why mastering this class is essential:

– Create sophisticated game AI: With NavigationAgent3D, NPCs can make decisions on how to move through the game world, making them appear more lifelike.
– Avoid the manual labor: Instead of programming how each character avoids obstacles, this class does the heavy lifting, saving you valuable development time.
– Enhance player experience: Characters that react and move realistically contribute to a more immersive gameplay experience for the player.
– Broaden your skillset: Expand your knowledge in game development by mastering a fundamental component of 3D environments.

The ability to effectively control the movement of objects within 3D space is a valuable skill for any aspiring game developer, and NavigationAgent3D provides a very accessible entry point into the world of AI, pathfinding, and character movement.

CTA Small Image

Setting Up Your NavigationMeshInstance

Before diving into the NavigationAgent3D specifics, we need to set up a NavigationMeshInstance for our scene. NavigationMeshInstance is essential as it defines the walkable and non-walkable areas within our 3D world. These areas dictate where an agent can and cannot move to.

var nav_mesh =
var navMeshInstance =

Replace yourMeshHere with your actual mesh resource that will be used as the navigation mesh. This mesh defines the navigable area.

Creating a Navigation Agent

Now let’s create a NavigationAgent3D node that will work with your NavigationMeshInstance for pathfinding. The following code adds a NavigationAgent3D instance as a child of the character or object that should move:

var agent =
agent.set_target_location(Vector3(10, 0, 10))

Setting set_target_location tells the agent where you want it to go. In this case, to the coordinates (10, 0, 10) in the 3D world space.

Moving the Agent Towards a Target

With the target set, create a simple function to move the agent towards its goal. You can call this function within the _process function to consistently move your agent.

func _process(delta):
    var path = agent.get_simple_path(agent.get_target_location(), true)
    if path.size() > 1:
        var direction = (path[1] - agent.global_transform.origin).normalized()
        agent.global_transform.origin += direction * speed * delta

This function obtains a simplified path to the target, calculates the direction, and updates the agent’s location. Be sure to replace speed with a pre-defined speed variable.

Handling Obstacle Avoidance

NavigationAgent3D natively supports obstacle avoidance using RVO. However, for this to work effectively, other moving objects must also be agents. Here is how you can set up other moving obstacles as agents:

for obstacle in get_tree().get_nodes_in_group("moving_obstacles"):
    var new_agent =

This code iterates through objects in the “moving_obstacles” group and adds a NavigationAgent3D to each. This allows your main agent to recognize them as dynamic obstacles to avoid.

Remember, when using obstacle avoidance, it is important to monitor performance, as simulating many agents can be computationally intensive. As you build up your scene, consider the number of active agents and their complexity to ensure that your game runs smoothly.

In the next part of the tutorial, we will delve into the signaling system provided by NavigationAgent3D and how we can link it to the game’s mechanics for an even more polished navigation experience.Now that we have a basic understanding of NavigationAgent3D and how it moves within the scene, it’s important to also utilize signals to ensure our agents are not just moving, but also interacting with the environment in a more dynamic and responsive manner.

Connecting Signals for Navigation Events

Godot’s signaling system allows you to connect events from the NavigationAgent3D node to custom callback functions. These events can be used to react to changes in the navigation process, such as reaching a destination or the path becoming invalid.

First, let’s connect to a signal that is triggered when the agent reaches its destination:

agent.connect("navigation_finished", self, "_on_NavigationAgent3D_navigation_finished")

func _on_NavigationAgent3D_navigation_finished():
    print("Destination reached!")

Similarly, we can connect to a signal that notifies us when the path changes, possibly due to moving obstacles or changes in the environment:

agent.connect("path_changed", self, "_on_NavigationAgent3D_path_changed")

func _on_NavigationAgent3D_path_changed():
    print("The path has changed!")

By responding to these signals, you can have your agents perform actions, like triggering animations or starting a new behavior, further increasing the realism of your game.

Adjusting the Agent’s Properties

Besides movement, the NavigationAgent3D class provides a variety of properties that can be adjusted to fine-tune the agent’s behavior. For example, you can set the agent’s maximum speed, acceleration, and radius for collision avoidance.

agent.max_speed = 5.0
agent.acceleration = 3.0
agent.radius = 1.0

These properties help define how quickly the agent can move, how fast it can reach its maximum speed, and how much space it requires to navigate around obstacles, respectively.

Velocity and Orientation

Sometimes, you may want to control the agent’s velocity directly or update its orientation to match the direction of movement. This can be especially useful when working with animations or needing the agent to face in the direction it’s traveling.

To set the agent’s velocity and update its orientation, use:

var desired_velocity = Vector3(1, 0, 1)
agent.velocity = desired_velocity

func _process(delta):
    var orientation = atan2(agent.velocity.x, agent.velocity.z)
    agent.rotation.y = orientation

Be sure to normalize and scale the velocity vector accordingly to match your game’s desired speed and controls.

Stopping and Resuming Movement

There will be situations where you need your agent to pause movement—perhaps the player is interacting with it, or it reached an area where it should wait.

To stop your agent, you can simply set its velocity to zero:

agent.velocity = Vector3.ZERO

To have it resume its pathfinding towards its target location, you can request a new path:

func resume_movement():
    var path = agent.get_simple_path(agent.get_target_location(), true)
    if path.size() > 1:
        # Continue moving towards the next checkpoint in the path
        # ... (Movement logic here)

Throughout the process, keeping code modular and encapsulating functionality for pathfinding, signal handling, and movement control within methods is considered good practice. It not only makes your code more maintainable but also allows for easier debugging and iteration.

With these examples, we can see how NavigationAgent3D offers a robust set of tools for implementing 3D pathfinding and obstacle avoidance in Godot Engine. By exploring these functionalities and incorporating them into your own projects, you’re sure to give life to characters that navigate your game world with impressively natural movement. Happy coding and game designing!Dynamic obstacle avoidance is a key feature of NavigationAgent3D. When the environment changes or other agents move, we must ensure our agent reacts accordingly. To manage dynamic updates, we can leverage the `obstacle_avoidance_enabled` property and adjust our approach with a few lines of code.

To enable dynamic obstacle avoidance, simply enable the corresponding property:

agent.obstacle_avoidance_enabled = true

Enabling this ensures that the agent will consider other registered agents in the scene when plotting a course.

Updating the Navigation Mesh at Runtime

Real-time changes in the game level might necessitate updates to the navigation mesh. For instance, if a bridge collapses or a wall is built, the navigation mesh should reflect these changes to maintain accurate pathfinding.

To update the navigation mesh at runtime, follow this procedure:

var new_navigation_mesh =
# Update the navigation mesh based on dynamic level changes
# ...

# Update the NavigationMeshInstance with the new data

This code snippet considers dynamic changes by creating a new `NavigationMesh` object and reassigning it to our agent’s `NavigationMeshInstance`.

Reacting to a Failed Pathfinding Attempt

In some cases, NavigationAgent3D may not find a path due to complex obstacles or blockages. It’s essential to handle these situations to prevent the agent from getting stuck or behaving erratically.

We can connect to the `navigation_failed` signal to handle failed pathfinding attempts gracefully:

agent.connect("navigation_failed", self, "_on_NavigationAgent3D_navigation_failed")

func _on_NavigationAgent3D_navigation_failed():
    print("Failed to find a path!")
    # Implement alternative behaviors or strategies

In this example, the `_on_NavigationAgent3D_navigation_failed` method could prompt the agent to perform another action like waiting, moving to an alternative target, or triggering an animation to show confusion.

Adjusting Path Smoothness

The paths generated by NavigationAgent3D might sometimes contain sharp turns or jittery movements that are not ideal for certain game types. In such cases, path smoothing can be employed.

Below is a method to smooth out the path points:

func smooth_path(raw_path):
    var smoothed_path = PoolVector3Array()
    for i in range(1, raw_path.size() - 1):
        var direction = raw_path[i + 1] - raw_path[i - 1]
        var point = raw_path[i] + direction.normalized() * 0.1
    smoothed_path.append(raw_path[raw_path.size() - 1])
    return smoothed_path

This adjusts each point along the path slightly towards the midpoint of its neighbors, resulting in a path that curves more naturally.

Integrating Pathfinding with Animation

When using a `KinematicBody3D` with NavigationAgent3D, it’s typical to want the movement to trigger appropriate animations. Below is a simple way to change animations based on the agent’s velocity:

func _process(delta):
    var velocity = agent.velocity
    if velocity.length() > 1:
        # The agent is moving, play the walk animation"walk")
        # The agent is stationary, play the idle animation"idle")

Replace `animation_player` with the actual instance of your `AnimationPlayer` node. This code will automatically switch between “walk” and “idle” animations based on the agent’s current movement status.

Following a Moving Target

In some scenarios, an agent must follow a moving target, such as a player character or a mobile point of interest. To achieve this, the agent requires constant updates to its target location.

Here’s a function that could be called every frame or at certain intervals to update the agent’s target position:

func follow_moving_target(target):
    var target_position = target.global_transform.origin

Ensure you call this function with a reference to the moving target in your `_process` function to keep the agent updated about the target’s position:

func _process(delta):

With these examples, we are beginning to see the versatility of the NavigationAgent3D class in Godot Engine 4. It’s clear that the functionality of NavigationAgent3D can be as simple or complex as the game demands, offering developers the flexibility to create nuanced and responsive AI behaviors.

Continuing Your Game Development Journey

Congratulations on taking the vital steps towards mastering NavigationAgent3D in Godot 4! With the tools and knowledge you’ve acquired, you’re well on your way to bringing your game’s AI to life. But don’t stop here; there’s a whole world within Godot waiting for you to explore. To further your game development journey, we invite you to check out our Godot Game Development Mini-Degree, which offers a comprehensive learning path to build cross-platform games with a focus on both practical and theoretical aspects of using Godot.

Whether you’re just starting out or seeking to enhance your existing skills, our well-structured curriculum and diverse course topics will guide you through 2D and 3D development, gameplay mechanics, and much more. All courses are designed to be flexible, allowing you to learn and create at your own pace, on any device. And to broaden your horizons even further, peruse our full catalogue of Godot courses to find content that matches your interests and advances your skill set.

Last but not least, remember that with Zenva, you’re building a portfolio of real projects that not only showcase your skills but also bring your game development dreams to fruition. Dive into our courses, emerge with new competencies, and stay at the forefront of the ever-evolving world of game development with Godot. Let’s make your game idea a playable reality!


Embarking on the journey of game creation with Godot’s NavigationAgent3D has opened up a universe of possibilities for crafting rich, navigable worlds filled with smart and dynamic characters. The concepts and techniques you’ve learned here pave the way for truly immersive and interactive games. But this is merely the beginning! As a creator, your potential is as vast as the open-world landscapes you can now orchestrate.

We at Zenva are thrilled to see the worlds you’ll build and the adventures you’ll design. Continue honing your skills with our Godot Game Development Mini-Degree and turn your creative vision into virtual reality. Every line of code brings you closer to becoming the game developer you aspire to be. So keep coding, keep creating, and let your imagination run wild – because the future of gaming is in your hands.

Python Blog Image

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