Godot NavigationServer2D 完全指南:2D 导航地图、区域、代理与碰撞避免的低层服务器 API

原创2026-10-14 09:08:561,645 阅读
文章标签:文档教程游戏开发

Godot NavigationServer2D 完全指南:2D 导航地图、区域、代理与碰撞避免的低层服务器 API

NavigationServer2D 是 Godot 引擎中负责 2D 导航底层运算的服务接口,它统一管理导航地图(Map)、导航区域(Region)与导航代理(Agent),并通过 RID 对外提供一套线程安全、基于物理帧同步的低层 API。本文以 classes/class_navigationserver2d.rst 类参考文档为骨架,结合仓库内 导航教程 与 ProjectSettings 导航配置 中的实现细节,系统讲解 NavigationServer2D 的全部方法族、信号与枚举,并给出可直接运行的 GDScript 实战示例,帮助你绕过 NavigationAgent 等高层节点、以脚本直接驾驭 Godot 的 2D 导航系统。

一、NavigationServer2D 是什么:职责边界与核心定位

1.1 服务器职责

NavigationServer2D 是 Godot 面向低层 2D 导航访问的服务接口(类参考原文:"A server interface for low-level 2D navigation access")。它继承自 Object,且当前在类参考中标记为 Experimental(未来版本可能改动或移除)。

它具体负责三件事:

  • 维护导航地图(maps)——承载整个 2D 世界可通行区域的抽象空间;
  • 维护导航区域(regions)——地图被划分为若干区域,每个区域由**导航多边形(navigation polygons)**组成;
  • 维护导航代理(agents)——用于碰撞避免(collision avoidance)计算。

需要特别注意职责边界:NavigationServer2D 不处理 AStar2D 与 AStarGrid2D 的 A* 寻路。AStar 系列是独立的基于"点/格图"的最短路径方案,而 NavigationServer2D 是基于导航网格(navigation mesh)的寻路。在 2D 导航总览 navigation_introduction_2d.rst 中明确指出:AStar2D 适合基于格子的玩法(只需到达预定义离散点),而 NavigationServer2D 更适合要求角色能到达导航网格定义区域内任意位置的实时 2D 玩法,且网格导航在大型游戏世界中扩展性更好——一个大区域往往只需一个多边形,而格子方案需要海量单元格。

1.2 RID 引用模型

与 Godot 其他 Server 一样,NavigationServer2D 内部对象(地图、区域、代理等)一律使用 RID(Resource ID) 作为句柄引用。场景树中每个导航相关节点都提供返回自身 RID 的函数:

  • NavigationRegion2D.get_rid()
  • NavigationAgent2D.get_rid()
  • NavigationLink2D.get_rid()
  • NavigationObstacle2D.get_rid()

RID 类型共有五种(见 navigation_introduction_2d.rst):

RID 类型 含义 关键点
NavMap 导航地图 持有区域与代理,按邻近度拼接各区域导航网格,每个物理帧同步
NavRegion 导航区域 持有导航网格数据,可启用/禁用,可用 navigation_layers 位掩码限制用途
NavLink 导航链接 连接两个导航网格位置,可跨越任意距离
NavAgent 避障代理 以 radius 半径参与碰撞避免
NavObstacle 避障障碍物 影响并约束代理的避障速度

所有已创建对象可通过 get_maps() 获取地图 RID 列表(注意:文档明确指出该方法同时返回 2D 与 3D 创建的导航地图,因为技术上 2D/3D 地图并无区别),并通过 free_rid(rid) 销毁指定 RID。

二、同步模型:为什么"所有更改都要等下一个物理帧"

这是理解 NavigationServer2D 最重要的一环。类参考反复强调:

大多数 NavigationServer2D 的更改在下一个物理帧之后才生效,而非立即生效。 这包括场景树中导航节点或脚本对地图、区域、代理所做的全部更改。

底层原因(参见 navigation_using_navigationservers.rst):

  1. 代价昂贵:某些更新(如整张导航地图的重算)非常耗时,需要所有其他对象的最新数据才能正确执行;
  2. 批处理:NavigationServer 把所有"要改状态"的 API 调用放入命令队列,在同步阶段统一执行,因此它是线程安全的——你可以在任意线程发起更改请求,无需担心并发问题(类参考原文:"This server keeps tracks of any call and executes them during the sync phase... using any thread, without worrying.");
  3. 线程池:默认情况下,避障计算等部分功能运行在后台线程池中。

同步时机:同步发生在物理帧中段——场景脚本与节点的输入处理完毕之后。一个物理帧内避障代理的执行顺序(来自教程):

  1. 物理帧开始
  2. _physics_process(delta) 运行
  3. 在 NavigationAgent 节点上设置 velocity 属性
  4. 代理把速度与位置发送给 NavigationServer
  5. NavigationServer 等待同步
  6. 同步并计算所有已注册避障代理的避障速度
  7. NavigationServer 通过信号向每个代理派发 safe_velocity
  8. 代理接收信号并移动父节点(如 move_and_slide 或 linear_velocity)
  9. PhysicsServer 同步
  10. 物理帧结束

