godot-navigation-pathfinding

导航与寻路中绝对不要做的事

• 绝对不要在等待物理帧之前设置 target_position — 在 _ready() 中调用时，NavigationServer 尚未就绪？路径会静默失败。必须先调用 call_deferred()，然后 await get_tree().physics_frame。
• 绝对不要在运行时使用 NavigationRegion2D.bake_navigation_polygon() — 同步烘焙会让游戏卡顿 100+ ms。应使用 NavigationServer.bake_from_source_geometry_data_async()，实现无卡顿更新。
• 绝对不要忘记检查 is_navigation_finished() — 到达目标后调用 get_next_path_position()，会得到过期路径，AI 会走向旧位置。
• 绝对不要在未设置半径的情况下启用 avoidance_enabled — 默认半径为 0，Agent 会穿过其他对象。设置 nav_agent.radius = collision_shape.radius，以实现正确的避让。
• 绝对不要每帧轮询追逐 AI 的 target_position — 每秒设置 60 次目标会导致路径反复重新计算。使用计时器（间隔 0.2s）或距离阈值来更新。
• 绝对不要假定路径一定存在 — 目标不可达（被墙挡住）？get_next_path_position() 会返回无效结果。检查 is_target_reachable() 或验证路径长度。
• 绝对不要对数千个简单实体使用开销大的基于节点的导航 — 直接使用 NavigationServer3D/2D RID，以避免节点开销。
• 绝对不要每帧调用 get_path() — 使用 query_path()，并复用 NavigationPathQueryResult 对象，以避免大量堆分配和 GC 压力。
• 绝对不要让高惩罚区域的 enter_cost 保持为 0 — 使用成本设置，让 AI 优先选择符合逻辑的路径（道路而非水域），而不只是选择几何距离最短的路径。
• 绝对不要忽略 agent_set_avoidance_callback — 始终使用回调安全地计算速度，以避免同步问题和移动“抖动”。

决策树 → 脚本

对于所选路径，必须使用。不要从此技能正文加载编辑器入门／官方文档引导方案（首次设置区域时请使用参考链接）。

需求	脚本
运行时／程序化烘焙，避免卡顿	必须 async_dynamic_baking.gd
Agent 卡住／抖动恢复	必须 agent_stuck_detection.gd
无节点的高数量 RVO	必须 low_level_avoidance.gd
移动平台／动态区域	dynamic_nav_manager.gd
仅使用 RID 的地图／区域	server_navigation_setup.gd
复用路径查询对象	memory_optimized_queries.gd
地形进入／通行成本	terrain_cost_manager.gd
将投射物用作 RVO 障碍物	moving_obstacle_server.gd
链接（跳跃／传送／电梯）	nav_link_traversal.gd
行走／飞行／游泳图层	layer_mask_navigation.gd
人群队形偏移	group_avoidance_formations.gd
服务端 RVO 人群 Agent（无节点）	crowd_agent_3d.gd
动态导航网格切割（冲击产生的洞）	nav_mesh_carver_3d.gd
烘焙时间基准测试	navmesh_profiler.gd
智能 Agent 封装器	smart_navigation_agent.gd

追逐／重新指定目标规则（绝不违反上述禁令）

不要在每个物理帧都赋值 target_position。应按计时器（约 0.2s）重新指定目标，或在被追逐的实体移动超过距离阈值时重新指定：

# Threshold retarget — not per-frame path spam
const RETARGET_DIST := 1.5
var _last_target: Vector3

func _physics_process(_delta: float) -> void:
    var desired := prey.global_position
    if desired.distance_to(_last_target) >= RETARGET_DIST:
        nav_agent.target_position = desired
        _last_target = desired
    if nav_agent.is_navigation_finished():
        return
    var next := nav_agent.get_next_path_position()
    velocity = (next - global_position).normalized() * speed
    move_and_slide()

可用脚本

async_dynamic_baking.gd

bake_from_source_geometry_data_async — 在主线程解析，在后台线程烘焙。

agent_stuck_detection.gd

基于距离随时间变化的停滞检测与恢复。

low_level_avoidance.gd

服务端 RVO Agent 和避障回调。

dynamic_nav_manager.gd

为移动平台更新运行时导航网格。

server_navigation_setup.gd

通过 NavigationServer RID 创建无节点地图／区域。

memory_optimized_queries.gd

重复使用路径查询参数／结果对象。

terrain_cost_manager.gd

使用 enter_cost / travel_cost 选择优先路线。

moving_obstacle_server.gd

