# 工具與 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-hant/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 即可還原；變更過的資產、場景與目前開啟的 prefab 會在變更後儲存。`rql-mutate` 也接受 `dry_run` 來預覽將會變更的內容，以及 `max_targets` 來限制單次變更可觸及的物件數量。

### Unity 中的 RQL 來源

| 來源 | 內容 |
| --- | --- |
| `scenes`、`roots`、`objects` | 已載入的場景、其根 GameObject，以及其中的每個 GameObject。 |
| `selection` | 編輯器目前的選取項目。 |
| `prefab` | 在 prefab 模式下開啟的 prefab。 |
| `editor` | 編輯器操作：建立 GameObject、材質、資料夾與場景；開啟與儲存場景和 prefab；複製、移動與刪除資產；執行選單項目；播放模式狀態。 |
| `settings` | 專案設定。 |
| `console` | 擷取到的編輯器記錄項目。 |
| `shaders`、`componentTypes` | 可用的著色器與元件型別。 |
| `tests`、`testResults` | 測試樹與最近一次的結果。 |
| `profiler` | 記憶體、算繪、腳本與影格資料；開始、停止、儲存與載入擷取資料。 |
| `lighting` | 目前作用中場景的環境（環境光、霧、天空盒、太陽、反射）、Lighting Settings 與烘焙。 |

資產可用 `unity.asset("Assets/…")` 依路徑存取，或以 `unity.assets("t:Material")` 搜尋。每個已安裝的[擴充套件](https://ai-game.dev/zh-hant/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-*`：改用 RQL 對 `objects`、`roots` 和 `selection` 搭配 `set` 與 `call`。
- `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-hant/docs/wiki/unity/custom-tools)，用來加入你自己的工具。
- [Unity 最佳實務](https://ai-game.dev/docs/best-practices/unity)，用來撰寫提示。

---

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

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