Add doc for NavigationLayers and area access

Adds documentation for NavigationLayers and how to use the bitmask for gameplay features like area access.

tutorials/navigation/index.rst

@@ -17,3 +17,5 @@ Navigation
    navigation_using_agent_avoidance
    navigation_debug_tools
    navigation_connecting_navmesh
+   navigation_using_navigationlayers
+   navigation_different_actor_area_access

tutorials/navigation/navigation_different_actor_area_access.rst

@@ -0,0 +1,29 @@
+.. _doc_navigation_different_actor_area_access:
+
+Support different actor area access
+===================================
+
+.. image:: img/nav_actor_doors.png
+
+A typical example for different area access in gameplay are doors that connect rooms 
+with different navigation meshes and are not accessible by all actors all the time.
+
+Add a NavigationRegion at the door position.
+Add an appropriated navigationmesh the size of the door that can connect with the surrounding navigationmeshes.
+In order to control access enable / disable navigation layer bits so path queries 
+that use the same navigation layer bits can find a path through the "door" navigationmesh.
+
+The bitmask can act as a set of door keys or abilities and only actors with at least 
+one matching and enabled bit layer in their pathfinding query will find a path through this region.
+See :ref:`doc_navigation_advanced_using_navigationlayers` for more information on how to work with navigation layers and the bitmask.
+
+.. image:: img/nav_actor_doorbitmask.png
+
+The entire "door" region can also be enabled / disable if required but if disabled will block access for all path queries.
+
+Prefer working with navigation layers in path queries whenever possible as enabling or disabling 
+navigation layers on a region triggers a performance costly recalculation of the navigation map connections.
+
+.. warning::
+
+    Changing navigation layers will only affect new path queries but not automatically update existing paths.

tutorials/navigation/navigation_using_navigationlayers.rst

@@ -0,0 +1,67 @@
+.. _doc_navigation_advanced_using_navigationlayers:
+
+Using NavigationLayers
+======================
+
+NavigationLayers are an optional feature to further control which navigation meshes are considered in a path query and which regions can be connected.
+They work similar to how physics layers control collision between collision objects or how visual layers control what is rendered to the Viewport.
+
+NavigationLayers can be named in the ``ProjectSettings`` the same as PhysicsLayers or VisualLayers.
+
+.. image:: img/navigationlayers_naming.png
+
+If two regions have not a single compatible layer they will not be merged by the NavigationServer. See :ref:`doc_navigation_connecting_navmesh` for more information on merging navmesh.
+
+If a region has not a single compatible navigation layer with the ``navigation_layers`` parameter of a path query this regions navigation mesh will be skipped in pathfinding.
+See :ref:`doc_navigation_using_navigationpaths` for more information on querying the NavigationServer for paths.
+
+NavigationLayers are a single ``int`` value that is used as a ``bitmask``. 
+Many navigation related nodes have ``set_navigation_layer_value()`` and 
+``get_navigation_layer_value()`` functions to set and get a layer number directly 
+without the need for more complex bitwise operations.
+
+In scripts the following helper functions can be used to work with the navigation_layers bitmask.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+    
+    func change_layers():
+        var region : NavigationRegion3D = get_node("NavigationRegion3D)
+        # enables 4-th layer for this region
+        region.navigation = enable_bitmask_inx(region.navigation, 4)
+        # disables 1-rst layer for this region
+        region.navigation = disable_bitmask_inx(region.navigation, 1)
+    
+        var agent : NavigationAgent3D = get_node("NavigationAgent3D)
+        # make future path queries of this agent ignore regions with 4-th layer
+        agent.navigation = disable_bitmask_inx(agent.navigation, 4)
+        
+        var path_query_layers : int = 0
+        path_query_layers = enable_bitmask_inx(path_layers, 2)
+        # get a path that only considers 2-nd layer regions
+        var path : PoolVector3Array = NavigationServer3D.map_get_path(
+            map,
+            start_position,
+            target_position,
+            true,
+            path_query_layers
+            )
+    
+    static func is_bitmask_inx_enabled(_bitmask : int, _index : int) -> bool:
+        return _bitmask & (1 << _index) != 0
+    
+    static func enable_bitmask_inx(_bitmask : int, _index : int) -> int:
+        return _bitmask | (1 << _index)
+    
+    static func disable_bitmask_inx(_bitmask : int, _index : int) -> int:
+        return _bitmask & ~(1 << _index)
+
+Changing navigation layers for path queries is a performance friendly alternative to 
+enabling / disabling entire navigation regions. Compared to region changes a 
+navigation path query with different navigation layers does not 
+trigger large scale updates on the NavigationServer.
+
+Changing the navigation layers of NavigationAgent nodes will have an immediate 
+effect on the next path query. Changing the navigation layers of 
+regions will have an immediate effect on the region but any new region 
+connect or disconnect will only be in effect after the next physics_frame.