工具
27 個內建 Unreal MCP 工具：RQL、Blueprints、C++ 原始碼、Python、螢幕擷取與主控台，以及 Unreal 編輯器中 AI 的範例提示。
本頁說明 AI agent 透過 Unreal MCP 在 Unreal 編輯器中能做什麼。此外掛提供 7 個系列共 27 個工具。你很少需要直接講出工具名稱：用自然語言提出需求，agent 就會挑選合適的工具。了解這些系列有助於你提出 agent 真正能完成的請求。
如需各工具的說明卡與參數，請參閱 Unreal 工具目錄。
RQL：編輯器資料的單一查詢語言
Unreal MCP 並不是每個編輯器操作都對應一個工具。編輯器資料改由 RQL 處理，這是一種查詢語言，能在一次呼叫中讀取與變更 actor、元件、資產、關卡與編輯器狀態。
| 工具 | 功能 |
|---|---|
rql-query | 對執行中的編輯器進行唯讀查詢，回傳精簡的表格結果 |
rql-mutate | 以 set 或 call 結尾的查詢；全有或全無、只算一個復原步驟，並提供 dry_run 預覽 |
rql-schema | 列出資料來源、函式與類別；若指定型別，則列出該型別的成員與方法 |
以下是幾個 RQL 範例（agent 會替你撰寫）：
actors | where $ is PointLight | select $ref Label Intensity
actors | where Label == "Door_01" | set Location = "(0, 0, 100)"
editor | call SpawnActor("PointLight")
console | where Verbosity == "Error"除了 actor 與元件之外，RQL 還能觸及：
- **資產與關卡：**建立、複製、移動、刪除與匯入資產，建立資料夾與材質實例，開啟、建立與儲存關卡，新增串流子關卡。
- **編輯器狀態：**選取項目、Play In Editor 狀態、復原歷程、編輯器記錄。
- **DataTables：**讀取與編輯資料列（
Rows["Sword"].Damage），新增、移除、重新命名與複製資料列。 - **Gameplay 標籤：**列出、新增、移除與重新命名標籤。
- **Project Settings 與 Editor Preferences：**讀取與變更設定屬性，並儲存到正確的
.ini檔案。 - **Blueprint 圖表：**新增函式呼叫、變數、事件、轉型、分支與迴圈，連接接腳，然後
call Compile()。 - **Widget Blueprints：**走訪與編輯 widget 樹、新增 widget 並設定版面配置。
- **使用者自訂結構：**新增、移除與重新命名欄位。
- **Level Sequences：**綁定 actor、新增軌道與關鍵影格。
每次變更都是一個編輯器交易，因此可用 Ctrl+Z 復原。agent 會從 unreal-rql skill 學習這套語言，該 skill 也會列出已安裝的擴充功能新增了哪些內容。
範例提示：
- 「列出關卡中每個點光源及其強度，然後把較暗的點光源強度加倍。」
- 「以 200 單位的間距，在 5 乘 4 的格線中生成 20 個立方體。」
- 「在 DT_Weapons DataTable 中新增一列 Bow，Damage 為 7。」
- 「將遊戲預設地圖設為 /Game/Maps/Arena。」
Blueprint 系列
Blueprint 編寫是 Unreal 主要的腳本撰寫介面，而 agent 能取得完整的回饋循環：建立、編輯、編譯、讀取錯誤、修正。
| 工具 | 功能 |
|---|---|
blueprint-create | 從父類別建立 Blueprint 類別 |
blueprint-get | 摘要 Blueprint：變數、元件、函式與事件、父類別鏈 |
blueprint-add-component | 將元件加入建構腳本 |
blueprint-remove-component | 移除元件 |
blueprint-add-variable | 新增具型別的成員變數 |
blueprint-modify-variable | 變更成員變數 |
blueprint-set-default | 設定類別預設屬性 |
blueprint-add-function | 新增函式雛形 |
blueprint-add-event | 新增事件，例如 BeginPlay 或 Tick |
blueprint-compile | 編譯並回傳結構化的錯誤與警告清單 |
blueprint-spawn | 在關卡中放置該 Blueprint 的實例 |
範例：「建立一個 Actor Blueprint BP_Door，包含 static mesh 元件與 bool 變數 IsOpen，編譯後在原點放置一個。」
原始碼 / C++ 系列
| 工具 | 功能 |
|---|---|
source-read | 分段讀取專案中的 C++ 檔案 |
source-create-class | 建立新 C++ 類別的骨架（標頭檔與原始檔） |
source-update | 編輯原始檔 |
source-delete | 刪除原始檔 |
source-list | 列出模組的原始檔 |
source-compile | 在 Live Coding 啟用時以它編譯，否則使用 Unreal Build Tool，並回傳結構化的錯誤報告 |
所有檔案操作僅限於 <Project>/Source/。範例：「建立一個 C++ 元件 UHealthComponent，包含 MaxHealth 與 TakeDamage 函式，編譯並修正所有錯誤。」
Python 系列
| 工具 | 功能 |
|---|---|
python-execute | 在編輯器中執行 Python，並預先匯入 unreal 模組 |
最後一個運算式的值會作為結果回傳，print 輸出會以日誌形式回來，錯誤則會指向出錯的那一行。include 會從 <Project>/.ai-game-dev/snippets 加入輔助檔案或資料夾，timeout（預設 30 秒）則會中止失控的腳本。此外掛會啟用 Unreal 的 Python Editor Script Plugin；Python 僅限編輯器使用，絕不會打包進發行後的遊戲。Blueprint 圖表的接線並未開放給 Python；請改用 Blueprint 工具或 RQL 來處理。
你也可以在終端機用 unreal-mcp-cli exec 執行 Python，請見 CLI 參考。
截圖系列
| 工具 | 功能 |
|---|---|
screenshot-viewport | 擷取目前作用中的編輯器視埠 |
screenshot-game-view | 擷取 Play In Editor 的遊戲視圖 |
screenshot-camera | 從攝影機 Actor 算圖 |
screenshot-isolated | 單獨算圖單一 Actor |
影像會以模型可檢視的 PNG 內容回傳，預設 1024 像素，每邊最多 2048 像素。這需要由 GPU 支援的編輯器；在 -nullrhi 下會回傳錯誤。範例：「從 CameraActor_Main 截一張圖，告訴我打光是不是太暗。」
主控台與工具清單
| 工具 | 功能 |
|---|---|
console-run-command | 執行 Unreal 主控台命令或設定主控台變數 |
unreal-tool-list | 列出所有工具（包含隱藏工具），可選擇加上篩選條件、說明與輸入 |
讀取日誌、Play In Editor 狀態與選取項目都透過 RQL。
AI 代理看不到的工具
有些系統工具是供 CLI 與應用程式使用，不會顯示給 AI 代理：
ping：檢查外掛、橋接層與伺服器鏈路。unreal-skill-generate：為每個工具寫出一份SKILL.md到 skills 資料夾（預設.claude/skills）；Generate skill files 按鈕就是用它。unreal-skill-create：在外掛的編輯器模組中產生新的 C++ 工具檔案。這需要以原始碼方式安裝外掛，並重新建置編輯器後工具才能運作。editor-quit：儲存並關閉由 CLI 工作階段啟動的編輯器。
提示詞與資源
此外掛也提供一個 MCP 提示詞 level-design-brief（依主題產生關卡設計簡報），以及兩個資源：unreal://project/levels（目前世界與其關卡的 JSON 快照）與 unreal://project/icon。
控制 AI 代理能看到什麼
在 MCP Tools 視窗中隱藏你不需要的工具，或用 UNREAL_MCP_TOOLS 只提供固定的一組工具。請見設定。若要新增功能，可安裝擴充套件或撰寫自訂工具。
僅限編輯器
全部 27 個工具都會操作編輯器。其中幾個功能強大（rql-mutate、console-run-command、python-execute），因此都不會被編譯進發行後的遊戲。選擇啟用執行階段連線的遊戲，只會暴露它自己註冊的工具。
想充分發揮這些工具的技巧，請見 Unreal 最佳實務。