Up to date
This page is up to date for Godot
If you still find outdated information, please open an issue.
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 behalf of the parent actor node in a more convenient manner for beginners.
New NavigationAgent nodes will automatically join the default navigation map on the World2D/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.
NavigationAgents query a new navigation path on their current navigation map when their
target_position is set with a global position.
The result of the pathfinding can be influenced with the following properties.
navigation_layersbitmask can be used to limit the navigation meshes that the agent can use.
pathfinding_algorithmcontrols how the pathfinding travels through the navigation mesh polygons in the path search.
path_postprocessingsets if or how the raw path corridor found by the pathfinding is altered before it is returned.
path_metadata_flagsenable the collection of additional path point meta data returned by the path.
Disabling path meta flags will disable related signal emissions on the agent.
target_position has been set for the agent, the next position to follow in the path
can be retrieved with the
Once the next path position is received move the parent actor node of the agent towards this path position with your own movement code.
The navigation system never moves the parent node of a NavigationAgent. The movement is entirely in the hands of users and their custom scripts.
NavigationAgents have their own internal logic to proceed with the current path and call for updates.
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
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.
The following properties influence the path following behavior.
path_desired_distancedefines the distance at which the agent advances its internal path index to the next path position.
target_desired_distancedefines the distance at which the agent considers the target position to be reached and the path at its end.
path_max_distancedefines when an agent requests a new path cause it was moved too far away from the current path point segment.
The important updates are all triggered with the
when called in
NavigationAgents can be used with
process but are still limited to a single update that happens in
Script examples for various nodes commonly used with NavigationAgents can be found further below.
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.
- 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.
- The agent is backtracking sometimes
If an agent moves very fast it might overshoot the path_desired_distance check without ever advancing the path index. This can lead to the agent backtracking to the path point now behind it until it passes the distance check to increase the path index. Increase the desired distances accordingly for your agent speed and update rate usually fixes this as well as a more balanced navigation mesh polygon layout with not too many polygon edges cramped together in small spaces.
- The agent is sometimes looking backwards for a frame
Same as with stuck dancing agents between two positions, this is usually caused by very frequent path updates every single frame. Depending on your navigation mesh layout, and especially when an agent is directly placed over a navigation mesh edge or edge connection, expect path positions to be sometimes slightly "behind" your actors current orientation. This happens due to precision issues and can not always be avoided. This is usually only a visible problem if actors are instantly rotated to face the current path position.
This section explains how to use the navigation avoidance specific to NavigationAgents.
In order for NavigationAgents to use the avoidance feature the
enable_avoidance property must be set to
The velocity_computed signal of the NavigationAgent node must be connected to receive the
safe_velocity calculation result.
set_velocity() on the NavigationAgent node in
_physics_process() to update the agent with the current velocity of the agent's parent node.
While avoidance is enabled on the agent the
safe_velocity vector will be received with the velocity_computed signal every physics frame.
This velocity vector should be used to move the NavigationAgent's parent node in order to avoidance collision with other avoidance using agents or avoidance obstacles.
Only other agents on the same map that are registered for avoidance themself will be considered in the avoidance calculation.
The following NavigationAgent properties are relevant for avoidance:
heightis available in 3D only. The height together with the current global y-axis position of the agent determines the vertical placement of the agent in the avoidance simulation. Agents using the 2D avoidance will automatically ignore other agents or obstacles that are below or above them.
radiuscontrols the size of the avoidance circle, or in case of 3D sphere, around the agent. This area describes the agents body and not the avoidance maneuver distance.
neighbor_distancecontrols the search radius of the agent when searching for other agents that should be avoided. A lower value reduces processing cost.
max_neighborscontrols how many other agents are considered in the avoidance cal