由此,在回调里用安全速度移动物理体角色是完全线程/物理安全的——这一切发生在同一物理帧内、PhysicsServer 提交变更并做自身计算之前。

例外:绝大多数 get() 查询函数(只读、不做更改)不需要等待同步;但要注意并非所有数据都会计入当帧更改——例如某帧代理切换了地图,agent_get_map() 在同步前仍返回旧地图。相反,节点自身存储的值是例外:对当帧已更新的值使用节点 getter 时,会返回节点上已更新的值。

2.1 开局与程序化生成的等待技巧

游戏开局或新场景加入时,导航地图尚为空,任何路径查询都会返回空或错误结果。教程推荐做法:用 call_deferred() 延迟执行自定义设置函数(确保所有节点就绪),在设置函数中完成程序化导航构建,然后 await get_tree().physics_frame 等待一次物理帧同步,再进行路径查询。

下面将教程中的 3D 示例改写为 2D 版本,演示完整的"建图 → 建区域 → 建网格 → 等同步 → 查路径"流程:

extends Node2D

func _ready():
    # 延迟调用,确保整个场景树节点已就绪;
    # 否则在 _ready() 中直接 await physics_frame 可能卡住。
    custom_setup.call_deferred()

func custom_setup():
    # 1. 创建新的导航地图并激活。
    var map: RID = NavigationServer2D.map_create()
    NavigationServer2D.map_set_active(map, true)

    # 2. 创建导航区域并挂到地图上。
    var region: RID = NavigationServer2D.region_create()
    NavigationServer2D.region_set_transform(region, Transform2D())
    NavigationServer2D.region_set_map(region, map)

    # 3. 为区域程序化构造一个三角形导航多边形。
    var new_navigation_polygon: NavigationPolygon = NavigationPolygon.new()
    var vertices: PackedVector2Array = PackedVector2Array([
        Vector2(0, 0),
        Vector2(9.0, 0),
        Vector2(0, 9.0)
    ])
    new_navigation_polygon.set_vertices(vertices)
    var polygon: PackedInt32Array = PackedInt32Array([0, 1, 2])
    new_navigation_polygon.add_polygon(polygon)
    NavigationServer2D.region_set_navigation_polygon(region, new_navigation_polygon)

    # 4. 等待 NavigationServer 同步,使更改生效。
    await get_tree().physics_frame

    # 5. 查询路径。
    var start_position: Vector2 = Vector2(0.1, 0.1)
    var target_position: Vector2 = Vector2(1.0, 1.0)
    var path: PackedVector2Array = NavigationServer2D.map_get_path(
        map, start_position, target_position, true
    )
    print("Found a path!")
    print(path)

更稳妥的做法是先用 map_get_iteration_id(map) 判断地图是否已同步过(返回 0 表示从未同步、地图为空),见下文"实战示例"。

三、导航地图(Map)API 全解析

地图是导航世界的容器。Godot 默认为每个根视口的 World2D/World3D 创建一张导航地图,可用 get_world_2d().get_navigation_map() 获取 2D 默认地图 RID(详见 navigation_using_navigationmaps.rst)。

Godot 导航地图与区域划分示意图(来自 navigation_using_navigationmaps 教程)

3.1 地图生命周期与激活

方法 说明
map_create() 创建新地图,返回 RID
map_set_active(map, active) / map_is_active(map) 激活/停用地毯;true 时参与寻路与同步
free_rid(rid) 销毁地图 RID(通用销毁接口)
get_maps() 返回全部已创建地图 RID(含 2D/3D)
map_get_iteration_id(map) 返回地图当前迭代 ID:每次地图变更并同步后递增,0 表示从未同步;达到上限后回绕到 1
map_force_update(map) 已弃用:与异步更新不兼容,仅限单线程上下文自担风险使用

关于 map_force_update(),类参考给出了非常直白的警告:默认地图只在物理帧末尾同步,该函数可立即(重新)计算导航网格与区域连接,使同一帧内能多次查询变化后地图的路径;但它会强制锁定 NavigationServer 并冲刷整个命令队列——所有已排队更新命令(包括其他地图、区域、代理的)都会被执行,只有指定地图做昂贵的网格重算。避障处理与 safe_velocity 信号派发不受影响。文档原话:"With great power comes great responsibility",只建议真正清楚后果的高级用户使用。

3.2 地图配置参数(含 ProjectSettings 默认值)

