# 開始使用 — Unreal Engine · AI Game Developer Wiki

第一次連線 Unreal MCP，登入 ai-game.dev，接上你的 AI 用戶端，並在 Unreal Editor 中送出第一批 AI 提示。

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

本頁將帶你從已安裝外掛的狀態，一路做到在 Unreal Editor 中完成第一個由 AI 驅動的變更。內容假設你已完成[安裝](https://ai-game.dev/zh-hant/docs/wiki/unreal/installation)。

## 步驟 1：開啟 AI Game Developer 視窗

1. 在 Unreal Editor 中開啟你的專案（從應用程式點選 **Open Editor**、使用 `unreal-mcp-cli open ./YourProject`，或依照你平常的方式開啟）。
2. 開啟 **Tools** 選單，然後選擇 **AI Game Developer**。

這個視窗是外掛的主要操作中心。由上而下依序顯示記錄等級、開啟記錄資料夾的按鈕與外掛版本；**Connection** 區段；**AI agent** 區段；**Extensions** 區段；以及說明與錯誤回報的連結。

## 步驟 2：連線至伺服器

**Connection** 區段提供 **Custom / Cloud** 切換。**Cloud** 是預設值，也是大多數人正確的選擇：它使用位於 ai-game.dev 的託管伺服器，因此本機不需要執行任何東西。

1. 確認已選取 **Cloud**。
2. 點選 **Authorize**。視窗會顯示驗證連結與一組簡短的用戶代碼。
3. 開啟該連結（或使用 **Open verification page**），登入 ai-game.dev，輸入代碼並核准。
4. 視窗會回報 **Authorized — signed in to AI Game Dev.**

如果你已在這台機器上用 `unreal-mcp-cli login` 或 AI Game Dev 應用程式登入過，編輯器可以直接沿用該登入狀態。第一次核准之後，之後啟動編輯器都不需要再點任何按鈕即可重新連線。

請留意狀態列。綠色圓點旁的 **Unreal: Connected** 表示外掛、橋接器與伺服器都已連通。**Unreal: Connecting…** 在橋接器啟動時出現幾秒是正常的。

**注意：** 想讓所有東西都留在自己的機器上嗎？改選 **Custom**，並在本機執行 `gamedev-mcp-server`。[連線 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unreal/connecting-ai-clients#custom)說明了做法。

## 步驟 3：連線你的 AI 用戶端

**AI agent** 區段會替你設定 AI 用戶端。

1. 從下拉式選單挑選你的代理，例如 Claude Code、Cursor、Visual Studio Code (Copilot)、Codex 或 Gemini。
2. 點選 **Configure**。外掛會將 Unreal MCP 項目寫入該代理的 MCP 設定檔。
3. 如果代理已在執行中，請重新啟動或重新載入，讓它載入新的伺服器。

你也可以在終端機中用 CLI 做同樣的事。以 Claude Code 為例：

```bash
unreal-mcp-cli setup-mcp claude-code --path ./YourProject
```

這會在專案資料夾中寫入 `.mcp.json`。執行 `unreal-mcp-cli setup-mcp --list` 可查看所有支援的代理，以及各自的設定檔位置。所有選項請見[連線 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unreal/connecting-ai-clients)。

代理連線後，會出現在 Connection 區段的 **AI agents** 列中。

## 步驟 4：檢查連線

向你的代理提出一個只有編輯器能回答的問題：

```text
List the actors in the current level with their class names.
```

代理應該會呼叫 `rql-query`，並以你目前開啟關卡中真實的 Actor 來回答。如果它說自己沒有 Unreal 工具，代表用戶端沒有載入 MCP 伺服器；請參閱[疑難排解](https://ai-game.dev/zh-hant/docs/wiki/unreal/troubleshooting#agent-no-tools)。

## 步驟 5：你的第一批正式提示

從小型且具體的任務開始。以下是幾個能展示不同工具家族的提示：

```text
Spawn three cubes in a row and a point light above them.
```

```text
Create a new Actor Blueprint called BP_Coin with a static mesh component
using the engine sphere, compile it, and place three of them in the level.
```

```text
Take a screenshot of the viewport and tell me what you see.
```

```text
Create a C++ actor class called AHealthPickup with a float Heal property,
then compile the project and fix any errors.
```

透過 RQL 進行的每一次編輯器變更都算一個復原步驟，因此在編輯器中按 **Ctrl+Z** 就能還原。編譯工具會回傳結構化的錯誤清單，所以「編譯它並修正所有錯誤」是個很好的後續提示。

**提示：** 截圖工具需要真正由 GPU 支援的編輯器。當編輯器以 `-nullrhi` 執行時，這些工具會回傳錯誤。

## 在 Unreal Editor 中使用 AI 的好習慣

- **把東西命名清楚。**「把標記為 KeyLight 的燈光強度改掉」會比「改一下那盞燈」有效得多。
- **先請它查看現況。**「先告訴我 BP\_Door 有哪些元件，再動手修改」能讓代理取得所需的事實。
- **讓它自行驗證。** 變更後請它截圖或進行編譯。
- **記得存檔。** 在進行較大的變更前，請代理儲存關卡，或在編輯器中存檔。
- **讓每次工作階段保持聚焦。** 一次對話只處理一項任務，能讓代理的上下文保持精簡且準確。

更多建議請見 [Unreal 最佳實務](https://ai-game.dev/docs/best-practices/unreal)。

## 後續步驟

- 在[工具](https://ai-game.dev/zh-hant/docs/wiki/unreal/tools)頁面查看代理能做的所有事情。
- 透過[擴充功能](https://ai-game.dev/zh-hant/docs/wiki/unreal/extensions)加入 Niagara、PCG、Enhanced Input 等更多能力。
- 在[設定](https://ai-game.dev/zh-hant/docs/wiki/unreal/configuration)頁面微調可見度、逾時與記錄。
- 使用 [CLI 參考](https://ai-game.dev/zh-hant/docs/wiki/unreal/cli)從腳本驅動編輯器。

---

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

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