Merge pull request godotengine#8199 from timothyqiu/nav-markup

Improve the navigation documentation markup

Author: skyace65

tutorials/navigation/navigation_connecting_navmesh.rst

@@ -26,7 +26,7 @@ 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 navigation meshes 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 navigation mesh edges cannot properly connect when they partly overlap.

tutorials/navigation/navigation_debug_tools.rst

@@ -5,22 +5,22 @@ Navigation debug tools
 
 .. note::
 
-    The debug tools, properties and functions are only available in Godot debug builds. 
+    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 navigation debug
 -------------------------
 
-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.
+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 through the NavigationServer singletons from scripts.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
-    
+
     NavigationServer2D.set_debug_enabled(false)
     NavigationServer3D.set_debug_enabled(true)
 
@@ -60,21 +60,21 @@ The connections can be made visible through geometry with ``enable_edge_connecti
 Debug performance
 -----------------
 
-To measure NavigationServer performance a dedicated monitor exists that can be found within the Editor Debugger under `Debugger->Monitors->NavigationProcess`.
+To measure NavigationServer performance a dedicated monitor exists that can be found within the Editor Debugger under *Debugger->Monitors->Navigation Process*.
 
 .. image:: img/navigation_debug_performance1.webp
 
-NavigationProcess shows how long the NavigationServer spends updating its internals this update frame in milliseconds.
-NavigationProcess works similar to Process for visual frame rendering and PhysicsProcess for collision and fixed updates.
+Navigation Process shows how long the NavigationServer spends updating its internals this update frame in milliseconds.
+Navigation Process works similar to Process for visual frame rendering and Physics Process for collision and fixed updates.
 
-NavigationProcess accounts for all updates to ``navigation maps``, ``navigation regions`` and ``navigation agents`` as well as all the ``avoidance calculations`` for the update frame.
+Navigation Process accounts for all updates to **navigation maps**, **navigation regions** and **navigation agents** as well as all the **avoidance calculations** for the update frame.
 
 .. note::
 
-    NavigationProcess does NOT include pathfinding performance cause pathfinding operates on the navigation map data independently from the server process update.
+    Navigation Process does NOT include pathfinding performance cause pathfinding operates on the navigation map data independently from the server process update.
 
-NavigationProcess should be in general kept as low and as stable as possible for runtime performance to avoid frame rate issues.
-Note that since the NavigationServer process update happens in the middle of the physics update an increase in NavigationProcess will automatically increase PhysicsProcess by the same amount.
+Navigation Process should be in general kept as low and as stable as possible for runtime performance to avoid frame rate issues.
+Note that since the NavigationServer process update happens in the middle of the physics update an increase in Navigation Process will automatically increase Physics Process by the same amount.
 
 Navigation also provides more detailed statistics about the current navigation related objects and navigation map composition on the NavigationServer.
 

tutorials/navigation/navigation_using_navigationagents.rst

@@ -3,16 +3,16 @@
 Using NavigationAgents
 ======================
 
-NavigationsAgents are helper nodes that combine functionality 
+NavigationsAgents are helper nodes that combine functionality
 for pathfinding, path following and agent avoidance for a Node2D/3D inheriting parent node.
-They facilitate common calls to the NavigationServer API on 
+They facilitate common calls to the NavigationServer API on
 behalf of the parent actor node in a more convenient manner for beginners.
 
 2D and 3D version of NavigationAgents are available as
 :ref:`NavigationAgent2D<class_NavigationAgent2D>` and
 :ref:`NavigationAgent3D<class_NavigationAgent3D>` respectively.
 
-New NavigationAgent nodes will automatically join the default navigation map on the World2D/World3D.
+New NavigationAgent nodes will automatically join the default navigation map on the :ref:`World2D<class_World2D>`/:ref:`World3D<class_World3D>`.
 
 NavigationsAgent nodes are optional and not a hard requirement to use the navigation system.
 Their entire functionality can be replaced with scripts and direct calls to the NavigationServer API.