方法 作用 对应 ProjectSettings 默认值
map_set_cell_size(map, cell_size) / map_get_cell_size 栅格化导航网格顶点用的单元格尺寸,必须与所用导航网格的 cell size 一致 navigation/2d/default_cell_size = 1.0
map_set_edge_connection_margin(map, margin) / map_get_edge_connection_margin 焊接兼容区域边缘用的边缘连接余量 navigation/2d/default_edge_connection_margin = 1.0
map_set_link_connection_radius(map, radius) / map_get_link_connection_radius 链接搜索导航网格多边形的最大半径 navigation/2d/default_link_connection_radius = 4.0
map_set_merge_rasterizer_cell_scale(map, scale) / map_get_merge_rasterizer_cell_scale 内部合并栅格化器单元格缩放,控制合并灵敏度 navigation/2d/merge_rasterizer_cell_scale = 1.0
map_set_use_edge_connections(map, enabled) / map_get_use_edge_connections 是否允许区域内网格在边缘连接余量范围内互相连接 navigation/2d/use_edge_connections = true
map_set_use_async_iterations(map, enabled) / map_get_use_async_iterations 地图同步是否运行在后台线程的异步进程 见 ProjectSettings

以上默认值均可在 class_projectsettings.rst 的 navigation/2d/ 配置段查到(第 1312~1324 行附近)。

3.3 区域连接的判定:edge_connection_margin

类参考对"两个区域如何连通"给出了精确判定规则:

两个区域要相连,必须共享一条相近的边缘。一条边缘被视为与另一条边缘相连,当且仅当它的两个顶点分别与对方边缘的对应顶点距离小于 edge_connection_margin。

2D 导航边缘连接可视化示意(来自 navigation_debug_tools 教程)

也就是说,边缘连接判定是"顶点对顶点"的双重距离检查,而非简单的中点距离。该余量默认 1.0 像素,可在 ProjectSettings 修改,也可用 map_set_edge_connection_margin() 按地图单独设置。若区域间距过大无法边缘连接,则需要 NavigationLink(见第五节)。

3.4 地图内容查询

方法 说明
map_get_regions(map) 返回地图上的全部区域 RID
map_get_agents(map) 返回地图上的全部代理 RID
map_get_links(map) 返回地图上的全部链接 RID
map_get_obstacles(map) 返回地图上的全部障碍物 RID
map_get_closest_point(map, to_point) 返回地图上最接近 to_point 的导航网格表面点
map_get_closest_point_owner(map, to_point) 返回该最近点所属区域 RID
map_get_random_point(map, navigation_layers, uniformly) 返回随机点:uniformly=true 时按区域/多边形/面面积加权(较慢),false 时随机选区域与多边形(较快)

注意:地图之间完全隔离,但区域和避障代理可以切换所属地图(切换在下次同步时生效);一张地图未收到变更时几乎不消耗处理时间。一张地图可容纳近乎无限数量的区域。

3.5 路径查询:map_get_path

map_get_path() 是导航查询的"主力"接口:

var path: PackedVector2Array = NavigationServer2D.map_get_path(
    map,               # 导航地图 RID
    origin,            # 起点 Vector2
    destination,       # 终点 Vector2
    optimize,          # 是否做路径优化(funnel 算法)
    navigation_layers  # 允许进入路径的区域导航层位掩码,默认 1
)
  • optimize = true:路径沿多边形拐角收缩,经过一次额外的 funnel 算法处理,适合多边形大小不一的自由移动网格;
  • optimize = false:路径点放在每条多边形边的中心,适合等大小多边形的纯格子移动(代价是在大面积开放区域产生不必要的绕行)。
  • 返回的 PackedVector2Array 中所有点都保证落在 NavigationPolygon 内:path[0] 是离起点最近的网格位置,path[-1] 是离终点最近的可达位置;若终点所在网格未合并或未连接,路径会止于起点网格上最接近终点的位置。

若需要更丰富的定制查询(路径元数据、区域过滤、路径裁剪、搜索限制等),应使用 query_path()(见第八节)。

四、导航区域(Region)API 全解析

区域是地图的组成单元,通过 NavigationPolygon 资源承载 2D 导航网格数据。场景树中使用 NavigationRegion2D 节点;也可用 region_create() 直接创建(教程提示:用 API 直接创建的必须手动分配地图,且一个区域只能属于一张地图,改挂新地图即离开旧地图)。节点的 global_transform 变化会自动推送(适合移动平台),但缩放不会——导航网格资源无缩放概念,源几何缩放时需完整重建网格(见 navigation_using_navigationregions.rst)。

4.1 区域生命周期

方法 说明
region_create() 创建新区域,返回 RID
region_set_map(region, map) / region_get_map 归属地图
region_set_enabled(region, enabled) / region_get_enabled 启用/禁用;禁用后不参与后续寻路(已存在的路径不会自动更新)
region_set_owner_id(region, owner_id) / region_get_owner_id 管理该区域对象的 ObjectID
region_set_transform(region, transform) / region_get_transform 区域全局变换
region_set_navigation_polygon(region, navigation_polygon) 设置区域导航多边形(NavigationPolygon 资源)

4.2 区域几何与所有权查询

