NavigationAgent2D in Godot – Complete Guide

Welcome to our deep dive into the realm of game mechanics with the NavigationAgent2D class in Godot 4! Are you interested in creating dynamic game characters that can elegantly maneuver around obstacles to reach their destination? Whether you’re at the beginning of your coding journey or you’ve been coding for years, the magic of pathfinding and avoiding obstacles in 2D space is an essential skill for any game developer. Our step-by-step tutorial will guide you through the intricacies of the NavigationAgent2D class, enabling you to bring sophisticated navigation capabilities to your game characters.

What is NavigationAgent2D?

// NavigationAgent2D: A class for dynamic pathfinding and obstacle avoidance in 2D games.

NavigationAgent2D is a Godot Engine class that represents an intelligent agent capable of finding its way in a 2D environment. It’s specifically designed to calculate paths and make characters or objects move towards a target while avoiding both static and dynamic obstacles. This class is part of Godot’s powerful navigation system, which includes other components like Navigation2D and NavigationPolygon.

What is it for?

The primary use of NavigationAgent2D is to automate movement within a game. It offers a rich set of features that are essential for creating smooth and natural-looking character movements. With NavigationAgent2D, you can ensure your characters do not walk through walls or collide with other moving characters, making gameplay feel more realistic and immersive.

Why should I learn it?

Learning to use the NavigationAgent2D class has several benefits:

– **Enhance Game Dynamics**: Comprehending how to implement sophisticated pathfinding can take your game’s dynamics to the next level. Characters with intelligent movement can respond to changes in the environment, offering a more engaging player experience.
– **Problem-Solving Skills**: Understanding pathfinding algorithms and obstacle avoidance challenges you to think critically about spatial problems, which can bolster your overall programming skills.
– **Versatility**: The knowledge gained from working with NavigationAgent2D is transferable to other areas of game development and beyond, making it a valuable tool in your developer’s toolkit.

By mastering NavigationAgent2D, you’ll unlock a new dimension of interactive possibilities for your games. Stay tuned as we delve into coding examples to showcase how to effectively employ this class in your own game projects!

CTA Small Image

Setting Up the Navigation2D Node

Before diving into the NavigationAgent2D code examples, it’s crucial to set up the Navigation2D node which will act as the ‘brain’ for our NavigationAgent2D instances. Here is how you can set up a basic Navigation2D node in your scene:

var navigation =

Ensure that your Navigation2D node contains a NavigationPolygon instance for your agents to understand the walkable area.

Creating Your First NavigationAgent2D

Now let’s create our first NavigationAgent2D. To do so, we need to add it as a child of the character we want to move. This snippet shows you how to set up a basic agent:

var agent =
agent.set_target_location(Vector2(500, 300))

This code initializes a new NavigationAgent2D and places a target location for the agent. The character will navigate towards the coordinates (500, 300).

Programming the Agent’s Movement

After setting the target, we need to make the agent move towards it. We will manually drive the agent by using the velocity calculated by the NavigationAgent2D.

func _physics_process(delta):
    var velocity = agent.desired_velocity
    if velocity.length() > 0:
        # Make your character move by updating its position here.
        var move_distance = velocity * delta
        agent.position += move_distance

The desired_velocity property provides us with the direction and speed at which the agent wants to move. We use this to update the agent’s position.

Handling Obstacle Avoidance

One of the key features of NavigationAgent2D is its ability to avoid obstacles. Let’s say you have dynamic obstacles such as other moving characters or enemies; NavigationAgent2D can navigate around them seamlessly.

func _on_body_entered(body):
    if body is NavigationObstacle2D:

func _on_body_exited(body):
    if body is NavigationObstacle2D:

In these functions, we’re adding and removing obstacles from the agent’s pathfinding consideration by detecting when bodies enter or exit the agent’s area.

Updating the Agent’s Target Dynamically

In many games, the target destination of your character isn’t static. You’ll often need to change it dynamically, such as when the player moves the mouse or touches a part of the screen. Here’s how you can update the agent’s target:

func _input(event):
    if event is InputEventMouseButton and event.pressed:
        var local_mouse_position = get_local_mouse_position()

