NavigationAgent3D

实验性： This class may be changed or removed in future versions.

继承： Item < Object

一种3D代理，用于在避开障碍物的同时找到一个位置。

描述

用于在避开静态和动态障碍物的同时找到位置的3D代理。父节点可以使用该计算沿路径动态移动它。需要导航数据才能正常工作。

动态障碍物采用RVO避碰方法进行避碰，避碰的计算先于物理步骤进行，因此在物理步骤中可以安全地使用寻路信息。

注意：设置target_position属性后，必须每物理帧使用一次get_next_path_position()方法来更新导航代理的内部路径逻辑，它返回的矢量位置应该作为代理父节点的下一个移动位置。

属性

bool	avoidance_enabled	false
int	avoidance_layers	1
int	avoidance_mask	1
float	avoidance_priority	1.0
bool	debug_enabled	false
Color	debug_path_custom_color	Color(1, 1, 1, 1)
float	debug_path_custom_point_size	4.0
bool	debug_use_custom	false
float	height	1.0
bool	keep_y_velocity	true
int	max_neighbors	10
float	max_speed	10.0
int	navigation_layers	1
float	neighbor_distance	50.0
float	path_desired_distance	1.0
float	path_height_offset	0.0
float	path_max_distance	5.0
BitField[PathMetadataFlags]	path_metadata_flags	7
PathPostProcessing	path_postprocessing	0
PathfindingAlgorithm	pathfinding_algorithm	0
float	radius	0.5
float	simplify_epsilon	0.0
bool	simplify_path	false
float	target_desired_distance	1.0
Vector3	target_position	Vector3(0, 0, 0)
float	time_horizon_agents	1.0
float	time_horizon_obstacles	0.0
bool	use_3d_avoidance	false
Vector3	velocity	Vector3(0, 0, 0)

方法

float	distance_to_target() const
bool	get_avoidance_layer_value(layer_number: int) const
bool	get_avoidance_mask_value(mask_number: int) const
PackedVector3Array	get_current_navigation_path() const
int	get_current_navigation_path_index() const
NavigationPathQueryResult3D	get_current_navigation_result() const
Vector3	get_final_position()
bool	get_navigation_layer_value(layer_number: int) const
RID	get_navigation_map() const
Vector3	get_next_path_position()
RID	get_rid() const
bool	is_navigation_finished()
bool	is_target_reachable()
bool	is_target_reached() const
void	set_avoidance_layer_value(layer_number: int, value: bool)
void	set_avoidance_mask_value(mask_number: int, value: bool)
void	set_navigation_layer_value(layer_number: int, value: bool)
void	set_navigation_map(navigation_map: RID)
void	set_velocity_forced(velocity: Vector3)

---

信号

link_reached(details: Dictionary) 🔗

代理到达导航链接的信号。当代理在路径的下一个位置path_desired_distance内移动时发出，此时该位置是导航链接。

详细信息字典可能包含以下键，具体取决于path_metadata_flags的值：

-point：到达的链接的开始位置。

-type：始终NavigationPathQueryResult3D.PATH_SEGMENT_TYPE_LINK。

-rid：链接的RID。

-所有者：管理链接的对象（通常是NavigationLink）。

-link_entry_position：如果所有者可用并且所有者是NavigationLink，它将包含代理正在进入的链接点的全局位置。

-link_exit_position：如果所有者可用并且所有者是NavigationLink，它将包含代理正在退出的链接点的全局位置。

---

navigation_finished() 🔗

表示代理导航已完成的信号。如果目标可达，则导航在到达目标时结束。如果目标不可达，则导航在到达路径的最后一个航点时结束。每个加载的路径只发出一次此信号。

该信号将在target_reached之后可达目标时发出。

---

path_changed() 🔗

当代理必须更新加载的路径时发出：

-因为路径以前为空。

-因为导航地图已经改变。

-因为代理比path_max_distance推得更远离当前路径段。

---

target_reached() 🔗

表示代理到达目标的信号，即代理在target_position的target_desired_distance内移动。每个加载路径只发出一次此信号。

当目标可达时，该信号将在navigation_finished之前发出。

不一定总能到达目标，但应该总能到达最终位置参见get_final_position()。

---

velocity_computed(safe_velocity: Vector3) 🔗

计算避碰速度时发出通知。只要avoidance_enabled为true并且代理有导航地图，就会发出每次更新。

---

waypoint_reached(details: Dictionary) 🔗

