NavigationServer3D

继承： Object

用于访问低阶 3D 导航的服务器接口。

描述

NavigationServer3D 是处理导航地图、区块、代理的服务器。它不处理来自 AStar3D 的 A* 导航。

地图由区块组成，区块由导航网格组成。它们共同定义了 3D 空间中的可达区域。

注意：大多数 NavigationServer3D 的更改都是在下一个物理帧进行的，不会立即生效。包括所有对地图、区块、代理的更改，无论是通过场景树中导航相关的节点作出的更改，还是通过脚本作出的更改。

两个区块必须共享一条相似的边才能相连。如果一条边的两个顶点与另一条边上相应顶点的距离都小于 edge_connection_margin，那么就会认为这两条边是相连的。

可以使用 region_set_navigation_layers 为区块分配导航层，使用 map_get_path 请求路径时会对导航层进行检查。可用于针对某些对象允许或禁止特定的区域。

使用碰撞躲避系统就需要使用代理。你可以为代理设置目标速度，然后服务器就会发出回调，提供修改后的速度。

注意：碰撞躲避系统会忽略区块。直接使用修改后的速度可能会将代理移动到可达区域之外。这是碰撞躲避系统的缺陷，更复杂的场合可能需要使用物理引擎。

服务器会对所有调用进行跟踪，并在同步阶段执行。这意味着你可以放心地从任何线程请求对地图作出任何修改。

教程

• 3D 导航网格演示

• 使用 NavigationServer

方法

信号

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 的同步。默认情况下，导航地图仅在每个物理帧结束时同步。该函数可用于立即（重新）计算该导航地图的所有导航网格和区块连接。这使得可以在同一帧中对修改后的地图的导航路径立即执行查询（如果需要，可以执行多次）。

由于技术上的限制，当前的 NavigationServer 命令队列将被冲刷。这意味着所有已在当前物理帧中入队的更新命令都会被执行，即使是那些用于其他地图、不属于指定地图的区块和代理的更新命令。 昂贵计算的导航网格和地图的区块连接将仅针对指定地图进行。其他地图将在物理帧结束时接收正常同步。如果指定的地图在强制更新后又收到了修改，则它将在其他地图收到更新时再次更新。

避障处理和 safe_velocity 信号的分发不受该函数影响，仍继续发生在物理帧结束时的所有地图和代理上。

注意：能力越大，责任越大。该函数仅该用于用户真正知道自己在做什么并且有充分理由的情况。强制立即更新导航地图需要锁定 NavigationServer 并冲刷整个 NavigationServer 命令队列。这不仅会严重影响游戏的性能，而且如果缺乏远见且使用不当，还会引入 bug。

RID[] map_get_agents ( RID map ) const

返回所有与请求的导航地图 map 关联的导航代理的 RID。

float map_get_cell_height ( RID map ) const

返回在 Y 轴上栅格化导航网格顶点所使用的地图单元格高度。

float map_get_cell_size ( RID map ) const

返回在 XZ 平面上栅格化导航网格顶点所使用的地图单元格大小。

Vector3 map_get_closest_point ( RID map, Vector3 to_point ) const

返回导航网格表面上与提供的 to_point 距离最近的点。

Vector3 map_get_closest_point_normal ( RID map, Vector3 to_point ) const

返回 map_get_closest_point 所返回的点的法线。

RID map_get_closest_point_owner ( RID map, Vector3 to_point ) const

返回由 map_get_closest_point 返回的点的所有者地区的 RID。

Vector3 map_get_closest_point_to_segment ( RID map, Vector3 start, Vector3 end, bool use_collision=false ) const

返回导航表面与该线段之间最接近的点。

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。

PackedVector3Array map_get_path ( RID map, Vector3 origin, Vector3 destination, bool optimize, int navigation_layers=1 ) const

返回从原点到达目的地的导航路径。navigation_layers 是被允许在路径中的所有区块导航层的位掩码。

RID[] map_get_regions ( RID map ) const

返回当前分配给所请求的导航 map 的所有导航区块的 RID。

