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 3D

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 3D e del loro utilizzo principale.

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

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

La classe AStar3D è più adatta al gameplay 3D basato su celle che non richiede agli attori di raggiungere qualsiasi posizione possibile all'interno di un'area, ma solo posizioni predefinite e distinte.
NavigationServer3D
NavigationServer3D 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 3D 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 è definita 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 NavigationServer3D.

Node NavigationRegion3D
Un nodo che contiene una risorsa NavigationMesh che definisce una mesh di navigazione per il NavigationServer3D.
- La regione può essere abilitata/disabilitata.
- L'uso nelle ricerche di percorsi può essere ulteriormente limitato tramite la maschera di bit navigation_layers.
- Il NavigationServer3D unirà le mesh di navigazione delle regioni in base alla prossimità per una mesh di navigazione combinata.
Nodo NavigationLink3D
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.
Nodo NavigationAgent3D
Un nodo ausiliare utilizzato per facilitare le chiamate comuni all'API del NavigationServer3D per le ricerche di percorsi e per l'evasione. Utilizza questo nodo con un nodo genitore che eredita Node3D.
Nodo NavigationObstacle3D
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 3D sono definite con le seguenti risorse:

Risorsa NavigationMesh
Una risorsa che contiene dati di mesh di navigazione 3D. Fornisce opzioni di precalcolo di geometria 3D per definire aree di navigazione all'interno dell'Editor e in fase di esecuzione.
- Il nodo NavigationRegion3D utilizza questa risorsa per definire la propria area di navigazione.
- Il NavigationServer3D utilizza questa risorsa per aggiornare la mesh di navigazione delle singole regioni.
- L'editor di GridMap utilizza questa risorsa quando vengono definite mesh di navigazione specifiche per ogni cella della griglia.

Vedi anche

È possibile osservare il funzionamento della navigazione 3D in azione attraverso il progetto demo di Navigazione 3D.

Preparazione per una scena 3D

I passaggi seguenti mostrano una configurazione di base per una navigazione minimamente praticabile in 3D. Utilizza il NavigationServer3D e un NavigationAgent3D per il movimento nel percorso.

Aggiungere un nodo NavigationRegion3D alla scena.
Cliccare sul nodo regione e aggiungere una nuova risorsa NavigationMesh a esso.
Aggiungere un nuovo nodo MeshInstance3D come figlio del nodo regione.
Selezionare il nodo MeshInstance3D e aggiungere un nuovo PlaneMesh, quindi aumentare le dimensioni xy a 10.
Selezionare nuovamente il nodo regione e premere il pulsante "Bake Navmesh" sulla barra in alto.
Ora appare una mesh di navigazione trasparente che fluttua a una certa distanza sopra il PlaneMesh.
Aggiungere un nodo CharacterBody3D nella scena con una forma di collisione basilare e uno sprite o una mesh per poterlo vedere.
Aggiungere un nodo NavigationAgent3D sotto il nodo CharacterBody3D.
Aggiungiamo uno script al nodo CharacterBody3D con il seguente contenuto. Assicuriamoci di impostare un obiettivo di movimento dopo che la scena è stata caricata completamente e il NavigationServer ha avuto il tempo di sincronizzarsi. Aggiungiamo anche una Camera3D e un po' di luce e ambiente per vedere qualcosa.

extends CharacterBody3D

var movement_speed: float = 2.0
var movement_target_position: Vector3 = Vector3(-3.0,0.0,2.0)

@onready var navigation_agent: NavigationAgent3D = $NavigationAgent3D

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

    # 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: Vector3):
    navigation_agent.set_target_position(movement_target)

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

    var current_agent_position: Vector3 = global_position
    var next_path_position: Vector3 = 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 MyCharacterBody3D : CharacterBody3D
{
    private NavigationAgent3D _navigationAgent;

    private float _movementSpeed = 2.0f;
    private Vector3 _movementTargetPosition = new Vector3(-3.0f, 0.0f, 2.0f);

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

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

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

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

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

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

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

        Vector3 currentAgentPosition = GlobalTransform.Origin;
        Vector3 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.