代理到达路径点的信号。当代理在路径的下一个位置path_desired_distance内移动时发出。

详细信息字典可能包含以下键，具体取决于path_metadata_flags的值：

-位置：到达的航点的位置。

-type：包含此航点的导航原语（区域或链接）的类型。

-rid：包含导航原语（区域或链接）的RID。

-所有者：管理包含导航原语（区域或链接）的对象。

---

属性说明

bool avoidance_enabled = false 🔗

• void set_avoidance_enabled(value: bool)

• bool get_avoidance_enabled()

如果true，则代理在NavigationServer3D上注册了RVO回避回调。当设置velocity并完成处理时，将收到safe_velocityVector3，并与velocity_computed进行信号连接。使用许多注册代理进行回避处理会产生很大的性能成本，并且应该只在当前需要它的代理上启用。

---

int avoidance_layers = 1 🔗

• void set_avoidance_layers(value: int)

• int get_avoidance_layers()

确定此NavigationAgent的避免层的位字段。avoidance_mask上具有匹配位的其他代理将避免此代理。

---

int avoidance_mask = 1 🔗

• void set_avoidance_mask(value: int)

• int get_avoidance_mask()

确定该NavigationAgent在位匹配其avoidance_layers中的至少一个时将避免哪些其他回避代理和障碍的位域。

---

float avoidance_priority = 1.0 🔗

• void set_avoidance_priority(value: float)

• float get_avoidance_priority()

代理不调整与avoidance_mask匹配但avoidance_priority较低的其他代理的速度。这反过来又使优先级较低的其他代理更多地调整它们的速度，以避免与该代理碰撞。

---

bool debug_enabled = false 🔗

• void set_debug_enabled(value: bool)

• bool get_debug_enabled()

如果true显示此代理的调试视觉对象。

---

Color debug_path_custom_color = Color(1, 1, 1, 1) 🔗

• void set_debug_path_custom_color(value: Color)

• Color get_debug_path_custom_color()

如果debug_use_custom为true，则此代理使用此颜色而不是全局颜色。

---

float debug_path_custom_point_size = 4.0 🔗

• void set_debug_path_custom_point_size(value: float)

• float get_debug_path_custom_point_size()

如果debug_use_custom为true则使用此光栅化点大小来呈现此代理的路径点，而不是全局点大小。

---

bool debug_use_custom = false 🔗

• void set_debug_use_custom(value: bool)

• bool get_debug_use_custom()

如果true为此代理使用定义的debug_path_custom_color而不是全局颜色。

---

float height = 1.0 🔗

• void set_height(value: float)

• float get_height()

回避剂的高度。在2D回避中，代理将忽略高于或低于其当前位置+高度的其他代理或障碍物。在仅使用半径球的3D回避中不做任何事情。

---

bool keep_y_velocity = true 🔗

• void set_keep_y_velocity(value: bool)

• bool get_keep_y_velocity()

如果true，并且代理使用2D回避，它将记住设置的y轴速度，并在回避步骤后重新应用它。虽然2D回避没有y轴并在平面上模拟，但此设置有助于软化不均匀3D几何上最明显的裁剪。

---

int max_neighbors = 10 🔗

• void set_max_neighbors(value: int)

• int get_max_neighbors()

代理考虑的最大邻居数。

---

float max_speed = 10.0 🔗

• void set_max_speed(value: float)

• float get_max_speed()

代理可以移动的最大速度。

---

int navigation_layers = 1 🔗

• void set_navigation_layers(value: int)

• int get_navigation_layers()

确定此代理将用于计算路径的导航区域的导航层的位字段。在运行时更改它将清除当前导航路径并根据新的导航层生成新的导航路径。

---

float neighbor_distance = 50.0 🔗

• void set_neighbor_distance(value: float)

• float get_neighbor_distance()

搜索其他代理的距离。

---

float path_desired_distance = 1.0 🔗

• void set_path_desired_distance(value: float)

• float get_path_desired_distance()

路径点之前的距离阈值被认为已经到达。这允许代理不必精确地击中路径上的路径点，而只需到达其一般区域。如果此值设置得太高，NavigationAgent将跳过路径上的点，这可能导致它离开导航网格。如果此值设置得太低，NavigationAgent将陷入repath循环，因为它会在每次物理帧更新时不断超调到下一个点的距离。

---

float path_height_offset = 0.0 🔗

• void set_path_height_offset(value: float)

• float get_path_height_offset()

