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...

NavigationAgent3D

實驗性： This class may be changed or removed in future versions.

繼承： Node < Object

用於尋路至某個位置並且能夠躲避障礙物的 3D 代理。

說明

A 3D agent used to pathfind to a position while avoiding static and dynamic obstacles. The calculation can be used by the parent node to dynamically move it along the path. Requires navigation data to work correctly.

Dynamic obstacles are avoided using RVO collision avoidance. Avoidance is computed before physics, so the pathfinding information can be used safely in the physics step.

Note: After setting the target_position property, the get_next_path_position() method must be used once every physics frame to update the internal path logic of the navigation agent. The vector position it returns should be used as the next movement position for the agent's parent node.

Note: Several methods of this class, such as get_next_path_position(), can trigger a new path calculation. Calling these in your callback to an agent's signal, such as waypoint_reached, can cause infinite recursion. It is recommended to call these methods in the physics step or, alternatively, delay their call until the end of the frame (see Object.call_deferred() or Object.CONNECT_DEFERRED).

教學

• 使用 NavigationAgent

屬性

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
float	path_return_max_length	0.0
float	path_return_max_radius	0.0
float	path_search_max_distance	0.0
int	path_search_max_polygons	4096
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()
float	get_path_length() const
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) 🔗

Signals that the agent reached a navigation link. Emitted when the agent moves within path_desired_distance of the next position of the path when that position is a navigation link.

The details dictionary may contain the following keys depending on the value of path_metadata_flags:

• position: The start position of the link that was reached.

• type: Always NavigationPathQueryResult3D.PATH_SEGMENT_TYPE_LINK.

• rid: The RID of the link.

• owner: The object which manages the link (usually NavigationLink3D).

• link_entry_position: If owner is available and the owner is a NavigationLink3D, it will contain the global position of the link's point the agent is entering.

• link_exit_position: If owner is available and the owner is a NavigationLink3D, it will contain the global position of the link's point which the agent is exiting.

---

navigation_finished() 🔗

Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path.

This signal will be emitted just after target_reached when the target is reachable.

---

path_changed() 🔗

當代理程式必須更新已載入的路徑時發出：

• 因為路徑以前是空的。

• 因為導覽地圖已經改變。

• 因為代理推離目前路徑段比 path_max_distance 更遠。

---

target_reached() 🔗

Signals that the agent reached the target, i.e. the agent moved within target_desired_distance of the target_position. This signal is emitted only once per loaded path.

This signal will be emitted just before navigation_finished when the target is reachable.

It may not always be possible to reach the target but it should always be possible to reach the final position. See get_final_position().

---

velocity_computed(safe_velocity: Vector3) 🔗

Notifies when the collision avoidance velocity is calculated. Emitted every update as long as avoidance_enabled is true and the agent has a navigation map.

---

waypoint_reached(details: Dictionary) 🔗

Signals that the agent reached a waypoint. Emitted when the agent moves within path_desired_distance of the next position of the path.

The details dictionary may contain the following keys depending on the value of path_metadata_flags:

• position: The position of the waypoint that was reached.

• type: The type of navigation primitive (region or link) that contains this waypoint.

• rid: The RID of the containing navigation primitive (region or link).

• owner: The object which manages the containing navigation primitive (region or link).

---

屬性說明

bool avoidance_enabled = false 🔗

• void set_avoidance_enabled(value: bool)

• bool get_avoidance_enabled()

如果為 true，該代理會在 NavigationServer3D 上註冊 RVO 避障回調。當設定 velocity 並且處理完成時，會通過與 velocity_computed 的訊號連接接收到安全速度 safe_velocity Vector3。註冊的代理過多會為避障處理帶來顯著的性能開銷，應該僅在需要它的代理上啟用。

---

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()

If true, and the agent uses 2D avoidance, it will remember the set y-axis velocity and reapply it after the avoidance step. While 2D avoidance has no y-axis and simulates on a flat plane this setting can help to soften the most obvious clipping on uneven 3D geometry.

