NavigationAgent3D

Экспериментальное: This class may be changed or removed in future versions.

Наследует: Node < Object

3D-агент, используемый для поиска пути к нужному месту с обходом препятствий.

Описание

3D-агент, используемый для поиска пути к заданной позиции с избеганием статических и динамических препятствий. Этот расчёт может использоваться родительским узлом для динамического перемещения по пути. Для корректной работы требуются навигационные данные.

Динамические препятствия обходят с помощью функции предотвращения столкновений RVO. Избегание вычисляется до физических процессов, поэтому информацию о поиске пути можно безопасно использовать на этапе физических процессов.

Примечание: После установки свойства target_position метод get_next_path_position() необходимо использовать один раз в каждом кадре физики для обновления внутренней логики пути навигационного агента. Возвращаемая им позиция вектора должна использоваться в качестве следующей позиции движения для родительского узла агента.

Примечание: Некоторые методы этого класса, такие как get_next_path_position(), могут инициировать новый расчёт пути. Вызов этих методов в обратном вызове сигнала агента, например, waypoint_reached, может привести к бесконечной рекурсии. Рекомендуется вызывать эти методы на этапе физики или, в качестве альтернативы, откладывать их вызов до конца кадра (см. Object.call_deferred() или Object.CONNECT_DEFERRED).

Обучающие материалы

• Использование NavigationAgents

Свойства

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

Сигнализирует, что агент достиг навигационной ссылки. Выдается, когда агент перемещается в пределах path_desired_distance от следующей позиции пути, когда эта позиция является навигационной ссылкой.

Словарь сведений может содержать следующие ключи в зависимости от значения path_metadata_flags:

• position: начальная позиция достигнутой ссылки.

• type: всегда NavigationPathQueryResult3D.PATH_SEGMENT_TYPE_LINK.

• rid: RID ссылки.

• owner: объект, управляющий ссылкой (обычно NavigationLink3D).

• link_entry_position: Если доступен owner и владелец — NavigationLink3D, он будет содержать глобальную позицию точки ссылки, в которую входит агент.

• link_exit_position: Если доступен owner и владелец — NavigationLink3D, он будет содержать глобальную позицию точки ссылки, из которой выходит агент.

---

navigation_finished() 🔗

Сигнализирует о том, что навигация агента завершена. Если цель достижима, навигация заканчивается, когда цель достигнута. Если цель недостижима, навигация заканчивается, когда достигнута последняя точка маршрута. Этот сигнал выдается только один раз на загруженный путь.

Этот сигнал будет выдан сразу после target_reached, когда цель достижима.

---

path_changed() 🔗

Выдается, когда агенту необходимо обновить загруженный путь:

• потому что путь ранее был пуст.

• потому что карта навигации изменилась.

• потому что агент оттолкнулся от текущего сегмента пути дальше, чем path_max_distance.

---

target_reached() 🔗

Сигнализирует о том, что агент достиг цели, т. е. агент переместился в пределах target_desired_distance от target_position. Этот сигнал посылается только один раз на загруженный путь.

Этот сигнал будет посылаться непосредственно перед navigation_finished, когда цель достижима.

Не всегда возможно достичь цели, но всегда должно быть возможно достичь конечной позиции. См. get_final_position().

---

velocity_computed(safe_velocity: Vector3) 🔗

Уведомляет, когда вычисляется скорость избегания столкновений. Выпускается каждое обновление, пока avoidance_enabled имеет значение true и у агента есть навигационная карта.

---

waypoint_reached(details: Dictionary) 🔗

Сигнализирует о том, что агент достиг путевой точки. Выдается, когда агент перемещается в пределах path_desired_distance от следующей позиции пути.

Словарь сведений может содержать следующие ключи в зависимости от значения path_metadata_flags:

• position: позиция путевой точки, которая была достигнута.

• type: тип навигационного примитива (регион или ссылка), который содержит эту путевую точку.

• rid: RID содержащего навигационного примитива (регион или ссылка).

• owner: объект, который управляет содержащим навигационным примитивом (регион или ссылка).

---

Описания свойств

bool avoidance_enabled = false 🔗

• void set_avoidance_enabled(value: bool)

• bool get_avoidance_enabled()

Если true, агент регистрируется для обратного вызова избегания RVO на NavigationServer3D. Когда velocity задано и обработка завершена, safe_velocity Vector3 принимается с сигнальным соединением на 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 застрянет в цикле повторного пути, поскольку он будет постоянно превышать расстояние до следующей точки при каждом обновлении физического кадра.

---

float path_height_offset = 0.0 🔗

• void set_path_height_offset(value: float)

• float get_path_height_offset()

Смещение высоты вычитается из значения оси Y любой позиции векторного пути для этого NavigationAgent. Смещение высоты 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()

Максимально допустимая длина возвращаемого пути в мировых единицах. При превышении этой длины путь будет обрезан.

---

