Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

使用 NavigationServer

NavigationServer 即导航服务器。2D 和 3D 版本的 NavigationServer 分别为 NavigationServer2DNavigationServer3D

2D 和 3D 使用的 NavigationServer 是一样的,NavigationServer3D 是主要服务器。NavigationServer2D 只是一个前端,会进行 2D 位置和 3D 位置的相互转换。因此,完全可以只用 NavigationServer3D 的 API 来实现 2D 导航(就是会有点繁琐)。

与 NavigationServer 通信

To work with the NavigationServer means to prepare parameters for a query that can be sent to the NavigationServer for updates or requesting data.

To reference the internal NavigationServer objects like maps, regions and agents RIDs are used as identification numbers. Every navigation related node in the scene tree has a function that returns the RID for this node.


The NavigationServer does not update every change immediately but waits until the end of the physics frame to synchronize all the changes together.

Waiting for synchronization is required to apply changes to all maps, regions and agents. Synchronization is done because some updates like a recalculation of the entire navigation map are very expensive and require updated data from all other objects. Also the NavigationServer uses a threadpool by default for some functionality like avoidance calculation between agents.

Waiting is not required for most get() functions that only request data from the NavigationServer without making changes. Note that not all data will account for changes made in the same frame. E.g. if an avoidance agent changed the navigation map this frame the agent_get_map() function will still return the old map before the synchronization. The exception to this are nodes that store their values internally before sending the update to the NavigationServer. When a getter on a node is used for a value that was updated in the same frame it will return the already updated value stored on the node.

The NavigationServer is thread-safe as it places all API calls that want to make changes in a queue to be executed in the synchronization phase. Synchronization for the NavigationServer happens in the middle of the physics frame after scene input from scripts and nodes are all done.


The important takeaway is that most NavigationServer changes take effect after the next physics frame and not immediately. This includes all changes made by navigation related nodes in the scene tree or through scripts.


All setters and delete functions require synchronization.

2D 和 3D NavigationServer 的区别

NavigationServer2D 和 NavigationServer3D 在各自维度中的功能是等价的,底层使用的相同的 NavigationServer。