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

NavigationAgent2D

Expérimental : This class may be changed or removed in future versions.

Hérite de : Node < Object

Un agent 2D utilisé pour rechercher un chemin vers une position tout en évitant les obstacles.

Description

A 2D 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).

Tutoriels

• Utilisation des NavigationAgents

Propriétés

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_line_width	-1.0
float	debug_path_custom_point_size	4.0
bool	debug_use_custom	false
int	max_neighbors	10
float	max_speed	100.0
int	navigation_layers	1
float	neighbor_distance	500.0
float	path_desired_distance	20.0
float	path_max_distance	100.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	10.0
float	simplify_epsilon	0.0
bool	simplify_path	false
float	target_desired_distance	10.0
Vector2	target_position	Vector2(0, 0)
float	time_horizon_agents	1.0
float	time_horizon_obstacles	0.0
Vector2	velocity	Vector2(0, 0)

Méthodes

float	distance_to_target() const
bool	get_avoidance_layer_value(layer_number: int) const
bool	get_avoidance_mask_value(mask_number: int) const
PackedVector2Array	get_current_navigation_path() const
int	get_current_navigation_path_index() const
NavigationPathQueryResult2D	get_current_navigation_result() const
Vector2	get_final_position()
bool	get_navigation_layer_value(layer_number: int) const
RID	get_navigation_map() const
Vector2	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: Vector2)

---

Signaux

link_reached(details: Dictionary) 🔗

Signale que l'agent a atteint un lien de navigation. Émis lorsque l'agent se déplace à une distance de path_desired_distance de la position suivante du chemin lorsque cette position est un lien de navigation.

Le dictionnaire de détails peut contenir les clés suivantes selon la valeur de path_metadata_flags:

• position : La position de départ du lien qui a été atteint.

• type : Toujours NavigationPathQueryResult2D.PATH_SEGMENT_TYPE_LINK.

• rid : Le RID du lien.

• owner : L'objet qui gère le lien (généralement NavigationLink2D).

• link_entry_position : Si owner est disponible et que le propriétaire est un NavigationLink2D, il contiendra la position globale du point de lien que l'agent entre.

• link_exit_position : Si owner est disponible et que le propriétaire est un NavigationLink2D, il contiendra la position globale du point de lien que l'agent quitte.

---

navigation_finished() 🔗

Signale que la navigation de l'agent est finie. Si la cible est atteinte, la navigation se termine lorsque la cible est atteinte. Si la cible est inatteignable, la navigation se termine lorsque le dernier point du chemin est atteint. Ce signal n'est émis qu'une fois par chemin chargé.

Ce signal sera émis juste après target_reached lorsque la cible est atteignable.

---

path_changed() 🔗

Émis lorsque l'agent a dû mettre à jour le chemin chargé :

• parce que le chemin était précédemment vide.

• parce que la carte de navigation a changé.

• parce que l'agent s'est éloigné du segment de chemin actuel de plus que path_max_distance.

---

target_reached() 🔗

Signale que l'agent a atteint la cible, c'est-à-dire que l'agent s'est déplacé à une distance inférieure à target_desired_distance de la position cible target_position. Ce signal n'est émis qu'une fois par chemin chargé.

Ce signal sera émis juste avant navigation_finished lorsque la cible est atteignable.

Il peut ne pas toujours être possible d'atteindre la cible mais il devrait toujours être possible d'atteindre la position finale. Voir get_final_position().

---

velocity_computed(safe_velocity: Vector2) 🔗

Notifie quand la vitesse d'évitement de collision est calculée. Émise à chaque mise à jour tant que avoidance_enabled vuat true et que l'agent a une carte de navigation.

---

waypoint_reached(details: Dictionary) 🔗

Signale que l'agent a atteint un point du chemin. Émis lorsque l'agent se déplace à une distance inférieure àpath_desired_distance de la position suivante du chemin.

Le dictionnaire de détails peut contenir les clés suivantes selon la valeur de path_metadata_flags :

• position : La position du point du chemin qui a été atteint.

• type : Le type de primitive de navigation (région ou lien) qui contient ce point du chemin.

• rid : Le RID de la primitive de navigation qui contient le point (région ou lien).

• owner : L'objet qui gère le la primitive de navigation qui contient le point (région ou lien).

---

Descriptions des propriétés

bool avoidance_enabled = false 🔗

• void set_avoidance_enabled(value: bool)

• bool get_avoidance_enabled()

Si true, l'agent est enregistré pour un rappel d'évitement RVO sur le NavigationServer2D. Lorsque velocity est utilisé et que le traitement est terminé, un Vector2 safe_velocity est reçu avec une connexion au signal velocity_computed. Le traitement de l'évitement avec de nombreux agents enregistrés a un coût de performance important et ne devrait être activé que pour les agents qui en ont actuellement besoin.