方法 说明
region_get_bounds(region) 返回区域变换后导航网格的轴对齐矩形 Rect2
region_get_closest_point(region, to_point) 区域网格上最接近给定点的位置
region_owns_point(region, point) 判断世界坐标点是否"属于"该区域:即该区域某多边形面到该点的最近距离,不超过地图上所有其他区域网格到该点的距离;等距时先注册的区域胜出(多边形按注册顺序处理)
region_get_connections_count(region) 该区域与地图内其他区域的连接数量
region_get_connection_pathway_start(region, connection) / region_get_connection_pathway_end 连接"门"的起点/终点,connection 取 0 到连接数之间的索引
region_get_random_point(region, navigation_layers, uniformly) 按导航层过滤的随机点(uniformly=true 按面积加权)

文档特别提醒:若不同区域的导航网格互相重叠(应尽量避免),region_owns_point() 的结果可能不符合预期。

4.3 区域寻路代价与导航层

方法 说明
region_set_enter_cost(region, enter_cost) / region_get_enter_cost 进入该区域附加的寻路代价
region_set_travel_cost(region, travel_cost) / region_get_travel_cost 穿越该区域的寻路代价(路径点进入该区域多边形时累加)
region_set_navigation_layers(region, navigation_layers) / region_get_navigation_layers 区域导航层位掩码,用于在 map_get_path() 中筛选允许/拒绝的区域
region_set_use_edge_connections(region, enabled) / region_get_use_edge_connections 该区域是否参与边缘连接(需在地图启用边缘连接的前提下)
region_set_use_async_iterations(region, enabled) / region_get_use_async_iterations 该区域是否使用后台线程异步同步

navigation_layers 是一个 int 位掩码(详见 navigation_using_navigationlayers.rst):若区域没有任何一位与查询参数 navigation_layers 兼容,其网格会在寻路中被跳过。与物理层/可视层类似,可在 ProjectSettings 中命名。相比启用/禁用整块区域,按层筛选是更省性能的替代方案——改变查询层不会触发 NavigationServer 的大规模更新(改变区域层需在下次同步后生效,而改变代理层对下次查询立即生效)。常见位运算辅助函数:

static func is_bitmask_inx_enabled(bitmask: int, index: int) -> bool:
    return bitmask & (1 << index) != 0

static func enable_bitmask_inx(bitmask: int, index: int) -> int:
    return bitmask | (1 << index)

static func disable_bitmask_inx(bitmask: int, index: int) -> int:
    return bitmask & ~(1 << index)

五、导航链接(Link)API:跨越任意距离的连接

当两个区域边缘相距过远(超出 edge_connection_margin)时,边缘连接失效,此时用 NavigationLink 在任意两点间建立连接。典型用途:梯子、跳板、传送点等游戏交互捷径。链接有两端点 start_position 与 end_position,可设 bidirectional 双向通行。

关键机制:链接放置后,会在搜索半径内(全局可在 ProjectSettings navigation/2d/default_link_connection_radius 设置,或按地图用 map_set_link_connection_radius() 单独设置)寻找离两端点最近的导航网格多边形建立边连接;若半径内找不到合法多边形,链接会被自动禁用。

重要局限:链接只告诉寻路"这里存在连接及代价",不提供任何穿越动作。当代理走到链接起点时,需要游戏代码介入(如 Area 触发器触发传送或动画),否则代理只会沿着链接路径直线行走(可能走过无底深坑)。类参考与教程均明确此点(见 navigation_using_navigationlinks.rst)。

5.1 链接方法速查

方法 说明
link_create() 创建链接
link_set_map(link, map) / link_get_map 归属地图
link_set_start_position(link, position) / link_get_start_position 入口位置
link_set_end_position(link, position) / link_get_end_position 出口位置
link_set_bidirectional(link, bidirectional) / link_is_bidirectional 是否双向通行
link_set_enabled(link, enabled) / link_get_enabled 是否参与所属地图寻路
link_set_navigation_layers(link, navigation_layers) / link_get_navigation_layers 导航层位掩码,参与 map_get_path() 筛选
link_set_enter_cost(link, enter_cost) / link_get_enter_cost 进入链接的寻路代价
link_set_travel_cost(link, travel_cost) / link_get_travel_cost 穿越链接的寻路代价
link_set_owner_id(link, owner_id) / link_get_owner_id 管理该链接对象的 ObjectID
link_get_iteration_id(link) 链接迭代 ID:每次变更同步后递增,0 表示从未同步,达到上限回绕到 1

5.2 脚本创建链接的完整示例

extends Node2D

var link_rid: RID
var link_start_position: Vector2 = Vector2(10, 10)
var link_end_position: Vector2 = Vector2(500, 500)

func _ready() -> void:
    link_rid = NavigationServer2D.link_create()

    NavigationServer2D.link_set_owner_id(link_rid, get_instance_id())
    NavigationServer2D.link_set_enter_cost(link_rid, 1.0)
    NavigationServer2D.link_set_travel_cost(link_rid, 1.0)
    NavigationServer2D.link_set_navigation_layers(link_rid, 1)
    NavigationServer2D.link_set_bidirectional(link_rid, true)

    # 启用链接并挂到默认导航地图。
    NavigationServer2D.link_set_enabled(link_rid, true)
    NavigationServer2D.link_set_map(link_rid, get_world_2d().get_navigation_map())

    # 移动到目标全局位置。
    NavigationServer2D.link_set_start_position(link_rid, link_start_position)
    NavigationServer2D.link_set_end_position(link_rid, link_end_position)

