Add doc for NavigationMesh connections and NavigationDebug

tutorials/navigation/index.rst

@@ -15,3 +15,5 @@ Navigation
    navigation_using_navigationservers
    navigation_using_navigationagents
    navigation_using_agent_avoidance
+   navigation_debug_tools
+   navigation_connecting_navmesh

tutorials/navigation/navigation_connecting_navmesh.rst

@@ -0,0 +1,62 @@
+.. _doc_navigation_connecting_navmesh:
+
+Connecting NavigationMeshes
+===========================
+
+Different NavigationMeshes are automatically merged by the NavigationServer 
+when at least two vertex positions of one edge exactly overlap.
+
+.. image:: img/navigation_vertex_merge.png
+
+The same is true for multiple NavigationPolygon resources. As long as their 
+outline points overlap exactly the NavigationServer will merge them.
+NavigationPolygon outlines must be from different NavigationPolygon resources to connect.
+
+Overlapping or intersecting outlines on the same NavigationPolygon 
+will fail the navigation mesh creation. Overlapping or intersecting 
+outlines from different NavigationPolygons will often fail to create the 
+navigation region edge connections on the NavigationServer and should be avoided.
+
+.. image:: img/navigation_vertex_merge2.png
+
+.. warning::
+
+    Exactly means exactly for the vertex position merge. Small float errors 
+    that happen quite regularly with imported meshes will prevent a successful vertex merge.
+
+Alternatively ``NavigationMesh``s are not merged but still considered as ``connected`` by 
+the NavigationServer when their edges are nearly parallel and within distance 
+to each other. The connection distance is defined by the  ``edge_connection_margin`` for each 
+navigation map. In many cases NavigationMesh edges cannot properly connect when they partly overlap. 
+Better avoid any navigation mesh overlap at all time for a consistent merge behavior.
+
+.. image:: img/navigation_edge_connection.png
+
+If navigation debug is enabled and the NavigationServer active the established navigation mesh connections will be visualized. 
+See :ref:`doc_navigation_debug_tools` for more info about navigation debug options.
+
+The default 2D ``edge_connection_margin`` can be changed in the ProjectSettings under ``navigation/2d/default_edge_connection_margin``.
+
+The default 3D ``edge_connection_margin`` can be changed in the ProjectSettings under ``navigation/3d/default_edge_connection_margin``.
+
+The edge connection margin value of any navigation map can also be changed at runtime with the NavigationServer API.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Node2D
+    # 2D margins are designed to work with "pixel" values
+    var default_2d_map_rid : RID = get_world_2d().get_navigation_map()
+    NavigationServer2D.map_set_edge_connection_margin(default_2d_map_rid, 50.0)
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Node3D
+    # 3D margins are designed to work with 3D unit values
+    var default_3d_map_rid : RID = get_world_3d().get_navigation_map()
+    NavigationServer3D.map_set_edge_connection_margin(default_3d_map_rid, 0.5)
+
+.. note::
+
+    Changing the edge connection margin will trigger a full update of all navigation mesh connections on the NavigationServer.

tutorials/navigation/navigation_debug_tools.rst

@@ -0,0 +1,61 @@
+.. _doc_navigation_debug_tools:
+
+Navigation Debug Tools
+======================
+
+.. note::
+
+    The debug tools, properties and functions are only available in Godot debug builds. 
+    Do not use any of them in code that will be part of a release build.
+
+Enabling debug navigation
+-------------------------
+
+The navigation debug visualization is enabled by default inside the Editor.
+To visualize navigation meshes and connections also at runtime 
+enable the option ``Visible Navigation`` in the editor debug menu.
+
+.. image:: img/navigation_debug_toggle.png
+
+In Godot debug builds the navigation debug can also be toggled on the NavigationServers from scripts.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    NavigationServer2D.set_debug_enabled(false)
+    NavigationServer3D.set_debug_enabled(true)
+
+Debug navigation settings
+-------------------------
+
+The appearance of navigation debug can be change in the ProjectSettings under ``debug/shapes/navigation``. 
+Certain debug features can also be enabled or disabled at will but may require a scene restart to apply.
+
+.. image:: img/nav_debug_settings.png
+
+Debug navigation mesh polygons
+------------------------------
+
+If ``enable_edge_lines`` is enabled the edges of navigation mesh polygons will be highlighted.
+If ``enable_edge_lines_xray`` is also enabled the edges of navigationmeshes will be visible through geometry.
+
+if ``enable_geometry_face_random_color`` is enabled each navigation mesh face receives 
+a random color that is mixed with the main color from ``geometry_face_color``.
+
+.. image:: img/nav_debug_xray_edge_lines.png
+
+
+Debug edge connections
+----------------------
+
+Different navigation meshes connected within ``edge_connection_margin`` distance are overlaid.
+The color of the overlay is controlled with the navigation debug ``edge_connection_color``.
+The connections can be made visible through geometry with the navigation debug ``enable_edge_connections_xray`` property.
+
+.. image:: img/nav_edge_connection2d.gif
+
+.. image:: img/nav_edge_connection3d.gif
+
+.. note::
+
+    Edge connections are only visible when the NavigationServer is active.