diff --git a/tutorials/navigation/img/nav_debug_settings.png b/tutorials/navigation/img/nav_debug_settings.png new file mode 100644 index 000000000..e732eb953 Binary files /dev/null and b/tutorials/navigation/img/nav_debug_settings.png differ diff --git a/tutorials/navigation/img/nav_debug_xray_edge_lines.png b/tutorials/navigation/img/nav_debug_xray_edge_lines.png new file mode 100644 index 000000000..d2cce62ab Binary files /dev/null and b/tutorials/navigation/img/nav_debug_xray_edge_lines.png differ diff --git a/tutorials/navigation/img/nav_edge_connection2d.gif b/tutorials/navigation/img/nav_edge_connection2d.gif new file mode 100644 index 000000000..12b1c1c0d Binary files /dev/null and b/tutorials/navigation/img/nav_edge_connection2d.gif differ diff --git a/tutorials/navigation/img/nav_edge_connection3d.gif b/tutorials/navigation/img/nav_edge_connection3d.gif new file mode 100644 index 000000000..2770e9205 Binary files /dev/null and b/tutorials/navigation/img/nav_edge_connection3d.gif differ diff --git a/tutorials/navigation/img/navigation_debug_toggle.png b/tutorials/navigation/img/navigation_debug_toggle.png new file mode 100644 index 000000000..31b51d628 Binary files /dev/null and b/tutorials/navigation/img/navigation_debug_toggle.png differ diff --git a/tutorials/navigation/img/navigation_edge_connection.png b/tutorials/navigation/img/navigation_edge_connection.png new file mode 100644 index 000000000..4a3312ccf Binary files /dev/null and b/tutorials/navigation/img/navigation_edge_connection.png differ diff --git a/tutorials/navigation/img/navigation_vertex_merge.png b/tutorials/navigation/img/navigation_vertex_merge.png new file mode 100644 index 000000000..1ae031599 Binary files /dev/null and b/tutorials/navigation/img/navigation_vertex_merge.png differ diff --git a/tutorials/navigation/img/navigation_vertex_merge2.png b/tutorials/navigation/img/navigation_vertex_merge2.png new file mode 100644 index 000000000..bae3169b6 Binary files /dev/null and b/tutorials/navigation/img/navigation_vertex_merge2.png differ diff --git a/tutorials/navigation/index.rst b/tutorials/navigation/index.rst index 51cdecf9d..a2a930e37 100644 --- a/tutorials/navigation/index.rst +++ b/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 diff --git a/tutorials/navigation/navigation_connecting_navmesh.rst b/tutorials/navigation/navigation_connecting_navmesh.rst new file mode 100644 index 000000000..a2a9ecb0b --- /dev/null +++ b/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. diff --git a/tutorials/navigation/navigation_debug_tools.rst b/tutorials/navigation/navigation_debug_tools.rst new file mode 100644 index 000000000..2fe679805 --- /dev/null +++ b/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.