Merge pull request #62429 from smix8/navigation_path_query_4.x

Add NavigationPathQuery objects and NavigationServer query_path()

6 files changed, 130 insertions, 0 deletions

diff --git a/doc/classes/NavigationPathQueryParameters2D.xml b/doc/classes/NavigationPathQueryParameters2D.xml
new file mode 100644
index 0000000000..70455017c4
--- /dev/null
+++ b/doc/classes/NavigationPathQueryParameters2D.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="NavigationPathQueryParameters2D" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Parameters to be sent to a 2D navigation path query.
+	</brief_description>
+	<description>
+		This class contains the start and target position and other parameters to be used with [method NavigationServer2D.query_path].
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="map" type="RID" setter="set_map" getter="get_map">
+			The navigation [code]map[/code] [RID] used in the path query.
+		</member>
+		<member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1">
+			The navigation layers the query will use (as a bitmask).
+		</member>
+		<member name="path_postprocessing" type="int" setter="set_path_postprocessing" getter="get_path_postprocessing" enum="NavigationPathQueryParameters2D.PathPostProcessing" default="0">
+		</member>
+		<member name="pathfinding_algorithm" type="int" setter="set_pathfinding_algorithm" getter="get_pathfinding_algorithm" enum="NavigationPathQueryParameters2D.PathfindingAlgorithm" default="0">
+			The pathfinding algorithm used in the path query.
+		</member>
+		<member name="start_position" type="Vector2" setter="set_start_position" getter="get_start_position" default="Vector2(0, 0)">
+			The pathfinding start position in global coordinates.
+		</member>
+		<member name="target_position" type="Vector2" setter="set_target_position" getter="get_target_position" default="Vector2(0, 0)">
+			The pathfinding target position in global coordinates.
+		</member>
+	</members>
+	<constants>
+		<constant name="PATHFINDING_ALGORITHM_ASTAR" value="0" enum="PathfindingAlgorithm">
+			The path query uses the default A* pathfinding algorithm.
+		</constant>
+		<constant name="PATH_POSTPROCESSING_CORRIDORFUNNEL" value="0" enum="PathPostProcessing">
+			Applies a funnel algorithm to the raw path corridor found by the pathfinding algorithm. This will result in the shortest path possible inside the path corridor. This postprocessing very much depends on the navmesh polygon layout and the created corridor. Especially tile- or gridbased layouts can face artifical corners with diagonal movement due to a jagged path corridor imposed by the cell shapes.
+		</constant>
+		<constant name="PATH_POSTPROCESSING_EDGECENTERED" value="1" enum="PathPostProcessing">
+			Centers every path position in the middle of the traveled navmesh polygon edge. This creates better paths for tile- or gridbased layouts that restrict the movement to the cells center.
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/NavigationPathQueryParameters3D.xml b/doc/classes/NavigationPathQueryParameters3D.xml
new file mode 100644
index 0000000000..4dd54601f5
--- /dev/null
+++ b/doc/classes/NavigationPathQueryParameters3D.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="NavigationPathQueryParameters3D" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Parameters to be sent to a 3D navigation path query.
+	</brief_description>
+	<description>
+		This class contains the start and target position and other parameters to be used with [method NavigationServer3D.query_path].
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="map" type="RID" setter="set_map" getter="get_map">
+			The navigation [code]map[/code] [RID] used in the path query.
+		</member>
+		<member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1">
+			The navigation layers the query will use (as a bitmask).
+		</member>
+		<member name="path_postprocessing" type="int" setter="set_path_postprocessing" getter="get_path_postprocessing" enum="NavigationPathQueryParameters3D.PathPostProcessing" default="0">
+		</member>
+		<member name="pathfinding_algorithm" type="int" setter="set_pathfinding_algorithm" getter="get_pathfinding_algorithm" enum="NavigationPathQueryParameters3D.PathfindingAlgorithm" default="0">
+			The pathfinding algorithm used in the path query.
+		</member>
+		<member name="start_position" type="Vector3" setter="set_start_position" getter="get_start_position" default="Vector3(0, 0, 0)">
+			The pathfinding start position in global coordinates.
+		</member>
+		<member name="target_position" type="Vector3" setter="set_target_position" getter="get_target_position" default="Vector3(0, 0, 0)">
+			The pathfinding target position in global coordinates.
+		</member>
+	</members>
+	<constants>
+		<constant name="PATHFINDING_ALGORITHM_ASTAR" value="0" enum="PathfindingAlgorithm">
+			The path query uses the default A* pathfinding algorithm.
+		</constant>
+		<constant name="PATH_POSTPROCESSING_CORRIDORFUNNEL" value="0" enum="PathPostProcessing">
+			Applies a funnel algorithm to the raw path corridor found by the pathfinding algorithm. This will result in the shortest path possible inside the path corridor. This postprocessing very much depends on the navmesh polygon layout and the created corridor. Especially tile- or gridbased layouts can face artifical corners with diagonal movement due to a jagged path corridor imposed by the cell shapes.
+		</constant>
+		<constant name="PATH_POSTPROCESSING_EDGECENTERED" value="1" enum="PathPostProcessing">
+			Centers every path position in the middle of the traveled navmesh polygon edge. This creates better paths for tile- or gridbased layouts that restrict the movement to the cells center.
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/NavigationPathQueryResult2D.xml b/doc/classes/NavigationPathQueryResult2D.xml
new file mode 100644
index 0000000000..a9b12d3b94
--- /dev/null
+++ b/doc/classes/NavigationPathQueryResult2D.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="NavigationPathQueryResult2D" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Result from a [NavigationPathQueryParameters2D] navigation path query.
+	</brief_description>
+	<description>
+		This class contains the result of a navigation path query from [method NavigationServer2D.query_path].
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="path" type="PackedVector2Array" setter="set_path" getter="get_path" default="PackedVector2Array()">
+			The resulting path array from the navigation query. All path array positions are in global coordinates. Without customized query parameters this is the same path as returned by [method NavigationServer2D.map_get_path].
+		</member>
+	</members>
+</class>
diff --git a/doc/classes/NavigationPathQueryResult3D.xml b/doc/classes/NavigationPathQueryResult3D.xml
new file mode 100644
index 0000000000..d8336111fc
--- /dev/null
+++ b/doc/classes/NavigationPathQueryResult3D.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="NavigationPathQueryResult3D" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Result from a [NavigationPathQueryParameters3D] navigation path query.
+	</brief_description>
+	<description>
+		This class contains the result of a navigation path query from [method NavigationServer3D.query_path].
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="path" type="PackedVector3Array" setter="set_path" getter="get_path" default="PackedVector3Array()">
+			The resulting path array from the navigation query. All path array positions are in global coordinates. Without customized query parameters this is the same path as returned by [method NavigationServer3D.map_get_path].
+		</member>
+	</members>
+</class>
diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml
index 0874e183e4..981ab8a5e1 100644
--- a/doc/classes/NavigationServer2D.xml
+++ b/doc/classes/NavigationServer2D.xml
@@ -368,6 +368,14 @@
 				Set the map's link connection radius used to connect links to navigation polygons.
 			</description>
 		</method>
