NavigationPathQueryParameters3D in Godot – Complete Guide

Understanding the intricacies of pathfinding is a critical skill when developing 3D games or simulations. Imagine your game character navigating through a dense jungle or finding their way across a bustling city street; the underlying logic that drives this intelligent movement is pathfinding. Today, we’re delving into the NavigationPathQueryParameters3D class in Godot 4 – your trusty guide for crafting efficient and realistic paths for your 3D worlds.

What is NavigationPathQueryParameters3D?

The NavigationPathQueryParameters3D class serves as a configuration tool for 3D path queries within Godot’s robust NavigationServer3D. By tweaking various properties, such as start and target positions, you tap into Godot’s mechanism to plot a navigable course through three-dimensional space.

What is NavigationPathQueryParameters3D Used For?

This pivotal class provides the setup for pathfinding. Whether it’s a simple point A to point B route, or a complex journey with specific criteria like avoiding certain areas or types of terrain, NavigationPathQueryParameters3D shapes these decisions.

Why Should I Learn About NavigationPathQueryParameters3D?

Mastering NavigationPathQueryParameters3D gives you the power to handcraft paths that feel natural and intuitive, enhancing the player’s in-game experience. Strong knowledge of pathfinding parameters also bolsters your game’s performance by optimizing navigation queries, important for any project from indie games to AAA titles.

CTA Small Image

Setting Up NavigationPathQueryParameters3D

Let’s begin by setting up our NavigationPathQueryParameters3D instance. This preparation is the first step towards enabling pathfinding in your 3D environment. Here’s how to instantiate it and set the start and end points for your path.

var path_query =
path_query.from_point = Vector3(0, 0, 0) # Starting point
path_query.to_point = Vector3(10, 0, 10) # Destination point

After setting the start and end points, we also need to decide how close our path should get to the destination before considering the path complete. Adjusting the ‘to_point_distance’ property gives us this control.

path_query.to_point_distance = 1.0 # Minimum distance to the endpoint necessary to consider path complete

Configuring Path Optimizations

One of the key advantages of using NavigationPathQueryParameters3D is the ability to optimize pathfinding. The ‘optimize’ property allows Godot to simplify the path by reducing the number of points, which can result in smoother and more natural movement.

path_query.optimize = true # Enable path optimization

Moreover, tweaking the ‘optimization_quality’ gives further granularity on the fidelity of the path relative to the actual navigable mesh, with higher values taking more time but potentially providing a smoother path.

path_query.optimization_quality = 0.5 # Balance between performance and path accuracy

Setting Navigation Filters

Filters allow you to omit certain areas of the navigation mesh or prioritize others. Here we configure the parameters to include points on a navigation mesh with the specified layers.

path_query.filter_mask = 1 # Include only the first layer of the navigation mesh

If your game requires avoiding areas deemed dangerous or inaccessible, you could control that by adjusting the filter parameters accordingly.

path_query.excluded_mask = 2 # Exclude the second layer of the navigation mesh, typically used for "dangerous" areas

Executing the Path Query

After setting up the query parameters, it’s time to put them to use. Call the NavigationServer3D to process your parameters and obtain the path.

var calculated_path = NavigationServer3D.map_get_path(path_query)

The resulting path is an array of Vector3 points. You can iterate through this array to move an object along the calculated path. Below is an example of how you might do that within the process function of a node:

var next_point_index = 0
var speed = 5.0

func _process(delta):
    if next_point_index < calculated_path.size():
        var direction = calculated_path[next_point_index] - global_transform.origin
        if direction.length() > 0.1:
            global_transform.origin += direction.normalized() * speed * delta
            next_point_index += 1

Learning how these examples translate into your game’s code not only increases the realism and dynamism of your game environment but also enriches your skillset as a game developer.

Advanced pathfinding in Godot 4 relies on careful manipulation of NavigationPathQueryParameters3D. It’s not just about defining the start and end points, but also about understanding how to fine-tune your path to fit various game scenarios. Let’s explore some further applications and code examples.

Adjusting Collision Layers: Sometimes, you may want your pathfinding to consider only specific layers of your game world. For instance, if you have a flying character that should not be influenced by ground obstacles:

path_query.collision_mask = 4 # Only consider the layer reserved for air paths

Multiple Navigation Points: What if your character needs to visit several locations? You can extend your configuration to include more than one target point, creating a path that goes through each in turn.

path_query.points.append(Vector3(5, 0, 5))
path_query.points.append(Vector3(10, 0, 10))

The ‘points’ property lets you add any number of points to your path for multi-stop route calculations.

Channel Radius: The ‘channel_radius’ property controls how close the path will stay to walls or edges of the navigation mesh. Setting a larger radius creates a safer path further from the edges, while a smaller one creates a more direct route.

path_query.channel_radius = 0.5 # Determines the padding distance from mesh edges

Diagonal Movement: In a grid-based game, you might want to disable or enable diagonal movement. While NavigationPathQueryParameters3D does not have a straightforward setting for this, your pathfinding logic can skip diagonal movements when processing the path:

func _is_straight_line(a, b):
    return a.x == b.x or a.y == b.y or a.z == b.z

calculated_path = calculated_path.filter(_is_straight_line)

This would filter out diagonal moves by ensuring consecutive points share at least one coordinate.

Handling Elevation: For characters that cannot jump or fly, you need to consider elevation. Make sure your path does not include points with too much height difference:

func _has_acceptable_elevation_change(a, b):
    return abs(a.y - b.y) < MAX_ELEVATION_CHANGE

# Filter out points that don't meet the elevation criteria
calculated_path = calculated_path.filter(_has_acceptable_elevation_change)

