Document 3D navigation server in Godot 3.5

tutorials/navigation/real_time_navigation_3d.rst

@@ -6,46 +6,99 @@ Real Time Navigation (3D)
 Introduction
 ------------
 
-Godot provides two nodes which can be used to achieve real time navigation
-in a 3D environment, :ref:`Navigation <class_Navigation>` and :ref:`NavigationMeshInstance <class_NavigationMeshInstance>`.
+Pathfinding in a 3D environment is crucial for many games, it's commonly
+how non directly controlled characters or entities find their way around
+an environment. Godot provides several nodes for this purpose:
+
+-  :ref:`Navigation<class_Navigation>`
+-  :ref:`NavigationMeshInstance<class_NavigationMeshInstance>`
+-  :ref:`NavigationAgent<class_NavigationAgent>`
+-  :ref:`NavigationObstacle<class_NavigationObstacle>`
+
+The map and navigation regions
+------------------------------
+
+The "map" is the entire world for navigation, it's similar to "space" for
+the physics engine. It's comprised of navigation regions, these regions
+define parts of the world that can be navigated around by navigation
+agents.
+
+To create a navigation region add the :ref:`Navigation<class_Navigation>`
+node to a 3D scene, then add a :ref:`NavigationMeshInstance<class_NavigationMeshInstance>`
+as child of the navigation node. Next in the inspector for that mesh create or add a
+:ref:`NavigationMesh<class_NavigationMesh>`. The navmesh contains options
+for how it will be generated when it's baked. The geometry options control
+which nodes, and types of nodes, are used to bake the mesh. A full
+description of each setting and how it works can be found in the :ref:`NavigationMesh class reference<class_NavigationMesh>`.
+
+Once the settings have been properly configured press the "Bake NavMesh"
+button at the top of the inspector to generate it.
 
-A navigation mesh instance is used to hold a :ref:`NavigationMesh <class_NavigationMesh>`,
-which defines what areas in a scene can be navigated to. The :ref:`Navigation <class_Navigation>`
-node is then used for pathfinding with the navigation mesh.
-
-Setting up navigation
----------------------
-
-To add navigation to a scene you need to add a navigation node, then
-a navigation mesh instance as a child of the navigation node. With the
-navigation mesh instance selected you need to go to the inspector and
-create a new navigation mesh.
-
-.. image:: img/new_navigation_mesh.png
-
-Click on the navigation mesh and you can now alter the properties that
-define how the navigation mesh is generated. You can find a full
-description for each of the properties in the class reference here:
-:ref:`NavigationMesh <class_NavigationMesh>`.
+.. image:: img/bake_navmesh.png
 
-After making the changes you want the mesh can be generated by clicking
-**Bake NavMesh** in the toolbar.
+.. note::
 
-.. image:: img/bake_navmesh.png
+    It can also be generated at runtime using the `bake_navigation_region()`
+    method of the navigation region node.
 
 Once the mesh has finished generating you should see the transparent
-navigation mesh above the areas in your scene that can be navigated to.
+navigation mesh above the areas in the scene that can be navigated to.
 
 .. image:: img/baked_navmesh.png
 
 Keep in mind that the navmesh shows where the center of an entity can
-go. For example, if you set the agent radius to 0.5 then your
+go. For example, if you set the agent radius to 0.5 then the
 navigation mesh will have a distance of 0.5 from any ledges or walls
 to prevent clipping into the wall or hanging off of the edge.
 
-Generating a path
+Navigation agents can moved from one region to another if they are next
+to each other. Additionally a baked navmesh can be moved at runtime and
+agents will still be able to navigate onto it from another region.
+For example, navigating onto a moving platform that has stopped will work.
+
+NavigationAgent3D
 -----------------
 
+Navigation agent nodes are what actually does the pathfinding in a scene,
+one can be attached to the root node of an entity that needs to navigate.
+
+To have it pathfind use its `set_target_location` method. Once the target
+has been set a path will be generated to the node using navigation regions,
+with several points on the way to the final destination.
+
+RVO processing
+--------------
+
+RVO stands for reciprocal velocity obstacle. RVO processing is a way to
+pathfind while taking into account other agents and physics bodies that
+are also moving.
+
+To use it set a target like normal. Then an agent needs to fetch its next
+nav path location, and compute its velocity to that location. Instead
+of using that value to move use it to set the velocity on the agent
+with `set_velocity`. Then a new velocity that takes into account other
+agents and obstacles is generated and emitted with the signal `velocity_computed`.
+
+However agents can only take into account a set number of other nearby
+agents, this is the :ref:`max neighbors<class_NavigationAgent_property_max_neighbors>`
+property of an agent and can be adjusted. This is **not** a limit for
+how many agents can use a navigation region at the same time.
+
+NavigationObstacle3D
+--------------------
+
+This node is used to mark physics bodies that move around a navigation area
+that agents need to avoid (this will only work if you use RVO processing).
+For example, this node would be useful for pieces of debris in a destructible
+environment. Add it as the child of a physics body and navigation agent
+nodes will avoid it while pathfinding.
+
+Generating a path (old method)
+------------------------------
+
+This is the old method for generating a navigation path, it will be
+removed in Godot 4.
+
 To get a path between two areas on a map you use the navigation node
 method ``get_simple_path()``. The first argument is a Vector3 of the
 starting location, the next is a Vector3 of the end location. And the
@@ -55,10 +108,3 @@ navmesh are considered when generating a path.
 The method will return a :ref:`PoolVector3Array <class_PoolVector3Array>` consisting of
 points that make a path. If there is no way to navigate to the end
 location the method will return a blank :ref:`PoolVector3Array <class_PoolVector3Array>`.
-
-Official example project
-------------------------
-
-There is an official example project on how to use 3D navigation.
-You can find the repository `here <https://github.com/godotengine/godot-demo-projects/tree/master/3d/navmesh>`__.
-It can also be found in the asset library.