Vector3 map_get_up ( RID map ) const

返回地图的上方向。

bool map_get_use_edge_connections ( RID map ) const

如果导航地图 map 允许导航区块使用边缘连接与位于导航地图边缘连接边距范围内的其他导航区块相连接，则返回 true。

bool map_is_active ( RID map ) const

如果地图处于活动状态，则返回 true。

void map_set_active ( RID map, bool active )

设置地图的激活态。

void map_set_cell_height ( RID map, float cell_height )

设置在 Y 轴上栅格化导航网格顶点所使用的地图单元格高度。必须与所使用的导航网格的单元格高度相匹配。

void map_set_cell_size ( RID map, float cell_size )

设置在 XZ 平面上栅格化导航网格顶点所使用的地图单元格大小。必须与所使用的导航网格的单元格大小相匹配。

void map_set_edge_connection_margin ( RID map, float margin )

设置用于焊接兼容地区边界的地图边界连接边距。

void map_set_link_connection_radius ( RID map, float radius )

设置该地图用于连接链接和导航多边形的链接连接半径。

void map_set_up ( RID map, Vector3 up )

设置地图的上方向。

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。

bool obstacle_get_use_3d_avoidance ( RID obstacle ) const

如果提供的 obstacle 使用 3D 空间的 Vector3(x,y,z)，不使用水平 2D Vector2(x,y) / Vector3(x,0.0,z)，则返回 true。

void obstacle_set_avoidance_enabled ( RID obstacle, bool enabled )

如果 enabled 为 true，则提供的障碍物 obstacle 会影响使用代理的避障。

void obstacle_set_avoidance_layers ( RID obstacle, int layers )

设置障碍物的避障层 avoidance_layers 位掩码。

void obstacle_set_height ( RID obstacle, float height )

设置 obstacle 的高度 height。3D 代理会忽略位于其上方和下方的障碍物，使用 2D 避障。

void obstacle_set_map ( RID obstacle, RID map )

将 obstacle 分配给导航地图。

void obstacle_set_paused ( RID obstacle, bool paused )

如果 paused 为 true，则不会处理指定的障碍物 obstacle，例如不会影响避障速度。

void obstacle_set_position ( RID obstacle, Vector3 position )

为 obstacle 更新世界空间中的位置 position。

void obstacle_set_radius ( RID obstacle, float radius )

设置动态障碍物的半径。

void obstacle_set_use_3d_avoidance ( RID obstacle, bool enabled )

设置 obstacle 在启用避障时使用 2D 避障还是 3D 避障。

void obstacle_set_velocity ( RID obstacle, Vector3 velocity )

将动态障碍物 obstacle 的速度设置为 velocity。能够让其他代理更好地预测该动态障碍物的移动。仅在与障碍物半径一同使用时有效。

void obstacle_set_vertices ( RID obstacle, PackedVector3Array vertices )

设置障碍物的轮廓顶点。如果顶点顺时针缠绕，则障碍物会将代理向内部推挤，否则向外推挤。

void parse_source_geometry_data ( NavigationMesh navigation_mesh, NavigationMeshSourceGeometryData3D source_geometry_data, Node root_node, Callable callback=Callable() )

根据 navigation_mesh 的属性解析 SceneTree 中的源几何体。会使用解析的结果对提供的 source_geometry_data 资源进行更新。后续可以在使用 bake_from_source_geometry_data 烘焙导航网格时使用该资源。解析过程完成后，会调用可选的 callback。

注意：因为 SceneTree 并不是线程安全的，所以这个函数需要在主线程执行或使用延迟调用。

注意：从 Mesh 资源读取数据数组虽然很方便，但会对帧率造成负面影响。这些数据需要从 GPU 获取，卡住正在处理的 RenderingServer。出于性能考量，请优先使用碰撞形状或在代码中创建完整的数据数组等方法。

void query_path ( NavigationPathQueryParameters3D parameters, NavigationPathQueryResult3D result ) const

