最后同步日期：2026-04-15 | Godot 官方原文 — NavigationAgent3D

NavigationAgent3D

节点继承关系

继承链：Node -> NavigationAgent3D

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

NavigationAgent3D 是 NavigationAgent2D 的 3D 版本，同样是一个"AI 司机"，但工作在三维空间中。你告诉它目标位置（一个 Vector3 坐标），它就会在 3D 的导航网格上规划路线，并不断告诉你下一步该往哪个方向走。

使用频率：★★★ 一般常用——几乎所有需要 AI 自动移动的 3D 游戏都需要它

节点用途

• 在 3D 场景中自动计算从当前位置到目标位置的最短路径
• 提供下一个路径点坐标（Vector3），让角色逐点移动
• 支持实时 3D 避障（开启 avoidance_enabled 后会自动绕开其他 Agent）
• 提供到达检测（是否到达目标、路径是否完成）

使用场景

1. 3D 游戏 AI 敌人：设置目标为玩家位置，敌人自动在 3D 地形上寻路追过来
2. 3D NPC 巡逻：给 NPC 设置多个巡逻点，依次导航过去
3. 3D 即时战略：点击地面，选中的单位自动在地形上寻路过去
4. 跟随系统：同伴角色在 3D 环境中自动跟随玩家

常用节点搭配

搭配节点	搭配方式
NavigationRegion3D	Agent 必须在 Region 覆盖的区域内才能正常寻路
CharacterBody3D	最常见的搭配，用 MoveAndSlide() 执行实际移动
NavigationObstacle3D	作为动态障碍物，Agent 会自动绕开它
NavigationLink3D	连接 3D 空间中不连续的区域（比如楼梯两端）

生效必备素材/资源

• NavigationRegion3D：场景中必须有至少一个 NavigationRegion3D 且分配了 NavigationMesh，否则 Agent 无法寻路
• 父节点：通常作为 CharacterBody3D 或 RigidBody3D 的子节点

节点属性与信号

属性

属性名	类型	默认值	说明
target_position	Vector3	—	目标位置，Agent 会自动计算到这里的路径
path_desired_distance	float	20.0	到达路径点的距离阈值
target_desired_distance	float	5.0	到达目标的距离阈值
avoidance_enabled	bool	false	是否启用避障
radius	float	10.0	角色半径，避障碰撞范围
max_speed	float	100.0	最大移动速度
velocity	Vector3	—	当前速度（只读）

信号

信号名	触发时机
path_changed	路径重新计算时
target_reached	到达目标位置时
navigation_finished	整条路径走完时
velocity_computed(safe_velocity)	避障速度计算完成时

常用方法

方法	返回值	说明
get_next_path_position()	Vector3	获取下一个路径点位置
get_current_navigation_path()	PackedVector3Array	获取当前整条路径的所有点
is_target_reached()	bool	是否已到达目标位置
is_navigation_finished()	bool	整条路径是否已走完
set_velocity(velocity)	void	设置期望速度（开启避障时使用）
set_target_position(position)	void	设置目标位置
get_target_position()	Vector3	获取当前目标位置

代码示例

3D AI 角色自动寻路

以下示例让一个 3D AI 角色自动导航到目标位置：

C

using Godot;

public partial class AICharacter3D : CharacterBody3D
{
    [Export] public float ExMoveSpeed = 5.0f;

    private NavigationAgent3D _agent;

    public override void _Ready()
    {
        _agent = GetNode<NavigationAgent3D>("NavigationAgent3D");
        _agent.TargetReached += OnTargetReached;
    }

    public override void _PhysicsProcess(double delta)
    {
        if (_agent.IsNavigationFinished())
            return;

        // 获取下一个路径点位置
        Vector3 nextPos = _agent.GetNextPathPosition();

        // 计算方向（只取 XZ 平面的水平方向）
        Vector3 direction = (nextPos - GlobalPosition);
        direction.Y = 0; // 保持水平移动
        direction = direction.Normalized();

        // 使用 MoveAndSlide 移动
        Velocity = direction * ExMoveSpeed;
        MoveAndSlide();
    }

    /// <summary>
    /// 设置目标位置
    /// </summary>
    public void MoveTo(Vector3 targetPosition)
    {
        _agent.TargetPosition = targetPosition;
    }

    private void OnTargetReached()
    {
        GD.Print("3D AI 已到达目标位置！");
    }
}

GDScript

extends CharacterBody3D

@export var move_speed: float = 5.0

@onready var _agent: NavigationAgent3D = $NavigationAgent3D

func _ready() -> void:
    _agent.target_reached.connect(_on_target_reached)

func _physics_process(_delta: float) -> void:
    if _agent.is_navigation_finished():
        return

    # 获取下一个路径点位置
    var next_pos: Vector3 = _agent.get_next_path_position()

    # 计算方向（只取 XZ 平面的水平方向）
    var direction: Vector3 = next_pos - global_position
    direction.y = 0  # 保持水平移动
    direction = direction.normalized()

    # 使用 move_and_slide 移动
    velocity = direction * move_speed
    move_and_slide()

## 设置目标位置
func move_to(target_position: Vector3) -> void:
    _agent.target_position = target_position

func _on_target_reached() -> void:
    print("3D AI 已到达目标位置！")