Merge pull request #63479 from DarkKilauea/nav-link

5 files changed, 394 insertions, 0 deletions

diff --git a/doc/classes/NavigationLink2D.xml b/doc/classes/NavigationLink2D.xml
new file mode 100644
index 0000000000..1e086fb730
--- /dev/null
+++ b/doc/classes/NavigationLink2D.xml
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="NavigationLink2D" inherits="Node2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Creates a link between two locations that [NavigationServer2D] can route agents through.
+	</brief_description>
+	<description>
+		Creates a link between two locations that [NavigationServer2D] can route agents through.  Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_navigation_layer_value" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="layer_number" type="int" />
+			<description>
+				Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [code]layer_number[/code] between 1 and 32.
+			</description>
+		</method>
+		<method name="set_navigation_layer_value">
+			<return type="void" />
+			<param index="0" name="layer_number" type="int" />
+			<param index="1" name="value" type="bool" />
+			<description>
+				Based on [code]value[/code], enables or disables the specified layer in the [member navigation_layers] bitmask, given a [code]layer_number[/code] between 1 and 32.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="bidirectional" type="bool" setter="set_bidirectional" getter="is_bidirectional" default="true">
+			Whether this link can be traveled in both directions or only from [member start_location] to [member end_location].
+		</member>
+		<member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true">
+			Whether this link is currently active. If [code]false[/code], [method NavigationServer2D.map_get_path] will ignore this link.
+		</member>
+		<member name="end_location" type="Vector2" setter="set_end_location" getter="get_end_location" default="Vector2(0, 0)">
+			Ending position of the link.
+			This position will search out the nearest polygon in the navigation mesh to attach to.
+			The distance the link will search is controlled by [method NavigationServer2D.map_set_link_connection_radius].
+		</member>
+		<member name="enter_cost" type="float" setter="set_enter_cost" getter="get_enter_cost" default="0.0">
+			When pathfinding enters this link from another regions navmesh the [code]enter_cost[/code] value is added to the path distance for determining the shortest path.
+		</member>
+		<member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1">
+			A bitfield determining all navigation layers the link belongs to. These navigation layers will be checked when requesting a path with [method NavigationServer2D.map_get_path].
+		</member>
+		<member name="start_location" type="Vector2" setter="set_start_location" getter="get_start_location" default="Vector2(0, 0)">
+			Starting position of the link.
+			This position will search out the nearest polygon in the navigation mesh to attach to.
+			The distance the link will search is controlled by [method NavigationServer2D.map_set_link_connection_radius].
+		</member>
+		<member name="travel_cost" type="float" setter="set_travel_cost" getter="get_travel_cost" default="1.0">
+			When pathfinding moves along the link the traveled distance is multiplied with [code]travel_cost[/code] for determining the shortest path.
+		</member>
+	</members>
+</class>
diff --git a/doc/classes/NavigationLink3D.xml b/doc/classes/NavigationLink3D.xml
new file mode 100644
index 0000000000..4d5d81bec5
--- /dev/null
+++ b/doc/classes/NavigationLink3D.xml
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="NavigationLink3D" inherits="Node3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Creates a link between two locations that [NavigationServer3D] can route agents through.
+	</brief_description>
+	<description>
+		Creates a link between two locations that [NavigationServer3D] can route agents through.  Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_navigation_layer_value" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="layer_number" type="int" />
+			<description>
+				Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [code]layer_number[/code] between 1 and 32.
+			</description>
+		</method>
+		<method name="set_navigation_layer_value">
+			<return type="void" />
+			<param index="0" name="layer_number" type="int" />
+			<param index="1" name="value" type="bool" />
+			<description>
+				Based on [code]value[/code], enables or disables the specified layer in the [member navigation_layers] bitmask, given a [code]layer_number[/code] between 1 and 32.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="bidirectional" type="bool" setter="set_bidirectional" getter="is_bidirectional" default="true">
+			Whether this link can be traveled in both directions or only from [member start_location] to [member end_location].
+		</member>
+		<member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true">
+			Whether this link is currently active. If [code]false[/code], [method NavigationServer3D.map_get_path] will ignore this link.
+		</member>
+		<member name="end_location" type="Vector3" setter="set_end_location" getter="get_end_location" default="Vector3(0, 0, 0)">
+			Ending position of the link.
+			This position will search out the nearest polygon in the navigation mesh to attach to.
+			The distance the link will search is controlled by [method NavigationServer3D.map_set_link_connection_radius].
+		</member>
+		<member name="enter_cost" type="float" setter="set_enter_cost" getter="get_enter_cost" default="0.0">
+			When pathfinding enters this link from another regions navmesh the [code]enter_cost[/code] value is added to the path distance for determining the shortest path.
+		</member>
+		<member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1">
+			A bitfield determining all navigation layers the link belongs to. These navigation layers will be checked when requesting a path with [method NavigationServer3D.map_get_path].
+		</member>
+		<member name="start_location" type="Vector3" setter="set_start_location" getter="get_start_location" default="Vector3(0, 0, 0)">
+			Starting position of the link.
+			This position will search out the nearest polygon in the navigation mesh to attach to.
+			The distance the link will search is controlled by [method NavigationServer3D.map_set_link_connection_radius].
+		</member>
+		<member name="travel_cost" type="float" setter="set_travel_cost" getter="get_travel_cost" default="1.0">
+			When pathfinding moves along the link the traveled distance is multiplied with [code]travel_cost[/code] for determining the shortest path.
+		</member>
+	</members>
+</class>
diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml
index b85c1c6649..0874e183e4 100644
--- a/doc/classes/NavigationServer2D.xml
+++ b/doc/classes/NavigationServer2D.xml
@@ -133,6 +133,117 @@
 				Returns all created navigation map [RID]s on the NavigationServer. This returns both 2D and 3D created navigation maps as there is technically no distinction between them.
 			</description>
 		</method>