六、导航代理(Agent)与碰撞避免

碰撞避免系统通过 agents 实现:为代理设置目标速度,服务器会在每次避障处理后通过回调返回修正后的速度。这是典型的 RVO(Reciprocal Velocity Obstacles)类算法。需牢记类参考的两条关键说明:

  1. 避障系统忽略导航区域:直接使用修正速度可能把代理移出可通行区域,这是避障系统的固有局限,更复杂的情况需要结合物理引擎;
  2. 避障只考虑同一地图上同样注册了避障的其他代理,且避障存在于独立空间,没有导航网格或物理碰撞的任何信息——避障代理在幕后只是平面上不同半径的圆(详见 navigation_using_navigationagents.rst)。

6.1 代理创建与基础属性

方法 说明
agent_create() 创建代理,返回 RID
agent_set_map(agent, map) / agent_get_map 归属地图(放入地图)
agent_set_position(agent, position) / agent_get_position 世界空间位置
agent_set_radius(agent, radius) / agent_get_radius 避障圆半径(描述代理身体大小,不是避障机动距离)
agent_set_paused(agent, paused) / agent_get_paused 暂停后不参与处理,如不计算避障速度、不收避障回调
agent_set_max_speed(agent, max_speed) / agent_get_max_speed 避障计算允许的最大速度,必须为正;父节点移动快于该值时 safe_velocity 可能不够准确
agent_set_velocity(agent, velocity) / agent_get_velocity 设置期望速度;避障模拟会尽量达成,但会为避免碰撞而调整
agent_set_velocity_forced(agent, velocity) 强制替换模拟内部速度。代理被传送到远处时应在同一帧调用;频繁调用会让代理卡住
agent_get_time_horizon_agents() / agent_get_time_horizon_obstacles() 见下文时间视界

关于 agent_set_velocity vs agent_set_velocity_forced:前者只是"期望",模拟会自主调整;后者直接重置内部速度状态,仅用于远距传送场景。

6.2 避障开关、层、掩码与优先级

方法 说明
agent_set_avoidance_enabled(agent, enabled) / agent_get_avoidance_enabled 开启避障
agent_set_avoidance_layers(agent, layers) / agent_get_avoidance_layers 自身所属避障层位掩码
agent_set_avoidance_mask(agent, mask) / agent_get_avoidance_mask 要避开的其他对象的层掩码(类物理层的 layer/mask 关系)
agent_set_avoidance_priority(agent, priority) / agent_get_avoidance_priority 优先级 0.0(最低)~1.0(最高);高优先级代理不为匹配 mask 但优先级更低的代理调整速度,低优先级者则会更大幅度调整以避让
agent_set_avoidance_callback(agent, callback) / agent_has_avoidance_callback 设置避障回调(见下文)

优先级机制的具体语义:指定代理不会为"匹配其 avoidance_mask 但 avoidance_priority 更低"的其他代理调整速度,这反过来迫使低优先级代理加大调整幅度来避免与该代理碰撞——适合给重要 NPC 赋予避障话语权。

6.3 邻居搜索与时间视界

方法 说明
agent_set_max_neighbors(agent, count) / agent_get_max_neighbors 避障计算考虑的最大其他代理数。数值越大模拟运行时间越长;太低则模拟不安全
agent_set_neighbor_distance(agent, distance) / agent_get_neighbor_distance 搜索其他代理的最大距离。越大运行时间越长;太低不安全。降低该值可减少处理开销
agent_set_time_horizon_agents(agent, time_horizon) / agent_get_time_horizon_agents 相对于其他代理的安全时间(秒):在此时间段内模拟算出的速度不会撞上其他代理。越大响应越快,但选择速度的自由度越小,过高会显著拖慢移动,必须为正
agent_set_time_horizon_obstacles(agent, time_horizon) / agent_get_time_horizon_obstacles 相对于静态避障障碍物的安全时间(秒),语义同上

教程给出的调参经验:预测时间应尽量保持低值,因为代理会为避免在该时间段内碰撞而减速;neighbor_distance 与 max_neighbors 降低可省性能,但过低可能让代理忽略避障。

6.4 避障回调机制

agent_set_avoidance_callback() 注册的回调在每个避障处理步骤后调用,计算出的 safe_velocity 会在物理计算前通过信号派发给对象。

关键注意(类参考原文):只要代理在导航地图上且未被释放,已创建的回调始终独立于 SceneTree 状态处理。要停止派发,需用 agent_set_avoidance_callback(agent, Callable()) 传空 Callable 再次调用。

extends NavigationAgent2D

