NavigationPathQueryParameters2D in Godot – Complete Guide

Navigating the digital realms of game development might often feel as complex as charting a course through uncharted territories. Understanding the intricacies of game mechanics and player movement can be a daunting task. Fortunately, with tools like Godot Engine’s NavigationPathQueryParameters2D class, developers can harness sophisticated pathfinding capabilities to create seamless and natural movement for characters and objects within their 2D games. By grasping the functionalities and applications of pathfinding, developers can elevate the gameplay experience, allowing characters to maneuver around obstacles and through environments with the finesse that players desire.

What is NavigationPathQueryParameters2D?

NavigationPathQueryParameters2D is a class within Godot 4 that provides a structured way to set up parameters for 2D path queries against the NavigationServer2D. Essentially, this class acts as a configuration tool, enabling you to dictate how objects in your game find their way from point A to point B. By tweaking its various properties, you can influence the start and end points of the path, the navigation layers to be considered, and much more.

What is it used for?

The utilization of NavigationPathQueryParameters2D is fundamental for games that rely on dynamic movement and navigation. For instance, in a strategy game, you would need non-playable characters (NPCs) to navigate around obstacles to reach their objectives smartly. Or in a puzzle game, you may require an object to trace a path through a maze. The refined control over pathfinding parameters offered by this class enables such nuanced behavior, which is vital for the believability and challenge of a game.

Why should I learn it?

Mastering NavigationPathQueryParameters2D puts a powerful tool at your fingertips. Learning it means you can:
– Create smarter AI that can navigate complex environments.
– Save development time by relying on Godot’s built-in pathfinding instead of creating your own from scratch.
– Enhance your game’s playability by ensuring smooth and logical movements, adding a layer of professionalism to your project.

By familiarizing yourself with this feature, you’ll be well-equipped to tackle an array of pathfinding-related challenges in your 2D games, making this knowledge not just useful but integral to a well-rounded game developer’s skill set.

CTA Small Image

Initializing NavigationPathQueryParameters2D

To start working with pathfinding in Godot 4, you first need to initialize the NavigationPathQueryParameters2D class. The following example shows how to create a new instance and set up basic parameters.

var path_query_parameters =
path_query_parameters.from_point = Vector2(100, 100)
path_query_parameters.to_point = Vector2(400, 400)

This code snippet defines two points: the starting point (‘from_point’) and the destination point (‘to_point’). With these, you can begin to calculate paths on your 2D map.

Setting Up Navigation Layers

In many games, the navigation space can be divided into layers, which allow for fine-tuned control over which areas can be traversed by which entities. The following example showcases how to specify navigation layers in your path queries.

path_query_parameters.navigation_layers = 1 | 2

With this, your path query will only consider layers 1 and 2 for navigation. This is especially useful when dealing with different types of surfaces or areas where only certain characters can go.

Pathfinding with Avoidance

Avoiding obstacles is a key part of intelligent pathfinding. You can specify parameters for how an object should navigate around them. Here’s how you can include obstacle avoidance within your path query parameters.

path_query_parameters.avoidance_enabled = true
path_query_parameters.avoidance_grow_amount = 10

With avoidance enabled and a ‘grow_amount’ specified, the navigation algorithm will keep a margin around obstacles, ensuring characters don’t get too close to walls or other hazards.

Finding a Path

Once you’ve set up your path query parameters, it’s time to actually find a path. This is done through Godot’s NavigationServer2D. Here are the steps you’ll take to compute a path:

var path = NavigationServer2D.map_get_path(1, path_query_parameters)

In this example, ‘1’ is the ID of your Navigation2D map. The ‘path’ variable now holds an array of points that form the path from the start to the end point, considering all the parameters you’ve set.

Using the Path in Your Game

After finding the path, your characters can follow it. Here’s a basic loop that could be used to move a character along the path:

# Assuming `entity` is your character and `speed` is its movement speed
for point in path:
    var direction = (point - entity.position).normalized()
    entity.position += direction * speed * delta
    yield(get_tree(), "idle_frame")  # Wait for the next frame

This code moves your character along each point on the path. The ‘yield’ function is used to wait until the next frame before continuing the loop, allowing you to move the character smoothly.In real-world scenarios, pathfinding rarely involves moving directly from one point to the next in a straight line. Your game’s characters may need to turn, follow winding paths, or even avoid dynamic obstacles. The Godot Engine provides numerous options for fine-tuning the pathfinding process to reflect the complexities of a living, breathing game world.

When you want to calculate a path that respects the environment and the obstacles within it, you can set up your query to account for different optimization methods.

path_query_parameters.result_mode = NavigationServer2D.PATH_RESULT_MODE_SMOOTH
path_query_parameters.agent_radius = 15
path_query_parameters.agent_height = 30

Here, we use the `PATH_RESULT_MODE_SMOOTH` result mode to ensure the path is nicely curved around corners, making movement appear more natural. The `agent_radius` and `agent_height` give the NavigationServer2D information about the size of the agent to use when determining if it fits through gaps or around corners.

To ensure that our moving entity (such as an AI character) stops exactly at the destination, we can enable snapping to the endpoint:

path_query_parameters.end_point_snapping_enabled = true
path_query_parameters.end_point_snapping_distance = 5

This code will cause the path to finish within 5 units of the destination, ensuring that the character comes to a stop right where you intend it to.

Sometimes, you might want to check if a direct path is possible, avoiding all the pathfinding if there is a clear line of sight. Here’s how you might perform such a check:

var direct_path_possible = NavigationServer2D.map_get_line_collision(1, path_query_parameters.from_point, path_query_parameters.to_point)

