Up to date
This page is up to date for Godot 4.1.
If you still find outdated information, please open an issue.
NavigationServer2D¶
Inherits: Object
A server interface for low-level 2D navigation access.
Description¶
NavigationServer2D is the server that handles navigation maps, regions and agents. It does not handle A* navigation from AStar2D or AStarGrid2D.
Maps are made up of regions, which are made of navigation polygons. Together, they define the traversable areas in the 2D world.
Note: Most NavigationServer2D 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 scene tree 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 can be used to allow or deny certain areas for some 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 directly may move an agent outside of the traversable 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.
bool agent_get_avoidance_enabled ( RID agent ) const
Return true if the specified agent uses avoidance.
RID agent_get_map ( RID agent ) const
Returns the navigation map RID the requested agent is currently assigned to.
bool agent_get_paused ( RID agent ) const
Returns true if the specified agent is paused.
bool agent_is_map_changed ( RID agent ) const
Returns true if the map got changed the previous frame.
void agent_set_avoidance_callback ( RID agent, Callable callback )
Sets the callback Callable that gets called after each avoidance processing step for the agent. The calculated safe_velocity will be dispatched with a signal to the object 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_avoidance_callback again with an empty Callable.
void agent_set_avoidance_enabled ( RID agent, bool enabled )
If enabled is true the specified agent uses avoidance.
void agent_set_avoidance_layers ( RID agent, int layers )
Set the agent's avoidance_layers bitmask.
void agent_set_avoidance_mask ( RID agent, int mask )
Set the agent's avoidance_mask bitmask.
void agent_set_avoidance_priority ( RID agent, float priority )
Set the agent's avoidance_priority with a priority between 0.0 (lowest priority) to 1.0 (highest priority).
The specified agent does not adjust the velocity for other agents that would match the avoidance_mask but have a lower `` avoidance_priority``. This in turn makes the other agents with lower priority adjust their velocities even more to avoid collision with this agent.
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,