func _ready() -> void:
    var agent: RID = get_rid()
    # 开启避障
    NavigationServer2D.agent_set_avoidance_enabled(agent, true)
    # 创建避障回调
    NavigationServer2D.agent_set_avoidance_callback(agent, Callable(self, "_avoidance_done"))

    # 关闭避障
    NavigationServer2D.agent_set_avoidance_enabled(agent, false)
    # 删除避障回调
    NavigationServer2D.agent_set_avoidance_callback(agent, Callable())

相关辅助查询:agent_is_map_changed(agent) 返回地图是否在上一帧发生变化;agent_get_time_horizon_agents/obstacles 与 agent_get_max_neighbors 等 getter 均可直接读取当前配置。

使用避障的完整 2D 角色脚本模板(Node2D 父节点版,来自 navigation_using_navigationagents.rst):

extends Node2D

@export var movement_speed: float = 4.0
@onready var navigation_agent: NavigationAgent2D = get_node("NavigationAgent2D")
var movement_delta: float

func _ready() -> void:
    navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed))

func set_movement_target(movement_target: Vector2):
    navigation_agent.set_target_position(movement_target)

func _physics_process(delta):
    # 地图从未同步且为空时不要查询。
    if NavigationServer2D.map_get_iteration_id(navigation_agent.get_navigation_map()) == 0:
        return
    if navigation_agent.is_navigation_finished():
        return

    movement_delta = movement_speed * delta
    var next_path_position: Vector2 = navigation_agent.get_next_path_position()
    var new_velocity: Vector2 = global_position.direction_to(next_path_position) * movement_delta
    if navigation_agent.avoidance_enabled:
        navigation_agent.set_velocity(new_velocity)
    else:
        _on_velocity_computed(new_velocity)

func _on_velocity_computed(safe_velocity: Vector2) -> void:
    global_position = global_position.move_toward(global_position + safe_velocity, movement_delta)

CharacterBody2D 版本只需把 _on_velocity_computed 改为 velocity = safe_velocity; move_and_slide(),RigidBody2D 版本改为 linear_velocity = safe_velocity。

七、导航障碍物(Obstacle)API:约束避障空间

NavigationObstacle 是双用途对象:既可在网格烘焙时剔除源几何(对应 affect_navigation_mesh 属性),也可在避障时影响代理(对应 avoidance_enabled,默认开启;不用避障时应关闭省性能)。详见 navigation_using_navigationobstacles.rst。

7.1 障碍物方法速查

方法 说明
obstacle_create() 创建障碍物
obstacle_set_map(obstacle, map) / obstacle_get_map 归属地图
obstacle_set_position(obstacle, position) / obstacle_get_position 世界空间位置
obstacle_set_avoidance_enabled(obstacle, enabled) / obstacle_get_avoidance_enabled 是否影响使用避障的代理
obstacle_set_avoidance_layers(obstacle, layers) / obstacle_get_avoidance_layers 避障层位掩码:mask 匹配的代理会避开此障碍物
obstacle_set_paused(obstacle, paused) / obstacle_get_paused 暂停后不再影响避障速度
obstacle_set_radius(obstacle, radius) / obstacle_get_radius 动态障碍物半径(大于 0 即为动态)
obstacle_set_velocity(obstacle, velocity) / obstacle_get_velocity 动态障碍物速度,帮助代理预测其移动;仅与半径配合有效
obstacle_set_vertices(obstacle, vertices) / obstacle_get_vertices 静态障碍物轮廓顶点数组

7.2 静态与动态障碍物

  • 静态障碍物:填充 vertices 轮廓数组,是代理不可越过的硬边界。顶点按顺时针绕序时把代理推入内部,逆时针则推出外部。静态障碍物不能逐帧改位置(只能"瞬移"后整体重建,成本高),瞬移也不可被代理预测,可能卡住代理。
  • 动态障碍物:radius > 0 即为动态,是"请离我远点"的软性推离物(2D 为圆)。可逐帧移动而无需额外成本,设置速度后可被代理预测其运动。

两者属性可以同时激活,但教程不建议这么做:理想做法是移动中用半径、到达最终位置后逐渐扩大半径推开其他代理、再补上静态轮廓并移除半径。

脚本创建障碍物示例:

# 创建障碍物并放到默认导航地图。
var new_obstacle_rid: RID = NavigationServer2D.obstacle_create()
var default_map_rid: RID = get_world_2d().get_navigation_map()

NavigationServer2D.obstacle_set_map(new_obstacle_rid, default_map_rid)
NavigationServer2D.obstacle_set_position(new_obstacle_rid, global_position)

# 动态用法:半径大于 0。
NavigationServer2D.obstacle_set_radius(new_obstacle_rid, 5.0)

# 静态用法:加入把代理推出的正方形轮廓。
var outline = PackedVector2Array([Vector2(-100, -100), Vector2(100, -100), Vector2(100, 100), Vector2(-100, 100)])
NavigationServer2D.obstacle_set_vertices(new_obstacle_rid, outline)