在给定导航地图中查询路径。起点、目标点以及其他参数通过 NavigationPathQueryParameters3D 定义。会使用路径和其他查询中请求的信息更新提供的 NavigationPathQueryResult3D。

void region_bake_navigation_mesh ( NavigationMesh navigation_mesh, Node root_node )

使用从 root_node 开始收集的烘焙源几何体来烘焙 navigation_mesh。

已弃用。 由于核心线程更改，该函数已弃用。要更新现有代码，请先创建一个 NavigationMeshSourceGeometryData3D 资源。将该资源与 parse_source_geometry_data 结合使用来解析 SceneTree 以查找有助于导航网格烘焙的节点。SceneTree 解析需要在主线程上进行。解析完成后，请在调用 bake_from_source_geometry_data 时使用该资源对导航网格进行烘焙。

RID region_create ( )

创建一个新的地区。

Vector3 region_get_connection_pathway_end ( RID region, int connection ) const

返回连接门的终点。connection 是一个索引，介于 0 和 region_get_connections_count 的返回值之间。

Vector3 region_get_connection_pathway_start ( RID region, int connection ) const

返回连接门的起点。connection 是一个索引，介于 0 和 region_get_connections_count 的返回值之间。

int region_get_connections_count ( RID region ) const

返回 region 地区与其他地区在地图上有多少连接。

bool region_get_enabled ( RID region ) const

如果指定的 region 已启用，则返回 true。

float region_get_enter_cost ( RID region ) const

返回 region 地区的进入消耗。

RID region_get_map ( RID region ) const

返回请求的 region 地区所关联的导航地图的 RID。

int region_get_navigation_layers ( RID region ) const

返回该地区的导航层。

int region_get_owner_id ( RID region ) const

返回管理该地区对象的 ObjectID。

float region_get_travel_cost ( RID region ) const

返回 region 地区的移动消耗。

bool region_get_use_edge_connections ( RID region ) const

如果导航区块 region 被设置为使用边缘连接与位于导航地图边缘连接边距范围内的其他导航区块相连接，则返回 true。

bool region_owns_point ( RID region, Vector3 point ) const

如果提供的世界空间中的 point 当前由提供的导航区块 region 拥有，则返回 true。在这里的上下文中，“拥有”意味着与来自其他导航区块的所有其他导航网格相比，该区块的导航网格多边形面中有一个距离该点最近的可能位置，这些其他导航区块也已在提供的区块的导航地图上注册。

如果有多个导航网格存在符合条件的位置并且距离相等，那么其多边形先被处理的导航区块将赢得所有权。多边形的处理顺序与导航区块在 NavigationServer 上的注册顺序一致。

注意：如果来自不同导航区块的导航网格存在重叠（通常应当避免），可能会得到预料之外的结果。

void region_set_enabled ( RID region, bool enabled )

如果 enabled 为 true，则指定的 region 会在它的当前导航地图中生效。

void region_set_enter_cost ( RID region, float enter_cost )

设置 region 地区的进入消耗 enter_cost。

void region_set_map ( RID region, RID map )

设置该地区的地图。

void region_set_navigation_layers ( RID region, int navigation_layers )

设置地区的导航层。能够在路径请求中选择地区（使用 map_get_path）。

void region_set_navigation_mesh ( RID region, NavigationMesh navigation_mesh )

设置该地图的导航网格。

void region_set_owner_id ( RID region, int owner_id )

设置管理该地区对象的 ObjectID。

void region_set_transform ( RID region, Transform3D transform )

设置该地区的全局变换。

void region_set_travel_cost ( RID region, float travel_cost )

设置 region 地区的移动消耗 travel_cost。

void region_set_use_edge_connections ( RID region, bool enabled )

如果 enabled 为 true，则导航区块 region 将使用边缘连接来与位于导航地图边缘连接边距范围内的其他导航区块相连接。

void set_active ( bool active )

控制这个服务器是否激活。

void set_debug_enabled ( bool enabled )

如果为 true，则该 NavigationServer 启用了调试模式。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.