工具與 RQL
AI 代理在 Unity 編輯器中透過 Unity MCP 能做什麼：RQL 查詢與變更、螢幕擷取、C# 腳本、測試、套件與效能分析。
本頁說明在連上 Unity MCP 之後，AI 代理能在你的 Unity 專案中做什麼：它會看到哪些工具、RQL 如何讓它讀取並變更編輯器中幾乎任何內容，以及哪些工具雖已安裝卻被隱藏。含參數的完整可搜尋清單請見 Unity 工具目錄，查詢語言的說明則在 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 越少，也留給模型更多推理空間。其他工具仍已安裝；請參閱隱藏的工具。
RQL：一套語言打通整個編輯器
RQL 是一套查詢語言，用來查詢編輯器的即時資料。查詢會從一個來源開始，並讓結果依序通過以 | 分隔的各個階段，例如 where、select、get、set 和 call。代理不必再為每個動作準備一個工具（舊有的 gameobject-create、scene-save、console-get-logs 等數十個），而是撰寫單一查詢。
讀取已開啟場景的完整階層：
roots | recurse children | select name active尋找玩家：
objects | where name == "Player" | select path name active建立地面平面：
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})加入元件並儲存：
objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()只讀取 Console 中的錯誤：
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") 搜尋。每個已安裝的擴充套件都會加入自己的來源與型別，例如 tilemap 或 cinemachine。
由於 RQL 透過反射運作，代理也能讀取並設定你自己元件的成員，而不只是 Unity 內建的元件。你可以用自訂轉接器讓 RQL 認識你自己的型別。
腳本與 C# 執行
script-execute 會用 Roslyn 編譯一段 C# 程式碼，並在編輯器中執行。它接受程式碼，以及選用的 className、methodName、額外的 usings 與要 include 的輔助檔案。凡是 RQL 無法涵蓋的情況，都可以用它作為逃生出口。在終端機中，unity-mcp-cli exec 會呼叫同一個工具：
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 記錄，以保持輸出精簡。
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 工具，或執行：
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 工具目錄 與 RQL 參考。
- 自訂工具，用來加入你自己的工具。
- Unity 最佳實務，用來撰寫提示。