unity-navmesh
GitHub提供Unity导航网格相关操作，包括烘焙NavMesh、计算路径、采样位置及配置Agent和障碍物组件。支持查询与变更操作，适用于游戏开发中的角色移动和寻路场景搭建。
Trigger Scenarios
Install
npx skills add Besty0728/Unity-Skills --skill unity-navmesh -g -y
SKILL.md
Frontmatter
{
"name": "unity-navmesh",
"description": "Bake and query Unity NavMesh"
}
Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via
GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.
Triggers
- Setting up navigation
- Baking a NavMesh
- Testing agent paths
- Tuning bake parameters
- 搭建导航、烘焙 NavMesh、测试 Agent 路径、调整烘焙参数
NavMesh Skills
Bake / clear NavMesh data, calculate paths, sample positions, and configure NavMeshAgent / NavMeshObstacle components.
Operating Mode
- 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同步阻塞主线程；大场景可能很慢，调用前提醒用户。
DO NOT (common hallucinations):
navmesh_createdoes not exist → usenavmesh_baketo generate NavMeshnavmesh_add_agent_component/navmesh_set_agent_speeddo not exist → usenavmesh_add_agent+navmesh_set_agent(convenience wrappers), orcomponent_add/component_set_propertyfor full control- NavMesh must be re-baked after scene geometry changes
Routing:
- For NavMeshAgent/NavMeshObstacle components → use
componentmodule - For path calculation →
navmesh_calculate_path(this module)
Skills
navmesh_bake
Bake the NavMesh (Synchronous). Warning: Can be slow. Parameters: None.
navmesh_clear
Clear the NavMesh data. Parameters: None.
navmesh_calculate_path
Calculate a path between two points. Parameters:
startX,startY,startZ(float): Start position.endX,endY,endZ(float): End position.areaMask(int, optional): NavMesh area mask.
Returns: { status, valid, distance, cornerCount, corners }
status: NavMeshPathStatus string (PathComplete/PathPartial/PathInvalid)valid:trueonly whenstatus == "PathComplete"distance: total path length (0 for invalid paths)cornerCount: number of corner points incornerscorners: array of{x, y, z}waypoints (empty when no path)
navmesh_add_agent
Add NavMeshAgent component to an object.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | No | null | GameObject name |
| instanceId | int | No | 0 | GameObject instance ID |
| path | string | No | null | GameObject hierarchy path |
Returns: { success, gameObject }
navmesh_set_agent
Set NavMeshAgent properties (speed, acceleration, radius, height, stoppingDistance).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | No | null | GameObject name |
| instanceId | int | No | 0 | GameObject instance ID |
| path | string | No | null | GameObject hierarchy path |
| speed | float | No | null | Agent movement speed |
| acceleration | float | No | null | Agent acceleration |
| angularSpeed | float | No | null | Agent angular speed |
| radius | float | No | null | Agent radius |
| height | float | No | null | Agent height |
| stoppingDistance | float | No | null | Distance to stop before target |
Returns: { success, gameObject, speed, radius }
navmesh_add_obstacle
Add NavMeshObstacle component to an object.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | No | null | GameObject name |
| instanceId | int | No | 0 | GameObject instance ID |
| path | string | No | null | GameObject hierarchy path |
| carve | bool | No | true | Enable carving |
Returns: { success, gameObject, carving }
navmesh_set_obstacle
Set NavMeshObstacle properties (shape, size, carving).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | No | null | GameObject name |
| instanceId | int | No | 0 | GameObject instance ID |
| path | string | No | null | GameObject hierarchy path |
| shape | string | No | null | Obstacle shape (e.g. Box, Capsule) |
| sizeX | float | No | null | Obstacle size X |
| sizeY | float | No | null | Obstacle size Y |
| sizeZ | float | No | null | Obstacle size Z |
| carving | bool | No | null | Enable carving |
Returns: { success, gameObject, shape, carving }
navmesh_sample_position
Find nearest point on NavMesh.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| x | float | Yes | - | Source position X |
| y | float | Yes | - | Source position Y |
| z | float | Yes | - | Source position Z |
| maxDistance | float | No | 10 | Maximum search distance |
Returns: { success, found, point: { x, y, z }, distance }
navmesh_set_area_cost
Set area traversal cost.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| areaIndex | int | Yes | - | NavMesh area index |
| cost | float | Yes | - | Traversal cost value |
Returns: { success, areaIndex, cost }
navmesh_get_settings
Get NavMesh build settings.
Parameters: None.
Returns: { success, agentRadius, agentHeight, agentSlope, agentClimb }
Exact Signatures
Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.
Version History
-
5ee8388
Current 2026-08-17 04:11
文档精简至6.2KB，协议细节移至参考文件；新增SKILL_GUIDE.md说明引导模式协议；增加手动/自动化边界表；更新版本锚点至2.6.0并添加CHANGELOG条目。
-
25d511e
2026-08-13 09:14
压缩75个SKILL.md描述至约5191字符，并将路由说明移至Triggers部分。
- ec9f870 2026-07-05 14:40
