Merge pull request godotengine#8028 from ershn/improve_the_navigation_docs_wording

Improve the navigation documentation wording

Author: mhilbrunner

tutorials/navigation/navigation_connecting_navmesh.rst

@@ -1,7 +1,7 @@
 .. _doc_navigation_connecting_navmesh:
 
-Connecting NavigationMeshes
-===========================
+Connecting navigation meshes
+============================
 
 Different NavigationMeshes are automatically merged by the NavigationServer
 when at least two vertex positions of one edge exactly overlap.
@@ -26,10 +26,10 @@ navigation region edge connections on the NavigationServer and should be avoided
     Exactly means exactly for the vertex position merge. Small float errors
     that happen quite regularly with imported meshes will prevent a successful vertex merge.
 
-Alternatively ``NavigationMesh``s are not merged but still considered as ``connected`` by
+Alternatively navigation meshes are not merged but still considered as ``connected`` by
 the NavigationServer when their edges are nearly parallel and within distance
 to each other. The connection distance is defined by the  ``edge_connection_margin`` for each
-navigation map. In many cases NavigationMesh edges cannot properly connect when they partly overlap.
+navigation map. In many cases navigation mesh edges cannot properly connect when they partly overlap.
 Better avoid any navigation mesh overlap at all time for a consistent merge behavior.
 
 .. image:: img/navigation_edge_connection.png

tutorials/navigation/navigation_debug_tools.rst

@@ -1,56 +1,53 @@
 .. _doc_navigation_debug_tools:
 
-Navigation Debug Tools
+Navigation debug tools
 ======================
 
 .. note::
 
     The debug tools, properties and functions are only available in Godot debug builds. 
     Do not use any of them in code that will be part of a release build.
 
-Enabling debug navigation
+Enabling navigation debug
 -------------------------
 
-The navigation debug visualization is enabled by default inside the Editor.
-To visualize navigation meshes and connections also at runtime 
-enable the option ``Visible Navigation`` in the editor debug menu.
+The navigation debug visualizations are enabled by default inside the Editor.
+To visualize navigation meshes and connections at runtime too, enable the option ``Visible Navigation`` in the editor ``Debug`` menu.
 
 .. image:: img/navigation_debug_toggle.png
 
-In Godot debug builds the navigation debug can also be toggled on the NavigationServers from scripts.
+In Godot debug builds the navigation debug can also be toggled through the NavigationServer singletons from scripts.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
 
     NavigationServer2D.set_debug_enabled(false)
     NavigationServer3D.set_debug_enabled(true)
 
-Debug navigation settings
+Navigation debug settings
 -------------------------
 
-The appearance of navigation debug can be change in the ProjectSettings under ``debug/shapes/navigation``. 
-Certain debug features can also be enabled or disabled at will but may require a scene restart to apply.
+The appearance of navigation debug can be changed in the ProjectSettings under ``debug/shapes/navigation``.
+Certain debug features can also be enabled or disabled at will but may require a scene restart to take effect.
 
 .. image:: img/nav_debug_settings.png
 
 Debug navigation mesh polygons
 ------------------------------
 
-If ``enable_edge_lines`` is enabled the edges of navigation mesh polygons will be highlighted.
-If ``enable_edge_lines_xray`` is also enabled the edges of navigationmeshes will be visible through geometry.
+If ``enable_edge_lines`` is enabled, the edges of navigation mesh polygons will be highlighted.
+If ``enable_edge_lines_xray`` is also enabled, the edges of navigation meshes will be visible through geometry.
 
-if ``enable_geometry_face_random_color`` is enabled each navigation mesh face receives 
-a random color that is mixed with the main color from ``geometry_face_color``.
+If ``enable_geometry_face_random_color`` is enabled, the color of each navigation mesh face will be mixed with a random color that is itself mixed with the color specified in ``geometry_face_color``.
 
 .. image:: img/nav_debug_xray_edge_lines.png
 
-
 Debug edge connections
 ----------------------
 
