godot-ai-navigation

用途

本技能是一个 AI 移动决策路由层，建立在 Godot 的 NavigationAgent / NavigationServer 之上。它不负责引擎导航网格的具体制作配方，而是回答「该用哪种方案」：节点代理还是 RID 服务器代理、烘焙还是障碍物、如何设置层级掩码、以及追逐与巡逻时的重定向策略。适用于 2D 俯视角/横版与 3D 地面/斜坡场景的 AI 移动决策。

主要能力

1. 节点代理 vs NavigationServer RID

• 2D 俯视/横版、约 50 个以下、可在编辑器调节的代理：使用挂在 CharacterBody2D 上的 NavigationAgent2D。
• 3D 地面/斜坡、约 50 个以下、由设计师放置区域的场景：使用挂在 CharacterBody3D 上的 NavigationAgent3D，并配合 godot-physics-3d 处理身体碰撞。
• 成百上千个简单移动体（2D 或 3D）：使用 NavigationServer 上的 RID 代理。
• 代理卡住或抖动：优先做卡住恢复，而不是反复重定向。

2. 烘焙 vs 障碍物

• 可行走几何体变化（程序生成、开门）：异步解析并烘焙。
• 移动平台/变化区域：动态区域管理器。
• 推动代理的抛射物/滚动危险物：RVO 障碍物，无需完整重新烘焙。
• 偏好道路而非泥地/水面：使用区域进入/行进成本。

3. 层级、链接与人群

• 走/飞/游（或阵营）过滤：导航层级位掩码。
• 跳跃/传送/电梯边缘：NavigationLink 遍历。
• 编队/防堆叠人群：相对队长的偏移。
• 热路径查询分配：复用查询参数/结果对象。

4. 追逐/巡逻重定向策略

• 追逐：按定时器（约 0.2 秒）或距离阈值重定向，绝不要每个物理帧都赋值 target_position。
• 巡逻：仅当 is_navigation_finished() 且 is_target_reachable() 时才推进路点；不可达时选择下一个或重新寻路。
• 状态归属：巡逻/追逐/搜索的状态转换属于 godot-state-machine-advanced；本技能只决定状态请求目的地后如何重定向。

巡逻状态交接（调用点）示例：在巡逻状态的 _physics_process 中，当代理完成一个路点时调用 retarget_if_needed(next_waypoint)，不要从状态机根节点直接设置 target_position。

# PatrolState.gd — 状态机负责转换；本技能负责重定向策略
func _physics_process(_delta: float) -> void:
	if nav_agent.is_navigation_finished() and nav_agent.is_target_reachable():
		_ai_nav.retarget_if_needed(_waypoints[_index])
		_index = (_index + 1) % _waypoints.size()

# 阈值重定向 — AI 策略，而非每帧路径风暴
const RETARGET_DIST := 1.5
var _last_target: Vector3

func retarget_if_needed(desired: Vector3) -> void:
	if desired.distance_to(_last_target) < RETARGET_DIST:
		return
	nav_agent.target_position = desired
	_last_target = desired

使用方式

1. 用上述决策树对 AI 需求分类。
2. 打开所选行对应的路径寻路脚本（强制要求），不要加载该技能其余脚本。
3. 在此处接线重定向/状态策略（定时器/阈值 + 状态机），移动通过 CharacterBody 执行。
4. 除非首次需要区域烘焙 UI，否则不要加载官方文档入门配方。

限制与禁止事项

• 绝不在等待物理帧之前设置 target_position，必须先 call_deferred() 再 await get_tree().physics_frame。
• 绝不使用同步运行期烘焙，应通过异步方式进行。
• 绝不每帧轮询追逐目标，避免路径重算泛滥。
• 绝不在此处发明本地重复导航脚本，只从 godot-navigation-pathfinding 实现。
• 绝不忽略 is_target_reachable() / 卡住恢复。
• 在 avoidance_enabled 时绝不把避让半径留为 0。
• 绝不每帧调用 get_path()，应复用路径查询对象。

回退方案

若未安装相邻的 godot-navigation-pathfinding 技能，可用以下最小卡住恢复清单，不要凭记忆粘贴完整的烘焙/RID 教程：

1. 用 call_deferred + await get_tree().physics_frame 延迟首个 target_position。
2. 按定时器（约 0.2 秒）或距离阈值重定向，绝不每帧执行。
3. 停滞时：若 !nav_agent.is_target_reachable() 或速度连续 N 帧接近 0，跳过路点或调用 get_next_path_position() 恢复。
4. 避让：avoidance_enabled 时设 radius > 0。
5. 在发布异步烘焙或 RID 人群前，重新安装 godot-navigation-pathfinding。

适用场景

适用于 RTS 单位移动指令与 RVO 人群、塔防的路线敌人与动态阻挡、潜行的守卫巡逻与调查点、战斗系统的交战/风筝/包抄移动，以及用蒙特卡洛平衡器模拟追逐可达性、行进时间带和人群压力。核心实现依赖 godot-navigation-pathfinding 脚本（异步烘焙、RID 设置、查询复用、卡住检测）；本技能本身不包含本地 scripts/ 目录。

参考链接包括 Godot 官方导航概览、2D/3D 导航入门、使用 NavigationAgents、使用 NavigationServers、使用导航网格、使用 NavigationRegions、使用 NavigationObstacles、使用 NavigationLinks、使用导航层级、使用导航路径查询对象、优化导航性能，以及 godot-charaterbody-2d、godot-2d-physics、godot-physics-3d、godot-raycasting-queries、godot-state-machine-advanced 等相关技能。