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

Panoramica della navigazione 2D

Godot fornisce numerosi oggetti, classi e server per facilitare la navigazione e le ricerche di percorsi basate su griglia o su mesh per i giochi 2D e 3D. La sezione seguente fornisce una rapida panoramica di tutti gli oggetti di navigazione disponibili in Godot per le scene 2D e del loro utilizzo principale.

Godot fornisce i seguenti oggetti e classi per la navigazione 2D:

Astar2D
Gli oggetti Astar2D offrono l'opzione di trovare il percorso più breve in un grafico di punti pesati.

La classe AStar2D è più adatta al gameplay 2D basato su celle che non richiede agli attori di raggiungere qualsiasi posizione possibile all'interno di un'area, ma solo posizioni predefinite e distinte.
AstarGrid2D
AstarGrid2D è una variante di AStar2D specializzata per griglie 2D parziali.

AstarGrid2D è più semplice da usare quando applicabile perché non richiede di creare manualmente punti e di collegarli tra loro.
NavigationServer2D
NavigationServer2D fornisce una potente API di server per trovare il percorso più breve tra due posizioni su un'area definita da una mesh di navigazione.

Il NavigationServer è particolarmente adatto per il gameplay 2D in tempo reale che richiede agli attori di raggiungere qualsiasi posizione possibile all'interno di un'area definita da una mesh di navigazione. La navigazione basata su mesh si adatta bene a grandi mondi di gioco, poiché un'area estesa si può spesso definire con un singolo poligono, mentre ciò richiederebbe molte, moltissime celle di griglia.

Il NavigationServer contiene diverse mappe di navigazione, ciascuna composta da regioni contenenti dati di mesh di navigazione. Gli agenti si possono posizionare su una mappa per i calcoli di evasione. I RID servono per fare riferimento a mappe, regioni e agenti interni quando si comunica con il server.
Sono disponibili i seguenti tipi di RID per il NavigationServer.
RID di NavMap
Riferimento a una mappa di navigazione specifica che contiene regioni e agenti. La mappa tenterà di unire le mesh di navigazione delle regioni in base alla prossimità. La mappa sincronizzerà regioni e agenti a ogni frame di fisica.

RID di NavRegion
Riferimento a una specifica regione di navigazione che può contenere dati di mesh di navigazione. La regione si può abilitare/disabilitare o il suo utilizzo si può limitare con una maschera di bit di strati di navigazione.

RID di NavLink
Riferimento a un collegamento di navigazione specifico che collega due posizioni di mesh di navigazione su distanze arbitrarie.

RID di NavAgent
Riferimento a uno specifico agente di evasione. L'evasione è specificata da un valore di raggio.

RID NavObstacle
Riferimento a uno specifico ostacolo di evasione utilizzato per influenzare e limitare le velocità di evasione degli agenti.

I seguenti nodi dell'albero di scene sono disponibili come supporto per lavorare con l'API del NavigationServer2D.

Nodo NavigationRegion2D
Un nodo che contiene una risorsa NavigationPolygon che definisce una mesh di navigazione per il NavigationServer2D.
- La regione può essere abilitata/disabilitata.
- L'uso nelle ricerche di percorsi può essere ulteriormente limitato tramite la maschera di bit navigation_layers.
- Il NavigationServer2D unirà le mesh di navigazione delle regioni in base alla prossimità per una mesh di navigazione combinata.
Node NavigationLink2D
Un nodo che collega due posizioni su mesh di navigazione su distanze arbitrarie per le ricerche di percorsi.
- Il collegamento può essere abilitato/disabilitato.
- Il collegamento può essere unidirezionale o bidirezionale.
- L'uso nelle ricerche di percorsi può essere ulteriormente limitato tramite la maschera di bit navigation_layers.
I collegamenti indicano alla ricerche che esiste una connessione e a quale costo. La gestione e lo spostamento effettivi degli agenti devono avvenire tramite script personalizzati.
Node NavigationAgent2D
Un nodo ausiliare utilizzato per facilitare le chiamate comuni all'API del NavigationServer2D per le ricerche di percorsi e per l'evasione. Utilizza questo nodo con un nodo genitore che eredita Node2D.
Nodo NavigationObstacle2D
Un nodo che si può utilizzare per influenzare e limitare la velocità di evasione degli agenti abilitati all'evasione. Questo nodo NON influenza le ricerche di percorso degli agenti. Per farlo, è necessario modificare le mesh di navigazione.

Le mesh di navigazione 2D sono definite con le seguenti risorse:

Risorsa NavigationPolygon
Una risorsa che contiene dati di mesh di navigazione 2D. Fornisce strumenti di disegno poligonale per definire aree di navigazione all'interno dell'Editor e in fase di esecuzione.
- Il nodo NavigationRegion2D utilizza questa risorsa per definire la propria area di navigazione.
- Il NavigationServer2D utilizza questa risorsa per aggiornare la mesh di navigazione delle singole regioni.
- L'editor di TileSet crea e utilizza questa risorsa internamente quando definisce le aree di navigazione dei tasselli.

Vedi anche

È possibile osservare come funziona la navigazione 2D attraverso i progetti demo 2D Navigation Polygon e Grid-based Navigation with AStarGrid2D.

Configurazione per una scena 2D

I passaggi seguenti mostrano la configurazione di base per una navigazione minimamente praticabile in 2D. Utilizza il NavigationServer2D e un NavigationAgent2D per il movimento nel percorso.

Aggiungere un nodo NavigationRegion2D alla scena.
Cliccare sul nodo regione e aggiungere una nuova risorsa NavigationPolygon a esso.
Definire l'area di navigazione movibile con lo strumento di disegno di NavigationPolygon. Quindi cliccare sul pulsante Bake NavigationPolygon sulla barra degli strumenti.

Nota

La mesh di navigazione definisce l'area in cui un attore può posizionarsi e muoversi rispetto al suo centro. Lasciare un margine sufficiente tra i bordi del poligono di navigazione e gli oggetti di collisione per evitare che gli attori che seguono un percorso si blocchino ripetutamente nelle collisioni.
Aggiungere un nodo CharacterBody2D nella scena con una forma di collisione basilare e uno sprite o una mesh per poterlo vedere.
Aggiungere un nodo NavigationAgent2D sotto il nodo CharacterBody2D.
Aggiungiamo il seguente script al nodo CharacterBody2D. Ci assicuriamo di impostare un obiettivo di movimento dopo che la scena è stata caricata completamente e il NavigationServer ha avuto il tempo di sincronizzarsi.

extends CharacterBody2D

var movement_speed: float = 200.0
var movement_target_position: Vector2 = Vector2(60.0,180.0)

@onready var navigation_agent: NavigationAgent2D = $NavigationAgent2D

func _ready():
    # These values need to be adjusted for the actor's speed
    # and the navigation layout.
    navigation_agent.path_desired_distance = 4.0
    navigation_agent.target_desired_distance = 4.0

    # Make sure to not await during _ready.
    actor_setup.call_deferred()

func actor_setup():
    # Wait for the first physics frame so the NavigationServer can sync.
    await get_tree().physics_frame

    # Now that the navigation map is no longer empty, set the movement target.
    set_movement_target(movement_target_position)

func set_movement_target(movement_target: Vector2):
    navigation_agent.target_position = movement_target

func _physics_process(delta):
    if navigation_agent.is_navigation_finished():
        return

    var current_agent_position: Vector2 = global_position
    var next_path_position: Vector2 = navigation_agent.get_next_path_position()

    velocity = current_agent_position.direction_to(next_path_position) * movement_speed
    move_and_slide()

using Godot;

public partial class MyCharacterBody2D : CharacterBody2D
{
    private NavigationAgent2D _navigationAgent;

    private float _movementSpeed = 200.0f;
    private Vector2 _movementTargetPosition = new Vector2(70.0f, 226.0f);

    public Vector2 MovementTarget
    {
        get { return _navigationAgent.TargetPosition; }
        set { _navigationAgent.TargetPosition = value; }
    }

    public override void _Ready()
    {
        base._Ready();

        _navigationAgent = GetNode<NavigationAgent2D>("NavigationAgent2D");

        // These values need to be adjusted for the actor's speed
        // and the navigation layout.
        _navigationAgent.PathDesiredDistance = 4.0f;
        _navigationAgent.TargetDesiredDistance = 4.0f;

        // Make sure to not await during _Ready.
        Callable.From(ActorSetup).CallDeferred();
    }

    public override void _PhysicsProcess(double delta)
    {
        base._PhysicsProcess(delta);

        if (_navigationAgent.IsNavigationFinished())
        {
            return;
        }

        Vector2 currentAgentPosition = GlobalTransform.Origin;
        Vector2 nextPathPosition = _navigationAgent.GetNextPathPosition();

        Velocity = currentAgentPosition.DirectionTo(nextPathPosition) * _movementSpeed;
        MoveAndSlide();
    }

    private async void ActorSetup()
    {
        // Wait for the first physics frame so the NavigationServer can sync.
        await ToSignal(GetTree(), SceneTree.SignalName.PhysicsFrame);

        // Now that the navigation map is no longer empty, set the movement target.
        MovementTarget = _movementTargetPosition;
    }
}

Nota

Nel primo frame, la mappa del NavigationServer non ha sincronizzato i dati delle regioni e qualsiasi query di percorso restituirà un valore vuoto. Attendere la sincronizzazione del NavigationServer, attendendo un frame nello script.