# 工具 — Unreal Engine · AI Game Developer Wiki

27 個內建 Unreal MCP 工具：RQL、Blueprints、C++ 原始碼、Python、螢幕擷取與主控台，以及 Unreal 編輯器中 AI 的範例提示。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/unreal/tools)。

本頁說明 AI agent 透過 Unreal MCP 在 Unreal 編輯器中能做什麼。此外掛提供 **7 個系列共 27 個工具**。你很少需要直接講出工具名稱：用自然語言提出需求，agent 就會挑選合適的工具。了解這些系列有助於你提出 agent 真正能完成的請求。

如需各工具的說明卡與參數，請參閱 [Unreal 工具目錄](https://ai-game.dev/docs/tools/unreal)。

## RQL：編輯器資料的單一查詢語言

Unreal MCP 並不是每個編輯器操作都對應一個工具。編輯器資料改由 **RQL** 處理，這是一種查詢語言，能在一次呼叫中讀取與變更 actor、元件、資產、關卡與編輯器狀態。

| 工具 | 功能 |
| --- | --- |
| `rql-query` | 對執行中的編輯器進行唯讀查詢，回傳精簡的表格結果 |
| `rql-mutate` | 以 `set` 或 `call` 結尾的查詢；全有或全無、只算一個復原步驟，並提供 `dry_run` 預覽 |
| `rql-schema` | 列出資料來源、函式與類別；若指定型別，則列出該型別的成員與方法 |

以下是幾個 RQL 範例（agent 會替你撰寫）：

```text
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 也會列出已安裝的[擴充功能](https://ai-game.dev/zh-hant/docs/wiki/unreal/extensions)新增了哪些內容。

範例提示：

- 「列出關卡中每個點光源及其強度，然後把較暗的點光源強度加倍。」
- 「以 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 參考](https://ai-game.dev/zh-hant/docs/wiki/unreal/cli#exec)。

## 截圖系列

| 工具 | 功能 |
| --- | --- |
| `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` 只提供固定的一組工具。請見[設定](https://ai-game.dev/zh-hant/docs/wiki/unreal/configuration#tool-visibility)。若要新增功能，可安裝[擴充套件](https://ai-game.dev/zh-hant/docs/wiki/unreal/extensions)或撰寫[自訂工具](https://ai-game.dev/zh-hant/docs/wiki/unreal/custom-tools)。

## 僅限編輯器

全部 27 個工具都會操作編輯器。其中幾個功能強大（`rql-mutate`、`console-run-command`、`python-execute`），因此都不會被編譯進發行後的遊戲。選擇啟用[執行階段連線](https://ai-game.dev/zh-hant/docs/wiki/unreal/custom-tools#runtime)的遊戲，只會暴露它自己註冊的工具。

想充分發揮這些工具的技巧，請見 [Unreal 最佳實務](https://ai-game.dev/docs/best-practices/unreal)。

---

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

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