---

int avoidance_layers = 1 🔗

• void set_avoidance_layers(value: int)

• int get_avoidance_layers()

Un champ de bits déterminant les couches d'évitement pour ce NavigationAgent. D'autres agents avec un bit correspondant sur leur avoidance_mask éviteront cet agent.

---

int avoidance_mask = 1 🔗

• void set_avoidance_mask(value: int)

• int get_avoidance_mask()

Un champ de bits déterminant quels autres agents et obstacles d'évitement ce NavigationAgent évitera lorsqu'un bit correspond à au moins un de leurs avoidance_layers.

---

float avoidance_priority = 1.0 🔗

• void set_avoidance_priority(value: float)

• float get_avoidance_priority()

L'agent n'ajuste pas la vitesse pour d'autres agents qui correspondraient au avoidance_mask, mais ayant un avoidance_priority inférieur. Cela fait que les autres agents de plus basse priorité ajusteront leurs vitesses encore plus pour éviter la collision avec cet agent.

---

bool debug_enabled = false 🔗

• void set_debug_enabled(value: bool)

• bool get_debug_enabled()

Si true, affiche des visuels de débogage pour cet agent.

---

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

• void set_debug_path_custom_color(value: Color)

• Color get_debug_path_custom_color()

Si debug_use_custom vaut true, utilise cette couleur pour cet agent au lieu de la couleur globale.

---

float debug_path_custom_line_width = -1.0 🔗

• void set_debug_path_custom_line_width(value: float)

• float get_debug_path_custom_line_width()

Si debug_use_custom vaut true, utilise cette largeur de ligne pour rendre les chemins pour cet agent au lieu de la largeur de ligne globale.

---

float debug_path_custom_point_size = 4.0 🔗

• void set_debug_path_custom_point_size(value: float)

• float get_debug_path_custom_point_size()

Si debug_use_custom vaut true, utilise cette taille de point rasterisée pour rendre les points du chemin pour cet agent au lieu de la taille de point globale.

---

bool debug_use_custom = false 🔗

• void set_debug_use_custom(value: bool)

• bool get_debug_use_custom()

Si true, utilise la couleur debug_path_custom_color définie pour cet agent au lieu de la couleur globale.

---

int max_neighbors = 10 🔗

• void set_max_neighbors(value: int)

• int get_max_neighbors()

Le nombre maximum de voisins à considérer par l'agent.

---

float max_speed = 100.0 🔗

• void set_max_speed(value: float)

• float get_max_speed()

La vitesse maximale à laquelle un agent peut se déplacer.

---

int navigation_layers = 1 🔗

• void set_navigation_layers(value: int)

• int get_navigation_layers()

Un masque de bits déterminant quelles couches de navigation des régions de navigation cet agent utilisera pour calculer un chemin. Le modifier durant l'exécution permettra de vider le chemin de navigation actuel et d'en générer un nouveau, correspondant aux nouvelles couches de navigation.

---

float neighbor_distance = 500.0 🔗

• void set_neighbor_distance(value: float)

• float get_neighbor_distance()

La distance pour chercher d'autres agents.

---

float path_desired_distance = 20.0 🔗

• void set_path_desired_distance(value: float)

• float get_path_desired_distance()

Le seuil de distance avant qu'un point du chemin soit considéré comme atteint. Cela permettra à un agent de ne pas avoir à atteindre un point du chemin exactement sur le chemin, mais uniquement un zone autour. Si cette valeur est trop élevée, le NavigationAgent sautera des points sur le chemin ce qui peut conduire à quitter le maillage de navigation. Si cette valeur est trop faible, le NavigationAgent sera coincé dans une boucle parce qu'il va constamment dépasser la distance jusqu'au point suivant à chaque mise à jour de trame de physique.

---

float path_max_distance = 100.0 🔗

• void set_path_max_distance(value: float)

• float get_path_max_distance()

La distance maximale du chemin idéal vers la position finale dont l'agent est autorisé de s'éloigner. Cela peut arriver en essayant d'éviter des collisions. Lorsque la distance maximale est dépassée, il recalcule le chemin idéal.

---

BitField[PathMetadataFlags] path_metadata_flags = 7 🔗

• void set_path_metadata_flags(value: BitField[PathMetadataFlags])

• BitField[PathMetadataFlags] get_path_metadata_flags()

Informations supplémentaires à renvoyer avec le chemin de navigation.

---

PathPostProcessing path_postprocessing = 0 🔗

• void set_path_postprocessing(value: PathPostProcessing)

• PathPostProcessing get_path_postprocessing()

