NavigationPolygon in Godot – Complete Guide

Navigating through virtual spaces can be just as crucial as moving around in the physical world, especially when it comes to game development. The paths that players, characters, or even automated systems take are determined by the invisible lines and barriers set by developers – these are defined using navigation tools. One such tool in Godot Engine’s impressive toolkit is the class NavigationPolygon, which serves as the cornerstone for pathfinding in 2D games.

Knowing how to manipulate these tools efficiently can truly make a world of difference in gameplay experience, making spatial navigation not only possible but also smooth and intuitive. Whether you’re just starting or are looking to refine your skills, this tutorial aims to demystify the NavigationPolygon class and equip you with the knowledge to implement advanced pathfinding features in your Godot projects.

What is NavigationPolygon?

The NavigationPolygon class in Godot 4 is a part of the engine’s 2D navigation system. It’s a resource that allows developers to define areas in a 2D space where characters or objects can move – think of it as creating a digital “walkable” floor plan for your game’s characters. These polygons mark where navigation is possible and also outline where it’s not, essentially creating obstacles.

What is it for?

The primary purpose of the NavigationPolygon class is to facilitate pathfinding. By designating areas as navigable or obstructed, you allow the pathfinding algorithms to compute the shortest and most efficient routes for moving characters and objects within the 2D space. This functionality is crucial for games where characters need to autonomously navigate around the levels, such as strategy games, simulations, or even puzzle games.

Why should I learn it?

Learning how to use the NavigationPolygon class can greatly enhance your game’s interactivity and realism. Whether you’re an indie game developer or aspiring to join a game studio, understanding navigation systems:

– Allows you to create more immersive gameplay experiences where characters move in a life-like manner.
– Improves your skills in a core area of game development, i.e., AI programming, making your skillset more marketable.
– Enables you to handle complex scenarios and design puzzles that can respond dynamically to the player’s actions.

Join us as we embark on a journey to unlock the full potential of NavigationPolygon and elevate your 2D game projects to the next level.

CTA Small Image

Setting Up NavigationPolygons in Godot

Before we dive into code examples, it’s important to lay the groundwork. Make sure you have your 2D map ready in the Godot editor. With your map as the backdrop, you’ll define NavigationPolygons that outline the navigable areas.

var nav_polygon =

This snippet creates a new NavigationPolygon instance.

Now let’s add vertices to our NavigationPolygon. These vertices define the corners of the navigable area.

var points = PoolVector2Array([Vector2(0, 0), Vector2(100, 0), Vector2(100, 100), Vector2(0, 100)])

Here we:

– Define a PoolVector2Array of points representing the vertices of a square area.
– Use `add_outline()` to add those points as an outline of a navigable area.
– Call `make_polygons_from_outlines()` to finalize the setup, turning outlines into navigable polygons.

Let’s assign this navigation polygon to a Navigation2D node.

var navigation =
var navpol_instance =

# Add to the scene

In this code block:

– We create a `Navigation2D` node, which will handle our 2D pathfinding logic.
– We also make a `NavigationPolygonInstance`, which is the instance that uses our NavigationPolygon.
– Then, we set our newly created NavigationPolygon as the polygon for this instance.
– Finally, we add the `NavigationPolygonInstance` to `Navigation2D` and add the `Navigation2D` node to the scene.

Making Use of NavigationPolygons

Now that we have a navigation system in place, let us see how to use it to calculate a path from one point to another.

To get a path, we need to get the `Navigation2D` node and use its `get_simple_path()` function.

var start_point = Vector2(10, 10)
var end_point = Vector2(90, 90)
var path = navigation.get_simple_path(start_point, end_point, false)

Here we:

– Define a start and an end point for our path.
– Call `get_simple_path(start_point, end_point, optimize)` where `optimize` is false; it can be set to true to smooth the path.

Now, let’s visualize this path by drawing it with a `Line2D` node.

var line =
line.points = path

This creates a new `Line2D` instance and sets its points to the path that was calculated, then adds it as a child to the `Navigation2D` node so we can see the path on the screen when we run the scene.

