Up to date
This page is up to date for Godot 4.0.
If you still find outdated information, please open an issue.
NavigationServer2D¶
Inherits: Object
Server interface for low-level 2D navigation access.
Description¶
NavigationServer2D is the server responsible for all 2D navigation. It handles several objects, namely maps, regions and agents.
Maps are made up of regions, which are made of navigation polygons. Together, they define the navigable areas in the 2D world.
Note: Most NavigationServer changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation related Nodes in the SceneTree or made through scripts.
For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than edge_connection_margin to the respective other edge's vertex.
You may assign navigation layers to regions with region_set_navigation_layers, which then can be checked upon when requesting a path with map_get_path. This allows allowing or forbidding some areas to 2D objects.
To use the collision avoidance system, you may use agents. You can set an agent's target velocity, then the servers will emit a callback with a modified velocity.
Note: The collision avoidance system ignores regions. Using the modified velocity as-is might lead to pushing an agent outside of a navigable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine.
This server keeps tracks of any call and executes them during the sync phase. This means that you can request any change to the map, using any thread, without worrying.
Tutorials¶
Methods¶
Signals¶
map_changed ( RID map )
Emitted when a navigation map is updated, when a region moves or is modified.
navigation_debug_changed ( )
Emitted when navigation debug settings are changed. Only available in debug builds.
Method Descriptions¶
RID agent_create ( )
Creates the agent.
RID agent_get_map ( RID agent ) const
Returns the navigation map RID the requested agent is currently assigned to.
bool agent_is_map_changed ( RID agent ) const
Returns true if the map got changed the previous frame.
void agent_set_callback ( RID agent, Callable callback )
Sets the callback that gets called after each avoidance processing step for the agent. The calculated safe_velocity will be passed as the first parameter just before the physics calculations.
Note: Created callbacks are always processed independently of the SceneTree state as long as the agent is on a navigation map and not freed. To disable the dispatch of a callback from an agent use agent_set_callback again with an empty Callable.
void agent_set_map ( RID agent, RID map )
Puts the agent in the map.
void agent_set_max_neighbors ( RID agent, int count )
Sets the maximum number of other agents the agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe.
void agent_set_max_speed ( RID agent, float max_speed )
Sets the maximum speed of the agent. Must be positive.
void agent_set_neighbor_distance ( RID agent, float distance )
Sets the maximum distance to other agents this agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe.
void agent_set_position ( RID agent, Vector2 position )
Sets the position of the agent in world space.
void agent_set_radius ( RID agent, float radius )
Sets the radius of the agent.
void agent_set_target_velocity ( RID agent, Vector2 target_velocity )
Sets the new target velocity.
void agent_set_time_horizon ( RID agent, float time )
The minimal amount of time for which the agent's velocities that are computed by the simulation are safe with respect to other agents. The larger this number, the sooner this agent will respond to the presence of other agents, but the less freedom this agent has in choosing its velocities. Must be positive.
void agent_set_velocity ( RID agent, Vector2 velocity )
Sets the current velocity of the agent.
void free_rid ( RID rid )
Destroys the given RID.
bool get_debug_enabled ( ) const
Returns true when the NavigationServer has debug enabled.
RID[] get_maps ( ) const
Returns all created navigation map RIDs on the NavigationServer. This returns both 2D and 3D created navigation maps as there is technically no distinction between them.
RID link_create ( )
Create a new link between two positions on a map.
Vector2 link_get_end_position ( RID link ) const
Returns the ending position of this link.
float link_get_enter_cost ( RID link ) const
Returns the enter cost of this link.
RID link_get_map ( RID link ) const
Returns the navigation map RID the requested link is currently assigned to.
int link_get_navigation_layers ( RID link ) const
Returns the navigation layers for this link.
int link_get_owner_id ( RID link ) const
Returns the ObjectID of the object which manages this link.
Vector2 link_get_start_position ( RID link ) const
Returns the starting position of this link.
float link_get_travel_cost ( RID link ) const
Returns the travel cost of this link.
bool link_is_bidirectional ( RID link ) const
Returns whether this link can be travelled in both directions.
void link_set_bidirectional ( RID link, bool bidirectional )
Sets whether this link can be travelled in both directions.
void link_set_end_position ( RID link, Vector2 position )
Sets the exit position for the link.
void link_set_enter_cost ( RID link, float enter_cost )
Sets the enter_cost for this link.
void link_set_map ( RID link, RID map )
Sets the navigation map RID for the link.
void link_set_navigation_layers ( RID link, int navigation_layers )
Set the links's navigation layers. This allows selecting links from a path request (when using map_get_path).
void link_set_owner_id ( RID link, int owner_id )
Set the ObjectID of the object which manages this link.
void link_set_start_position (