+		<method name="link_create" qualifiers="const">
+			<return type="RID" />
+			<description>
+				Create a new link between two locations on a map.
+			</description>
+		</method>
+		<method name="link_get_end_location" qualifiers="const">
+			<return type="Vector2" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the ending location of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_enter_cost" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the [code]enter_cost[/code] of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_map" qualifiers="const">
+			<return type="RID" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the navigation map [RID] the requested [code]link[/code] is currently assigned to.
+			</description>
+		</method>
+		<method name="link_get_navigation_layers" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the navigation layers for this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_start_location" qualifiers="const">
+			<return type="Vector2" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the starting location of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_travel_cost" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the [code]travel_cost[/code] of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_is_bidirectional" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns whether this [code]link[/code] can be travelled in both directions.
+			</description>
+		</method>
+		<method name="link_set_bidirectional" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="bidirectional" type="bool" />
+			<description>
+				Sets whether this [code]link[/code] can be travelled in both directions.
+			</description>
+		</method>
+		<method name="link_set_end_location" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="location" type="Vector2" />
+			<description>
+				Sets the exit location for the [code]link[/code].
+			</description>
+		</method>
+		<method name="link_set_enter_cost" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="enter_cost" type="float" />
+			<description>
+				Sets the [code]enter_cost[/code] for this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_set_map" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="map" type="RID" />
+			<description>
+				Sets the navigation map [RID] for the link.
+			</description>
+		</method>
+		<method name="link_set_navigation_layers" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="navigation_layers" type="int" />
+			<description>
+				Set the links's navigation layers. This allows selecting links from a path request (when using [method NavigationServer2D.map_get_path]).
+			</description>
+		</method>
+		<method name="link_set_start_location" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="location" type="Vector2" />
+			<description>
+				Sets the entry location for this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_set_travel_cost" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="travel_cost" type="float" />
+			<description>
+				Sets the [code]travel_cost[/code] for this [code]link[/code].
+			</description>
+		</method>
 		<method name="map_create" qualifiers="const">
 			<return type="RID" />
 			<description>
@@ -186,6 +297,20 @@
 				Returns the edge connection margin of the map. The edge connection margin is a distance used to connect two regions.
 			</description>
 		</method>