@@ -39,7 +39,7 @@ NavigationAgent Pathfollowing
 After a ``target_position`` has been set for the agent, the next position to follow in the path
 can be retrieved with the ``get_next_path_position()`` function.
 
-Once the next path position is received move the parent actor node of the agent 
+Once the next path position is received move the parent actor node of the agent
 towards this path position with your own movement code.
 
 .. note::
@@ -50,8 +50,8 @@ towards this path position with your own movement code.
 NavigationAgents have their own internal logic to proceed with the current path and call for updates.
 
 The ``get_next_path_position()`` function is responsible for updating many of the agent's internal states and properties.
-The function should be repeatedly called `once` every ``physics_process`` until ``is_navigation_finished()`` tells that the path is finished.
-The function should not be called after the target position or path end has been reached 
+The function should be repeatedly called *once* every ``physics_process`` until ``is_navigation_finished()`` tells that the path is finished.
+The function should not be called after the target position or path end has been reached
 as it can make the agent jitter in place due to the repeated path updates.
 Always check very early in script with ``is_navigation_finished()`` if the path is already finished.
 
@@ -74,7 +74,7 @@ Pathfollowing common problems
 There are some common user problems and important caveats to consider when writing agent movement scripts.
 
 - The path is returned empty
-    If an agent queries a path before the navigation map synchronisation, e.g. in a _ready() function, the path might return empty. In this case the get_next_path_position() function will return the same position as the agent parent node and the agent will consider the path end reached. This is fixed by making a deferred call or using a callback e.g. waiting for the navigation map changed signal.
+    If an agent queries a path before the navigation map synchronisation, e.g. in a ``_ready()`` function, the path might return empty. In this case the ``get_next_path_position()`` function will return the same position as the agent parent node and the agent will consider the path end reached. This is fixed by making a deferred call or using a callback e.g. waiting for the navigation map changed signal.
 
 - The agent is stuck dancing between two positions
     This is usually caused by very frequent path updates every single frame, either deliberate or by accident (e.g. max path distance set too short). The pathfinding needs to find the closest position that are valid on navigation mesh. If a new path is requested every single frame the first path positions might end up switching constantly in front and behind the agent's current position, causing it to dance between the two positions.
@@ -94,7 +94,7 @@ In order for NavigationAgents to use the avoidance feature the ``enable_avoidanc
 
 .. image:: img/agent_avoidance_enabled.png
 
-The velocity_computed signal of the NavigationAgent node must be connected to receive the ``safe_velocity`` calculation result.
+The ``velocity_computed`` signal of the NavigationAgent node must be connected to receive the safe velocity calculation result.
 
 .. image:: img/agent_safevelocity_signal.png
 
@@ -132,7 +132,7 @@ NavigationObstacles can be used to add some environment constrains to the avoida
     Avoidance does not affect the pathfinding. It should be seen as an additional option for constantly moving objects that cannot be (re)baked to a navigation mesh efficiently in order to move around them.
 
 Using the NavigationAgent ``enable_avoidance`` property is the preferred option
-to toggle avoidance. The following code snippets can be used to 
+to toggle avoidance. The following code snippets can be used to
 toggle avoidance on agents, create or delete avoidance callbacks or switch avoidance modes.
 
 .. tabs::
@@ -179,7 +179,7 @@ The following sections provides script templates for nodes commonly used with Na
 Actor as Node3D
 ~~~~~~~~~~~~~~~
 
-This script adds basic navigation movement to a Node3D with a NavigationAgent3D child node.
+This script adds basic navigation movement to a :ref:`Node3D <class_Node3D>` with a :ref:`NavigationAgent3D <class_NavigationAgent3D>` child node.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -214,7 +214,7 @@ This script adds basic navigation movement to a Node3D with a NavigationAgent3D
 Actor as CharacterBody3D
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-This script adds basic navigation movement to a CharacterBody3D with a NavigationAgent3D child node.
+This script adds basic navigation movement to a :ref:`CharacterBody3D <class_CharacterBody3D>` with a :ref:`NavigationAgent3D <class_NavigationAgent3D>` child node.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -248,7 +248,7 @@ This script adds basic navigation movement to a CharacterBody3D with a Navigatio
 Actor as RigidBody3D
 ~~~~~~~~~~~~~~~~~~~~
 
