# nav

> 导航操作。create_region: 创建 NavigationRegion3D（可选烘焙）。bake_mesh: 烘焙导航网格（耗时较长）。create_agent: 创建 NavigationAgent3D。set_params: 设置导航参数。create_link: 创建 NavigationLink3D。query_path: 查询 3D 导航路径。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

| 属性 | 值 |
|------|-----|
| 所属层 | headless |
| 安全级别 | guarded |
| 需要 Godot | 是 |
| 需要编辑器 | 否 |
| 只读 | 否 |
| 长耗时 | 否 |

## Actions

- `create_region`
- `bake_mesh`
- `create_agent`
- `set_params`
- `create_link`
- `query_path`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (6 项) | ✓ | 操作类型 |
| `project_path` | string |  | Godot 项目目录路径（可选，默认使用 GODOT_PROJECT_PATH 环境变量或当前目录） |
| `name` | string |  | create_region/create_agent/create_link: 节点名称 |
| `parent` | string |  | create_region/create_agent/create_link: 父节点路径（默认 root） |
| `node_path` | string |  | bake_mesh/set_params: 目标节点路径 |
| `position` | object |  | create_region: 位置 {x,y,z} |
| `bake` | boolean |  | create_region: 是否立即烘焙导航网格（默认 false） |
| `target_position` | object |  | create_agent: 目标位置 {x,y,z} |
| `path_desired_distance` | number |  | create_agent: 路径期望距离（默认 0.5） |
| `target_desired_distance` | number |  | create_agent: 目标期望距离（默认 1.0） |
| `avoidance_enabled` | boolean |  | create_agent: 是否启用避障（默认 false） |
| `params` | object |  | set_params: 导航参数（仅传入需要修改的字段） |
| `start_position` | object |  | create_link: 起始位置 {x,y,z} |
| `end_position` | object |  | create_link: 终点位置 {x,y,z} |
| `bidirectional` | boolean |  | create_link: 是否双向通行（默认 true） |
| `start_pos` | object |  | query_path: 起点 {x,y,z} |
| `end_pos` | object |  | query_path: 终点 {x,y,z} |
| `navigation_region` | string |  | query_path: NavigationRegion3D 节点路径（可选） |
| `load_autoloads` | boolean |  | 是否加载 Autoload 上下文（默认 true） |
| `timeout` | number |  | bake_mesh 烘焙超时秒数（默认 120，大场景可调至 600） |

## 风险分布

读 1 / 写 5

---
<!-- AUTO-GENERATED by scripts/gen-tool-docs.mjs from capability-matrix.json v0.32.21. DO NOT edit manually; re-run npm run gen:tool-docs after tool changes. -->