Remember that real-world usage of the NavigationPolygon includes complex scenarios which may not be covered in this introduction. You’ll often end up creating NavigationPolygons that fit snugly around your level geometry to ensure accurate pathfinding. Keep in mind that Navigation2D will only find paths within the polygons, and obstacles should be properly outlined by them to prevent characters from ‘walking’ over them.

Stay tuned for the next part where we’ll handle dynamic obstacles and discuss how to update NavigationPolygons at runtime!Managing dynamic obstacles is a natural progression in mastering the NavigationPolygons in Godot. It’s not uncommon for game levels to change as the player progresses or due to interactions with in-game objects. In such cases, the navigable areas need to be updated to reflect those changes. Let’s delve into how you can add or remove NavigationPolygons during runtime to adapt to dynamic obstacles.

To remove a polygon from a `NavigationPolygonInstance`, you first have to retrieve the instance and then modify its `NavigationPolygon`.

# Assume 'navpol_instance' is a pre-existing NavigationPolygonInstance in your scene
var new_outline = PoolVector2Array([Vector2(10,10), Vector2(110,10), Vector2(110,110), Vector2(10,110)])

In this code:

– We start by creating a new outline representing the area we want to be navigable after removing the original polygon.
– `remove_outline_at_index(0)` removes the first outline from the `NavigationPolygon`.
– We then add the new outline and call `make_polygons_from_outlines()` to update the NavigationPolygon accordingly.

When obstacles move, you might want to cut their shape out of your navigable area. This is done by subtracting polygons from the `NavigationPolygon`.

# Here, 'obstacle_shape' is a PoolVector2Array representing the dynamic obstacle's outline
var cutout = navpol_instance.navigation_polygon.subtract_polygon(obstacle_shape)
navpol_instance.navigation_polygon = cutout

In this piece:

– We define a `subtract_polygon(obstacle_shape)` call that “cuts out” the shape of the obstacle from the `NavigationPolygon`.
– We assign the new polygon to the instance and regenerate the visibility using `make_polygons_from_outlines()`.

Adding dynamic obstacles follows a similar process, but instead of subtracting, you merge different NavigationPolygons.

# 'additional_navpoly' is another NavigationPolygon representing the area to be added
var merged_polygon = navpol_instance.navigation_polygon.merge_with(additional_navpoly)
navpol_instance.navigation_polygon = merged_polygon

Here, `merge_with()` takes another NavigationPolygon and adds it to the current one, making a larger navigable area.

Sometimes, you might need to update your paths after changing the NavigationPolygons. This is essential to refresh the paths that have been calculated previously.

var path = navigation.get_simple_path(start_point, end_point, true)
line.points = path

This code recalculates the path after the NavigationPolygon modifications and updates a `Line2D` with the new path.

Lastly, to handle the situation where your dynamic obstacles move frequently, you’ll want to wrap these updates in a function and call it whenever the obstacle moves.

func update_obstacles():
    # Updates to NavigationPolygonInstance go here
    # ...
    navpol_instance.update() # Don't forget to call update on the instance

# Call this function whenever obstacles move

By wrapping NavigationPolygon updates in a function like `update_obstacles()`, we have a flexible way to handle dynamic changes in our game’s navigation data.

With these skills in your toolset, you’re now prepared to create dynamic, responsive environments in your Godot 2D games. Remember that efficient use of these techniques can differentiate between good and great game design. Keep experimenting and refining your approach to NavigationPolygons, and you’ll bring your game worlds to life in new and exciting ways.In the previous section, we focused on updating NavigationPolygons in response to dynamic obstacles. However, as games evolve, the demand for even more sophisticated navigation increases. Characters might have to avoid moving enemies, traverse changing terrains, or navigate through levels that transform in real-time. This requires a deeper understanding of NavigationPolygons and how they can be manipulated during gameplay.

Let’s consider the case of avoiding moving enemies. To achieve this, you would need to update the navigation mesh every time an enemy moves to a new location. Here’s how you can dynamically update a NavigationPolygon based on an enemy’s position:

# Assuming 'enemy' is the Node2D for the enemy that moves
func _on_enemy_moved():
    var enemy_shape = enemy.get_collision_shape_as_polygon()
    # Update navigation to account for the new position of the enemy

