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 to facilitate common calls to the NavigationServer API on behalf of the parent actor node in a more convenient manner for beginners.
NavigationsAgents are entirely optional for navigation pathfinding. The functionality of NavigationsAgents can be recreated with scripts and direct calls to the NavigationServer API. If the default NavigationsAgent does not do what you want for your game feel free to design your own NavigationsAgent with scripts.
NavigationsAgent nodes and NavigationServer
agents are not the same.
The later is an RVO avoidance agent and solely used for avoidance.
RVO avoidance agents are not involved in regular pathfinding.
To use NavigationAgents for pathfinding, place a NavigationAgent2D/3D Node below a Node2D/3D inheriting parent node.
To have the agent query a path to a target position use the
Once the target has been set, the next position to follow in the path
can be retrieved with the
get_next_path_position() function. Move the parent actor node
to this position with your own movement code. On the next
get_next_path_position() again for the next position and repeat this until the path ends.
NavigationAgents have their own internal logic to proceed with the current path and call for updates.
NavigationAgents recognize by distance when a path point or the final target is reached.
NavigationAgents refresh a path automatically when too far away from the current pathpoint.
The important updates are all triggered with the
when called in
Be careful calling other NavigationAgent functions not required for path movement while the actor is following a path, as many function trigger a full path refresh.
New NavigationAgents will automatically join the default navigation map for their 2D/3D dimension.
Resetting the path every frame (by accident) might get the actor to stutter or spin around in place.
The important restriction for non-physics characters is that the NavigationAgent node only accepts a single update each
physics_frame as further updates will be blocked.
If a NavigationAgent is used with
_process() at high framerate make sure to accumulate the values of multiple frames and call the NavigationAgent function only once each