-This script adds basic navigation movement to a RigidBody3D with a NavigationAgent3D child node.
+This script adds basic navigation movement to a :ref:`RigidBody3D <class_RigidBody3D>` with a :ref:`NavigationAgent3D <class_NavigationAgent3D>` child node.
 
 .. tabs::
  .. code-tab:: gdscript GDScript

tutorials/navigation/navigation_using_navigationlayers.rst

@@ -6,7 +6,7 @@ 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.
+NavigationLayers can be named in the **ProjectSettings** the same as physics layers or visual layers.
 
 .. image:: img/navigationlayers_naming.png
 
@@ -15,12 +15,12 @@ If two regions have not a single compatible layer they will not be merged by the
 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``.
+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.
+In scripts the following helper functions can be used to work with the ``navigation_layers`` bitmask.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -64,4 +64,4 @@ 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.
+connect or disconnect will only be in effect after the next physics frame.

tutorials/navigation/navigation_using_navigationlinks.rst

@@ -5,17 +5,17 @@ Using NavigationLinks
 
 .. image:: img/nav_navmesh_links.png
 
-NavigationLinks are used to connect navigation mesh polygons from :ref:`NavigationRegion2D<class_NavigationRegion2D>` 
+NavigationLinks are used to connect navigation mesh polygons from :ref:`NavigationRegion2D<class_NavigationRegion2D>`
 and :ref:`NavigationRegion3D<class_NavigationRegion3D>` over arbitrary distances for pathfinding.
 
-NavigationLinks are also used to consider movement shortcuts in pathfinding available through 
+NavigationLinks are also used to consider movement shortcuts in pathfinding available through
 interacting with gameplay objects e.g. ladders, jump pads or teleports.
 
-2D and 3D versions of NavigationJumplinks nodes are available as 
-:ref:`NavigationLink2D<class_NavigationLink2D>` and 
+2D and 3D versions of NavigationJumplinks nodes are available as
+:ref:`NavigationLink2D<class_NavigationLink2D>` and
 :ref:`NavigationLink3D<class_NavigationLink3D>` respectively.
 
-Different NavigationRegions can connect their navigation meshes without the need for a NavigationLink 
+Different NavigationRegions can connect their navigation meshes without the need for a NavigationLink
 as long as they are within navigation map ``edge_connection_margin`` and have compatible ``navigation_layers``.
 As soon as the distance becomes too large, building valid connections becomes a problem - a problem that NavigationLinks can solve.
 
@@ -25,17 +25,17 @@ See :ref:`doc_navigation_connecting_navmesh` to learn more about how to connect
 .. image:: img/nav_link_properties.png
 
 NavigationLinks share many properties with NavigationRegions like ``navigation_layers``.
-NavigationLinks add a single connection between two positions over an arbitrary distance 
+NavigationLinks add a single connection between two positions over an arbitrary distance
 compared to NavigationRegions that add a more local traversable area with a navigation mesh resource.
 
 NavigationLinks have a ``start_position`` and ``end_position`` and can go in both directions when ``bidirectional`` is enabled.
 When placed a navigationlink connects the navigation mesh polygons closest to its ``start_position`` and ``end_position`` within search radius for pathfinding.
 
-The polygon search radius can be configured globally in the ProjectSettings under ``navigation/2d_or_3d/default_link_connection_radius`` 
-or set for each navigation ``map`` individually using the ``NavigationServer.map_set_link_connection_radius()`` function.
+The polygon search radius can be configured globally in the ProjectSettings under ``navigation/2d_or_3d/default_link_connection_radius``
+or set for each navigation **map** individually using the ``NavigationServer.map_set_link_connection_radius()`` function.
 
 Both ``start_position`` and ``end_position`` have debug markers in the Editor.