Le post-traitement du chemin appliqué au couloir de chemin brut trouvé par pathfinding_algorithm.

---

float path_return_max_length = 0.0 🔗

• void set_path_return_max_length(value: float)

• float get_path_return_max_length()

La longueur maximale autorisée du chemin renvoyé en unités globales. Un chemin sera coupé s'il dépasse cette longueur.

---

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

L'algorithme de recherche de chemin utilisé dans la recherche de chemin.

---

float radius = 10.0 🔗

• void set_radius(value: float)

• float get_radius()

Le rayon d'évitement de l'agent. Il s'agit du « corps » de l'agent d'évitement et non le rayon de départ de la manœuvre d'évitement (qui est contrôlé par neighbor_distance).

N'affecte pas la recherche de chemin normale. Pour changer le rayon de recherche de chemin d'un acteur, pré-calculez les ressources NavigationPolygon avec une propriété NavigationPolygon.agent_radius différente et utilisez des cartes de navigation différentes pour chaque taille d'acteur.

---

float simplify_epsilon = 0.0 🔗

• void set_simplify_epsilon(value: float)

• float get_simplify_epsilon()

Le montant de simplification du chemin en unités du monde.

---

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 = 10.0 🔗

• void set_target_desired_distance(value: float)

• float get_target_desired_distance()

Le seuil de distance avant que la cible soit considérée comme atteinte. En atteignant la cible, target_reached est émis et la navigation se finit (voir is_navigation_finished() et navigation_finished).