此NavigationAgent的任何矢量路径位置的y轴值减去高度偏移。NavigationAgent高度偏移不会改变或影响导航网格或寻路查询结果。需要使用具有导航网格的区域的附加导航地图，开发人员使用适当的代理半径或高度值烘焙这些区域以支持不同大小的代理。

---

float path_max_distance = 5.0 🔗

• void set_path_max_distance(value: float)

• float get_path_max_distance()

代理被允许离开理想路径到最终位置的最大距离。这可能是由于试图避免碰撞而发生的。当超过最大距离时，它会重新计算理想路径。

---

BitField[PathMetadataFlags] path_metadata_flags = 7 🔗

• void set_path_metadata_flags(value: BitField[PathMetadataFlags])

• BitField[PathMetadataFlags] get_path_metadata_flags()

与导航路径一起返回的附加信息。

---

PathPostProcessing path_postprocessing = 0 🔗

• void set_path_postprocessing(value: PathPostProcessing)

• PathPostProcessing get_path_postprocessing()

应用于pathfinding_algorithm找到的原始路径走廊的路径后处理。

---

PathfindingAlgorithm pathfinding_algorithm = 0 🔗

• void set_pathfinding_algorithm(value: PathfindingAlgorithm)

• PathfindingAlgorithm get_pathfinding_algorithm()

路径查询中使用的寻路算法。

---

float radius = 0.5 🔗

• void set_radius(value: float)

• float get_radius()

回避剂的半径。这是回避剂的“身体”，而不是回避机动开始半径（由neighbor_distance控制）。

不影响正常寻路。要更改参与者的寻路半径，请使用不同的NavigationMesh.agent_radius属性烘焙NavigationMesh资源，并为每个参与者大小使用不同的导航地图。

---

float simplify_epsilon = 0.0 🔗

• void set_simplify_epsilon(value: float)

• float get_simplify_epsilon()

以世界为单位的路径简化量。

---

bool simplify_path = false 🔗

• void set_simplify_path(value: bool)

• bool get_simplify_path()

如果true将返回路径的简化版本，其中删除了较少的关键路径点。简化量由simplify_epsilon控制。简化使用Ramer-Douglas-Peucker算法的变体进行曲线点抽取。

路径简化有助于缓解某些代理类型和脚本行为可能出现的各种路径跟踪问题。例如。“引导”代理或在“开放领域”中回避。

---

float target_desired_distance = 1.0 🔗

• void set_target_desired_distance(value: float)

• float get_target_desired_distance()

认为到达目标前的距离阈值，到达目标时发射target_reached，导航结束（见is_navigation_finished()和navigation_finished）。

您可以通过将此属性设置为大于path_desired_distance的值来提前结束导航（导航将在到达最后一个航点之前结束）。

您还可以通过将此属性设置为低于path_desired_distance的值（导航不会在到达最后一个航点时立即结束）来使导航结束比每个单独的路径位置更靠近目标。但是，如果设置的值太低，代理将陷入repath循环，因为它会在每次物理帧更新时不断超出到目标的距离。

---

Vector3 target_position = Vector3(0, 0, 0) 🔗

• void set_target_position(value: Vector3)

• Vector3 get_target_position()

如果设置，则从NavigationServer请求从当前代理位置到target_position的新导航路径。

---

float time_horizon_agents = 1.0 🔗

• void set_time_horizon_agents(value: float)

• float get_time_horizon_agents()

用碰撞避免算法计算的该代理速度的最小时间量，相对于其他代理是安全的。数字越大，代理对其他代理的响应越快，但选择速度的自由度越小。太高的值会大大减慢代理的运动。必须是积极的。

---

float time_horizon_obstacles = 0.0 🔗

• void set_time_horizon_obstacles(value: float)

• float get_time_horizon_obstacles()

用碰撞避免算法计算的该代理速度的最小时间量，相对于静态回避障碍物是安全的。数字越大，代理对静态回避障碍物的反应越快，但选择速度的自由度越小。太高的值会大大减慢代理的运动。必须是积极的。

---

bool use_3d_avoidance = false 🔗

• void set_use_3d_avoidance(value: bool)

• bool get_use_3d_avoidance()

如果true，代理将全方位计算3D回避速度，例如对于在空中、水下或太空中发生的应用。使用3D回避的代理仅避开使用3D回避的其他代理，并对基于半径的回避障碍物做出反应。他们忽略任何基于顶点的障碍物。