-The visible radius of a position shows the polygon search radius. 
+The visible radius of a position shows the polygon search radius.
 All navigation mesh polygons inside are compared and the closest is picked for the edge connection.
 If no valid polygon is found within the search radius the navigation link gets disabled.
 
@@ -48,6 +48,6 @@ The visibility of the debug can also be controlled in the Editor 3D Viewport giz
 
     NavigationLinks do not move agents between the two link positions by themselves.
 
-A navigation link does not provide any automated movement through the link. Instead, when 
-an agent reaches the position of a link, game code needs to react (e.g. through area triggers) and provide means for the agent 
+A navigation link does not provide any automated movement through the link. Instead, when
+an agent reaches the position of a link, game code needs to react (e.g. through area triggers) and provide means for the agent
 to move through the link to end up at the links other position (e.g. through teleport or animation) to continue along the path.

tutorials/navigation/navigation_using_navigationmaps.rst

@@ -21,9 +21,9 @@ Default navigation maps
 
 By default Godot creates a navigation map for each :ref:`World2D<class_World2D>` and :ref:`World3D<class_World3D>` of the root viewport.
 
-The 2D default navigation ``map`` RID can be obtained with ``get_world_2d().get_navigation_map()`` from any :ref:`Node2D<class_Node2D>` inheriting Node.
+The 2D default navigation map RID can be obtained with ``get_world_2d().get_navigation_map()`` from any :ref:`Node2D<class_Node2D>` inheriting Node.
 
-The 3D default navigation ``map`` RID can be obtained with ``get_world_3d().get_navigation_map()`` from any :ref:`Node3D<class_Node3D>` inheriting Node.
+The 3D default navigation map RID can be obtained with ``get_world_3d().get_navigation_map()`` from any :ref:`Node3D<class_Node3D>` inheriting Node.
 
 .. tabs::
  .. code-tab:: gdscript GDScript

tutorials/navigation/navigation_using_navigationmeshes.rst

@@ -30,7 +30,7 @@ that appear in the top bar of the editor when a NavigationRegion2D is selected.
 
 .. image:: img/nav_polydrawtool.png
 
-The NavigationPolygon draw tools can be used to create and edit navigation meshes by defining ``outline`` polygons.
+The NavigationPolygon draw tools can be used to create and edit navigation meshes by defining **outline** polygons.
 The outline polygons are later converted to real navigation mesh resources for the NavigationServer regions.
 
 .. image:: img/nav_polymatroschka.png

tutorials/navigation/navigation_using_navigationpaths.rst

@@ -16,7 +16,7 @@ To obtain a 3D path, use ``NavigationServer3D.map_get_path(map, from, to, optimi
 For more customizable navigation path queries that require additional setup see :ref:`doc_navigation_using_navigationpathqueryobjects`.
 
 One of the required parameters for the query is the RID of the navigation map.
-Each game ``World`` has a default navigation map automatically created.
+Each game world has a default navigation map automatically created.
 The default navigation maps can be retrieved with ``get_world_2d().get_navigation_map()`` from
 any Node2D inheriting node or ``get_world_3d().get_navigation_map()`` from any Node3D inheriting node.
 The second and third parameters are the starting position and the target position as Vector2 for 2D or Vector3 for 3D.

tutorials/navigation/navigation_using_navigationregions.rst

@@ -3,7 +3,7 @@
 Using NavigationRegions
 =======================
 
-NavigationRegions are the visual Node representation of a ``region`` of the navigation ``map`` on the NavigationServer.
+NavigationRegions are the visual Node representation of a **region** of the navigation **map** on the NavigationServer.
 Each NavigationRegion node holds a resource for the navigation mesh data.
 
 Both 2D and 3D version are available as :ref:`NavigationRegion2D<class_NavigationRegion2D>`