Replace MAX_ELEVATION_CHANGE with the maximum height difference your character can handle.

Adaptive Pathfinding: Dynamic environments require you to regularly update paths. If an obstacle appears, you’ll need to recalculate:

func update_path_if_obstacle_appears():
    # Assuming obstacle detection is implemented
    if detect_obstacle():
        path_query.from_point = global_transform.origin
        calculated_path = NavigationServer3D.map_get_path(path_query)

This function could be triggered whenever an obstacle is detected, recalculating the path from the character’s current position.

As you can see, Godot’s NavigationPathQueryParameters3D allows for a vast array of pathfinding customizations. Whether you’re crafting a simple point-to-point navigation or constructing a complex, dynamic pathfinding system, these tools provide the foundation you need to create intuitive and efficient movement within your game. By incorporating these configurations into your Godot projects, you’ll be well on your way to developing gameplay that is both engaging and technically impressive.

Enhancing the realism in your games means having dynamic, adaptive pathfinding that can manage various complexities. We’ll look at additional capabilities provided by NavigationPathQueryParameters3D and provide you with practical code examples to implement advanced pathfinding features in your Godot 4 projects.

Navigation with Avoidance: Sometimes, you might want your character to not only find a path but also avoid dynamic obstacles temporarily, like other moving characters:

path_query.avoidance_enabled = true # Enable dynamic obstacle avoidance

This enables the built-in avoidance system which is helpful in scenes with moving characters or objects.

Navmesh Generation: To use pathfinding, you need a navigation mesh. While this is usually pre-built, you may want to generate it during runtime, especially for procedurally generated terrains:

var navmesh_data =
# Configure the navigation mesh properties here
NavigationServer3D.navmesh_add(navmesh_data, Transform.IDENTITY, "path")

Generating your navigation mesh at runtime allows your pathfinding system to be as dynamic as your game world.

Customizing Path Query: Sometimes you might need to adjust the path query’s properties depending on the character. For example, a larger character might need a larger channel_radius:

if character_type == "large":
    path_query.channel_radius = 1.0
    path_query.channel_radius = 0.5

This modification allows the pathfinding algorithm to account for the character’s size when determining how close it can get to walls and obstacles.

Path Smoothing: If your paths are looking too mechanical, you can implement a simple smoothing algorithm:

func smooth_path(raw_path):
    var smooth_path = []
    var current_direction = Vector3()
    for i in range(raw_path.size() - 1):
        var direction = (raw_path[i + 1] - raw_path[i]).normalized()
        if direction != current_direction:
            current_direction = direction
    return smooth_path

calculated_path = smooth_path(calculated_path)

This code adds a new point to the path only when the direction changes, resulting in a smoother appearance with fewer sharp turns.

Dynamic Path Updates: For an NPC that follows a player or moves within a changing environment, you should continually update the path:

func _process(delta):
    if is_time_to_recalculate_path():
        path_query.from_point = global_transform.origin
        path_query.to_point = player.global_transform.origin
        calculated_path = NavigationServer3D.map_get_path(path_query)

This simple snippet recalculates the path at certain intervals or triggered events, ensuring that the NPC constantly follows the player or navigates the changing landscape efficiently.

Through these examples, you should now have a better grasp of the power and flexibility Godot’s NavigationPathQueryParameters3D provides. It is a cornerstone for creating immersive, smart, and engaging games where navigation and movement are key. Experimenting with various parameters and integrating path query updates opens up a world of possibilities for your game’s AI, making it able to adapt to a myriad of in-game situations, environments, and player interactions.

Remember, these tools and techniques represent the kind of high-quality content we teach here at Zenva. We’re passionate about enabling you to create games that stand out, and mastering pathfinding with Godot 4 is just the beginning of what we offer. Game creation is an ongoing learning journey, and we’re here to guide you every step of the way.

Continuing Your Game Development Journey

Embarking on the path of game development is an adventure of continuous learning and creativity, and the art and science of pathfinding in Godot 4 is just one exciting part of that journey. If you’ve enjoyed exploring the intricacies of NavigationPathQueryParameters3D and are ready to dive even deeper into game creation with Godot, we have just the resource for you.

Our comprehensive Godot Game Development Mini-Degree is meticulously crafted to guide you through building cross-platform games using the powerful Godot 4 engine. As you progress through interactive courses, you’ll gain hands-on experience with 2D and 3D assets, master the GDScript programming language, implement engaging gameplay mechanics, and so much more. The curriculum’s structure ensures that even those starting from scratch can emerge with the skills to bring their gaming visions to life.

And for those looking to expand their Godot mastery even further, our broad collection of Godot courses covers a wide array of game development topics. Each course is designed with flexibility in mind, allowing you to learn at your own pace and on your schedule. With over 250 supported courses, Zenva provides a rich environment for you to move from beginner to professional, ready to join the vibrant game development community. Dive into new challenges, expand your skills, and let your creativity run wild with Zenva.


Delving into Godot 4’s NavigationPathQueryParameters3D is more than just a technical exercise; it’s about breathing life into the worlds you create. It’s about the thrill of seeing your characters interact with their environment in a believable way, moving with purpose and intelligence. The skills you’ve begun to develop here are just the tip of the iceberg when it comes to game creation with Godot 4.

We hope this look into advanced pathfinding has inspired you to explore further, to experiment with new ideas, and to push the boundaries of what you thought possible. Take the next step and enhance your Godot toolkit with Zenva’s Godot Game Development Mini-Degree. Whether you’re aiming to be a professional developer or just love making games as a hobby, we’re here to support your passion and growth every step of the way. Onward to your next game development milestone!

Python Blog Image

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