unity-navmesh

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

调用本模块中任何skill之前： 如果你打算仅凭skill名称或描述猜测参数来调用，请停止——先阅读本文档（或通过
GET /skills/recommend?includeSchema=true
获取其schema）。如果你已经从推荐/schema中获取了参数定义，可以直接进行dryRun。

Triggers

触发场景

Setting up navigation
Baking a NavMesh
Testing agent paths
Tuning bake parameters
搭建导航、烘焙 NavMesh、测试 Agent 路径、调整烘焙参数

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

NavMesh Skills

NavMesh技能

Bake / clear NavMesh data, calculate paths, sample positions, and configure NavMeshAgent / NavMeshObstacle components.

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

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_create
```
does not exist → use
```
navmesh_bake
```
to generate NavMesh

navmesh_add_agent_component

navmesh_set_agent_speed

do not exist → use

navmesh_add_agent

navmesh_set_agent

(convenience wrappers), or

component_add

component_set_property

for full control

NavMesh must be re-baked after scene geometry changes

Routing:

For NavMeshAgent/NavMeshObstacle components → use
```
component
```
module
For path calculation →
```
navmesh_calculate_path
```
(this module)

Approval模式：查询类skill（

navmesh_calculate_path

navmesh_sample_position

navmesh_get_settings

，源码标记为

SkillMode.SemiAuto

）可直接执行；变更类skill（

navmesh_bake

navmesh_add_agent

navmesh_set_agent

navmesh_add_obstacle

navmesh_set_obstacle

navmesh_set_area_cost

，标记为

SkillMode.FullAuto

）需要用户授权（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_bake

Bake the NavMesh (Synchronous). Warning: blocks the Editor, can be slow on large scenes. Parameters: None.

烘焙NavMesh（同步执行）。警告：会阻塞编辑器，大场景下可能很慢。 参数：无

navmesh_clear

navmesh_clear

Clear the NavMesh data. Parameters: None.

清除NavMesh数据。 参数：无

navmesh_calculate_path

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
```
:
```
true
```
only when
```
status == "PathComplete"
```
```
distance
```
: total path length (0 for invalid paths)
```
cornerCount
```
: number of corner points in
```
corners
```
```
corners
```
: array of
```
{x, y, z}
```
waypoints (empty when no 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

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 }

为对象添加NavMeshAgent组件。

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

返回值：

{ success, gameObject }

navmesh_set_agent

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 }

设置NavMeshAgent属性（速度、加速度、半径、高度、停止距离）。

参数	类型	必填	默认值	描述
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

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 }

为对象添加NavMeshObstacle组件。

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

返回值：

{ success, gameObject, carving }

navmesh_set_obstacle

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 }

设置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_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上最近的点。

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

返回值：

{ success, found, point: { x, y, z }, distance }

navmesh_set_area_cost

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 }

设置区域遍历成本。

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

返回值：

{ success, areaIndex, cost }

navmesh_get_settings

navmesh_get_settings

Get NavMesh build settings.

Parameters: None.

Returns:

{ success, agentRadius, agentHeight, agentSlope, agentClimb }

获取NavMesh构建设置。

参数：无

返回值：

{ success, agentRadius, agentHeight, agentSlope, agentClimb }

Exact Signatures

精确签名

Exact names, parameters, defaults, and returns are defined by

GET /skills/schema

unity_skills.get_skill_schema()

, not by this file.

精确的名称、参数、默认值和返回值由

GET /skills/schema

或

unity_skills.get_skill_schema()

定义，而非本文档。

unity-navmesh

Original

Translation

Triggers

触发场景

NavMesh Skills

NavMesh技能

Operating Mode

运行模式

Skills

技能列表

`navmesh_bake`

`navmesh_bake`

`navmesh_clear`

`navmesh_clear`

`navmesh_calculate_path`

`navmesh_calculate_path`

`navmesh_add_agent`

`navmesh_add_agent`

`navmesh_set_agent`

`navmesh_set_agent`

`navmesh_add_obstacle`

`navmesh_add_obstacle`

`navmesh_set_obstacle`

`navmesh_set_obstacle`

`navmesh_sample_position`

`navmesh_sample_position`

`navmesh_set_area_cost`

`navmesh_set_area_cost`

`navmesh_get_settings`

`navmesh_get_settings`

Exact Signatures

精确签名