Up to date
This page is up to date for Godot 4.0.
If you still find outdated information, please open an issue.
NavigationServer3D¶
Inherits: Object
Server interface for low-level 3D navigation access.
Description¶
NavigationServer3D is the server responsible for all 3D navigation. It handles several objects, namely maps, regions and agents.
Maps are made up of regions, which are made of navigation meshes. Together, they define the navigable areas in the 3D 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 3D 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 and 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.
Enumerations¶
enum ProcessInfo:
ProcessInfo INFO_ACTIVE_MAPS = 0
Constant to get the number of active navigation maps.
ProcessInfo INFO_REGION_COUNT = 1
Constant to get the number of active navigation regions.
ProcessInfo INFO_AGENT_COUNT = 2
Constant to get the number of active navigation agents processing avoidance.
ProcessInfo INFO_LINK_COUNT = 3
Constant to get the number of active navigation links.
ProcessInfo INFO_POLYGON_COUNT = 4
Constant to get the number of navigation mesh polygons.
ProcessInfo INFO_EDGE_COUNT = 5
Constant to get the number of navigation mesh polygon edges.
ProcessInfo INFO_EDGE_MERGE_COUNT = 6
Constant to get the number of navigation mesh polygon edges that were merged due to edge key overlap.
ProcessInfo INFO_EDGE_CONNECTION_COUNT = 7
Constant to get the number of navigation mesh polygon edges that are considered connected by edge proximity.
ProcessInfo INFO_EDGE_FREE_COUNT = 8
Constant to get the number of navigation mesh polygon edges that could not be merged but may be still connected by edge proximity or with links.
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, Vector3 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, Vector3 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, Vector3 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.
int get_process_info ( ProcessInfo process_info ) const
Returns information about the current state of the NavigationServer. See ProcessInfo for a list of available states.
RID link_create ( )
Create a new link between two positions on a map.
Vector3 link_get_end_position