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
Sperimentale: This class may be changed or removed in future versions.
Un agente 2D utilizzato per individuare il percorso verso una posizione evitando gli ostacoli.
Descrizione
Un agente 2D utilizzato per trovare il percorso verso una posizione evitando ostacoli statici e dinamici. Il calcolo può essere utilizzato dal nodo genitore per spostarlo dinamicamente lungo il percorso. Richiede dati di navigazione per funzionare correttamente.
Gli ostacoli dinamici vengono evitati attraverso l'evasione delle collisioni RVO. L'evasione viene calcolata prima della fisica, quindi le informazioni di ricerca del percorso possono essere utilizzate in modo sicuro nella passaggio di fisica.
Nota: Dopo aver impostato la proprietà target_position, il metodo get_next_path_position() deve essere utilizzato una volta per ogni frame di fisica per aggiornare la logica interna del percorso dell'agente di navigazione. La posizione del vettore che restituisce deve essere utilizzata come posizione successiva del movimento per il nodo genitore dell'agente.
Nota: Diversi metodi di questa classe, come get_next_path_position(), possono attivare un nuovo calcolo del percorso. Chiamarli nel callback al segnale di un agente, come waypoint_reached, può causare una ricorsione infinita. Si consiglia di chiamare questi metodi nel processo di fisica o, in alternativa, ritardarne la chiamata fino alla fine del frame (vedi Object.call_deferred() o Object.CONNECT_DEFERRED).
Tutorial
Proprietà
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
BitField[PathMetadataFlags] |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Metodi
distance_to_target() const |
|
get_avoidance_layer_value(layer_number: int) const |
|
get_avoidance_mask_value(mask_number: int) const |
|
get_current_navigation_path() const |
|
get_current_navigation_result() const |
|
get_navigation_layer_value(layer_number: int) const |
|
get_navigation_map() const |
|
get_path_length() const |
|
get_rid() const |
|
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) |
Segnali
link_reached(details: Dictionary) 🔗
Segnala che l'agente ha raggiunto un collegamento di navigazione. Emesso quando l'agente si sposta entro path_desired_distance dalla posizione successiva del percorso quando tale posizione è un collegamento di navigazione.
Il dizionario dei dettagli può contenere le seguenti chiavi a seconda del valore di path_metadata_flags:
position: la posizione iniziale del collegamento che è stato raggiunto.type: sempre NavigationPathQueryResult2D.PATH_SEGMENT_TYPE_LINK.rid: il RID del collegamento.owner: l'oggetto che gestisce il collegamento (solitamente NavigationLink2D).link_entry_position: seownerè disponibile e il proprietario è un NavigationLink2D, conterrà la posizione globale del punto del collegamento in cui l'agente sta entrando.link_exit_position: seownerè disponibile e il proprietario è un NavigationLink2D, conterrà la posizione globale del punto del collegamento da cui l'agente sta uscendo.
navigation_finished() 🔗
Segnala che la navigazione dell'agente è terminata. Se la destinazione è raggiungibile, la navigazione termina quando la destinazione viene raggiunta. Se la destinazione non è raggiungibile, la navigazione termina quando l'ultimo punto del percorso viene raggiunto. Questo segnale viene emesso una sola volta per percorso caricato.
Questo segnale verrà emesso subito dopo target_reached quando la destinazione è raggiungibile.
path_changed() 🔗
Emesso quando l'agente ha dovuto aggiornare il percorso caricato:
perché il percorso era precedentemente vuoto.
perché la mappa di navigazione è cambiata.
perché l'agente si è allontanato dal segmento attuale del percorso rispetto a path_max_distance.
target_reached() 🔗
Segnala che l'agente ha raggiunto la destinazione, ovvero che l'agente si è spostato entro target_desired_distance da target_position. Questo segnale viene emesso una sola volta per percorso caricato.
Questo segnale verrà emesso appena prima di navigation_finished quando la destinazione è raggiungibile.
Potrebbe non essere sempre possibile raggiungere la destinazione, ma dovrebbe essere sempre possibile raggiungere la posizione finale. Vedi get_final_position().
velocity_computed(safe_velocity: Vector2) 🔗
Notifica quando viene calcolata la velocità di evasione delle collisioni. Emesso a ogni aggiornamento fin quando avoidance_enabled è true e l'agente ha una mappa di navigazione.
waypoint_reached(details: Dictionary) 🔗
Segnala che l'agente ha raggiunto un punto. Emesso quando l'agente si sposta entro path_desired_distance dalla posizione successiva del percorso.
Il dizionario dei dettagli potrebbe contenere le seguenti chiavi a seconda del valore di path_metadata_flags:
position: la posizione del punto che è stato raggiunto.type: il tipo della primitiva di navigazione (regione o collegamento) che contiene questo punto.rid: il RID della primitiva di navigazione (regione o collegamento) che lo contiene.owner: l'oggetto che gestisce il primitivo di navigazione contenitore (regione o collegamento).
Descrizioni delle proprietà
bool avoidance_enabled = false 🔗
Se true l'agente è registrato per un callback di evasione RVO su NavigationServer2D. Quando velocity è utilizzato e l'elaborazione è completata, un Vector2 safe_velocity viene ricevuto con una connessione di segnale a velocity_computed. L'elaborazione dell'evasione con molti agenti registrati ha un costo di prestazioni significativo e dovrebbe essere abilitata solo sugli agenti che la richiedono attualmente.
Un campo di bit che determina gli strati di evasione per questo NavigationAgent. Altri agenti con un bit corrispondente sulla avoidance_mask eviteranno questo agente.
Un campo di bit che determina quali altri agenti di evasione e ostacoli questo NavigationAgent eviterà quando un bit corrisponde ad almeno uno dei suoi avoidance_layers.
float avoidance_priority = 1.0 🔗
L'agente non regola la velocità per altri agenti che corrisponderebbero a avoidance_mask ma hanno una avoidance_priority inferiore. Ciò a sua volta causa gli altri agenti con priorità inferiore a regolare ulteriormente le loro velocità per evitare collisioni con questo agente.
Se true mostra visuali di debug per questo agente.
Color debug_path_custom_color = Color(1, 1, 1, 1) 🔗
Se debug_use_custom è true utilizza questo colore per questo agente invece del colore globale.
float debug_path_custom_line_width = -1.0 🔗
Se debug_use_custom è true, utilizza questo spessore di linea per il rendering dei percorsi per questo agente anziché lo spessore di linea globale.
float debug_path_custom_point_size = 4.0 🔗
Se debug_use_custom è true, è utilizzata questa dimensione di punto rasterizzato per renderizzare i punti del percorso per questo agente anziché la dimensione di punto globale.
bool debug_use_custom = false 🔗
Se true utilizza il colore debug_path_custom_color definito per questo agente invece del colore globale.
Il numero massimo di vicini che l'agente può prendere in considerazione.
La velocità massima alla quale un agente può muoversi.
Un campo di bit che determina quali strati di navigazione delle regioni di navigazione questo agente utilizzerà per calcolare un percorso. Modificandolo in fase d'esecuzione, il percorso di navigazione attuale sarà cancellato e uno nuovo ne verrà generato, in base ai nuovi strati di navigazione.
float neighbor_distance = 500.0 🔗
La distanza per cercare altri agenti.
float path_desired_distance = 20.0 🔗
La soglia di distanza prima che un punto del percorso sia considerato raggiunto. Ciò permette agli agenti di non dover raggiungere esattamente un punto sul percorso, ma solo di raggiungere la sua area generale. Se questo valore è impostato troppo alto, il NavigationAgent ignorerà i punti sul percorso, il che può portarlo ad abbandonare la mesh di navigazione. Se questo valore è impostato troppo basso, il NavigationAgent rimarrà bloccato in un ciclo di cambio del percorso perché supererà costantemente la distanza dal punto successivo a ogni aggiornamento nel frame di fisica.
float path_max_distance = 100.0 🔗
La distanza massima consentita all'agente dal percorso ideale alla posizione finale. Ciò può accadere tentando di evitare le collisioni. Quando la distanza massima viene superata, l'agente ricalcola il percorso ideale.
BitField[PathMetadataFlags] path_metadata_flags = 7 🔗
void set_path_metadata_flags(value: BitField[PathMetadataFlags])
BitField[PathMetadataFlags] get_path_metadata_flags()
Informazioni aggiuntive da restituire con il percorso di navigazione.
PathPostProcessing path_postprocessing = 0 🔗
void set_path_postprocessing(value: PathPostProcessing)
PathPostProcessing get_path_postprocessing()
Post-elaborazione del percorso applicata al corridoio del percorso grezzo trovato dall'pathfinding_algorithm.
float path_return_max_length = 0.0 🔗
La lunghezza massima consentita del percorso restituito in unità mondiali. Un percorso verrà troncato quando supera questa lunghezza.
float path_return_max_radius = 0.0 🔗
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 🔗
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 🔗
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()
Algoritmo di ricerca del percorso utilizzato nella ricerca del percorso.
The radius of the avoidance agent. This is the "body" of the avoidance agent and not the avoidance maneuver starting radius (which is controlled by neighbor_distance).
Does not affect normal pathfinding. To change an actor's pathfinding radius bake NavigationPolygon resources with a different NavigationPolygon.agent_radius property and use different navigation maps for each actor size.
float simplify_epsilon = 0.0 🔗
La quantità di semplificazione del percorso in unità mondiali.
Se true una versione semplificata del percorso sarà restituita, con i punti meno critici rimossi. La quantità di semplificazione è controllata da simplify_epsilon. La semplificazione utilizza una variazione dell'algoritmo Ramer-Douglas-Peucker per decimare i punti della curva.
La semplificazione del percorso può essere utile per mitigare vari problemi di seguimento del percorso che possono sorgere con certi tipi di agenti e comportamenti di script. Ad esempio, agenti che "sterzano" o evasione in "campi aperti".
float target_desired_distance = 10.0 🔗
La soglia di distanza prima che la destinazione sia considerata raggiunta. Al raggiungimento della destinazione, target_reached viene emesso e la navigazione termina (vedi is_navigation_finished() e navigation_finished).
È possibile terminare la navigazione in anticipo impostando questa proprietà su un valore maggiore di path_desired_distance (la navigazione terminerà prima di raggiungere l'ultimo punto).
È inoltre possibile terminare la navigazione più vicino alla destinazione rispetto a ogni singola posizione nel percorso impostando questa proprietà su un valore inferiore a path_desired_distance (la navigazione non terminerà subito dopo aver raggiunto l'ultimo punto). Tuttavia, se il valore impostato è troppo basso, l'agente rimarrà bloccato in un ciclo di cambio del percorso perché supererà costantemente la distanza dalla destinazione a ogni aggiornamento nel frame di fisica.
Vector2 target_position = Vector2(0, 0) 🔗
Se impostato, viene richiesto un nuovo percorso di navigazione dalla posizione attuale dell'agente a target_position dal NavigationServer.
float time_horizon_agents = 1.0 🔗
La quantità minima di tempo per cui le velocità di questo agente, calcolate con l'algoritmo di evasione delle collisioni, sono sicure rispetto ad altri agenti. Maggiore è il numero, più presto l'agente risponderà ad altri agenti, ma minore sarà la libertà nella scelta delle sue velocità. Un valore troppo alto rallenterà notevolmente il movimento degli agenti. Deve essere positivo.
float time_horizon_obstacles = 0.0 🔗
La quantità minima di tempo per cui le velocità di questo agente, calcolate con l'algoritmo di evasione delle collisioni, sono sicure rispetto agli ostacoli di evasione statici. Maggiore è il numero, più presto l'agente risponderà agli ostacoli di evasione statici, ma minore sarà la libertà nella scelta delle sue velocità. Un valore troppo alto rallenterà notevolmente il movimento degli agenti. Deve essere positivo.
Vector2 velocity = Vector2(0, 0) 🔗
Imposta la nuova velocità desiderata per l'agente. La simulazione dell'evasione cercherà di soddisfare questa velocità se possibile, ma la modificherà per evitare collisioni con altri agenti e ostacoli. Quando un agente viene teletrasportato in una nuova posizione, usa anche set_velocity_forced() per reimpostare la velocità interna di simulazione.
Descrizioni dei metodi
float distance_to_target() const 🔗
Restituisce la distanza dalla posizione di destinazione, utilizzando la posizione globale dell'agente. È necessario impostare target_position affinché questo valore sia accurato.
bool get_avoidance_layer_value(layer_number: int) const 🔗
Restituisce se lo strato specificato del bitmask avoidance_layers è abilitato, dato un layer_number tra 1 e 32.
bool get_avoidance_mask_value(mask_number: int) const 🔗
Restituisce se la maschera specificata del bitmask avoidance_mask è abilitata, dato un mask_number tra 1 e 32.
PackedVector2Array get_current_navigation_path() const 🔗
Restituisce il percorso attuale di questo agente dall'inizio alla fine in coordinate globali. Il percorso si aggiorna solo quando la posizione di destinazione viene modificata o l'agente richiede di cambiare il percorso. L'array del percorso non si dovrebbe utilizzare nel movimento diretto del percorso, in quanto l'agente ha la sua logica interna del percorso che verrebbe danneggiata se si modifica manualmente l'array del percorso. Utilizza il metodo previsto get_next_path_position() una volta per ogni frame di fisica per ricevere il punto successivo del percorso per il movimento dell'agente poiché tale funzione aggiorna anche la logica interna del percorso.
int get_current_navigation_path_index() const 🔗
Restituisce l'indice sul quale l'agente è attualmente in corso nel PackedVector2Array del percorso di navigazione.
NavigationPathQueryResult2D get_current_navigation_result() const 🔗
Restituisce il risultato della richiesta sul percorso per il percorso che l'agente sta attualmente seguendo.
Vector2 get_final_position() 🔗
Restituisce la posizione finale raggiungibile del percorso di navigazione attuale in coordinate globali. Questa posizione può cambiare se l'agente deve aggiornare il percorso di navigazione, il che provoca l'agente a emettere il segnale path_changed.
bool get_navigation_layer_value(layer_number: int) const 🔗
Restituisce se lo strato specificato della maschera di bit navigation_layers è abilitato o meno, fornito un layer_number tra 1 e 32.
RID get_navigation_map() const 🔗
Restituisce il RID della mappa di navigazione per questo nodo NavigationAgent. Questa funzione restituisce sempre la mappa impostata sul nodo NavigationAgent e non la mappa dell'agente astratto sul NavigationServer. Se la mappa dell'agente viene modificata direttamente con l'API del NavigationServer, il nodo NavigationAgent non sarà a conoscenza della modifica della mappa. Utilizza set_navigation_map() per modificare la mappa di navigazione per NavigationAgent e aggiornare anche l'agente sul NavigationServer.
Vector2 get_next_path_position() 🔗
Restituisce la posizione successiva in coordinate globali in cui è possibile muoversi, assicurandosi che non vi siano oggetti statici nella via. Se l'agente non ha un percorso di navigazione, restituirà la posizione del genitore dell'agente. È necessario usare questa funzione una volta ogni frame di fisica per aggiornare la logica interna del percorso del NavigationAgent.
float get_path_length() const 🔗
Restituisce la lunghezza del percorso attualmente calcolato. Il valore restituito è 0.0, se il percorso è ancora in fase di calcolo o nessun calcolo è stato ancora richiesto.
Restituisce il RID di questo agente sul NavigationServer2D.
bool is_navigation_finished() 🔗
Restituisce true se la navigazione dell'agente è terminata. Se la destinazione è raggiungibile, la navigazione termina quando la destinazione viene raggiunta. Se la destinazione non è raggiungibile, la navigazione termina quando viene raggiunto l'ultimo punto del percorso.
Nota: Quando è true è ideale interrompere la chiamata di funzioni di aggiornamento come get_next_path_position(). Ciò evita di far tremare l'agente a causa di chiamate ripetute per aggiornare il percorso.
Restituisce true se il risultato di get_final_position() è all'interno di target_desired_distance di target_position.
bool is_target_reached() const 🔗
Restituisce true se l'agente ha raggiunto la sua destinazione, ovvero l'agente si è spostato all'interno di target_desired_distance del target_position. Potrebbe non essere sempre possibile raggiungere la destinazione, ma dovrebbe essere sempre possibile raggiungere la posizione finale. Vedi get_final_position().
void set_avoidance_layer_value(layer_number: int, value: bool) 🔗
Basato su value, attiva o disattiva lo strato specificato nel bitmask avoidance_layers, dato un layer_number tra 1 e 32.
void set_avoidance_mask_value(mask_number: int, value: bool) 🔗
Basato su value, attiva o disattiva la maschera specificata nel bitmask avoidance_mask, dato un mask_number tra 1 e 32.
void set_navigation_layer_value(layer_number: int, value: bool) 🔗
In base al value, abilita o disabilita lo strato specificato nella maschera di bit navigation_layers, fornito un layer_number compreso tra 1 e 32.
void set_navigation_map(navigation_map: RID) 🔗
Imposta il RID della mappa di navigazione che questo nodo NavigationAgent dovrebbe utilizzare e aggiorna anche l'agent sul NavigationServer.
void set_velocity_forced(velocity: Vector2) 🔗
Sostituisce la velocità interna nella simulazione di evasione delle collisioni con velocity. Quando un agente è teletrasportato in una nuova posizione, questa funzione dovrebbe essere utilizzata nello stesso frame. Se chiamata spesso, questa funzione può bloccare gli agenti.