Update `NavigationPathQueryObjects` to explain all (new) options #11044

smix8 · 2025-06-22T00:59:27Z

Updates NavigationPathQueryObjects to explain all (new) options (or flesh out existing).

.. available for NavigationPathQueryParameters2D / NavigationPathQueryParameters3D.

How to do a basic NavigationServer path query using parameters and result objects.
What all the different path postprocessing options do and how they should be used.
Path simplification.
Path meta data.
Filtering regions with the newer exclude or include filters.
Clipping paths and setting search limits

This is for Godot 4.5 only as some of the options are not available in older Godot versions or behave differently.

Mickeon · 2025-06-22T12:39:59Z

tutorials/navigation/navigation_using_navigationagents.rst

+.. tip::
+
+    For more advanced uses consider :ref:`doc_navigation_using_navigationpathqueryobjects` over NavigationAgent nodes.


Feels like this tip is better suited to the bottom of this section.
It's not even begun talking about navigation agents and the page is already suggesting to rethink your choice

Mickeon · 2025-06-22T12:52:29Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+.. tip::
+
+    Path query parameters expose various options to improve pathfinding performance or lower memory consumptions.
+
+    They cater to more advanced pathfinding needs that the high-level nodes can not always cover.
+
+    See the respective option sections below.
+


This doesn't sound like a tip. It's describing exactly what these objects are for, I assume. Not sure what to do about that.

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

Updates NavigationPathQueryObjects to explain all (new) options.

skyace65 · 2025-06-22T21:56:18Z

Is this only applicable to 4.5?

smix8 · 2025-06-23T07:56:28Z

Is this only applicable to 4.5?

This is for Godot 4.5 only as some of the options are not available in older Godot versions or behave differently.

I was sneaky and placed that note at the very bottom below the image :D

AThousandShips · 2025-06-22T10:26:51Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

@@ -3,6 +3,14 @@
 Using NavigationPathQueryObjects
 ================================

+.. tip::
+
+    Path query parameters expose various options to improve pathfinding performance or lower memory consumptions.


Suggested change

Path query parameters expose various options to improve pathfinding performance or lower memory consumptions.

Path query parameters expose various options to improve pathfinding performance or lower memory consumption.

AThousandShips · 2025-06-22T10:29:43Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+
+   Path post-processing differences depending on navigation mesh polygon layout.
+
+A path query search travels from closest navigation mesh polygon edge to closest edge along the available polygons.


Suggested change

A path query search travels from closest navigation mesh polygon edge to closest edge along the available polygons.

A path query search travels from the closest navigation mesh polygon edge to the closest edge along the available polygons.

AThousandShips · 2025-06-22T10:30:54Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+
+- The ``PATH_POSTPROCESSING_CORRIDORFUNNEL`` post processing shortens paths by funneling paths around corners **inside the available polygon corridor**.
+
+  This is the default post processing and usually also the most useful as it gives the shortest path result **inside the available polygon corridor**. If the polygon corridor is already suboptimal, e.g. due to a suboptimal navigation mesh layout, the funnel can snap to unexpected polygon corners causing detours.


Suggested change

This is the default post processing and usually also the most useful as it gives the shortest path result **inside the available polygon corridor**. If the polygon corridor is already suboptimal, e.g. due to a suboptimal navigation mesh layout, the funnel can snap to unexpected polygon corners causing detours.

This is the default post processing and usually also the most useful as it gives the shortest path result **inside the available polygon corridor**.

If the polygon corridor is already suboptimal, e.g. due to a suboptimal navigation mesh layout,

the funnel can snap to unexpected polygon corners causing detours.

AThousandShips · 2025-06-22T10:32:14Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+
+- The ``PATH_POSTPROCESSING_EDGECENTERED`` post processing forces all path points to be placed in the middle of the crossed polygon edges  **inside the available polygon corridor**.
+
+  This post processing is usually only useful when used with strictly tile-like navigation mesh polygons that are all evenly sized and where the excepted path following is also constrained to cell centers, e.g. typical grid game with movement constrained to grid cell centers.


Suggested change

This post processing is usually only useful when used with strictly tile-like navigation mesh polygons that are all evenly sized and where the excepted path following is also constrained to cell centers, e.g. typical grid game with movement constrained to grid cell centers.

This post processing is usually only useful when used with strictly tile-like navigation mesh polygons that are all

evenly sized and where the excepted path following is also constrained to cell centers,

e.g. typical grid game with movement constrained to grid cell centers.

I believe every single mention of "post processing" should be hyphenated ("post-processing"), too.

AThousandShips · 2025-06-23T08:13:11Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+   Path point difference with or without path simplification.
+
+If ``simplify_path`` is enabled a variant of the Ramer-Douglas-Peucker path simplification algorithm is applied to the path.
+This algorithm straightens paths by removing less relevant path points depending on the used ``simplify_epsilon``.


Suggested change

This algorithm straightens paths by removing less relevant path points depending on the used ``simplify_epsilon``.

This algorithm straightens paths by removing less relevant path points depending on the ``simplify_epsilon`` used.

AThousandShips · 2025-06-23T08:28:40Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+Path length clips can be helpful to create paths that better fit constrained gameplay, e.g. tactical games with limited movement ranges.
+
+- Property ``path_return_max_length`` can be used to clip the returned path to a specific max length.
+- Property ``path_return_max_radius`` can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.


Suggested change

- Property ``path_return_max_radius`` can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.

- The ``path_return_max_radius`` property can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.

