|
@@ -18,30 +18,30 @@ To work with the NavigationServer means to prepare parameters for a ``query`` th
|
|
|
To reference the internal NavigationServer objects like maps, regions and agents RIDs are used as identification numbers.
|
|
|
Every navigation related node in the SceneTree has a function that returns the RID for this node.
|
|
|
|
|
|
-Threading and Synchronisation
|
|
|
+Threading and Synchronization
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
The NavigationServer does not update every change immediately but waits until
|
|
|
-the end of the ``physics_frame`` to synchronise all the changes together.
|
|
|
+the end of the ``physics_frame`` to synchronize all the changes together.
|
|
|
|
|
|
-Waiting for synchronisation is required to apply changes to all maps, regions and agents.
|
|
|
-Synchronisation is done because some updates like a recalculation of the entire navigation map are very expensive and require updated data from all other objects.
|
|
|
+Waiting for synchronization is required to apply changes to all maps, regions and agents.
|
|
|
+Synchronization is done because some updates like a recalculation of the entire navigation map are very expensive and require updated data from all other objects.
|
|
|
Also the NavigationServer uses a ``threadpool`` by default for some functionality like avoidance calculation between agents.
|
|
|
|
|
|
Waiting is not required for most ``get()`` functions that only request data from the NavigationServer without making changes.
|
|
|
Note that not all data will account for changes made in the same frame.
|
|
|
-E.g. if an avoidance ``agent`` changed the navigation ``map`` this frame the ``agent_get_map()`` function will still return the old map before the synchronisation.
|
|
|
+E.g. if an avoidance ``agent`` changed the navigation ``map`` this frame the ``agent_get_map()`` function will still return the old map before the synchronization.
|
|
|
The exception to this are nodes that store their values internally before sending the update to the NavigationServer.
|
|
|
When a getter on a node is used for a value that was updated in the same frame it will return the already updated value stored on the node.
|
|
|
|
|
|
-The NavigationServer is ``thread-safe`` as it places all API calls that want to make changes in a queue to be executed in the synchronisation phase.
|
|
|
-Synchronisation for the NavigationServer happens in the middle of the physics frame after scene input from scripts and nodes are all done.
|
|
|
+The NavigationServer is ``thread-safe`` as it places all API calls that want to make changes in a queue to be executed in the synchronization phase.
|
|
|
+Synchronization for the NavigationServer happens in the middle of the physics frame after scene input from scripts and nodes are all done.
|
|
|
|
|
|
.. note::
|
|
|
The important takeaway is that most NavigationServer changes take effect after the next physics frame and not immediately.
|
|
|
This includes all changes made by navigation related nodes in the SceneTree or through scripts.
|
|
|
|
|
|
-The following functions will be executed in the synchronisation phase only:
|
|
|
+The following functions will be executed in the synchronization phase only:
|
|
|
|
|
|
- map_set_active()
|
|
|
- map_set_up()
|
|
@@ -97,7 +97,7 @@ as well and both 2D and 3D avoidance agents can exist on the same map.
|
|
|
.. warning::
|
|
|
It is not possible to use NavigationServer2D while disabling 3D on a Godot custom build.
|
|
|
|
|
|
-Waiting for synchronisation
|
|
|
+Waiting for synchronization
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
At the start of the game, a new scene or procedural navigation changes any path query to a NavigationServer will return empty or wrong.
|
|
@@ -105,7 +105,7 @@ At the start of the game, a new scene or procedural navigation changes any path
|
|
|
The navigation map is still empty or not updated at this point.
|
|
|
All nodes from the SceneTree need to first upload their navigation related data to the NavigationServer.
|
|
|
Each added or changed map, region or agent need to be registered with the NavigationServer.
|
|
|
-Afterward the NavigationServer requires a ``physics_frame`` for synchronisation to update the maps, regions and agents.
|
|
|
+Afterward the NavigationServer requires a ``physics_frame`` for synchronization to update the maps, regions and agents.
|
|
|
|
|
|
One workaround is to make a deferred call to a custom setup function (so all nodes are ready).
|
|
|
The setup function makes all the navigation changes, e.g. adding procedural stuff.
|
|
@@ -167,7 +167,7 @@ Server Avoidance Callbacks
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
If RVO avoidance agents are registered for avoidance callbacks the NavigationServer dispatches
|
|
|
-their ``safe_velocity`` signals just before the PhysicsServer synchronisation.
|
|
|
+their ``safe_velocity`` signals just before the PhysicsServer synchronization.
|
|
|
|
|
|
To learn more about NavigationAgents see :ref:`doc_navigation_using_navigationagents`.
|
|
|
To learn more about RVO Avoidance see :ref:`doc_navigation_using_agent_avoidance`.
|
|
@@ -178,11 +178,11 @@ The simplified order of execution for NavigationAgents that use avoidance:
|
|
|
- _physics_process(delta).
|
|
|
- set_velocity() on NavigationAgent Node.
|
|
|
- Agent sends velocity and position to NavigationServer.
|
|
|
-- NavigationServer waits for synchronisation.
|
|
|
-- NavigationServer synchronises and computes avoidance velocities for all registered avoidance agents.
|
|
|
+- NavigationServer waits for synchronization.
|
|
|
+- NavigationServer synchronizes and computes avoidance velocities for all registered avoidance agents.
|
|
|
- NavigationServer sends safe_velocity vector with signals for each registered avoidance agents.
|
|
|
- Agents receive the signal and move their parent e.g. with move_and_slide or linear_velocity.
|
|
|
-- PhysicsServer synchronises.
|
|
|
+- PhysicsServer synchronizes.
|
|
|
- physics frame ends.
|
|
|
|
|
|
Therefore moving a physicsbody actor in the callback function with the safe_velocity is perfectly thread- and physics-safe
|