unity-navmesh

**在调用本模块中的任何 skill 之前：**如果你打算根据 skill 的名称或描述猜测参数后调用该 skill，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其 schema）。如果你已从 recommend/schema 中获取参数定义，则可直接执行 dryRun。

触发条件

• 设置导航
• 烘焙 NavMesh
• 测试 Agent 路径
• 调整烘焙参数
• 搭建导航、烘焙 NavMesh、测试 Agent 路径、调整烘焙参数

NavMesh Skills

烘焙／清除 NavMesh 数据、计算路径、采样位置，以及配置 NavMeshAgent／NavMeshObstacle 组件。

运行模式

• Approval：查询类 skill（navmesh_calculate_path／navmesh_sample_position／navmesh_get_settings，源码标记为 SkillMode.SemiAuto）直接执行；变更类（navmesh_bake／navmesh_add_agent／navmesh_set_agent／navmesh_add_obstacle／navmesh_set_obstacle／navmesh_set_area_cost，标记为 SkillMode.FullAuto）需用户 grant，grant 后由服务端一步执行并返回结果。
• Auto / Bypass：所有未被禁止列表拦截的 skill 直接执行。
• 本模块包含 Delete 类 skill：navmesh_clear 标记为 SkillOperation.Delete，会被 IsForbiddenInSemi 静态拦截——仅在 Bypass 模式下或将其加入 Allowlist 后才能调用。
• navmesh_bake 会同步阻塞主线程；大型场景可能很慢，调用前请提醒用户。

请勿（常见臆造）：

• navmesh_create 不存在 → 使用 navmesh_bake 生成 NavMesh
• navmesh_add_agent_component／navmesh_set_agent_speed 不存在 → 使用 navmesh_add_agent + navmesh_set_agent（便捷封装），或使用 component_add／component_set_property 进行完整控制
• 场景几何发生变化后，必须重新烘焙 NavMesh

路由：

• 对于 NavMeshAgent／NavMeshObstacle 组件 → 使用 component 模块
• 对于路径计算 → 使用 navmesh_calculate_path（本模块）

Skills

navmesh_bake

烘焙 NavMesh（同步）。警告：会阻塞 Editor，大型场景可能耗时较长。 **参数：**无。

navmesh_clear

清除 NavMesh 数据。 **参数：**无。

navmesh_calculate_path

计算两点之间的路径。 参数：

• startX、startY、startZ（float）：起始位置。
• endX、endY、endZ（float）：结束位置。
• areaMask（int，可选）：NavMesh 区域遮罩。

返回值：{ status, valid, distance, cornerCount, corners }

• status：NavMeshPathStatus 字符串（PathComplete／PathPartial／PathInvalid）
• valid：仅当 status == "PathComplete" 时为 true
• distance：路径总长度（路径无效时为 0）
• cornerCount：corners 中转角点的数量
• corners：{x, y, z} 路径点数组（无路径时为空）

navmesh_add_agent

向对象添加 NavMeshAgent 组件。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径

返回值：{ success, gameObject }

navmesh_set_agent

设置 NavMeshAgent 属性（speed、acceleration、radius、height、stoppingDistance）。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
speed	float	否	null	Agent 移动速度
acceleration	float	否	null	Agent 加速度
angularSpeed	float	否	null	Agent 角速度
radius	float	否	null	Agent 半径
height	float	否	null	Agent 高度
stoppingDistance	float	否	null	在目标前停止的距离

返回值：{ success, gameObject, speed, radius }

navmesh_add_obstacle

为对象添加 NavMeshObstacle 组件。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
carve	bool	否	true	启用挖刻

返回： { success, gameObject, carving }

navmesh_set_obstacle

设置 NavMeshObstacle 属性（形状、大小、挖刻）。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
shape	string	否	null	障碍物形状（例如 Box、Capsule）
sizeX	float	否	null	障碍物大小 X
sizeY	float	否	null	障碍物大小 Y
sizeZ	float	否	null	障碍物大小 Z
carving	bool	否	null	启用挖刻

返回： { success, gameObject, shape, carving }

navmesh_sample_position

查找 NavMesh 上最近的点。

参数	类型	必填	默认值	描述
x	float	是	-	源位置 X
y	float	是	-	源位置 Y
z	float	是	-	源位置 Z
maxDistance	float	否	10	最大搜索距离

返回： { success, found, point: { x, y, z }, distance }

navmesh_set_area_cost

设置区域遍历成本。

参数	类型	必填	默认值	描述
areaIndex	int	是	-	NavMesh 区域索引
cost	float	是	-	遍历成本值

返回： { success, areaIndex, cost }

navmesh_get_settings

获取 NavMesh 构建设置。

参数： 无。

返回： { success, agentRadius, agentHeight, agentSlope, agentClimb }

---

精确签名

精确名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。