# 启用障碍物。
NavigationServer2D.obstacle_set_avoidance_enabled(new_obstacle_rid, true)

八、导航网格烘焙与高级路径查询

8.1 源几何解析与烘焙

NavigationServer2D 支持程序化烘焙 2D 导航网格,核心是三组方法:

方法 说明
parse_source_geometry_data(navigation_polygon, source_geometry_data, root_node, callback = Callable()) 按 navigation_polygon 的属性解析 SceneTree 中的源几何,把结果写入 source_geometry_data 资源,随后可交给烘焙
bake_from_source_geometry_data(navigation_polygon, source_geometry_data, callback = Callable()) 用源几何数据烘焙导航多边形,结束后调用可选 callback
bake_from_source_geometry_data_async(...) 同上,但在后台线程异步执行
is_baking_navigation_polygon(navigation_polygon) 判断该多边形是否正在后台线程烘焙
source_geometry_parser_create() / source_geometry_parser_set_callback(parser, callback) 创建自定义源几何解析器;解析 parse_source_geometry_data() 时对每个节点调用回调,回调收到三个参数:navigation_mesh(只读的 NavigationPolygon 引用,勿直接编辑)、source_geometry_data(向其中添加自定义烘焙几何)、node(当前被解析节点)

parse_source_geometry_data() 两条重要约束(类参考原文):

  • 必须在主线程或延迟调用中执行(SceneTree 非线程安全);
  • 性能警告:从 Mesh 资源读取数据数组需要 GPU 回读,会阻塞 RenderingServer 造成掉帧;性能敏感场景优先使用碰撞形状或在代码中直接构造数据数组。

烘焙完整流程示例(含程序化障碍物剔除,来自 navigation_using_navigationobstacles.rst):

var obstacle_outline = PackedVector2Array([
    Vector2(-50, -50),
    Vector2(50, -50),
    Vector2(50, 50),
    Vector2(-50, 50)
])

var navigation_mesh = NavigationPolygon.new()
var source_geometry = NavigationMeshSourceGeometryData2D.new()

NavigationServer2D.parse_source_geometry_data(navigation_mesh, source_geometry, $MyTestRootNode)

var obstacle_carve: bool = true
source_geometry.add_projected_obstruction(obstacle_outline, obstacle_carve)

NavigationServer2D.bake_from_source_geometry_data(navigation_mesh, source_geometry)

8.2 query_path:可定制的路径查询

query_path(parameters, result, callback = Callable()) 使用 NavigationPathQueryParameters2D 定义查询参数、把结果写入 NavigationPathQueryResult2D。两个对象建议提前创建、复用以省去反复分配内存。参数对象可配置:map、start_position、target_position、navigation_layers、pathfinding_algorithm、path_postprocessing、path_metadata_flags、simplify_path/simplify_epsilon、included_regions/excluded_regions、path_return_max_length、path_return_max_radius、path_search_max_distance、path_search_max_polygons 等(详见 navigation_using_navigationpathqueryobjects.rst)。

与 map_get_path() 等价的 2D 基础查询:

extends Node2D

var query_parameters := NavigationPathQueryParameters2D.new()
var query_result := NavigationPathQueryResult2D.new()

func query_path(p_start_position: Vector2, p_target_position: Vector2, p_navigation_layers: int = 1) -> PackedVector2Array:
    if not is_inside_tree():
        return PackedVector2Array()

    var map: RID = get_world_2d().get_navigation_map()

    if NavigationServer2D.map_get_iteration_id(map) == 0:
        # 该地图从未同步且为空,查询无意义。
        return PackedVector2Array()

    query_parameters.map = map
    query_parameters.start_position = p_start_position
    query_parameters.target_position = p_target_position
    query_parameters.navigation_layers = p_navigation_layers

    NavigationServer2D.query_path(query_parameters, query_result)
    var path: PackedVector2Array = query_result.get_path()

    return path

8.3 simplify_path:路径简化

var simplified: PackedVector2Array = NavigationServer2D.simplify_path(path, epsilon)

simplify_path() 返回去除次要路径点的简化路径,简化量以世界单位计、由 epsilon 控制,算法是 Ramer-Douglas-Peucker 的变体。类参考指出:路径简化有助于缓解"转向(steering)"代理或"开阔地(open fields)"避障中的路径跟随问题。该函数是通用工具,可脱离导航查询用于任意位置数组。注意:简化是额外的后处理,会增加查询开销,仅在确实需要时启用。

九、信号与进程统计

9.1 信号

信号 说明
avoidance_debug_changed() 避障调试设置变更时发出,仅调试构建可用
navigation_debug_changed() 导航调试设置变更时发出,仅调试构建可用
map_changed(map: RID) 导航地图更新(区域移动或被修改)时发出

