Merge pull request #6046 from smix8/doc_navigation_obstacles_4.x

Add doc for NavigationObstacle nodes and NavigationServerAPI obstacle agents

tutorials/navigation/index.rst

@@ -10,3 +10,4 @@ Navigation
    navigation_using_navigationmaps
    navigation_different_actor_types
    navigation_different_actor_locomotion
+   navigation_using_navigationobstacles

tutorials/navigation/navigation_using_navigationobstacles.rst

@@ -0,0 +1,54 @@
+.. _doc_navigation_using_navigationobstacles:
+
+Using NavigationObstacles
+=========================
+
+NavigationObstacles are used to set an avoidance radius around objects 
+that, due to their constant movement, cannot be efficiently (re)baked 
+to a 2D NavigationPolygon or 3D NavigationMesh. 
+
+2D and 3D versions of NavigationObstacles nodes are available as 
+:ref:`NavigationObstacle2D<class_NavigationObstacle2D>` and 
+:ref:`NavigationObstacle3D<class_NavigationObstacle3D>`  respectively.
+
+NavigationObstacles are not intended for any kind of static geometry 
+or temporary barriers that may change their position occasionally.
+Those changes should be (re)baked so actors can follow the outlines 
+of these objects at higher detail with navigation paths. The obstacle avoidance 
+should be seen as a last resort option intended for objects that are constantly moving.
+
+To use NavigationObstacles for avoidance, place a NavigationObstacle2D/3D node 
+below a Node2D/3D inheriting parent node. While the obstacle node has an 
+option to ``estimate_radius`` from child collisions, prefer to set a 
+more reliable manual ``radius`` value. If estimated, the obstacle will use 
+a radius that encapsulates the entire parent node which can result in a very large 
+radius value if the parent is not a circle shape but e.g. a long rectangle shape.
+
+.. note::
+
+    The obstacle ``radius`` is the area that will be strictly avoided whenever possible.
+    Do not set it too large. Agents start to avoid way before 
+    this radius depending on parameters and velocity.
+
+
+While NavigationObstacle nodes do require a Node parent the NavigationServer obstacles do not.
+New obstacles created in scripts require only a ``map``, ``radius`` and ``position``.
+Obstacles can be placed directly on the NavigationMap with the NavigationServer API.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+    
+    extends Node3D
+    # create a new "obstacle" agent and place it on the default map``
+    var new_agent_rid : RID = NavigationServer3D.agent_create()
+    var default_3d_map_rid : RID = get_world_3d().get_navigation_map()
+    
+    NavigationServer3D.agent_set_map(new_agent_rid, default_3d_map_rid)
+    NavigationServer3D.agent_set_radius(new_agent_rid, 0.5)
+    NavigationServer3D.agent_set_position(new_agent_rid, global_transform.origin)
+
+.. note::
+
+    The NavigationServer API has no dedicated functions for obstacles.
+    Obstacles are technically considered just normal agents.
+    All "agent" prefixed functions are intended for obstacles as well.