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

NavigationAgent2D

节点继承关系

继承链：Node -> NavigationAgent2D

Node

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

定义

NavigationAgent2D 是一个"AI 司机"——你只需要告诉它"我要去那里"（设置目标位置），它就会自动在 NavigationRegion2D 定义的可行走区域内规划路线，并告诉你下一步该往哪个方向走。它不负责真正移动角色，而是像一个 GPS 导航仪一样不断告诉你"前方 50 米左转"。

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

节点用途

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

使用场景

1. 敌人 AI 追击玩家：设置目标为玩家位置，敌人自动寻路追过来
2. NPC 日常巡逻：给 NPC 设置多个巡逻点，依次导航过去
3. RTS 部队移动：点击地图上的位置，选中的单位自动寻路过去
4. 跟随系统：同伴角色自动跟随玩家，保持一定距离

常用节点搭配

搭配节点	搭配方式
NavigationRegion2D	Agent 必须在 Region 覆盖的区域内才能正常寻路
CharacterBody2D	最常见的搭配，用 MoveAndSlide() 执行实际移动
NavigationObstacle2D	作为动态障碍物，Agent 会自动绕开它
NavigationLink2D	连接跳跃点、传送门等不连续区域

生效必备素材/资源

• NavigationRegion2D：场景中必须有至少一个 NavigationRegion2D 且分配了 NavigationMesh，否则 Agent 无法寻路
• 父节点：通常作为 CharacterBody2D 或 RigidBody2D 的子节点，这样 Agent 的位置自动跟随物理体

节点属性与信号

属性

属性名	类型	默认值	说明
target_position	Vector2	—	目标位置，Agent 会自动计算到这里的路径
path_desired_distance	float	20.0	到达路径点的距离阈值，小于此值就认为已到达该路径点
target_desired_distance	float	5.0	到达目标的距离阈值，小于此值触发 target_reached 信号
avoidance_enabled	bool	false	是否启用避障，开启后会自动绕开其他 Agent 和 Obstacle
radius	float	10.0	角色半径，避障时用来判断碰撞范围
max_speed	float	100.0	最大移动速度，避障系统会参考此值
velocity	Vector2	—	当前速度（只读，由避障系统计算）

信号

信号名	触发时机
path_changed	路径重新计算时（比如目标位置变了或障碍物移动了）
target_reached	Agent 到达目标位置时（距离小于 target_desired_distance）
navigation_finished	整条路径走完时
velocity_computed(safe_velocity)	避障速度计算完成时，返回一个安全的移动速度

常用方法

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

代码示例

AI 角色自动寻路到目标位置

以下示例让一个 AI 角色自动导航到鼠标点击的位置：

C

using Godot;

public partial class AICharacter : CharacterBody2D
{
    [Export] public float ExMoveSpeed = 200.0f;

    private NavigationAgent2D _agent;
    private Vector2 _movementDirection = Vector2.Zero;

    public override void _Ready()
    {
        _agent = GetNode<NavigationAgent2D>("NavigationAgent2D");

        // 监听目标到达信号
        _agent.TargetReached += OnTargetReached;
    }

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

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

        // 计算朝向下一个路径点的方向
        Vector2 direction = (nextPos - GlobalPosition).Normalized();

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

    /// <summary>
    /// 设置目标位置（可由外部调用，比如点击地图时）
    /// </summary>
    public void MoveTo(Vector2 targetPosition)
    {
        _agent.TargetPosition = targetPosition;
    }

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

GDScript

extends CharacterBody2D

@export var move_speed: float = 200.0

@onready var _agent: NavigationAgent2D = $NavigationAgent2D

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: Vector2 = _agent.get_next_path_position()

    # 计算朝向下一个路径点的方向
    var direction: Vector2 = (next_pos - global_position).normalized()

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

## 设置目标位置（可由外部调用，比如点击地图时）
func move_to(target_position: Vector2) -> void:
    _agent.target_position = target_position

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