---

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()

The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to it leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot the distance to the next point on each physics frame update.

---

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 找到的原始路徑走廊套用的路徑後期處理。

---

float path_return_max_length = 0.0 🔗

• void set_path_return_max_length(value: float)

• float get_path_return_max_length()

The maximum allowed length of the returned path in world units. A path will be clipped when going over this length.

---

float path_return_max_radius = 0.0 🔗

• void set_path_return_max_radius(value: float)

• float get_path_return_max_radius()

The maximum allowed radius in world units that the returned path can be from the path start. The path will be clipped when going over this radius. Compared to path_return_max_length, this allows the agent to go that much further, if they need to walk around a corner.

Note: This will perform a sphere clip considering only the actual navigation mesh path points with the first path position being the sphere's center.

---

float path_search_max_distance = 0.0 🔗

• void set_path_search_max_distance(value: float)

• float get_path_search_max_distance()

The maximum distance a searched polygon can be away from the start polygon before the pathfinding cancels the search for a path to the (possibly unreachable or very far away) target position polygon. In this case the pathfinding resets and builds a path from the start polygon to the polygon that was found closest to the target position so far. A value of 0 or below counts as unlimited. In case of unlimited the pathfinding will search all polygons connected with the start polygon until either the target position polygon is found or all available polygon search options are exhausted.

---

int path_search_max_polygons = 4096 🔗

• void set_path_search_max_polygons(value: int)

• int get_path_search_max_polygons()

The maximum number of polygons that are searched before the pathfinding cancels the search for a path to the (possibly unreachable or very far away) target position polygon. In this case the pathfinding resets and builds a path from the start polygon to the polygon that was found closest to the target position so far. A value of 0 or below counts as unlimited. In case of unlimited the pathfinding will search all polygons connected with the start polygon until either the target position polygon is found or all available polygon search options are exhausted.

---

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 資源時使用不同的 NavigationMesh.agent_radius 屬性，針對不同的角色大小使用不同的導覽地圖。

---

float simplify_epsilon = 0.0 🔗

• void set_simplify_epsilon(value: float)

• float get_simplify_epsilon()

The path simplification amount in worlds units.

---

bool simplify_path = false 🔗

• void set_simplify_path(value: bool)

• bool get_simplify_path()

If true a simplified version of the path will be returned with less critical path points removed. The simplification amount is controlled by simplify_epsilon. The simplification uses a variant of Ramer-Douglas-Peucker algorithm for curve point decimation.

Path simplification can be helpful to mitigate various path following issues that can arise with certain agent types and script behaviors. E.g. "steering" agents or avoidance in "open fields".

---

float target_desired_distance = 1.0 🔗

• void set_target_desired_distance(value: float)

• float get_target_desired_distance()

The distance threshold before the target is considered to be reached. On reaching the target, target_reached is emitted and navigation ends (see is_navigation_finished() and navigation_finished).

You can make navigation end early by setting this property to a value greater than path_desired_distance (navigation will end before reaching the last waypoint).