+		<method name="query_path" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="parameters" type="NavigationPathQueryParameters2D" />
+			<param index="1" name="result" type="NavigationPathQueryResult2D" />
+			<description>
+				Queries a path in a given navigation map. Start and target position and other parameters are defined through [NavigationPathQueryParameters2D]. Updates the provided [NavigationPathQueryResult2D] result object with the path among other results requested by the query.
+			</description>
+		</method>
 		<method name="region_create" qualifiers="const">
 			<return type="RID" />
 			<description>
diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml
index 255f2a902c..943aa03ef7 100644
--- a/doc/classes/NavigationServer3D.xml
+++ b/doc/classes/NavigationServer3D.xml
@@ -410,6 +410,14 @@
 				[b]Note:[/b] This function is not thread safe.
 			</description>
 		</method>
+		<method name="query_path" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="parameters" type="NavigationPathQueryParameters3D" />
+			<param index="1" name="result" type="NavigationPathQueryResult3D" />
+			<description>
+				Queries a path in a given navigation map. Start and target position and other parameters are defined through [NavigationPathQueryParameters3D]. Updates the provided [NavigationPathQueryResult3D] result object with the path among other results requested by the query.
+			</description>
+		</method>
 		<method name="region_bake_navmesh" qualifiers="const">
 			<return type="void" />
 			<param index="0" name="mesh" type="NavigationMesh" />