Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
NavigationServer3D¶
继承： Object
用于访问低阶 3D 导航的服务器接口。
描述¶
NavigationServer3D 是处理导航地图、区块、代理的服务器。它不处理来自 AStar3D 的 A* 导航。
地图由区块组成，区块由导航网格组成。它们共同定义了 3D 空间中的可达区域。
注意：大多数 NavigationServer3D 的更改都是在下一个物理帧进行的，不会立即生效。包括所有对地图、区块、代理的更改，无论是通过场景树中导航相关的节点作出的更改，还是通过脚本作出的更改。
两个区块必须共享一条相似的边才能相连。如果一条边的两个顶点与另一条边上相应顶点的距离都小于 edge_connection_margin，那么就会认为这两条边是相连的。
可以使用 region_set_navigation_layers 为区块分配导航层，使用 map_get_path 请求路径时会对导航层进行检查。可用于针对某些对象允许或禁止特定的区域。
使用碰撞躲避系统就需要使用代理。你可以为代理设置目标速度，然后服务器就会发出回调，提供修改后的速度。
注意：碰撞躲避系统会忽略区块。直接使用修改后的速度可能会将代理移动到可达区域之外。这是碰撞躲避系统的缺陷，更复杂的场合可能需要使用物理引擎。
服务器会对所有调用进行跟踪，并在同步阶段执行。这意味着你可以放心地从任何线程请求对地图作出任何修改。
教程¶
方法¶
信号¶
avoidance_debug_changed ( )
当避障调试设置更改时发出。仅在调试版本中可用。
map_changed ( RID map )
当导航地图更新时、地区移动或被修改时发出。
navigation_debug_changed ( )
当导航调试设置更改时发出。仅在调试版本中可用。
枚举¶
enum ProcessInfo:
ProcessInfo INFO_ACTIVE_MAPS = 0
常量，用于获取活动导航地图的数量。
ProcessInfo INFO_REGION_COUNT = 1
常量，用于获取活动导航地区的数量。
ProcessInfo INFO_AGENT_COUNT = 2
常量，用于获取正在进行避障的活动导航代理的数量。
ProcessInfo INFO_LINK_COUNT = 3
常量，用于获取活动导航链接的数量。
ProcessInfo INFO_POLYGON_COUNT = 4
常量，用于获取导航网格多边形的数量。
ProcessInfo INFO_EDGE_COUNT = 5
常量，用于获取导航网格多边形的边的数量。
ProcessInfo INFO_EDGE_MERGE_COUNT = 6
常量，用于获取由于边键重叠而被合并的导航网格多边形的边的数量。
ProcessInfo INFO_EDGE_CONNECTION_COUNT = 7
常量，用以获取被认为由于边接近而连接的导航网格多边形的边的数量。
ProcessInfo INFO_EDGE_FREE_COUNT = 8
常量，用于获取无法合并但仍可通过边接近或链接连接的导航网格多边形的边的数量。
方法说明¶
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_get_use_3d_avoidance ( RID agent ) const
如果指定代理 agent 使用 3D 空间 Vector3(x,y,z) 的避障而不是水平 2D Vector2(x,y) / Vector3(x,0.0,z) 避障，则返回 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_height ( RID agent, float height )
更新指定代理 agent 的高度 height。
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, Vector3 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_use_3d_avoidance ( RID agent, bool enabled )
设置该代理在启用避障时使用 2D 避障还是 3D 避障。
如果为 true，则代理会为 XYZ 轴计算 3D 避障速度，例如在空中、水中、太空中进行的游戏。使用 3D 的代理只会躲避其他使用 3D 避障的代理。使用 3D 的代理只会响应基于半径的避障障碍物。使用 3D 的代理会忽略基于顶点的障碍物。使用 3D 的代理只会躲避其他使用 3D 的代理。
如果为 false，则代理会沿 XZ 轴计算 2D 避障速度，忽略 Y 轴。使用 2D 的代理只会躲避其他使用 2D 避障的代理。使用 2D 的代理会响应基于半径的避障障碍物。使用 2D 的代理会响应基于顶点的避障障碍物。使用 2D 的代理只会躲避其他使用 2D 的代理。在 2D 避障时，使用 2D 的代理会忽略它们位于当前位置之下或者位于当前位置与代理高度之和之上的其他使用 2D 的代理和障碍物。
void agent_set_velocity ( RID agent, Vector3 velocity )
将 velocity 设置为指定代理 agent 的新的需求速度。避障仿真会尽可能尝试满足这个速度，但为了躲避与其他代理和障碍物的碰撞也会对它进行修改。将代理传送至新的位置时，请使用 agent_set_velocity_forced 重置内部仿真速度。
void agent_set_velocity_forced ( RID agent, Vector3 velocity )
将指定代理 agent 的避障仿真内部速度替换为 velocity。将代理传送至新的位置时，应该在同一帧里使用这个函数。频繁调用这个函数可能让代理卡住。
void bake_from_source_geometry_data ( NavigationMesh navigation_mesh, NavigationMeshSourceGeometryData3D source_geometry_data, Callable callback=Callable() )
使用 source_geometry_data 中提供的数据对 navigation_mesh 进行烘焙。烘焙过程结束后，会调用可选的 callback。
void bake_from_source_geometry_data_async ( NavigationMesh navigation_mesh, NavigationMeshSourceGeometryData3D source_geometry_data, Callable callback=Callable() )
使用提供的 source_geometry_data 中的数据烘焙提供的 navigation_mesh，并作为在后台线程上运行的异步任务。该过程完成后，将调用可选的 callback。
void free_rid ( RID rid )
销毁给定的 RID。
bool get_debug_enabled ( ) const
如果该 NavigationServer 启用了调试，则返回 true。
RID[] get_maps ( ) const
返回该 NavigationServer 上所有已创建的导航地图的 RID。会同时返回已创建的 2D 和 3D 导航地图，因为理论上它们之间是没有区别的。
int get_process_info ( ProcessInfo process_info ) const
返回有关 NavigationServer 当前状态的信息。有关可用状态的列表，请参阅 ProcessInfo。
RID link_create ( )
在地图上新建两个地点之间的链接。
bool link_get_enabled ( RID link ) const
如果指定的 link 已启用，则返回 true。
Vector3 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。
Vector3 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, Vector3 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, Vector3 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 的同步。默认情况下，导航地图仅在每个物理帧结束时同步。该函数可用于立即（重新）计算该导航地图的所有导航网格和区块连接。这使得可以在同一帧中对修改后的地图的导航路径立即执行查询（如果需要，可以执行多次）。
由于技术上的限制，当前的 NavigationS