+		<method name="map_get_link_connection_radius" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="map" type="RID" />
+			<description>
+				Returns the link connection radius of the map. This distance is the maximum range any link will search for navigation mesh polygons to connect to.
+			</description>
+		</method>
+		<method name="map_get_links" qualifiers="const">
+			<return type="RID[]" />
+			<param index="0" name="map" type="RID" />
+			<description>
+				Returns all navigation link [RID]s that are currently assigned to the requested navigation [code]map[/code].
+			</description>
+		</method>
 		<method name="map_get_path" qualifiers="const">
 			<return type="PackedVector2Array" />
 			<param index="0" name="map" type="RID" />
@@ -235,6 +360,14 @@
 				Set the map edge connection margin used to weld the compatible region edges.
 			</description>
 		</method>
+		<method name="map_set_link_connection_radius" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="map" type="RID" />
+			<param index="1" name="radius" type="float" />
+			<description>
+				Set the map's link connection radius used to connect links to navigation polygons.
+			</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 5b2a8fc08b..255f2a902c 100644
--- a/doc/classes/NavigationServer3D.xml
+++ b/doc/classes/NavigationServer3D.xml
@@ -133,6 +133,117 @@
 				Returns all created navigation map [RID]s on the NavigationServer. This returns both 2D and 3D created navigation maps as there is technically no distinction between them.
 			</description>
 		</method>
+		<method name="link_create" qualifiers="const">
+			<return type="RID" />
+			<description>
+				Create a new link between two locations on a map.
+			</description>
+		</method>
+		<method name="link_get_end_location" qualifiers="const">
+			<return type="Vector3" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the ending location of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_enter_cost" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the [code]enter_cost[/code] of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_map" qualifiers="const">
+			<return type="RID" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the navigation map [RID] the requested [code]link[/code] is currently assigned to.
+			</description>
+		</method>
+		<method name="link_get_navigation_layers" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the navigation layers for this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_start_location" qualifiers="const">
+			<return type="Vector3" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the starting location of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_get_travel_cost" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns the [code]travel_cost[/code] of this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_is_bidirectional" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="link" type="RID" />
+			<description>
+				Returns whether this [code]link[/code] can be travelled in both directions.
+			</description>
+		</method>
+		<method name="link_set_bidirectional" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="bidirectional" type="bool" />
+			<description>
+				Sets whether this [code]link[/code] can be travelled in both directions.
+			</description>
+		</method>
+		<method name="link_set_end_location" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="location" type="Vector3" />
+			<description>
+				Sets the exit location for the [code]link[/code].
+			</description>
+		</method>
+		<method name="link_set_enter_cost" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="enter_cost" type="float" />
+			<description>
+				Sets the [code]enter_cost[/code] for this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_set_map" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="map" type="RID" />
+			<description>
+				Sets the navigation map [RID] for the link.
+			</description>
+		</method>
+		<method name="link_set_navigation_layers" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="navigation_layers" type="int" />
+			<description>
+				Set the links's navigation layers. This allows selecting links from a path request (when using [method NavigationServer3D.map_get_path]).
+			</description>
+		</method>
+		<method name="link_set_start_location" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="location" type="Vector3" />
+			<description>
+				Sets the entry location for this [code]link[/code].
+			</description>
+		</method>
+		<method name="link_set_travel_cost" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="link" type="RID" />
+			<param index="1" name="travel_cost" type="float" />
+			<description>
+				Sets the [code]travel_cost[/code] for this [code]link[/code].
+			</description>
+		</method>
 		<method name="map_create" qualifiers="const">
 			<return type="RID" />
 			<description>
@@ -204,6 +315,20 @@
 				Returns the edge connection margin of the map. This distance is the minimum vertex distance needed to connect two edges from different regions.
 			</description>
 		</method>
+		<method name="map_get_link_connection_radius" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="map" type="RID" />
+			<description>
+				Returns the link connection radius of the map. This distance is the maximum range any link will search for navigation mesh polygons to connect to.
+			</description>
+		</method>
+		<method name="map_get_links" qualifiers="const">
+			<return type="RID[]" />
+			<param index="0" name="map" type="RID" />
+			<description>
+				Returns all navigation link [RID]s that are currently assigned to the requested navigation [code]map[/code].
+			</description>
+		</method>
 		<method name="map_get_path" qualifiers="const">
 			<return type="PackedVector3Array" />
 			<param index="0" name="map" type="RID" />
