Godot NavigationServer2D 完全指南:2D 导航地图、区域、代理与碰撞避免的低层服务器 API
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):
- 代价昂贵:某些更新(如整张导航地图的重算)非常耗时,需要所有其他对象的最新数据才能正确执行;
- 批处理:NavigationServer 把所有"要改状态"的 API 调用放入命令队列,在同步阶段统一执行,因此它是线程安全的——你可以在任意线程发起更改请求,无需担心并发问题(类参考原文:"This server keeps tracks of any call and executes them during the sync phase... using any thread, without worrying.");
- 线程池:默认情况下,避障计算等部分功能运行在后台线程池中。
同步时机:同步发生在物理帧中段——场景脚本与节点的输入处理完毕之后。一个物理帧内避障代理的执行顺序(来自教程):
- 物理帧开始
_physics_process(delta)运行- 在 NavigationAgent 节点上设置
velocity属性 - 代理把速度与位置发送给 NavigationServer
- NavigationServer 等待同步
- 同步并计算所有已注册避障代理的避障速度
- NavigationServer 通过信号向每个代理派发
safe_velocity - 代理接收信号并移动父节点(如
move_and_slide或linear_velocity) - PhysicsServer 同步
- 物理帧结束
由此,在回调里用安全速度移动物理体角色是完全线程/物理安全的——这一切发生在同一物理帧内、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)。
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。
也就是说,边缘连接判定是"顶点对顶点"的双重距离检查,而非简单的中点距离。该余量默认 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)类算法。需牢记类参考的两条关键说明:
- 避障系统忽略导航区域:直接使用修正速度可能把代理移出可通行区域,这是避障系统的固有局限,更复杂的情况需要结合物理引擎;
- 避障只考虑同一地图上同样注册了避障的其他代理,且避障存在于独立空间,没有导航网格或物理碰撞的任何信息——避障代理在幕后只是平面上不同半径的圆(详见 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):
- 场景中添加
NavigationRegion2D节点; - 为区域新建
NavigationPolygon资源,用绘制工具圈出可通行区域并点击 Bake NavigationPolygon; - 添加带碰撞形状与视觉的
CharacterBody2D,其下挂NavigationAgent2D子节点; - 给角色挂以下脚本(注意:导航网格定义的是角色中心可站立移动的区域,边缘与碰撞体之间要留足余量;
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()
十一、最佳实践与注意事项总结
- 等待同步是常态:开局、新场景、程序化改动后,务必等待一个物理帧(或检查
map_get_iteration_id() == 0)再查询路径,否则路径为空或错误。 - 用延迟调用包裹启动逻辑:
call_deferred()+await physics_frame是官方推荐的启动模式。 - 查询免费、修改付费:只读
get()无需等待;所有 setter 与销毁函数都需要同步。 - 区域连接依赖顶点距离:
edge_connection_margin判定的是两个顶点对的距离;距离过大请改用 NavigationLink。 - 避障独立于导航网格:安全速度可能把代理带出可通行区域;复杂局面需结合物理引擎。避障也不影响寻路,只适合"无法高效烘焙进网格的动态物体"。
- 成本与优先级的权衡:
max_neighbors、neighbor_distance越大模拟越慢;时间视界越大代理响应越早但减速越明显。 - 传送后使用
agent_set_velocity_forced():重置内部速度状态,但勿频繁调用以免卡死。 - 导航层优于区域启停:按层筛选路径不触发地图大规模更新,是性能友好的做法;静态障碍物勿逐帧改位置。
map_force_update()是危险接口:已弃用、会冲刷整个命令队列并锁定服务器,仅限明确理解后果的单线程场景。
NavigationServer2D 是 Godot 2D 导航系统的"发动机",掌握其地图、区域、链接、代理、障碍物五大对象体系与"物理帧同步 + 命令队列"的运行模型后,你可以完全脱离高层节点,用脚本构建高度定制的程序化导航方案。进一步深入可阅读仓库内 navigation_using_navigationservers.rst 教程总览、navigation_using_navigationpathqueryobjects.rst 高级查询指南,以及 NavigationServer2D 类参考 原文。