float path_return_max_radius = 0.0 🔗

• void set_path_return_max_radius(value: float)

• float get_path_return_max_radius()

Максимально допустимый радиус возвращаемого пути от начала пути в мировых единицах. При превышении этого радиуса путь будет обрезан. По сравнению с path_return_max_length, это позволяет агенту пройти значительно больше, если ему потребуется обойти угол.

Примечание: При этом будет выполнено обрезание сферы с учётом только фактических точек пути навигационной сетки, при этом первая точка пути будет находиться в центре сферы.

---

float path_search_max_distance = 0.0 🔗

• void set_path_search_max_distance(value: float)

• float get_path_search_max_distance()

Максимальное расстояние, на которое может отдалиться искомый полигон от начального полигона, прежде чем поиск пути отменит поиск пути к целевому полигону (возможно, недостижимому или очень удалённому). В этом случае поиск пути сбрасывается и строит путь от начального полигона до полигона, который был найден ближайшим к целевой позиции. Значение 0 или ниже считается неограниченным. В случае неограниченного значения поиск пути будет искать все полигоны, соединённые с начальным полигоном, пока не будет найден целевой полигон или пока не будут исчерпаны все доступные варианты поиска полигонов.

---

int path_search_max_polygons = 4096 🔗

• void set_path_search_max_polygons(value: int)

• int get_path_search_max_polygons()

Максимальное количество полигонов, которые будут просмотрены до того, как поиск пути отменит поиск пути к целевому полигону (возможно, недостижимому или очень удалённому). В этом случае поиск пути сбрасывается и строит путь от начального полигона до полигона, который был найден ближайшим к целевой позиции. Значение 0 или меньше считается неограниченным. В случае неограниченного поиска пути поиск пути будет искать все полигоны, соединённые с начальным полигоном, пока не будет найден целевой полигон или пока не будут исчерпаны все доступные варианты поиска полигонов.

---

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

Величина упрощения пути в мировых единицах.

---

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 (навигация не завершится немедленно при достижении последней точки маршрута). Однако, если заданное значение слишком низкое, агент застрянет в цикле повторного пути, поскольку он будет постоянно превышать расстояние до цели при каждом обновлении физического кадра.

---

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

Возвращает достижимую конечную позицию текущего навигационного пути в глобальных координатах. Эта позиция может измениться, если агенту необходимо обновить навигационный путь, что заставляет агента испускать сигнал path_changed.

---

bool get_navigation_layer_value(layer_number: int) const 🔗

Возвращает, включен ли указанный слой битовой маски navigation_layers, учитывая layer_number от 1 до 32.

---

RID get_navigation_map() const 🔗

Возвращает RID навигационной карты для этого узла NavigationAgent. Эта функция всегда возвращает набор карт на узле NavigationAgent, а не карту абстрактного агента на NavigationServer. Если карта агента изменяется напрямую с помощью API NavigationServer, узел NavigationAgent не будет знать об изменении карты. Используйте set_navigation_map() для изменения навигационной карты для NavigationAgent, а также для обновления агента на NavigationServer.

---

Vector3 get_next_path_position() 🔗

Возвращает следующую позицию в глобальных координатах, в которую можно переместиться, убедившись, что на пути нет статических объектов. Если у агента нет пути навигации, он вернет позицию родителя агента. Использование этой функции один раз в каждом кадре физики требуется для обновления внутренней логики пути NavigationAgent.

---

float get_path_length() const 🔗

Возвращает длину текущего вычисленного пути. Возвращаемое значение — 0.0, если путь всё ещё вычисляется или вычисление ещё не было запрошено.

---

RID get_rid() const 🔗

Возвращает RID этого агента на NavigationServer3D.

---

bool is_navigation_finished() 🔗

Возвращает true, если навигация агента завершена. Если цель достижима, навигация завершается, когда цель достигнута. Если цель недостижима, навигация завершается, когда достигнута последняя точка маршрута пути.

Примечание: В то время как true будет прекращать вызывать функции обновления, такие как get_next_path_position(). Это позволяет избежать дрожания стоящего агента из-за вызова повторяющихся обновлений пути.

---

bool is_target_reachable() 🔗

Возвращает true , если get_final_position() находится в пределах target_desired_distance от target_position.

---

bool is_target_reached() const 🔗

Возвращает true, если агент достиг цели, т. е. агент переместился в пределах target_desired_distance от target_position. Не всегда возможно достичь цели, но всегда должно быть возможно достичь конечной позиции. См. 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) 🔗

Устанавливает RID навигационной карты, которую должен использовать этот узел NavigationAgent, а также обновляет agent на NavigationServer.

---

void set_velocity_forced(velocity: Vector3) 🔗

Заменяет внутреннюю скорость в моделировании избегания столкновений на velocity. Когда агент телепортируется в новое положение, эта функция должна использоваться в том же кадре. При частом вызове эта функция может привести к застреванию агентов.