如果false，则代理沿x和z轴计算2D中的回避速度，忽略y轴。使用2D回避的代理仅避开使用2D回避的其他代理，并对基于半径的回避障碍物或基于顶点的回避障碍物做出反应。低于或高于其当前位置（包括height）的其他使用2D回避的代理被忽略。

---

Vector3 velocity = Vector3(0, 0, 0) 🔗

• void set_velocity(value: Vector3)

• Vector3 get_velocity()

为代理设置新的所需速度。如果可能，回避模拟将尝试实现此速度，但会修改它以避免与其他代理和障碍物碰撞。当代理被传送到新位置时，也使用set_velocity_forced()重置内部模拟速度。

---

方法说明

float distance_to_target() const 🔗

使用代理的全局位置返回到目标位置的距离。用户必须设置target_position以使其准确。

---

bool get_avoidance_layer_value(layer_number: int) const 🔗

返回是否启用avoidance_layers位掩码的指定层，给定介于1和32之间的layer_number。

---

bool get_avoidance_mask_value(mask_number: int) const 🔗

返回是否启用avoidance_mask位掩码的指定掩码，给定介于1和32之间的mask_number。

---

PackedVector3Array get_current_navigation_path() const 🔗

在全局坐标中返回此代理从开始到结束的当前路径。路径仅在目标位置更改或代理需要repath时更新。路径数组不打算用于直接路径移动，因为代理有自己的内部路径逻辑，手动更改路径数组会损坏。使用预期的get_next_path_position()在每个物理帧中接收代理移动的下一个路径点，因为此函数也会更新内部路径逻辑。

---

int get_current_navigation_path_index() const 🔗

返回代理当前在导航路径的PackedVector3Array中的索引。

---

NavigationPathQueryResult3D get_current_navigation_result() const 🔗

返回代理当前遵循的路径的路径查询结果。

---

Vector3 get_final_position() 🔗

返回当前导航路径在全局坐标中的可达最终位置。如果代理需要更新使代理发出path_changed信号的导航路径，此位置可能会改变。

---

bool get_navigation_layer_value(layer_number: int) const 🔗

返回是否启用navigation_layers位掩码的指定层，给定介于1和32之间的layer_number。

---

RID get_navigation_map() const 🔗

返回此NavigationAgent节点的导航地图的RID。此函数始终返回NavigationAgent节点上设置的地图，而不是NavigationServer上抽象代理的地图。如果直接使用NavigationServer API更改代理地图，NavigationAgent节点将不知道地图更改。使用set_navigation_map()更改NavigationAgent的导航地图并更新NavigationServer上的代理。

---

Vector3 get_next_path_position() 🔗

返回全局坐标中可以移动到的下一个位置，确保途中没有静态对象。如果代理没有导航路径，它将返回代理父级的位置。每个物理帧都需要使用此函数一次来更新NavigationAgent的内部路径逻辑。

---

RID get_rid() const 🔗

返回NavigationServer3D上此代理的RID。

---

bool is_navigation_finished() 🔗

如果代理的导航已完成，则返回true。如果目标可达，则导航在到达目标时结束。如果目标不可达，则导航在到达路径的最后一个航点时结束。

注意：虽然true更喜欢停止调用get_next_path_position()之类的更新函数。这避免了由于调用重复的路径更新而导致常设代理抖动。

---

bool is_target_reachable() 🔗

如果get_final_position()在target_position的target_desired_distance内，则返回true。

---

bool is_target_reached() const 🔗

如果代理到达目标，即代理在target_position的target_desired_distance内移动，则返回true。它可能并不总是能够到达目标，但应该总是能够到达最终位置。参见get_final_position()。

---

void set_avoidance_layer_value(layer_number: int, value: bool) 🔗

基于value，启用或禁用avoidance_layers位掩码中的指定层，给定介于1和32之间的layer_number。

---

void set_avoidance_mask_value(mask_number: int, value: bool) 🔗

基于value，启用或禁用avoidance_mask位掩码中的指定掩码，给定介于1和32之间的mask_number。

---

void set_navigation_layer_value(layer_number: int, value: bool) 🔗

基于value，启用或禁用navigation_layers位掩码中的指定层，给定介于1和32之间的layer_number。

---

void set_navigation_map(navigation_map: RID) 🔗

设置此NavigationAgent节点应使用的导航地图的RID，并更新NavigationServer上的agent。

---

void set_velocity_forced(velocity: Vector3) 🔗

将避碰模拟中的内部速度替换为velocity。当代理被传送到新位置时，此函数应在同一帧中使用。如果频繁调用此函数，可能会使代理卡住。