无需完整重新烘焙即可创建动态 RVO 障碍物。

nav_link_traversal.gd

处理 NavigationLink 跳跃／传送／电梯。

layer_mask_navigation.gd

多领域导航层（行走／飞行／游泳）。

group_avoidance_formations.gd

通过相对于领队的偏移减少扎堆。

smart_navigation_agent.gd

生产环境中的 NavigationAgent 封装模式。

专家提示

• 首次了解 NavigationRegion 烘焙界面时，优先阅读官方文档简介；此技能涵盖异步烘焙、服务端 RVO、成本和卡住恢复。
• 数千个简单 Agent → 使用 RID 服务端路径（server_navigation_setup.gd + low_level_avoidance.gd），而不是为每个 Agent 创建一个 NavigationAgent 节点。
• 人群 RVO／挖除／烘焙基准示例 → crowd_agent_3d.gd、nav_mesh_carver_3d.gd、navmesh_profiler.gd

深入阅读（按需）

• 2D／3D 追逐、巡逻、避障信号 → agent-movement-patterns.md
• 服务端 RVO 人群、投影挖除、烘焙基准 → expert-nav-architectures.md

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作路由到关联领域时加载相关技能——不要预加载整个技能网络。

官方文档

• 导航简介（2D） — 最简 NavigationRegion2D + NavigationAgent2D 配置、可行走多边形烘焙，以及首帧就绪状态。
• 导航简介（3D） — 对应的 3D 初始配置，使用 NavigationRegion3D / NavigationAgent3D，并介绍网格烘焙的预期效果。
• 使用 NavigationAgent — target_position、get_next_path_position、避让半径，以及 velocity_computed 安全速度流程。
• 使用 NavigationServer — 使用 RID 地图/区域/Agent 实现无节点群体和自定义服务端配置。
• 使用导航网格 — 解析/烘焙源几何体、异步烘焙，以及用于动态挖空的投影障碍物。
• 使用 NavigationRegion — 区域所有权、进入/通行成本，以及分块/运行时区域更新。
• 使用 NavigationObstacle — RVO 推开障碍物与烘焙时挖空，无需每帧都进行完整重建网格。
• 使用 NavigationLink — 跳跃/传送/电梯边，以及 Agent 上的手动链接遍历。
• 使用导航层 — 用于行走/飞行/游泳（或阵营）路径筛选的 32 位层位掩码。
• 使用导航路径查询对象 — 重用 NavigationPathQueryParameters/Result，避免群体场景中每帧触发 GC。
• 优化导航性能 — 为大型 AI 群体介绍烘焙成本、Agent/障碍物数量和服务端查询预算。

相关技能

前置要求

• godot-characterbody-2d — 路径转角会通过 move_and_slide 转换为 CharacterBody 速度；Agent 脚本假定父节点是一个实体。
• godot-2d-physics — 碰撞层/形状仍会阻挡实体；导航网格不能替代墙体和触发器的物理碰撞。
• godot-physics-3d — 3D Agent 也遵循相同的分工：NavigationServer 负责路径，RigidBody/CharacterBody 负责碰撞和斜坡。

补充

• godot-raycasting-queries — 视线、瞄准锥和命中预测与寻路相辅相成，适用于追逐／潜行 AI。
• godot-state-machine-advanced — 巡逻／追逐／搜索状态负责决定何时重新指定 NavigationAgent 的目标，以及何时停止。
• godot-tilemap-mastery — 2D 关卡中的 TileMap／TileSet 几何体常用于生成 NavigationPolygon。
• godot-3d-world-building — 静态网格和 GridMap 通常是烘焙区域的 NavigationMesh 源几何体。
• godot-procedural-generation — 运行时布局生成后，需要调用 parse + bake_from_source_geometry_data_async。
• godot-performance-optimization — 群体会促使你采用服务端 RID、复用查询，并调整本技能中提到的避障设置。

下游／使用者

• godot-genre-rts — 单位移动命令和 RVO 群体会直接使用 NavigationAgent／Server 模式。
• godot-genre-tower-defense — 路线／路径上的敌人和动态障碍物依赖区域、代价及障碍物更新。
• godot-genre-stealth — 守卫巡逻和调查点是由检测状态控制的 NavigationAgent 路线。
• godot-combat-system — 接敌／风筝／侧翼移动会基于路径指定新目标，并处理卡住后的恢复。
• godot-monte-carlo-balancer — 调整 AI 难度时，模拟追逐可达性、行进时间区间和群体压力。

主技能

• godot-master — 此领域技能的库路由器和镜像模块入口。