本頁面由英文機器翻譯而成。閱讀英文原文。

開始使用

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

更新於 2026年11月4日 以 Markdown 檢視

本頁會帶你從安裝好外掛，一路走到讓 AI 代理實際修改你的 Unity 場景。內容採用透過 ai-game.dev 的預設 Cloud 連線，並以 Claude Code 作為範例代理；換成其他任何用戶端，步驟都相同。若還沒安裝外掛，請先從 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。

步驟 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 用戶端；若它已在執行中，請重新啟動，讓它載入新的設定。

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

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

setup-skills 需要編輯器處於開啟且已連線的狀態。其他用戶端與手動設定請見 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：你的第一批提示詞

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

Explain my scene hierarchy.
Create 3 spheres stacked on top of each other, then save the scene.
Create a metallic golden material and assign it to a new sphere.

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

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

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

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

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。

Unity 最佳實務頁面有更多提示詞撰寫建議。

後續步驟