# 開始使用 — Unity · AI Game Developer Wiki

透過 Unity MCP 把你的第一個 AI 代理連接到 Unity 編輯器，檢查連線，並在 Claude Code、Cursor 或 Copilot 中試用第一批提示詞。

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

本頁會帶你從安裝好外掛，一路走到讓 AI 代理實際修改你的 Unity 場景。內容採用透過 ai-game.dev 的預設 Cloud 連線，並以 Claude Code 作為範例代理；換成其他任何用戶端，步驟都相同。若還沒安裝外掛，請先從 [Installation](https://ai-game.dev/zh-hant/docs/wiki/unity/installation) 開始。

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

在 Unity 中開啟你的專案，然後選擇 **Window > AI Game Developer — MCP**（Ctrl+Alt+A，macOS 上為 Cmd+Option+A）。視窗的分頁標題是 **Game Developer**。你也可以點擊 Scene View 工具列上的 **AI** 按鈕。

視窗會由上而下以時間軸呈現連線狀態：先是 **Unity**，接著 **MCP server**，最後是 **AI agent**。每個節點都有狀態圓圈。你的目標是讓這三個都變成綠色。

## 步驟 2：登入（Cloud 模式）

最上方的 **Connection** 切換開關有兩個選項：**Custom** 和 **Cloud**。全新安裝預設使用 **Cloud**。

1. 點擊 **Cloud Token** 欄位旁的 **Authorize**。
2. 瀏覽器會開啟 ai-game.dev 的裝置登入頁面。視窗中會顯示一組短碼（「Code: … — Authorize in browser」）。確認瀏覽器顯示相同的代碼後核准。
3. 該欄位會變成「Signed in via account」，而 Unity 狀態會變成 **Connected**。

登入資訊會以整台機器為單位儲存在 `~/.ai-game-dev/credentials.json`。如果你已透過 `unity-mcp-cli login` 或 AI Game Dev app 登入，編輯器會沿用該憑證，你可以跳過此步驟。更多細節請見 [Authentication](https://ai-game.dev/docs/auth)。

**注意**

試用此外掛不需要帳號。你可以把連線切換成 **Custom**，改為在自己的機器上執行本機 MCP server。參見 [Configuration](https://ai-game.dev/zh-hant/docs/wiki/unity/configuration#connection-modes)。

## 步驟 3：設定你的 AI 代理

1. 在 **AI agent** 區段中，從下拉選單挑選你的用戶端，例如 **Claude Code**。
2. 在 **Model Context Protocol (MCP)** 底下點擊 **Configure**。此外掛會寫入該用戶端的 MCP 設定檔（以 Claude Code 為例，是專案根目錄下的 `.mcp.json`），其中的 URL 會固定指向這個專案。
3. 在 **Skills** 底下開啟 **Auto-generate**，或點擊 **Generate**。這會寫入技能檔案，供代理讀取以學會如何使用 Unity MCP 和 RQL（以 Claude Code 為例，會寫入 `.claude/skills`）。支援 skills 的代理搭配使用時，表現會明顯更好。
4. 從專案資料夾啟動你的 AI 用戶端；若它已在執行中，請重新啟動，讓它載入新的設定。

同樣的事也能在終端機中完成：

```bash
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-skills claude-code ./MyUnityProject
```

`setup-skills` 需要編輯器處於開啟且已連線的狀態。其他用戶端與手動設定請見 [Connecting AI clients](https://ai-game.dev/zh-hant/docs/wiki/unity/connecting-ai-clients)。

## 步驟 4：檢查連線

- 在視窗中，Unity 狀態顯示為 **Connected**，而 AI agent 節點會顯示你的用戶端已完成設定。
- 在你的 AI 用戶端中列出 MCP server 或工具。在 Claude Code 中執行 `/mcp`；你應該會看到 `ai-game-developer`，其中包含 `rql-query`、`rql-mutate`、`rql-schema`、`script-execute`、`screenshot-isolated`、`tests-run` 和 `unity-tool-list` 等工具。
- 若你的用戶端在 Unity 就緒之前就已連線，請重新連線，讓它重新列出工具。

在終端機中，`unity-mcp-cli status ./MyUnityProject` 會顯示 Unity 是否正在執行，以及設定的 server 是否可連線。

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

先從讀取場景的請求開始，再試一個會修改場景的請求：

```text
Explain my scene hierarchy.
```

```text
Create 3 spheres stacked on top of each other, then save the scene.
```

```text
Create a metallic golden material and assign it to a new sphere.
```

觀察 Hierarchy：隨著代理運作，物件會逐一出現。背後代理送出的是 RQL，例如像這樣的 mutation：

```text
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
```

每一次 RQL 變更都會記錄成一個 Undo 步驟，因此按 Ctrl+Z（Cmd+Z）就能像手動編輯一樣還原。

一個會用到多種工具的較長範例：

```text
Create a new scene called Playground. Add a plane scaled to 10, 1, 10 and a capsule
named Player at 0, 1, 0 with a Rigidbody. Write a PlayerController script that moves
the Player with WASD, attach it, and take a screenshot of the Player.
```

更多可以嘗試的點子：

- 「讀取 Console，告訴我有沒有任何錯誤。」
- 「執行所有 EditMode 測試，並總結失敗的項目。」
- 「列出所有已開啟場景中的每個 Rigidbody 及其質量。」
- 「啟動 profiler，錄製幾秒的 Play 模式，並回報每幀時間。」

## 讓結果更好的訣竅

- 名稱、位置和檔案路徑要講清楚。請求越精確，需要修正的地方就越少。
- 在用戶端中選擇強大的模型；工具密集的工作會因此受益。
- 在 VS Code 搭配 Copilot 時，把聊天切換到 **Agent** 模式，否則工具不會被呼叫。
- 讓代理的工具清單保持精簡。隱藏的工具被以名稱呼叫時仍會執行，而可見工具越少，就能留越多上下文給推理使用。參見 [Configuration](https://ai-game.dev/zh-hant/docs/wiki/unity/configuration#tools-prompts-resources)。

[Unity 最佳實務](https://ai-game.dev/docs/best-practices/unity)頁面有更多提示詞撰寫建議。

## 後續步驟

- [Tools and RQL](https://ai-game.dev/zh-hant/docs/wiki/unity/tools-and-rql)：代理能做的所有事情。
- [Extensions](https://ai-game.dev/zh-hant/docs/wiki/unity/extensions)：加入 Animation、Cinemachine、ProBuilder、Tilemap 及其他套件。
- [Custom tools](https://ai-game.dev/zh-hant/docs/wiki/unity/custom-tools)：把你自己的 C# 方法開放給代理使用。
- 卡住了嗎？請見 [Troubleshooting](https://ai-game.dev/zh-hant/docs/wiki/unity/troubleshooting)。

---

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

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