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

Visão geral de navegação 3D

O Godot fornece múltiplos objetos, classes e servidores para facilitar a navegação baseada em grades ou malhas e a busca de caminhos (pathfinding) para jogos 2D e 3D. A seção a seguir fornece uma visão geral rápida de todos os objetos relacionados à navegação disponíveis no Godot para cenas 3D e seu uso principal.

O Godot fornece os seguintes objetos e classes para navegação 3D:

Astar3D
Objetos Astar3D fornecem uma opção para encontrar o caminho mais curto em um grafo de pontos ponderados.

A classe AStar3D é mais adequada para jogabilidade 3D baseada em células que não exige que os atores alcancem qualquer posição possível dentro de uma área, mas apenas posições predefinidas e distintas.
NavigationServer3D
O NavigationServer3D fornece uma poderosa API de servidor para encontrar o caminho mais curto entre duas posições em uma área definida por uma malha de navegação.

O NavigationServer é mais adequado para jogabilidade 3D em tempo real que exige que os atores alcancem qualquer posição possível dentro de uma área definida por uma malha de navegação. A navegação baseada em malhas escala bem com grandes mundos de jogo, pois uma grande área geralmente pode ser definida com um único polígono, quando exigiria muitas e muitas células de grade.

O NavigationServer possui mapas de navegação diferentes, cada um composto por regiões que contêm dados de malha de navegação. Os agentes podem ser colocados em um mapa para o cálculo de desvio (avoidance). RIDs são usados para referenciar mapas internos, regiões e agentes ao se comunicar com o servidor.
Os seguintes tipos de RID do NavigationServer estão disponíveis.
RID do NavMap
Referência a um mapa de navegação específico que contém regiões e agentes. O mapa tentará unir as malhas de navegação das regiões por proximidade. O mapa sincronizará as regiões e os agentes a cada quadro de física.

RID da NavRegion
Referência a uma região de navegação específica que pode conter dados de malha de navegação. A região pode ser ativada/desativada ou ter seu uso restrito com uma máscara de bits de camada de navegação (navigation layer bitmask).

RID do NavLink
Referência a um link de navegação específico que conecta duas posições de malha de navegação ao longo de distâncias arbitrárias.

RID do NavAgent
Referência a um agente de desvio específico. O desvio é definido por um valor de raio.

RID de NavObstacle
Referência a um obstáculo de desvio específico usado para afetar e restringir a velocidade de desvio dos agentes.

Os seguintes nós da árvore de cenas estão disponíveis como auxiliares para trabalhar com a API do NavigationServer3D.

Nó NavigationRegion3D
Um Nó que contém um recurso Navigation Mesh que define uma malha de navegação para o NavigationServer3D.
- A região pode ser ativada / desativada.
- O uso na busca de caminhos pode ser ainda mais restrito através da máscara de bits navigation_layers.
- O NavigationServer3D unirá as malhas de navegação das regiões por proximidade para formar uma malha de navegação combinada.
Nó NavigationLink3D
Um Nó que conecta duas posições em malhas de navegação ao longo de distâncias arbitrárias para a busca de caminhos.
- O link pode ser ativado / desativado.
- O link pode ser configurado como de mão única (one-way) ou bidirecional.
- O uso na busca de caminhos pode ser ainda mais restrito através da máscara de bits navigation_layers.
Os links informam à busca de caminhos que existe uma conexão e com qual custo. A manipulação e o movimento reais do agente precisam acontecer em scripts personalizados.
Nó NavigationAgent3D
Um Nó auxiliar usado para facilitar chamadas comuns da API do NavigationServer3D para busca de caminhos e desvio. Use este Nó com um Nó pai que herde de Node3D.
Nó NavigationObstacle3D
Um Nó que pode ser usado para afetar e restringir a velocidade de desvio de agentes com o desvio ativado. Este Nó NÃO afeta a busca de caminhos dos agentes. Em vez disso, você precisa alterar as malhas de navegação para isso.

As malhas de navegação 3D são definidas com as seguintes recursos:

Recurso NavigationMesh
Um recurso que contém dados de malha de navegação 3D. Ele fornece opções de geração (baking) de geometria 3D para definir áreas de navegação dentro do Editor, bem como em tempo de execução.
- O Nó NavigationRegion3D usa este recurso para definir sua área de navegação.
- O NavigationServer3D usa este recurso para atualizar a malha de navegação de regiões individuais.
- O Editor de GridMap usa este recurso quando malhas de navegação específicas são definidas para cada célula da grade.

Ver também

Você pode ver como a navegação 3D funciona em ação usando o projeto de demonstração de Navegação 3D.

Configuração para cena 3D

Os passos a seguir mostram uma configuração básica para uma navegação mínima viável em 3D. Ela usa o NavigationServer3D e um NavigationAgent3D para o movimento pelo caminho.

Adicione um Nó NavigationRegion3D à cena.
Clique no nó da região e adicione um novo Recurso NavigationMesh ao nó da região.
Adicione um novo nó MeshInstance3D como filho do nó de região.
Selecione o nó MeshInstance3D, adicione um novo PlaneMesh e aumente o tamanho xy para 10.
Selecione o nó da região novamente e pressione o botão "Bake Navmesh" na barra superior.
Agora, uma malha de navegação transparente aparece flutuando a uma certa distância no topo do PlaneMesh.
Adicione um nó CharacterBody3D na cena com uma forma de colisão básica e alguma mesh para o visual.
Adicione um nó NavigationAgent3D abaixo do nó do personagem.
Adicione um script ao nó CharacterBody3D com o seguinte conteúdo. Certificamo-nos de definir um alvo de movimento após a cena ter sido totalmente carregada e o NavigationServer ter tido tempo de sincronizar. Além disso, adicione uma Camera3D e um pouco de luz e ambiente para conseguir enxergar alguma coisa.

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

No primeiro quadro, o mapa do NavigationServer não sincronizou os dados da região e qualquer consulta de caminho retornará vazia. Aguarde a sincronização do NavigationServer esperando um quadro no script.