`map_get_line_collision` returns information about any obstructions directly between the start and end points. With this, you can bypass more complex pathfinding calculations when a simple straight-line movement will suffice.

While moving along the path, you might want the character to be aware of its immediate surroundings, including other moving entities. Dynamic obstacle avoidance can be crucial in games with a lot of entities moving around. You can adjust the query parameters for this purpose:

path_query_parameters.avoidance_initialize_with_neighbours = true

With `avoidance_initialize_with_neighbours` turned on, the navigation system will consider other nearby moving entities when calculating the path, aiming to create a more dynamic and reactive navigation experience.

Finally, once you have the path as an array of vectors, you might want to visualize it for debugging purposes. We can draw the path using the `_draw()` function in a Godot script.

func _draw():
    for i in range(path.size() - 1):
        draw_line(path[i], path[i + 1],, 2)

This loop draws a line between each pair of consecutive points in the path array. Executing this in the `_draw()` function of a Node2D-derived class will render the path in blue color on the screen, allowing you to see exactly how your navigation algorithm calculates the route.

Learning to work with the intricate options in the Godot Engine‘s pathfinding system not only empowers your AI but also equips you with a deeper understanding of how to bring intelligent navigation into your games. Through practical applications and continued experimentation with classes like NavigationPathQueryParameters2D, we can create immersive and dynamic worlds for players to enjoy.To enhance the usability of the path you’ve calculated, you might want to simplify it, removing unnecessary points that could cause jittery movement or overly complex paths.

path_query_parameters.simplify_path = true

The `simplify_path` property tells the navigation server to reduce the number of points in the path, leading to smoother navigation and easier handling of character movement.

When dealing with characters that can move at different speeds or have different movement capabilities, it’s useful to set a maximum distance for the pathfinding query, so they don’t end up with a destination that’s too far away to reach in a reasonable time.

path_query_parameters.max_distance = 1000

Here, the `max_distance` limits the pathfinding to within 1000 units from the `from_point`. If the `to_point` is beyond this range, the navigation system will not generate a valid path.

For characters that have particular movement patterns or constraints, the path query can include custom points for more precise navigation:

var custom_points = PoolVector2Array([Vector2(250, 250), Vector2(500, 500)])
path_query_parameters.custom_points = custom_points

Using `custom_points`, you can introduce specific waypoints that the character must pass through, giving you greater control over the route taken.

Furthermore, in complex games with many characters and potential paths, it’s often necessary to prioritize certain pathfinding queries over others to ensure important characters or actions are resolved first.

path_query_parameters.priority = 10

A higher `priority` value will ensure that the path query is processed sooner by the navigation server, which can be crucial in time-sensitive scenarios.

Optimizations are also available for cases when the computed path does not need to be perfect, such as when an enemy is far away from the player, and slight inaccuracies won’t affect the gameplay.

path_query_parameters.optimization_quality = 0.5

The `optimization_quality` property, when set to a value between 0 and 1, controls the balance between path quality and calculation time.

Lastly, you might want to process the pathfinding asynchronously, so your game’s performance isn’t impacted by complex path calculations:

var path = yield(NavigationServer2D.map_get_path(1, path_query_parameters), "completed")

Here, we execute the `map_get_path` function and immediately yield control. This coroutine will resume once the pathfinding process has completed, preventing any performance hiccups.

By incorporating these advanced parameters and techniques, developers can fine-tune how their game characters navigate through the game world, ensuring that movements are not just efficient, but also make sense within the context of the game’s environment and the narrative being told. Whether you’re working on a sprawling RPG landscape, a tight maze-like dungeon, or an isometric tactical battlefield, mastering the diverse functionalities of Godot’s pathfinding system paves the way for creating a more immersive gaming experience.

Where to go next

Now that you’ve dipped your toes into the world of pathfinding with Godot’s NavigationPathQueryParameters2D, your journey into game development is just getting started. To continue honing your skills and learn how to bring whole worlds to life, the Godot Game Development Mini-Degree is the perfect next step. This comprehensive series of courses will guide you through the ins and outs of creating cross-platform games with Godot, an engine celebrated for its capability to produce stunning graphics while maintaining top-notch performance.

Whether you are a beginner eager to create your first game, or an experienced developer looking to expand your portfolio, our Mini-Degree provides valuable insight into essential development topics. From mastering GDScript, to designing engaging combat systems, to understanding UI intricacies, our curriculum will empower you with the tools and knowledge needed to become a proficient game developer.

Want to explore even more? Check out our wide array of Godot courses that cater to all levels of experience. With Zenva, you can learn at your own pace, build a robust portfolio of real projects, and earn certificates that showcase your expertise. Take the next step in your game development career with us, and turn your creative visions into reality.


Delving into the realms of game development can be an exhilarating journey, brimming with opportunities for innovation and creativity. With the understanding of Godot’s NavigationPathQueryParameters2D under your belt, you’re now equipped to give your game characters the intelligence they need to navigate the dynamic worlds you create. The pathfinding principles and methodologies you’ve learned here are just the beginning, serving as a solid foundation for building immersive, responsive, and engaging gameplay.

Ready to transform your newfound knowledge into action-packed games that captivate audiences? Embark on your next stage of learning with our Godot Game Development Mini-Degree. Let’s turn your gaming ideas into digital realities, one line of code at a time. Together, we can craft the future of gaming with skill, passion, and the power of Godot Engine. Join us, and be part of a new wave of game developers shaping the interactive entertainment of tomorrow.

Python Blog Image

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