Here, we’re using input events to detect mouse clicks and update the agent’s destination accordingly.

Working with Agent Properties

The NavigationAgent2D class comes with numerous properties to fine-tune its behavior. Let’s customize our agent’s pathfinding with some of these properties.

# Set the agent's maximum speed.
agent.max_speed = 200

# Set how close the agent can get to the target location before stopping navigation.
agent.target_desired_distance = 10

# Adjusting the agent's pathfinding algorithm.
agent.navigation_a_star_weight = 1.1

In this script snippet, we set the agent’s maximum speed, determined how close it needs to be to the target to stop navigation, and tweaked the pathfinding algorithm by setting the A* weight property.

We have now covered the essentials of creating and programming a simple but effective NavigationAgent2D in Godot 4. In the next section, we’ll delve into slightly more advanced examples to further enhance your navigation logic and gameplay. Stay tuned!Let’s continue enhancing our navigation logic. Now we’ll explore how to handle more complex scenarios where our agent needs to avoid sudden changes in terrain or dynamic changes in the environment.

Recomputing the Path When the Environment Changes

Sometimes you need to update the path when obstacles move or the environment changes. Here’s how to trigger a path recomputation:

func _on_obstacle_moved(obstacle):
    agent.navpoly_dirty = true

Using the navpoly_dirty property, we can inform the NavigationAgent2D that it needs to reconsider its path because the environment has changed.

Following a Precomputed Path

While NavigationAgent2D computes and follows paths automatically, you might want to precompute a path and make your character follow it. To do this, use the path property:

var path = navigation.get_simple_path(agent.global_position, target_position)
agent.path = path

Here, we use the parent Navigation2D node to compute the path and then assign it to our agent.

Customizing Agent Acceleration and Speed

You might want to provide a different feel for different characters by adjusting their acceleration and top speeds. Adjust these using the max_accel and max_speed properties:

agent.max_accel = 150
agent.max_speed = 300

By modifying these properties, you can easily make some characters move more swiftly or accelerate faster than others.

Using Signals to React to Navigation Events

The NavigationAgent2D class emits signals to indicate various events. For example, you can react when the agent has reached its destination:

agent.connect("path_finished", self, "_on_path_finished")

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

Subscribing to the path_finished signal lets you trigger actions when an agent arrives at its target location.

Adjusting Agent’s Path Following Precision

Sometimes you’ll want to adjust how closely your agent follows the calculated path. The navigation_radius property can help you set this precision:

agent.navigation_radius = 5

A smaller navigation_radius will make the agent follow a tighter path, while a larger radius allows for more flexibility in movement.

Stopping and Resuming Navigation

In some gameplay scenarios, you might want to pause the agent’s movement temporarily and then resume it. This can be done by stopping the agent and setting its velocity to zero:

agent.velocity = Vector2.ZERO

And to resume movement towards the previously set target:

agent.navpoly_dirty = true

By setting the navpoly_dirty to true, you’re essentially telling the agent to recalculate the path and continue navigation.


We’ve looked at several advanced features and scenarios involving the NavigationAgent2D class in Godot. From adjusting the precision of path following to reacting to dynamic changes in the environment, this class offers a robust set of tools for adding complex navigation behaviors to your game characters or objects.

For those looking to integrate sophisticated 2D navigation in their Godot games, understanding and utilizing the power of NavigationAgent2D is a must. Whether you are creating a stealth-based game where precision movement is key or a dynamic battlefield with numerous obstacles, these code snippets provide a solid foundation to build upon.

Remember, each game will have its unique challenges, and as developers, we must adapt and extend these examples to suit our specific needs. Keep experimenting and refining your navigation systems, and as always, we here at Zenva are excited to see the innovative solutions that you’ll bring to life in your games!

Integrating NavigationAgent2D with Animation

Combining navigation behaviors with animations can greatly enhance the visual feedback in response to character movement. Let’s use Godot’s animation system with NavigationAgent2D to animate our character’s movement.

var animation_player = $AnimationPlayer