-Different navigation meshes connected within ``edge_connection_margin`` distance are overlaid.
-The color of the overlay is controlled with the navigation debug ``edge_connection_color``.
-The connections can be made visible through geometry with the navigation debug ``enable_edge_connections_xray`` property.
+When two navigation meshes are connected within ``edge_connection_margin`` distance, the connection is overlaid.
+The color of the overlay is controlled by ``edge_connection_color``.
+The connections can be made visible through geometry with ``enable_edge_connections_xray``.
 
 .. image:: img/nav_edge_connection2d.gif
 
@@ -60,7 +57,7 @@ The connections can be made visible through geometry with the navigation debug `
 
     Edge connections are only visible when the NavigationServer is active.
 
-Debug Performance
+Debug performance
 -----------------
 
 To measure NavigationServer performance a dedicated monitor exists that can be found within the Editor Debugger under `Debugger->Monitors->NavigationProcess`.

tutorials/navigation/navigation_different_actor_area_access.rst

@@ -9,9 +9,9 @@ A typical example for different area access in gameplay are doors that connect r
 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.
+Add an appropriate navigation mesh the size of the door that can connect with the surrounding navigation meshes.
+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" navigation mesh.
 
 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.
@@ -22,7 +22,7 @@ See :ref:`doc_navigation_advanced_using_navigationlayers` for more information o
 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.
+navigation layers on a region triggers a costly recalculation of the navigation map connections.
 
 .. warning::
 

tutorials/navigation/navigation_introduction_2d.rst

@@ -1,6 +1,6 @@
 .. _doc_navigation_overview_2d:
 
-2D Navigation Overview
+2D navigation overview
 ======================
 
 Godot provides multiple objects, classes and servers to facilitate grid-based or mesh-based navigation and pathfinding for 2D and 3D games.
@@ -11,66 +11,68 @@ Godot provides the following objects and classes for 2D navigation:
 - :ref:`Astar2D<class_Astar2D>`
     ``Astar2D`` objects provide an option to find the shortest path in a graph of weighted **points**.
 
-    The AStar2D class is best suited for cellbased 2D gameplay that does not require actors to reach any possible position within an area but only predefined, distinct positions.
+    The AStar2D class is best suited for cell-based 2D gameplay that does not require actors to reach any possible position within an area but only predefined, distinct positions.
 
 - :ref:`NavigationServer2D<class_NavigationServer2D>`
     ``NavigationServer2D`` provides a powerful server API to find the shortest path between two positions on a area defined by a navigation mesh.
 
-    The NavigationServer is best suited for 2D realtime gameplay that does require actors to reach any possible position within an navmesh defined area.
-    Meshbased navigation scales well with large gameworlds as a large area can often be defined with a single polygon when it would require many, many grid cells.
+    The NavigationServer is best suited for 2D realtime gameplay that does require actors to reach any possible position within a navigation mesh defined area.
+    Mesh-based navigation scales well with large game worlds as a large area can often be defined with a single polygon when it would require many, many grid cells.
 
     The NavigationServer holds different navigation maps that each consist of regions that hold navigation mesh data.
     Agents can be placed on a map for avoidance calculation.
-    RIDs are used to reference the internal maps, regions and agents when communicating with the server.
+    RIDs are used to reference internal maps, regions, and agents when communicating with the server.
 
     The following NavigationServer RID types are available.
         - NavMap RID
             Reference to a specific navigation map that holds regions and agents.
-            The map will attempt to join changed navigation meshes of regions by proximity.
+            The map will attempt to join the navigation meshes of the regions by proximity.
             The map will synchronize regions and agents each physics frame.
         - NavRegion RID
             Reference to a specific navigation region that can hold navigation mesh data.
-            The region can be enabled / disabled or the use restricted with a navigationlayer bitmask.
+            The region can be enabled / disabled or the use restricted with a navigation layer bitmask.
         - NavLink RID
             Reference to a specific navigation link that connects two navigation mesh positions over arbitrary distances.
         - NavAgent RID
-            Reference to a specific avoidance agent with a radius value use solely in avoidance.
+            Reference to a specific avoidance agent.
+            The avoidance is specified by a radius value.
         - NavObstacle RID
-            Reference to a specific avoidance obstacle used to affect and constrain avoidance velocities of agents.
+            Reference to a specific avoidance obstacle used to affect and constrain the avoidance velocity of agents.
 
 The following SceneTree Nodes are available as helpers to work with the NavigationServer2D API.
 
 - :ref:`NavigationRegion2D<class_NavigationRegion2D>` Node
     A Node that holds a NavigationPolygon resource that defines a navigation mesh for the NavigationServer2D.
 
     - The region can be enabled / disabled.
-    - The use in pathfinding can be further restricted through the navigationlayers bitmask.
-    - Regions can join their navigation meshes by proximity for a combined navigation mesh.
+    - The use in pathfinding can be further restricted through the ``navigation_layers`` bitmask.
+    - The NavigationServer2D will join the navigation meshes of regions by proximity for a combined navigation mesh.
 
 - :ref:`NavigationLink2D<class_NavigationLink2D>` Node
-    A Node that connects two positions on navigation mesh over arbitrary distances for pathfinding.
+    A Node that connects two positions on navigation meshes over arbitrary distances for pathfinding.
 
     - The link can be enabled / disabled.
     - The link can be made one-way or bidirectional.
-    - The use in pathfinding can be further restricted through the navigationlayers bitmask.
+    - The use in pathfinding can be further restricted through the ``navigation_layers`` bitmask.
 
     Links tell the pathfinding that a connection exists and at what cost. The actual agent handling and movement needs to happen in custom scripts.
 
 -  :ref:`NavigationAgent2D<class_NavigationAgent2D>` Node
-    An optional helper Node to facilitate common NavigationServer2D API calls for pathfinding and avoidance
-    for a Node2D inheriting parent Node.
+    A helper Node used to facilitate common NavigationServer2D API calls for pathfinding and avoidance.
+    Use this Node with a Node2D inheriting parent Node.
 
 -  :ref:`NavigationObstacle2D<class_NavigationObstacle2D>` Node
-    A Node that can be used to affect and constrain avoidance velocities of avoidance enabled agents.
-    This Node does NOT affect the pathfinding of agents which requires changing the navigation mesh instead.
+    A Node that can be used to affect and constrain the avoidance velocity of avoidance enabled agents.
+    This Node does NOT affect the pathfinding of agents. You need to change the navigation meshes for that instead.
 
 The 2D navigation meshes are defined with the following resources:
 
 - :ref:`NavigationPolygon<class_NavigationPolygon>` Resource
-    A resource that holds 2D navigation mesh data and provides polygon drawtools to define navigation areas inside the Editor as well as at runtime.
+    A resource that holds 2D navigation mesh data.
+    It provides polygon drawing tools to allow defining navigation areas inside the Editor as well as at runtime.
 
     - The NavigationRegion2D Node uses this resource to define its navigation area.
-    - The NavigationServer2D uses this resource to update navmesh of individual regions.
+    - The NavigationServer2D uses this resource to update the navigation mesh of individual regions.
     - The TileSet Editor creates and uses this resource internally when defining tile navigation areas.
 
 .. seealso::
@@ -83,8 +85,8 @@ The 2D navigation meshes are defined with the following resources:
 Setup for 2D scene
 ------------------
 
-The following steps show the basic setup for a minimum viable navigation in 2D that uses the
-NavigationServer2D and a NavigationAgent2D for path movement.
+The following steps show the basic setup for minimal viable navigation in 2D.
+It uses the NavigationServer2D and a NavigationAgent2D for path movement.
 
 #. Add a NavigationRegion2D Node to the scene.
 
@@ -99,8 +101,7 @@ NavigationServer2D and a NavigationAgent2D for path movement.
    .. note::
 
         The navigation mesh defines the area where an actor can stand and move with its center.
-        Leave enough margin between the navpolygon edges and collision objects to not get path
-        following actors repeatedly stuck on collision.
+        Leave enough margin between the navigation polygon edges and collision objects to not get path following actors repeatedly stuck on collision.
 
 #. Add a CharacterBody2D node in the scene with a basic collision shape and a sprite or mesh
    for visuals.
@@ -211,5 +212,4 @@ NavigationServer2D and a NavigationAgent2D for path movement.
 
 .. note::
 
-    On the first frame the NavigationServer map has not synchronized region data and any path query
-    will return empty. Await one frame to pause scripts until the NavigationServer had time to sync.
+    On the first frame the NavigationServer map has not synchronized region data and any path query will return empty. Wait for the NavigationServer synchronization by awaiting one frame in the script.