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.
Checking the stable version of the documentation...
NavigationServer2D¶
继承： Object
用于访问低阶 2D 导航的服务器接口。
描述¶
NavigationServer2D 是负责处理导航地图、区块、代理的服务器。不负责处理 AStar2D 和 AStarGrid2D 的 A* 导航。
地图由区块组成，区块由导航多边形组成。它们共同定义了 2D 空间中的可达区域。
注意：大多数 NavigationServer2D 的更改都是在下一个物理帧进行的，不会立即生效。包括所有对地图、区块、代理的更改，无论是通过场景树中导航相关的节点作出的更改，还是通过脚本作出的更改。
两个区块必须共享一条相似的边才能相连。如果一条边的两个顶点与另一条边上相应顶点的距离都小于 edge_connection_margin，那么就会认为这两条边是相连的。
可以使用 region_set_navigation_layers 为区块分配导航层，使用 map_get_path 请求路径时会对导航层进行检查。可用于允许或禁止某些对象进入特定的区域。
使用碰撞躲避系统就需要使用代理。你可以为代理设置目标速度，然后服务器就会发出回调，提供修改后的速度。
注意：碰撞躲避系统并不考虑区块。直接使用修改后的速度可能会将代理移动到可达区域之外。这是碰撞躲避系统的缺陷，更复杂的场合可能需要使用物理引擎。
服务器会对所有调用进行跟踪，并在同步阶段执行。这意味着你可以放心地从任何线程请求对地图作出任何修改。
教程¶
方法¶
信号¶
map_changed ( RID map )
当导航地图更新时、地区移动或被修改时发出。
navigation_debug_changed ( )
当导航调试设置更改时发出。仅在调试版本中可用。
方法说明¶
RID agent_create ( )
创建代理。
bool agent_get_avoidance_enabled ( RID agent ) const
如果指定的 agent 使用避障，则返回 true。
RID agent_get_map ( RID agent ) const
返回请求 agent 目前分配到的导航地图 RID。
bool agent_get_paused ( RID agent ) const
如果指定的 agent 处于暂停状态，则返回 true。
bool agent_is_map_changed ( RID agent ) const
如果该地图在上一帧发生了改变，则返回 true。
void agent_set_avoidance_callback ( RID agent, Callable callback )
设置在 agent 的每个避障处理步骤之后调用的回调 Callable。计算出的 safe_velocity 将在物理计算之前通过信号发送。
注意：只要代理还在导航地图上且未被释放，创建的回调就会始终独立于 SceneTree 状态进行处理。要为某个代理禁用回调的发送，请再次使用一个空的 Callable 来调用 agent_set_avoidance_callback。
void agent_set_avoidance_enabled ( RID agent, bool enabled )
如果 enabled 为 true，则指定的 agent 使用避障。
void agent_set_avoidance_layers ( RID agent, int layers )
设置该代理的 avoidance_layers 位掩码。
void agent_set_avoidance_mask ( RID agent, int mask )
设置该代理的 avoidance_mask 位掩码。
void agent_set_avoidance_priority ( RID agent, float priority )
设置该代理的 avoidance_priority，优先级 priority 在 0.0（最低优先级）到 1.0（最高优先级）之间。
agent 指定的代理不会针对 avoidance_mask 存在匹配但 `` avoidance_priority`` 更低的代理调整速度。相应地，优先级更低的代理则会对其速度进行更大的调整，从而避免与这个代理发生碰撞。
void agent_set_map ( RID agent, RID map )
将代理放入地图中。
void agent_set_max_neighbors ( RID agent, int count )
设置在导航中，该代理所考虑的其他代理的最大数量。这个数越大，模拟的运行时间越长。如果这个数太小，则模拟会不安全。
void agent_set_max_speed ( RID agent, float max_speed )
设置该代理的最大速度。必须为正数。
void agent_set_neighbor_distance ( RID agent, float distance )
设置在导航中，该代理所考虑的其他代理的最大距离。这个数越大，模拟的运行时间越长。如果这个数太小，则模拟会不安全。
void agent_set_paused ( RID agent, bool paused )
如果 paused 为 true，则不会对指定的 agent 进行处理，例如计算避障速度以及收到避障回调。
void agent_set_position ( RID agent, Vector2 position )
设置该代理在世界空间中的位置。
void agent_set_radius ( RID agent, float radius )
设置该代理的半径。
void agent_set_time_horizon_agents ( RID agent, float time_horizon )
考虑其他代理的前提下，该代理的速度的最短安全时间，这个速度是通过仿真得到的。数值越大，代理响应其他代理的速度就越快，但该代理选择速度的自由度也就越小。太高的取值会大大降低代理的移动速度。必须为正数。
void agent_set_time_horizon_obstacles ( RID agent, float time_horizon )
考虑其他静态避障障碍物的前提下，该代理的速度的最短安全时间，这个速度是通过仿真得到的。数值越大，代理响应存在的静态避障障碍物的速度就越快，但该代理选择速度的自由度也就越小。太高的取值会大大降低代理的移动速度。必须为正数。
void agent_set_velocity ( RID agent, Vector2 velocity )
将 velocity 设置为指定代理 agent 的新的需求速度。避障仿真会尽可能尝试满足这个速度，但为了躲避与其他代理和障碍物的碰撞也会对它进行修改。将代理传送至新的较远的位置时，请改用 agent_set_velocity_forced 重置内部速度状态。
void agent_set_velocity_forced ( RID agent, Vector2 velocity )
将指定代理 agent 的避障仿真内部速度替换为 velocity。将代理传送至新的较远的位置时，应该在同一帧里使用这个函数。频繁调用这个函数可能让代理卡住。
void bake_from_source_geometry_data ( NavigationPolygon navigation_polygon, NavigationMeshSourceGeometryData2D source_geometry_data, Callable callback=Callable() )
使用提供的 source_geometry_data 中的数据烘焙提供的 navigation_polygon。该过程完成后，将调用可选的 callback。
void bake_from_source_geometry_data_async ( NavigationPolygon navigation_polygon, NavigationMeshSourceGeometryData2D source_geometry_data, Callable callback=Callable() )
使用提供的 source_geometry_data 中的数据烘焙提供的 navigation_polygon，并作为在后台线程上运行的异步任务。该过程完成后，将调用可选的 callback。
void free_rid ( RID rid )
销毁给定的 RID。
bool get_debug_enabled ( ) const
如果该 NavigationServer 启用了调试，则返回 true。
RID[] get_maps ( ) const
返回该 NavigationServer 上所有已创建的导航地图的 RID。会同时返回已创建的 2D 和 3D 导航地图，因为理论上它们之间是没有区别的。
RID link_create ( )
在地图上新建两个地点之间的链接。
bool link_get_enabled ( RID link ) const
如果指定的 link 已启用，则返回 true。
Vector2 link_get_end_position ( RID link ) const
返回链接 link 的结束位置。
float link_get_enter_cost ( RID link ) const
返回 link 链接的进入消耗。
RID link_get_map ( RID link ) const
返回请求的导航链接 link 当前分配的导航地图的 RID。
int link_get_navigation_layers ( RID link ) const
返回 link 的导航层。
int link_get_owner_id ( RID link ) const
返回管理该链接的对象的 ObjectID。
Vector2 link_get_start_position ( RID link ) const
返回 link 链接的入口位置。
float link_get_travel_cost ( RID link ) const
返回 link 链接的移动消耗。
bool link_is_bidirectional ( RID link ) const
返回该 link 是否能够双向通行。
void link_set_bidirectional ( RID link, bool bidirectional )
设置该 link 是否能够双向通行。
void link_set_enabled ( RID link, bool enabled )
如果 enabled 为 true，则指定的 link 会在它的当前导航地图中生效。
void link_set_end_position ( RID link, Vector2 position )
设置 link 的出口位置。
void link_set_enter_cost ( RID link, float enter_cost )
设置 link 的进入消耗 enter_cost。
void link_set_map ( RID link, RID map )
设置该链接的导航地图 RID。
void link_set_navigation_layers ( RID link, int navigation_layers )
设置该链接的导航层。可以在（使用 map_get_path）进行路径请求时选择链接。
void link_set_owner_id ( RID link, int owner_id )
设置管理该链接的对象的 ObjectID。
void link_set_start_position ( RID link, Vector2 position )
设置 link 的入口位置。
void link_set_travel_cost ( RID link, float travel_cost )
设置 link 的移动消耗 travel_cost。
RID map_create ( )
创建一张新地图。
void map_force_update ( RID map )
该函数将立即强制指定的导航 map RID 的同步。默认情况下，导航地图仅在每个物理帧结束时同步。该函数可用于立即（重新）计算该导航地图的所有导航网格和区块连接。这使得可以在同一帧中对修改后的地图的导航路径立即执行查询（如果需要，可以执行多次）。
由于技术上的限制，当前的 NavigationServer 命令队列将被冲刷。这意味着所有已在当前物理帧中入队的更新命令都会被执行，即使是那些用于其他地图、不属于指定地图的区块和代理的更新命令。 昂贵计算的导航网格和地图的区块连接将仅针对指定地图进行。其他地图将在物理帧结束时接收正常同步。如果指定的地图在强制更新后又收到了修改，则它将在其他地图收到更新时再次更新。
避障处理和 safe_velocity 信号的分发不受该函数影响，仍继续发生在物理帧结束时的所有地图和代理上。
注意：能力越大，责任越大。该函数仅该用于用户真正知道自己在做什么并且有充分理由的情况。强制立即更新导航地图需要锁定 NavigationServer 并冲刷整个 NavigationServer 命令队列。这不仅会严重影响游戏的性能，而且如果缺乏远见且使用不当，还会引入 bug。
RID[] map_get_agents ( RID map ) const
返回所有与请求的导航地图 map 关联的导航代理的 RID。
float map_get_cell_size ( RID map ) const
返回地图的单元格大小，用于将导航网格的顶点进行栅格化。
Vector2 map_get_closest_point ( RID map, Vector2 to_point ) const
返回导航网格表面上与提供的 to_point 距离最近的点。
RID map_get_closest_point_owner ( RID map, Vector2 to_point ) const
返回由 map_get_closest_point 返回的点的所有者地区的 RID。
float map_get_edge_connection_margin ( RID map ) const
返回地图的边界连接边距。边界连接边距是用于连接两个地区的距离。
float map_get_link_connection_radius ( RID map ) const
返回该地图的链接连接半径。该距离是任何链接将搜索要连接的导航网格多边形的最大范围。
RID[] map_get_links ( RID map ) const
返回当前分配给请求的导航地图 map 的所有导航链接的 RID。
RID[] map_get_obstacles ( RID map ) const
返回当前分配给请求的导航地图 map 的所有导航障碍物的 RID。
PackedVector2Array map_get_path ( RID map, Vector2 origin, Vector2 destination, bool optimize, int navigation_layers=1 ) const
返回从原点到达目的地的导航路径。navigation_layers 是被允许在路径中的所有区块导航层的位掩码。
RID[] map_get_regions ( RID map ) const
返回当前分配给所请求的导航 map 的所有导航区块的 RID。
bool map_get_use_edge_connections ( RID map ) const
返回是否允许导航地图 map 使用边缘连接与位于导航地图边缘连接边距范围内的其他导航区块相连接。
bool map_is_active ( RID map ) const
如果地图处于活动状态，则返回 true。
void map_set_active ( RID map, bool active )
设置地图的激活态。
void map_set_cell_size ( RID map, float cell_size )
设置用于栅格化导航网格顶点的地图单元格大小。必须与所使用的导航网格单元格大小相匹配。
void map_set_edge_connection_margin ( RID map, float margin )
设置用于焊接兼容地区边界的地图边界连接边距。
void map_set_link_connection_radius ( RID map, float radius )
设置该地图用于连接链接和导航多边形的链接连接半径。
void map_set_use_edge_connections ( RID map, bool enabled )
设置导航地图 map 的边缘连接使用情况。如果 enabled 为 true，则导航地图允许导航区块使用边缘连接与位于导航地图边缘连接边距范围内的其他导航区块相连接。
RID obstacle_create ( )
新建导航障碍物。
bool obstacle_get_avoidance_enabled ( RID obstacle ) const
如果给定的 obstacle 启用了避障，则返回 true。
RID obstacle_get_map ( RID obstacle ) const
返回请求的障碍物 obstacle 当前分配的导航地图 RID。
bool obstacle_get_paused ( RID obstacle ) const
如果指定的 obstacle 被暂停，则返回 true。