调试相关方法还有:set_debug_enabled(enabled) / get_debug_enabled()(开启/查询 NavigationServer 调试模式)、set_active(active)(控制整个服务器激活状态)。调试可视化可在 ProjectSettings debug/shapes/navigation/2d/ 下配置(如 enable_edge_lines = true、enable_edge_connections = true、各类颜色与点大小等,见 class_projectsettings.rst)。

9.2 ProcessInfo 枚举

get_process_info(process_info) 返回 NavigationServer 当前状态统计,通过 ProcessInfo 枚举取值:

常量 值 含义
INFO_ACTIVE_MAPS 0 活跃导航地图数量
INFO_REGION_COUNT 1 活跃导航区域数量
INFO_AGENT_COUNT 2 处理避障的活跃导航代理数量
INFO_LINK_COUNT 3 活跃导航链接数量
INFO_POLYGON_COUNT 4 导航网格多边形数量
INFO_EDGE_COUNT 5 导航网格多边形边数量
INFO_EDGE_MERGE_COUNT 6 因边键重叠而合并的多边形边数量
INFO_EDGE_CONNECTION_COUNT 7 因边邻近而被视为连接的多边形边数量
INFO_EDGE_FREE_COUNT 8 未能合并、但仍可能通过邻近度或链接连接的多边形边数量
INFO_OBSTACLE_COUNT 9 活跃导航障碍物数量

这些统计非常适合性能监控与调试面板(配合 navigation_debug_tools.rst 与 navigation_optimizing_performance.rst 中的优化思路使用)。

十、完整实战:最小 2D 导航设置

综合以上 API,一个"最小可行"的 2D 导航场景只需四步(详见 navigation_introduction_2d.rst):

  1. 场景中添加 NavigationRegion2D 节点;
  2. 为区域新建 NavigationPolygon 资源,用绘制工具圈出可通行区域并点击 Bake NavigationPolygon;
  3. 添加带碰撞形状与视觉的 CharacterBody2D,其下挂 NavigationAgent2D 子节点;
  4. 给角色挂以下脚本(注意:导航网格定义的是角色中心可站立移动的区域,边缘与碰撞体之间要留足余量;path_desired_distance 与 target_desired_distance 需按角色速度与场景布局调整):
extends CharacterBody2D

var movement_speed: float = 200.0
var movement_target_position: Vector2 = Vector2(60.0, 180.0)

@onready var navigation_agent: NavigationAgent2D = $NavigationAgent2D

func _ready():
    navigation_agent.path_desired_distance = 4.0
    navigation_agent.target_desired_distance = 4.0

    # 不要在 _ready() 中 await,延迟到场景就绪后执行。
    actor_setup.call_deferred()

func actor_setup():
    # 等待第一个物理帧,让 NavigationServer 完成同步。
    await get_tree().physics_frame

    # 此时导航地图不再为空,可安全设置移动目标。
    set_movement_target(movement_target_position)

func set_movement_target(movement_target: Vector2):
    navigation_agent.target_position = movement_target

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

    var current_agent_position: Vector2 = global_position
    var next_path_position: Vector2 = navigation_agent.get_next_path_position()

    velocity = current_agent_position.direction_to(next_path_position) * movement_speed
    move_and_slide()

十一、最佳实践与注意事项总结

  1. 等待同步是常态:开局、新场景、程序化改动后,务必等待一个物理帧(或检查 map_get_iteration_id() == 0)再查询路径,否则路径为空或错误。
  2. 用延迟调用包裹启动逻辑:call_deferred() + await physics_frame 是官方推荐的启动模式。
  3. 查询免费、修改付费:只读 get() 无需等待;所有 setter 与销毁函数都需要同步。
  4. 区域连接依赖顶点距离:edge_connection_margin 判定的是两个顶点对的距离;距离过大请改用 NavigationLink。
  5. 避障独立于导航网格:安全速度可能把代理带出可通行区域;复杂局面需结合物理引擎。避障也不影响寻路,只适合"无法高效烘焙进网格的动态物体"。
  6. 成本与优先级的权衡:max_neighbors、neighbor_distance 越大模拟越慢;时间视界越大代理响应越早但减速越明显。
  7. 传送后使用 agent_set_velocity_forced():重置内部速度状态,但勿频繁调用以免卡死。
  8. 导航层优于区域启停:按层筛选路径不触发地图大规模更新,是性能友好的做法;静态障碍物勿逐帧改位置。
  9. map_force_update() 是危险接口:已弃用、会冲刷整个命令队列并锁定服务器,仅限明确理解后果的单线程场景。

NavigationServer2D 是 Godot 2D 导航系统的"发动机",掌握其地图、区域、链接、代理、障碍物五大对象体系与"物理帧同步 + 命令队列"的运行模型后,你可以完全脱离高层节点,用脚本构建高度定制的程序化导航方案。进一步深入可阅读仓库内 navigation_using_navigationservers.rst 教程总览、navigation_using_navigationpathqueryobjects.rst 高级查询指南,以及 NavigationServer2D 类参考 原文。

登录后查看全文
godot-docs