Vous pouvez faire que la navigation se termine tôt en définissant cette propriété à une valeur supérieure à path_desired_distance (la navigation se terminera avant d'atteindre le dernier point du chemin).

Vous pouvez également faire que la navigation se termine plus proche de la cible que n'importe quelle position de chemin individuelle en définissant cette propriété à une valeur inférieure à path_desired_distance (la navigation ne se terminera pas immédiatement en atteignant le dernier point du chemin). Cependant, si la valeur définie est trop basse, l'agent sera coincé dans une boucle parce qu'il va constamment dépasser la distance jusqu'à la cible à chaque mise à jour de trame de physique.

---

Vector2 target_position = Vector2(0, 0) 🔗

• void set_target_position(value: Vector2)

• Vector2 get_target_position()

Si elle est définie, un nouveau chemin de navigation de la position actuelle de l'agent vers la position cible target_position est demandé au NavigationServer.

---

float time_horizon_agents = 1.0 🔗

• void set_time_horizon_agents(value: float)

• float get_time_horizon_agents()

La quantité minimale de temps pour laquelle les vitesses de cet agent, calculées avec l'algorithme d'évitement de collision, sont sûres par rapport aux autres agents. Plus le nombre est élevé, plus tôt l'agent répondra à d'autres agents, mais moins il aura la liberté de choisir sa vitesse. Une valeur trop élevée ralentira considérablement le mouvement de l'agent. Doit être positif.

---

float time_horizon_obstacles = 0.0 🔗

• void set_time_horizon_obstacles(value: float)

• float get_time_horizon_obstacles()

La quantité minimale de temps pour laquelle les vitesses de cet agent, calculées avec l'algorithme d'évitement de collision, sont sûres par rapport aux obstacle d'évitement statiques. Plus le nombre est élevé, plus tôt l'agent répondra aux obstacles d'évitement statiques, mais moins il aura la liberté de choisir sa vitesse. Une valeur trop élevée ralentira considérablement le mouvement de l'agent. Doit être positif.

---

Vector2 velocity = Vector2(0, 0) 🔗

• void set_velocity(value: Vector2)

• Vector2 get_velocity()

Définit la nouvelle vitesse désirée pour l'agent. La simulation d'évitement tentera d'atteindre cette vitesse si possible, mais la modifiera pour éviter toute collision avec d'autres agents et obstacles. Lorsqu'un agent est téléporté à une nouvelle position, utilisez aussi set_velocity_forced() pour réinitialiser la vitesse de simulation interne.

---

Descriptions des méthodes

float distance_to_target() const 🔗

Renvoie la distance jusqu'à l'emplacement cible, en utilisant la position globale de l'agent. L'utilisateur doit définir la position cible avec target_position afin que ceci soit précis.

---

bool get_avoidance_layer_value(layer_number: int) const 🔗

Renvoie si la couche spécifiée du masque de bits avoidance_layers est activée, étant donné un numéro de couche layer_number entre 1 et 32.

---

bool get_avoidance_mask_value(mask_number: int) const 🔗

Renvoie si le masque spécifié du masque de bits avoidance_mask est activée, selon un numéro de masque mask_number donné entre 1 et 32.

---

PackedVector2Array get_current_navigation_path() const 🔗

Renvoie le chemin actuel de cet agent du début à la fin dans les coordonnées globales. Le chemin ne se met à jour que lorsque la position cible est changée ou que l'agent requiert un nouveau chemin. Le tableau du chemin n'est pas destiné à être utilisé pour modifier directement le chemin car l'agent a sa propre logique de chemin interne qui serait corrompue en changeant le tableau du chemin manuellement. Utilisez plutôt get_next_path_position() une fois à chaque trame de physique pour recevoir le point suivant du chemin pour le mouvement de l'agent car cette fonction met également à jour la logique interne du chemin.

---

int get_current_navigation_path_index() const 🔗

Renvoie l'indice sur lequel l'agent est actuellement sur le PackedVector2Array du chemin de navigation.

---

NavigationPathQueryResult2D get_current_navigation_result() const 🔗

Renvoie le résultat de recherche de chemin pour le chemin que l'agent suit actuellement.

---

Vector2 get_final_position() 🔗

Renvoie la position finale accessible du chemin de navigation actuel dans les coordonnées globales. Cette position peut changer si l'agent doit mettre à jour le chemin de navigation, ce qui fait que l'agent émet le signal path_changed.

---

bool get_navigation_layer_value(layer_number: int) const 🔗

Renvoie si la couche spécifiée du masque de bits navigation_layers est activée, étant donné un numéro de couche layer_number entre 1 et 32.

---

RID get_navigation_map() const 🔗

Renvoie le RID de la carte de navigation pour ce nœud NavigationAgent. Cette fonction renvoie toujours la carte définie sur le nœud NavigationAgent et non la carte de l'agent abstrait sur le serveur Navigation. Si la carte de l'agent est changée directement avec l'API de NavigationServer, le nœud NavigationAgent ne sera pas au courant du changement de carte. Utilisez set_navigation_map() pour changer la carte de navigation pour le NavigationAgent et mettre à jour l'agent sur le NavigationServer.

---

Vector2 get_next_path_position() 🔗

Renvoie la position suivante dans les coordonnées globales à laquelle il est possible de se rendre, en s'assurant qu'il n'y a pas d'objets statiques sur le chemin. Si l'agent n'a pas de chemin de navigation, il renverra la position du parent de l'agent. L'utilisation de cette fonction une fois à chaque trame de physique est nécessaire pour mettre à jour la logique interne de chemin du NavigationAgent.

---

float get_path_length() const 🔗

Renvoie la longueur du chemin actuellement calculé. La valeur renvoyée vaut 0.0, si le chemin est encore en calcul ou si aucun calcul n'a pour l'instant été demandé.

---

RID get_rid() const 🔗

Renvoie le RID de cet agent sur le NavigationServer2D.

---

bool is_navigation_finished() 🔗

Renvoie true si la navigation de l'agent est finie. Si la cible est atteignable, la navigation se termine lorsque la cible est atteinte. Si la cible est inatteignable, la navigation se termine lorsque le dernier point du chemin est atteint.

Note : Lorsque cette propriété vaut true, préférez cesser d'appeler les fonctions de mise à jour comme get_next_path_position(). Cela évite des tremblements (jitter) chez l'agent fixe en raison de l'appel répété à des mises à jour du chemin.

---

bool is_target_reachable() 🔗

Renvoie true si get_final_position() se trouve à une distance à target_desired_distance de la position cible target_position.

---

bool is_target_reached() const 🔗

Renvoie true si l'agent a atteint la cible, c'est-à-dire que l'agent s'est déplacé à une distance inférieure à target_desired_distance de la position cible target_position. Il peut ne pas toujours être possible d'atteindre la cible mais il devrait toujours être possible d'atteindre la position finale. Voir get_final_position().

---

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

Selon value, active ou désactive la couche spécifiée dans le masque de bits avoidance_layers, étant donné un numéro de couche layer_number entre 1 et 32.

---

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

Selon value, active ou désactive le masque spécifié dans le masque de bits avoidance_mask, selon un numéro de masque mask_number donné entre 1 et 32.

---

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

Selon value, active ou désactive la couche spécifiée dans le masque de bits navigation_layers, étant donné un numéro de couche layer_number entre 1 et 32.

---

void set_navigation_map(navigation_map: RID) 🔗

Définit le RID de la carte de navigation que ce nœud NavigationAgent devrait utiliser et met à jour l'agent sur le NavigationServer.

---

void set_velocity_forced(velocity: Vector2) 🔗

Remplace la vélocité interne dans la simulation d'évitement de collision par velocity. Lorsqu'un agent est téléporté à une nouvelle position, cette fonction doit être utilisée dans la même trame. Si appelée fréquemment, cette fonction peut coincer des agents.