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'evitamento delle collisioni RVO. L'evitamento 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 evitamento 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 evitamento 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'evitamento con molti agenti registrati ha un impatto notevole sulle prestazioni e dovrebbe essere abilitata solo sugli agenti che la richiedono al momento.
Un campo di bit che determina gli strati di evitamento 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 evitamento 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 🔗
Il raggio massimo consentito in unità mondiali che il percorso restituito può avere dall'inizio del percorso. Il percorso verrà troncato quando supera questo raggio. Rispetto a path_return_max_length, questo consente all'agente di andare molto più lontano, se ha bisogno di aggirare un angolo.
Nota: Questo eseguirà un ritaglio sferico, considerando solo i punti effettivi del percorso della mesh di navigazione, con la prima posizione del percorso che corrisponde al centro della sfera.
float path_search_max_distance = 0.0 🔗
La distanza massima che un poligono cercato può avere dal poligono di partenza, prima che il pathfinding annulli la ricerca di un percorso verso il poligono di destinazione (potenzialmente irraggiungibile o molto lontano). In questo caso, il pathfinding si azzera e crea un percorso dal poligono di partenza al poligono trovato più vicino alla posizione di destinazione fino a quel momento. Un valore pari o inferiore a 0 è considerato illimitato. In caso di valore illimitato, il pathfinding cercherà in tutti i poligoni collegati al poligono di partenza finché non verrà trovato il poligono di destinazione o finché non saranno esaurite tutte le opzioni di ricerca disponibili.
int path_search_max_polygons = 4096 🔗
Il numero massimo di poligoni ricercati, prima che il pathfinding annulli la ricerca di un percorso verso il poligono di destinazione (potenzialmente irraggiungibile o molto lontano). In questo caso, il pathfinding si azzera e crea un percorso dal poligono di partenza al poligono trovato più vicino alla posizione di destinazione fino a quel momento. Un valore pari o inferiore a 0 è considerato illimitato. In caso di valore illimitato, il pathfinding cercherà in tutti i poligoni collegati al poligono di partenza finché non verrà trovato il poligono di destinazione o finché non saranno esaurite tutte le opzioni di ricerca poligonale disponibili.
PathfindingAlgorithm pathfinding_algorithm = 0 🔗
void set_pathfinding_algorithm(value: PathfindingAlgorithm)
PathfindingAlgorithm get_pathfinding_algorithm()
Algoritmo di ricerca del percorso utilizzato nella ricerca del percorso.
Il raggio dell'agente di evitamento. Questo è il "corpo" dell'agente di evitamento e non il raggio di partenza della manovra di evitamento (che è controllato da neighbor_distance).
Non influisce sulla ricerca normale del percorso. Per modificare il raggio di ricerca del percorso di un attore, prepara le risorse NavigationMesh con una proprietà NavigationMesh.agent_radius diversa e utilizza mappe di navigazione diverse per ogni dimensione dell'attore.
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ò aiutare a 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 evitamento 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 evitamento 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 evitamento delle collisioni, sono sicure rispetto agli ostacoli di evitamento statici. Maggiore è il numero, più presto l'agente risponderà agli ostacoli di evitamento 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'evitamento 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 di avoidance_layers è abilitato, fornito un layer_number tra 1 e 32.
bool get_avoidance_mask_value(mask_number: int) const 🔗
Restituisce se la maschera specificata di avoidance_mask è abilitata, fornito 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) 🔗
In base a value, attiva o disattiva lo strato specificato in avoidance_layers, fornito un layer_number tra 1 e 32.
void set_avoidance_mask_value(mask_number: int, value: bool) 🔗
In base a value, attiva o disattiva la maschera specificata in avoidance_mask, fornito 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 evitamento delle collisioni con velocity. Quando un agente viene teletrasportato in una nuova posizione, questa funzione si dovrebbe usare nello stesso frame. Se chiamata spesso, questa funzione può bloccare gli agenti.