Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

Using NavigationAgents

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.

2D and 3D version of NavigationAgents are available as NavigationAgent2D and NavigationAgent3D respectively.

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.

Warning

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.

NavigationAgent 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 set_target_position() method. 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 physics_frame, call 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 get_next_path_position() function when called in _physics_process().

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.

Note

New NavigationAgents will automatically join the default navigation map for their 2D/3D dimension.

Warning

Resetting the path every frame (by accident) might get the actor to stutter or spin around in place.

NavigationAgents were designed with _physics_process() in mind to keep in sync with both NavigationServer3D and PhysicsServer3D.

They work well out of the box with CharacterBody2D and CharacterBody3D as well as any rigid bodies.

Warning

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.

Warning

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 physics_frame.

NavigationAgent Avoidance

This section explains how to use the built-in avoidance specific to NavigationAgent nodes. For general avoidance use and more technical details on RVO avoidance see