@@ -260,6 +385,14 @@
 				Set the map edge connection margin used to weld the compatible region edges.
 			</description>
 		</method>
+		<method name="map_set_link_connection_radius" qualifiers="const">
+			<return type="void" />
+			<param index="0" name="map" type="RID" />
+			<param index="1" name="radius" type="float" />
+			<description>
+				Set the map's link connection radius used to connect links to navigation polygons.
+			</description>
+		</method>
 		<method name="map_set_up" qualifiers="const">
 			<return type="void" />
 			<param index="0" name="map" type="RID" />
diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index ffafff0ff4..e62c0433b4 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -497,6 +497,12 @@
 		<member name="debug/shapes/navigation/enable_geometry_face_random_color" type="bool" setter="" getter="" default="true">
 			If enabled, colorizes each navigation mesh polygon face with a random color when "Visible Navigation" is enabled in the Debug menu.
 		</member>
+		<member name="debug/shapes/navigation/enable_link_connections" type="bool" setter="" getter="" default="true">
+			If enabled, displays navigation link connections when "Visible Navigation" is enabled in the Debug menu.
+		</member>
+		<member name="debug/shapes/navigation/enable_link_connections_xray" type="bool" setter="" getter="" default="true">
+			If enabled, displays navigation link connections through geometry when "Visible Navigation" is enabled in the Debug menu.
+		</member>
 		<member name="debug/shapes/navigation/geometry_color" type="Color" setter="" getter="" default="Color(0.1, 1, 0.7, 0.4)">
 			Color of the navigation geometry, visible when "Visible Navigation" is enabled in the Debug menu.
 		</member>
@@ -512,6 +518,12 @@
 		<member name="debug/shapes/navigation/geometry_face_disabled_color" type="Color" setter="" getter="" default="Color(0.5, 0.5, 0.5, 0.4)">
 			Color to display disabled navigation mesh polygon faces, visible when "Visible Navigation" is enabled in the Debug menu.
 		</member>
+		<member name="debug/shapes/navigation/link_connection_color" type="Color" setter="" getter="" default="Color(1, 0.5, 1, 1)">
+			Color to use to display navigation link connections, visible when "Visible Navigation" is enabled in the Debug menu.
+		</member>
+		<member name="debug/shapes/navigation/link_connection_disabled_color" type="Color" setter="" getter="" default="Color(0.5, 0.5, 0.5, 1)">
+			Color to use to display disabled navigation link connections, visible when "Visible Navigation" is enabled in the Debug menu.
+		</member>
 		<member name="debug/shapes/paths/geometry_color" type="Color" setter="" getter="" default="Color(0.1, 1, 0.7, 0.4)">
 			Color of the curve path geometry, visible when "Visible Paths" is enabled in the Debug menu.
 		</member>
@@ -1439,12 +1451,18 @@
 		<member name="navigation/2d/default_edge_connection_margin" type="int" setter="" getter="" default="1">
 			Default edge connection margin for 2D navigation maps. See [method NavigationServer2D.map_set_edge_connection_margin].
 		</member>
+		<member name="navigation/2d/default_link_connection_radius" type="int" setter="" getter="" default="4">
+			Default link connection radius for 2D navigation maps. See [method NavigationServer2D.map_set_link_connection_radius].
+		</member>
 		<member name="navigation/3d/default_cell_size" type="float" setter="" getter="" default="0.25">
 			Default cell size for 3D navigation maps. See [method NavigationServer3D.map_set_cell_size].
 		</member>
 		<member name="navigation/3d/default_edge_connection_margin" type="float" setter="" getter="" default="0.25">
 			Default edge connection margin for 3D navigation maps. See [method NavigationServer3D.map_set_edge_connection_margin].
 		</member>
+		<member name="navigation/3d/default_link_connection_radius" type="float" setter="" getter="" default="1.0">
+			Default link connection radius for 3D navigation maps. See [method NavigationServer3D.map_set_link_connection_radius].
+		</member>
 		<member name="network/limits/debugger/max_chars_per_second" type="int" setter="" getter="" default="32768">
 			Maximum number of characters allowed to send as output from the debugger. Over this value, content is dropped. This helps not to stall the debugger connection.
 		</member>