AThousandShips · 2025-06-23T08:29:11Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+- Property ``path_return_max_length`` can be used to clip the returned path to a specific max length.
+- Property ``path_return_max_radius`` can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.
+
+Query parameters allow to limit the path search to only searched up to a specific distance or a specific amount of searched polygons.


Suggested change

Query parameters allow to limit the path search to only searched up to a specific distance or a specific amount of searched polygons.

Query parameters allow limiting the path search to only search up to a specific distance or a specific number of searched polygons.

AThousandShips · 2025-06-23T08:30:01Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+Query parameters allow to limit the path search to only searched up to a specific distance or a specific amount of searched polygons.
+These options are for performance and affect the path search directly.
+
+- Property ``path_search_max_distance`` can be used to stop the path search when going over this distance from the start position.


Suggested change

- Property ``path_search_max_distance`` can be used to stop the path search when going over this distance from the start position.

- The ``path_search_max_distance`` property can be used to stop the path search when going over this distance from the start position.

AThousandShips · 2025-06-23T08:30:19Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+These options are for performance and affect the path search directly.
+
+- Property ``path_search_max_distance`` can be used to stop the path search when going over this distance from the start position.
+- Property ``path_search_max_polygons`` can be used to stop the path search when going over this searched polygon amount.


Suggested change

- Property ``path_search_max_polygons`` can be used to stop the path search when going over this searched polygon amount.

- The ``path_search_max_polygons`` property can be used to stop the path search when going over this searched polygon number.

AThousandShips · 2025-06-23T08:30:48Z

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

+- Property ``path_search_max_distance`` can be used to stop the path search when going over this distance from the start position.
+- Property ``path_search_max_polygons`` can be used to stop the path search when going over this searched polygon amount.
+
+When the path search is stopped by reaching a limit the path resets and creates a path from the start position polygon to the so far found polygon that is closest to the target position.


Suggested change

When the path search is stopped by reaching a limit the path resets and creates a path from the start position polygon to the so far found polygon that is closest to the target position.

When the path search is stopped by reaching a limit the path resets and creates a path from the start position polygon

to the polygon found so far that is closest to the target position.

Mickeon added area:manual Issues and PRs related to the Manual/Tutorials section of the documentation topic:navigation labels Jun 22, 2025

Mickeon reviewed Jun 22, 2025

View reviewed changes

Update NavigationPathQueryObjects to explain all (new) options

06d6dc7

Updates NavigationPathQueryObjects to explain all (new) options.

smix8 force-pushed the path_queries branch from f36ae3c to 06d6dc7 Compare June 22, 2025 18:32

AThousandShips reviewed Jun 23, 2025

View reviewed changes

skyace65 added this to the 4.5 milestone Jun 23, 2025

		.. tip::

		For more advanced uses consider :ref:`doc_navigation_using_navigationpathqueryobjects` over NavigationAgent nodes.

	Path query parameters expose various options to improve pathfinding performance or lower memory consumptions.
	Path query parameters expose various options to improve pathfinding performance or lower memory consumption.


		Path post-processing differences depending on navigation mesh polygon layout.

		A path query search travels from closest navigation mesh polygon edge to closest edge along the available polygons.

	A path query search travels from closest navigation mesh polygon edge to closest edge along the available polygons.
	A path query search travels from the closest navigation mesh polygon edge to the closest edge along the available polygons.


		- The ``PATH_POSTPROCESSING_CORRIDORFUNNEL`` post processing shortens paths by funneling paths around corners inside the available polygon corridor.

		This is the default post processing and usually also the most useful as it gives the shortest path result inside the available polygon corridor. If the polygon corridor is already suboptimal, e.g. due to a suboptimal navigation mesh layout, the funnel can snap to unexpected polygon corners causing detours.


		- The ``PATH_POSTPROCESSING_EDGECENTERED`` post processing forces all path points to be placed in the middle of the crossed polygon edges inside the available polygon corridor.

		This post processing is usually only useful when used with strictly tile-like navigation mesh polygons that are all evenly sized and where the excepted path following is also constrained to cell centers, e.g. typical grid game with movement constrained to grid cell centers.

	This algorithm straightens paths by removing less relevant path points depending on the used ``simplify_epsilon``.
	This algorithm straightens paths by removing less relevant path points depending on the ``simplify_epsilon`` used.

	- Property ``path_return_max_radius`` can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.
	- The ``path_return_max_radius`` property can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.

	Query parameters allow to limit the path search to only searched up to a specific distance or a specific amount of searched polygons.
	Query parameters allow limiting the path search to only search up to a specific distance or a specific number of searched polygons.

	- Property ``path_search_max_distance`` can be used to stop the path search when going over this distance from the start position.
	- The ``path_search_max_distance`` property can be used to stop the path search when going over this distance from the start position.

	- Property ``path_search_max_polygons`` can be used to stop the path search when going over this searched polygon amount.
	- The ``path_search_max_polygons`` property can be used to stop the path search when going over this searched polygon number.

	When the path search is stopped by reaching a limit the path resets and creates a path from the start position polygon to the so far found polygon that is closest to the target position.
	When the path search is stopped by reaching a limit the path resets and creates a path from the start position polygon
	to the polygon found so far that is closest to the target position.

Uh oh!

Update NavigationPathQueryObjects to explain all (new) options #11044

Are you sure you want to change the base?

Update NavigationPathQueryObjects to explain all (new) options #11044

Conversation

smix8 commented Jun 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

skyace65 commented Jun 22, 2025

Uh oh!

smix8 commented Jun 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Update `NavigationPathQueryObjects` to explain all (new) options #11044

Update `NavigationPathQueryObjects` to explain all (new) options #11044