Add navigation section and document 3D navigation (3.4)

index.rst

@@ -99,6 +99,7 @@ The main documentation for the site is organized into the following sections:
    tutorials/viewports/index
    tutorials/shading/index
    tutorials/networking/index
+   tutorials/navigation/index
    tutorials/assetlib/index
    tutorials/vr/index
    tutorials/plugins/index

tutorials/navigation/index.rst

@@ -0,0 +1,8 @@
+Navigation
+==========
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-learn-features-navigation
+
+   real_time_navigation_3d

tutorials/navigation/real_time_navigation_3d.rst

@@ -0,0 +1,64 @@
+.. _doc_real_time_navigation_3d:
+
+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>`.
+
+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>`.
+
+After making the changes you want the mesh can be generated by clicking
+**Bake NavMesh** in the toolbar.
+
+.. image:: img/bake_navmesh.png
+
+Once the mesh has finished generating you should see the transparent
+navigation mesh above the areas in your 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 1 then your
+navigation mesh will have a distance of .5 from any ledges or walls
+to prevent clipping into the wall or hanging off of the edge.
+
+Generating a path
+-----------------
+
+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
+last argument is a boolean for whether or not agent properties of a
+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.