This function, which would be triggered on the enemy’s movement, computes the enemy’s collision shape as a polygon, ready to be used to modify the navigational area.

func update_navigation_polygon(shape):
    var cutout = navpol_instance.navigation_polygon.subtract_polygon(shape)
    navpol_instance.navigation_polygon = cutout
    # This ensures the NavigationPolygonInstance reflects the changes

Here, we perform the cutout to exclude the enemy’s area from the navigable space and notify the engine that the property list of `navpol_instance` has changed.

For a game where terrains change in real-time, say platforms that move or appear/disappear, we must adjust our NavigationPolygon to accommodate these changes. Platforms might have their own `NavigationPolygonInstance` that is added or removed from the main `Navigation2D` node:

func _on_platform_moved(platform):
    if platform.is_active():

When the platform moves or changes state, the corresponding `NavigationPolygonInstance` is added or removed from the `Navigation2D` node. This ensures that the navigation system immediately accounts for the changes in the terrain.

A scenario might also call for the need to alter the connectivity of navigation polygons on the fly. We could achieve this through edges:

# Add a connection between two non-adjacent polygons
navpol_instance.navigation_polygon.add_edge(polygon_index1, polygon_index2)

# Remove a connection between two polygons
navpol_instance.navigation_polygon.remove_edge(polygon_index1, polygon_index2)

These methods allow game developers to create and remove pathways between different areas by adding or removing connections between non-adjacent polygons.

Finally, in more advanced scenarios, we might want to recreate our `NavigationPolygon` entirely. This may occur in a level editor or a game feature that allows players to modify the map. Here’s how you’d reset and create a new one:

# Clear the existing polygon

# Add new outlines and create the polygons
var new_points = PoolVector2Array( your_new_point_data_here )

# Notify the NavigationPolygonInstance of the change

In this code, we remove all the polygons previously defined, set up new outlines per the updated requirements, and notify the instance of these changes to reflect them in the navigation system.

Keep in mind that these dynamic updates to NavigationPolygons may impact performance, especially if done frequently or with large navigation meshes. It’s important to find a balance between dynamic interactivity and maintaining good performance.

By now, you should have a robust understanding of working with NavigationPolygons in Godot to create fully interactive, dynamic 2D worlds. Remember that game development is often about experimenting and iterating to find the best solution for your specific projects. As with any feature in Godot, practice and exploration will help you develop a feel for how to best use NavigationPolygons in your games. Keep experimenting, and have fun creating more immersive game worlds!

Where to Go Next with Your Godot Journey

Your adventure with Godot and the power of NavigationPolygons doesn’t have to end here. If you’ve enjoyed this tutorial and are eager to dive deeper into game development with Godot, our Godot Game Development Mini-Degree is the perfect next step. This comprehensive collection of courses is meticulously crafted to guide you through the nuances of the Godot 4 engine, whether you are a budding game developer or looking to polish your skills.

At Zenva, we understand the importance of practical learning, which is why our courses allow you to build cross-platform games from the ground up. Covering essential topics like 2D and 3D assets, GDScript, game mechanics, and much more. You’ll not only learn the theory but also apply it by creating your own games.

If you feel like exploring a broader range of our Godot content, you can always check out our full selection of Godot courses. With the flexibility and freedom to learn at your own pace, it’s never been easier to fit game development studies into your busy schedule. So why wait? Start your comprehensive learning journey with us today and take your game development expertise to new heights.


Embarking on the Godot 4 journey with us at Zenva means you’re not just learning – you’re becoming part of a vibrant movement of indie developers and creators who are shaping the future of gaming. The pathways of knowledge within game development are endless, and mastering elements like NavigationPolygons is just the beginning. Your passion combined with our Godot Game Development Mini-Degree will unlock realms of possibility, whether you dream of creating the next indie hit or simply want to bring your own visions to life.

We at Zenva are committed to empowering you throughout your development journey, offering top-tier education tailored for real-world application. So as you finish this tutorial and look forward to the next challenge, remember that every line of code you write is another step towards your goal. We’re here to guide and support you every step of the way – let’s create, innovate, and revolutionize the gaming world together!

Python Blog Image

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