Add doc for NavigationRegions

Adds documentation for NavigationRegions and NavigationServer API use.

tutorials/navigation/index.rst

@@ -20,3 +20,4 @@ Navigation
    navigation_using_navigationlayers
    navigation_different_actor_area_access
    navigation_using_navigationpaths
+   navigation_using_navigationregions

tutorials/navigation/navigation_using_navigationregions.rst

@@ -0,0 +1,70 @@
+.. _doc_navigation_using_navigationregions:
+
+Using NavigationRegions
+=======================
+
+NavigationRegions are the visual Node representation of a ``region`` of the navigation ``map`` on the NavigationServer.
+Each NavigationRegion node holds a resource for the navigationmesh data.
+
+Both 2D and 3D version are available as :ref:`NavigationRegion2D<class_NavigationRegion2D>` 
+and :ref:`NavigationRegion3D<class_NavigationRegion3D>` respectively.
+
+Individual NavigationRegions upload their 2D NavigationPolygon or 3D NavigationMesh resource data to the NavigationServer.
+The NavigationServer map turns this information into a combined navigation map for pathfinding.
+
+To create a navigation region using the SceneTree add a ``NavigationRegion3D`` or ``NavigationRegion3D`` node to the scene.
+All regions require a navigationmesh resource to function. See :ref:`doc_navigation_using_navigationmeshes` to learn how to create and apply navigationmeshes.
+
+NavigationRegions will automatically push ``global_transform`` changes to the region on the NavigationServer which makes them suitable for moving platforms.
+The NavigationServer will attempt to connect navmeshes of individual regions when they are close enough. For more detail see :ref:`doc_navigation_connecting_navmesh`.
+
+.. warning::
+
+    While changing the transform of a NavigationRegion node does update the region position on the 
+    NavigationServer changing the scale does not. A navigationmesh resource has no scale and needs 
+    to be fully updated when source geometry changes scale.
+
+Regions can be enabled / disabled and if disabled will not contribute to future pathfinding queries.
+
+.. note::
+
+    Existing paths will not be automatically updated when a region gets enabled / disabled.
+
+Creating new navigation regions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New navigation regions will automatically register to the default world navigation map.
+
+The region RID can be obtained from NavigationRegion Nodes with ``get_region_rid()``.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends NavgiationRegion3D
+    
+    var navigationserver_region_rid : RID = get_region_rid()
+
+New regions can also be created with the NavigationServer API and added to any existing map.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Node2D
+    
+    var new_2d_region_rid : RID = NavigationServer2D.region_create()
+    var default_2d_map_rid : RID = get_world_2d().get_navigation_map()
+    NavigationServer2D.region_set_map(new_2d_region_rid, default_2d_map_rid)
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Node3D
+    
+    var new_3d_region_rid : RID = NavigationServer3D.region_create()
+    var default_3d_map_rid : RID = get_world_3d().get_navigation_map()
+    NavigationServer3D.region_set_map(new_3d_region_rid, default_3d_map_rid)
+
+.. note::
+
+    NavigationRegions can only be assigned to a single NavigationMap.
+    If an existing region is assigned to a new map it will leave the old map.