func _physics_process(delta):
    var velocity = agent.desired_velocity
    if velocity.length() > 0:
        agent.position += velocity * delta"walk")

In this example, we animate the character with a “walk” animation when moving and revert back to an “idle” animation when stationary, providing a dynamic and responsive feel.

Adding Pathfinding Debug Visualization

Seeing the path your agent will follow can be instrumental during development. Let’s add a way to visualize the path.

var line_2d = $Line2D

func _draw():
    if agent.has_path():
        line_2d.points = agent.path

func _process(delta):

With this code, we add a Line2D node to our agent to represent the path and redraw it every frame whenever the path is updated.

Detecting and Reacting to Collisions Along the Path

Detection and handling of collisions can influence how your agent reacts to encounters with other objects. Here’s an example of how you can handle such scenarios:

func _on_agent_body_entered(body):
    if body.has_method("apply_damage"):

In this function, we check if the colliding body has an `apply_damage` method and apply damage accordingly. We also stop the agent to prevent it from continuously running into the object.

Adjusting Navigation Agent to Deal with Slopes

Handling slopes is an important aspect of navigation. We want our agent to be able to climb slopes or avoid them based on its capabilities.

agent.max_climb = 10
agent.is_enabled = true

The `max_climb` property defines the maximum height that the NavigationAgent2D can navigate over, such as climbing up a small step or slope.

Optimizing Path Following on Longer Paths

For longer paths, calculating every step can be resource-intensive. We can optimize this by recalculating the path less frequently.

var time_since_last_repath = 0.0
var repath_interval = 1.0

func _physics_process(delta):
    time_since_last_repath += delta
    if time_since_last_repath >= repath_interval:
        agent.navpoly_dirty = true
        time_since_last_repath = 0

Here, we establish a repathing interval, ensuring the agent only recalculates its path every second rather than every frame.


By integrating NavigationAgent2D with animations, visualizing paths, handling collisions, adjusting to slopes, and optimizing path calculation intervals, we’ve created a more polished and efficient navigation experience in our 2D Godot game.

These small additions and optimizations can make a significant impact on both the game’s performance and the player’s experience. Many of these examples can be mixed and matched to suit specific game mechanics or styled to match your game’s theme.

Good navigation underlies the believability of a game world and the characters within it – it’s well worth spending time to get these details right. Keep refining your skills, and your 2D adventures are guaranteed to feel more alive and interactive than ever before!

Where to Go Next in Your Godot Journey

You’ve taken quite the adventure through the versatile and powerful NavigationAgent2D class with us, and we are thrilled to see the worlds you’ll build and the characters you’ll bring to life with these newfound skills. However, the road doesn’t end here – it’s just the beginning.

If you’re eager to keep expanding your Godot knowledge and take your game development skills to the next level, our Godot Game Development Mini-Degree is the perfect next step. This comprehensive suite of courses is designed to teach you the ins and outs of building cross-platform games from the ground up in Godot. You’ll dive into topics ranging from 2D and 3D game development to mastering GDScript, and from designing intuitive UI systems to crafting detailed RPG, RTS, survival, and platformer mechanics.

Our flexible, project-based courses cover everything you need to make your game ideas a reality and are purposely crafted to cater to both new coders and seasoned developers. Plus, for those looking to explore even more of what Godot has to offer, browse our broad collection of Godot courses. With every Zenva course, you’ll learn at your own pace, build a portfolio of engaging game projects, and earn certificates to showcase your skills. Keep learning, keep creating, and remember – with Zenva, you’re never coding alone.


As we close the chapter on our NavigationAgent2D walkthrough, remember that every line of code you write, every problem you solve, and every character you breathe life into is a step forward in your game development journey. Techniques like pathfinding and character navigation are more than just features; they create the pulse of player interaction and the essence of engaging gameplay. Your passion, combined with the knowledge you’ve gained today, sets the stage for truly incredible creations.

So whether you’re just starting out or honing your existing skills, we invite you to continue learning with us. Keep the momentum going by checking out our Godot Game Development Mini-Degree and join a community where turning dreams into reality is just a tutorial away. See you in the next lesson, where your next game awaits!

Python Blog Image

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