# 工具与 RQL — Unity · AI Game Developer Wiki

AI 智能体在 Unity 编辑器中借助 Unity MCP 能做什么——RQL 查询与变更、截图、C# 脚本、测试、包管理与性能分析。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unity/tools-and-rql)。

本页说明在连接 Unity MCP 之后，AI 智能体能在你的 Unity 项目中做什么：它能看到哪些工具，RQL 如何让它读取和修改编辑器中的几乎任何内容，以及哪些工具已安装但被隐藏。带参数的完整可搜索列表见 [Unity 工具目录](https://ai-game.dev/docs/tools/unity)，查询语言的文档见 [RQL 参考](https://ai-game.dev/docs/rql)。

## 智能体默认看到的工具

从 1.0.0 版本起，插件让智能体的工具列表保持精简。安装后可见的是以下七个工具：

| 工具 | 功能 |
| --- | --- |
| `rql-query` | 用 RQL 查询读取编辑器数据：场景、GameObject、组件、资源、Console、设置、测试、性能分析器。 |
| `rql-mutate` | 用 RQL 修改编辑器数据或调用编辑器操作：创建、修改、移动和删除对象与资源，打开和保存场景。 |
| `rql-schema` | 描述 RQL 可用的来源、类型、成员和调用，并打印主题指南。智能体不确定时从这里开始。 |
| `script-execute` | 用 Roslyn 在编辑器中编译并运行 C# 代码，并返回结果。 |
| `screenshot-isolated` | 从选定角度单独渲染一个 GameObject，可选输出为 2x2 拼图，以便模型查看。 |
| `tests-run` | 运行 EditMode 或 PlayMode 测试，并返回每项测试的结果。 |
| `unity-tool-list` | 列出所有工具，以及智能体是否能看到它们。 |

精简的列表消耗更少的 token，给模型留出更多推理空间。其他工具仍然处于安装状态；参见[隐藏的工具](https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql#hidden-tools)。

## RQL：一种语言覆盖整个编辑器

RQL 是一种针对编辑器实时数据的查询语言。查询以**来源**开头，并通过以 `|` 分隔的阶段传递结果，例如 `where`、`select`、`get`、`set` 和 `call`。智能体不再为每个操作准备一个工具（旧的 `gameobject-create`、`scene-save`、`console-get-logs` 等几十个），而是编写一条查询。

读取已打开场景的完整层级：

```text
roots | recurse children | select name active
```

查找玩家：

```text
objects | where name == "Player" | select path name active
```

创建一个地面平面：

```text
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
```

添加组件并保存：

```text
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()
```

只读取 Console 中的错误：

```text
console | where logType == "Error"
```

每次 `rql-mutate` 调用都是一个撤销组，因此 Ctrl+Z 可以还原它；变更之后，被修改的资源、场景和打开中的预制体都会被保存。`rql-mutate` 还接受 `dry_run` 以预览将会发生的变化，以及 `max_targets` 来限制一次变更可触及的对象数量。

### Unity 中的 RQL 来源

| 来源 | 内容 |
| --- | --- |
| `scenes`、`roots`、`objects` | 已加载的场景、它们的根 GameObject，以及其中的所有 GameObject。 |
| `selection` | 当前的编辑器选择。 |
| `prefab` | 在预制体模式下打开的预制体。 |
| `editor` | 编辑器操作：创建 GameObject、材质、文件夹和场景；打开并保存场景和预制体；复制、移动和删除资源；执行菜单项；播放模式状态。 |
| `settings` | 项目设置。 |
| `console` | 已捕获的编辑器日志条目。 |
| `shaders`、`componentTypes` | 可用的着色器和组件类型。 |
| `tests`、`testResults` | 测试树和最近一次的结果。 |
| `profiler` | 内存、渲染、脚本和帧数据；开始、停止、保存和加载采集。 |
| `lighting` | 活动场景的环境（环境光、雾、天空盒、太阳、反射）、Lighting Settings 以及烘焙。 |

资源用 `unity.asset("Assets/…")` 按路径寻址，或用 `unity.assets("t:Material")` 搜索。每个已安装的[扩展](https://ai-game.dev/zh-hans/docs/wiki/unity/extensions)都会添加自己的来源和类型，例如 `tilemap` 或 `cinemachine`。

由于 RQL 通过反射工作，智能体也能读取和设置你自己组件中的成员，而不只是 Unity 内置的组件。你可以通过[自定义适配器](https://ai-game.dev/docs/rql/custom-adapters)让 RQL 了解你自己的类型。

## 脚本与 C# 执行

`script-execute` 用 Roslyn 编译一段 C# 代码片段并在编辑器中运行。它接受代码以及可选的 `className`、`methodName`、额外的 `usings` 和要 `include` 的辅助文件。它是 RQL 未覆盖之处的应急出口。在终端中，`unity-mcp-cli exec` 调用同一个工具：

```bash
unity-mcp-cli exec 'Application.unityVersion'
```

若要写入文件而不是运行代码，隐藏工具 `script-read`、`script-update-or-create` 和 `script-delete` 可以管理项目中的 `.cs` 文件。更改后 Unity 会重新编译；连接会在域重载期间短暂断开，然后自行恢复。

## 测试

`tests-run` 运行 EditMode 或 PlayMode 测试（`testMode`，默认 EditMode）。可按程序集、命名空间、类或方法过滤，或者传入基于 `tests` 来源的 RQL 选择，把选中的测试作为一次运行执行。结果可以用 RQL 基于 `testResults` 过滤。选项控制是否包含通过的测试、消息、堆栈跟踪和 Console 日志，从而让输出保持精简。

```bash
unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'
```

## 截图

`screenshot-isolated` 默认可见。另外三个是隐藏的：`screenshot-scene-view`、`screenshot-game-view` 和 `screenshot-camera`。图像最长边被限制为 3840 像素，以便通过 MCP 传输。截图需要图形设备：以 `-nographics` 启动的编辑器会返回错误，而不是空白图像。

## 隐藏的工具

这些工具已经安装，但不在智能体的列表中。隐藏的工具在被按名称调用时仍会运行。

- 截图：`screenshot-scene-view`、`screenshot-game-view`、`screenshot-camera`。
- 脚本：`script-read`、`script-update-or-create`、`script-delete`。
- 包：用于 Unity Package Manager 的 `package-list`、`package-search`、`package-add`、`package-remove`。
- 工具管理：`tool-set-visibility`，以及其已弃用的别名 `tool-set-enabled-state`。

在 AI Game Developer 窗口中显示它们（**Tools > Open**），或用 `tool-set-visibility` 工具，或使用：

```bash
unity-mcp-cli configure ./MyUnityProject --enable-tools package-add,package-list
```

## 提示词与技能

插件还附带 46 个 MCP 提示词（斜杠命令模板，例如 `setup-basic-scene` 或 `add-event-system`），分为六组：脚本编写、GameObject 与组件、场景、调试与测试、资源管理、动画与时间轴。它们默认隐藏；在 **Prompts > Open** 中启用你需要的那些。

**Skills** 是插件生成到你的智能体技能文件夹中的 Markdown 文件。它们包括 `unity-rql` 指南，内含 Unity 及每个已安装扩展的 RQL 语法，以及安装和 CLI 说明。可在窗口中通过 **Skills > Auto-generate** 开启，或运行 `unity-mcp-cli setup-skills <agent>`。

## 旧教程中的工具名称

\\1.0.0 版本移除了“一个操作一个工具”的工具。如果某篇教程提到了其中之一，请改用 RQL：

- `gameobject-create`、`gameobject-find`、`gameobject-modify`、`gameobject-destroy`、`gameobject-component-*`：针对 `objects`、`roots` 和 `selection` 使用 `set` 和 `call` 的 RQL。
- `scene-create`、`scene-open`、`scene-save`：`editor | call NewScene(…)`、`OpenScene(…)`、`SaveScenes()`。
- `assets-*`、`assets-prefab-*`、`assets-material-create`：`unity.asset(…)`、`unity.assets(…)` 以及 `editor` 调用，例如 `CreateMaterial`、`CopyAsset`、`InstantiatePrefab`。
- `console-get-logs`、`console-clear-logs`：`console` 来源和 `editor | call ClearConsole()`。
- `editor-application-*`、`editor-selection-*`：`editor` 的成员，例如 `isPlaying` 和 `selection`。
- `reflection-method-find`、`reflection-method-call`、`type-get-json-schema`：RQL `call` 和 `rql-schema`。
- `profiler-*`：`profiler` 来源。

## 相关页面

- [Unity 工具目录](https://ai-game.dev/docs/tools/unity) 与 [RQL 参考](https://ai-game.dev/docs/rql)。
- [自定义工具](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools)，用于添加你自己的工具。
- [Unity 最佳实践](https://ai-game.dev/docs/best-practices/unity)，用于撰写提示词。

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/unity/tools-and-rql