You can also make navigation end closer to the target than each individual path position by setting this property to a value lower than path_desired_distance (navigation won't immediately end when reaching the last waypoint). However, if the value set is too low, the agent will be stuck in a repath loop because it will constantly overshoot the distance to the target on each physics frame update.

---

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，則代理會在 2D 空間中沿 X 和 Z 軸計算避障速度，忽略 Y 軸。使用 2D 避障的代理只會躲避其他使用 2D 避障的代理、對基於半徑和基於頂點的障礙物作出反應。其他使用 2D 避障的代理如果在該代理之下，或者高於該代理當前位置與 height 之和則會被忽略。

---

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 位元遮罩中指定的層是否啟用，給定的 layer_number 應在 1 和 32 之間。

---

bool get_avoidance_mask_value(mask_number: int) const 🔗

返回 avoidance_mask 位元遮罩中指定的遮罩是否啟用，給定的 mask_number 應在 1 和 32 之間。

---

PackedVector3Array get_current_navigation_path() const 🔗

返回這個代理從起點到終點的目前路徑，使用全域座標。該路徑只會在目標位置發生變化，或者代理要求重新計算路徑時更新。路徑陣列不套用於直接路徑移動，因為代理有自己的內部路徑邏輯，手動更改路徑陣列可能會破壞該邏輯。每個物理影格上使用一次預期的 get_next_path_position()，來接收用於該代理移動的下一個路徑點，因為該函式還會更新內部路徑邏輯。

---

int get_current_navigation_path_index() const 🔗

返回該代理目前位於導覽路徑 PackedVector3Array 中的哪一個索引。

---

NavigationPathQueryResult3D get_current_navigation_result() const 🔗

返回該代理目前正在使用的路徑所對應的路徑查詢結果。

---

Vector3 get_final_position() 🔗

返回目前導覽路徑上可到達的最終位置的全域座標。如果導覽路徑由於任何原因發生改變，這個位置也可能發生變化。因此，最好每一影格都檢查一下。

---

bool get_navigation_layer_value(layer_number: int) const 🔗

返回 navigation_layers 位元遮罩中指定的層是否啟用，給定的 layer_number 應在 1 和 32 之間。

---

RID get_navigation_map() const 🔗

返回這個 NavigationAgent 節點的導覽地圖的 RID。這個函式返回的始終是在 NavigationAgent 上設定的地圖，不是 NavigationServer 上的抽象代理所使用的地圖。如果通過 NavigationServer API 修改了代理的地圖，該 NavigationAgent 節點是不會感知到地圖的變化的。請使用 set_navigation_map() 修改該 NavigationAgent 的導覽地圖，能夠同時在 NavigationServer 上的代理。

---

Vector3 get_next_path_position() 🔗

返回可以移動至的下一個位置，使用全域座標，確保中途沒有靜態物件的阻擋。如果該代理沒有導覽路徑，則會返回該代理父節點的位置。這個函式每個物理影格都必須呼叫一次，更新 NavigationAgent 內部的路徑邏輯。

---

float get_path_length() const 🔗

Returns the length of the currently calculated path. The returned value is 0.0, if the path is still calculating or no calculation has been requested yet.

---

RID get_rid() const 🔗

返回這個代理在 NavigationServer3D 上的 RID。

---

bool is_navigation_finished() 🔗

Returns true if the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached.

Note: While true prefer to stop calling update functions like get_next_path_position(). This avoids jittering the standing agent due to calling repeated path updates.

---

bool is_target_reachable() 🔗

如果可到達 target_position，則返回 true。目標位置由 target_position 設定。

---

bool is_target_reached() const 🔗

Returns true if the agent reached the target, i.e. the agent moved within target_desired_distance of the target_position. It may not always be possible to reach the target but it should always be possible to reach the final position. See get_final_position().

---

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

根據 value 啟用或禁用 avoidance_layers 位元遮罩中指定的層，給定的 layer_number 應在 1 和 32 之間。

---

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

根據 value 啟用或禁用 avoidance_mask 位元遮罩中指定的遮罩，給定的 mask_number 應在 1 和 32 之間。

---

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

根據 value，啟用或禁用 navigation_layers 位元遮罩中指定的層，給定的 layer_number 應在 1 和 32 之間。

---

void set_navigation_map(navigation_map: RID) 🔗

設定這個 NavigationAgent 節點所應使用的導覽地圖的 RID，同時還會更新 NavigationServer 上的代理 agent。

---

void set_velocity_forced(velocity: Vector3) 🔗

將防撞模擬的內部速度替換為 velocity。代理傳送到新的位置之後，應該在同一影格裡使用這個函式。如果頻繁呼叫這個函式，可能會讓代理卡住。