Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Aperçu de la navigation 3D¶

Godot fournit plusieurs objets, classes et serveurs pour faciliter la navigation et la recherche de chemin, basées sur des grilles ou des meshs, pour des jeux-vidéo en 2D et 3D. Les sections suivantes fournissent un aperçu rapide de tous les objets disponibles liés à la navigation dans Godot pour les scènes 3D et leurs utilisations primaires.

Godot fournit les objets et classes pour la navigation en 3D suivants :

Astar3D
Les objets Astar3D fournissent une option pour trouver le chemin le plus court dans un graphe de points pondérés.

La classe AStar3D est plus appropriée à un gameplay 3D basé sur des cellules qui ne requièrent pas aux acteurs d'atteindre n'importe quelle position à l'intérieur d'une zone, mais uniquement des positions distinctes et prédéfinies.
NavigationServer3D
NavigationServer3D fournit une API de serveur puissante pour trouver le chemin le plus court entre deux position dans une zone définie par un mesh de navigation.

Le NavigationServer est plus approprié pour un gameplay 3D en temps réel qui requiert les acteurs d'atteindre n'importe quelle position possible à l'intérieur d'une zone définie par un mesh de navigation. La navigation basée sur les meshs s'adapte bien aux grands univers de jeu puisqu'une grande zone peut souvent être définie avec un polygone seul alors qu'il faudrait beaucoup, beaucoup de cellules de grille.

The NavigationServer holds different navigation maps that each consist of regions that hold navigation mesh data. Agents can be placed on a map for avoidance calculation. RIDs are used to reference internal maps, regions, and agents when communicating with the server.
The following NavigationServer RID types are available.
NavMap RID
Reference to a specific navigation map that holds regions and agents. The map will attempt to join the navigation meshes of the regions by proximity. The map will synchronize regions and agents each physics frame.

NavRegion RID
Reference to a specific navigation region that can hold navigation mesh data. The region can be enabled / disabled or the use restricted with a navigation layer bitmask.

NavLink RID
Reference to a specific navigation link that connects two navigation mesh positions over arbitrary distances.

NavAgent RID
Référence à une agent d'évitement spécifique. L'évitement est définit par une valeur de rayon.

NavObstacle RID
Reference to a specific avoidance obstacle used to affect and constrain the avoidance velocity of agents.

Les nœuds de hiérarchie suivants sont disponibles en tant qu'aide pour travailler avec l'API NavigationServer3D.

Nœud NavigationRegion3D
Un nœud qui tient une ressource de mesh de navigation qui définit un mesh de navigation pour le NavigationServer3D.
- The region can be enabled / disabled.
- The use in pathfinding can be further restricted through the navigation_layers bitmask.
- Le NavigationServer3D rejoindra les meshs de navigation des régions par proximité pour un mesh de navigation combiné.
Nœud NavigationLink3D
A Node that connects two positions on navigation meshes over arbitrary distances for pathfinding.
- The link can be enabled / disabled.
- The link can be made one-way or bidirectional.
- The use in pathfinding can be further restricted through the navigation_layers bitmask.
Links tell the pathfinding that a connection exists and at what cost. The actual agent handling and movement needs to happen in custom scripts.
Nœud NavigationAgent3D
Un nœud assistant pour faciliter les appels communs de l'API NavigationServer3D pour la recherche de chemin et l'évitement. Utilisez ce nœud avec un nœud parent héritant de Node3D.
Nœud NavigationObstacle3D
A Node that can be used to affect and constrain the avoidance velocity of avoidance enabled agents. This Node does NOT affect the pathfinding of agents. You need to change the navigation meshes for that instead.

Les meshs de navigation 3D sont définis avec les ressources suivantes :

Ressource NavigationMesh
Une ressource qui tient les données de mesh de navigation 3D. Elle fournit des options de précalcul de géométrie 3D pour définir des zones de navigation à l'intérieur de l'éditeur ainsi qu'à l’exécution.
- Le nœud NavigationRegion3D utilise cette ressource pour définir sa zone de navigation.
- Le NavigationServer3D utilise cette ressource pour mettre à jour le mesh de navigation des régions individuelles.
- L'éditeur GridMap utilise cette ressource lorsque des meshs de navigation spécifiques sont définis pour chaque cellule de la grille.

Voir aussi

Vous pouvez voir comment la navigation 3D fonctionne en utilisant le projet de démonstration de navigation 3D.

Configuration pour une scène 3D¶

The following steps show a basic setup for minimal viable navigation in 3D. It uses the NavigationServer3D and a NavigationAgent3D for path movement.

Add a NavigationRegion3D Node to the scene.
Click on the region node and add a new NavigationMesh Resource to the region node.
Add a new MeshInstance3D node as a child of the region node.
Select the MeshInstance3D node and add a new PlaneMesh and increase the xy size to 10.
Select the region node again and press the "Bake Navmesh" button on the top bar.
Now a transparent navigation mesh appears that hovers some distance on top of the PlaneMesh.
Add a CharacterBody3D node in the scene with a basic collision shape and some mesh for visuals.
Add a NavigationAgent3D node below the character node.
Add a script to the CharacterBody3D node with the following content. We make sure to set a movement target after the scene has fully loaded and the NavigationServer had time to sync. Also, add a Camera3D and some light and environment to see something.

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.
    call_deferred("actor_setup")

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;
    }
}

Note

On the first frame the NavigationServer map has not synchronized region data and any path query will return empty. Wait for the NavigationServer synchronization by awaiting one frame in the script.