# Unity 外掛設定 — AI Game Developer

一步步設定 Unity 的 AI Game Developer 外掛：安裝、登入、連接你的 AI 用戶端並新增擴充功能，同時附上常見問題的解決方法。

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

Unity · 手動設定

從空的 Unity 專案到讓 AI 代理在編輯器中工作，你需要的一切都在這裡：安裝外掛、登入、連接 AI 用戶端，並新增你需要的擴充功能。[Unity 安裝頁面](https://ai-game.dev/zh-hant/engines/unity)有簡短版本。

01

## 開始之前

Unity 2022.3 或更新版本、ai-game.dev 帳號，以及 AI 用戶端。

- **Unity 2022.3 或更新版本** — 支援 Unity 6。
- **ai-game.dev 帳號**，用於預設的雲端連線 — 若你沒有帳號，請[建立一個](https://ai-game.dev/create-account)。
- **AI 用戶端** — AI Game Dev 應用程式、Claude Code、Cursor、Copilot、Gemini、Codex，或[14 個支援的 MCP 用戶端](https://ai-game.dev/zh-hant/mcp-endpoint-info)中的任何一個。
- **第一次開啟時需要網際網路連線** — 外掛會從 NuGet 下載其 .NET 套件。

02

## 安裝外掛

可透過應用程式、CLI、OpenUPM 或安裝程式套件 — 擇一即可。

四種新增外掛的方式，從最簡單的開始：

**桌面應用程式**

在[AI Game Dev 應用程式](https://ai-game.dev/zh-hant/download)中開啟你的 Unity 專案，然後按一下**安裝套件**。應用程式會從 OpenUPM 安裝最新的外掛、讓外掛完成登入，並設定你的代理。

**unity-mcp-cli**

從 npm 安裝 CLI，然後將外掛新增到你的專案（它會替你編輯 `Packages/manifest.json`）：

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
```

**OpenUPM 安裝**

使用 OpenUPM CLI 時，在專案資料夾中執行下列指令：

```bash
openupm add com.ivanmurzak.unity.mcp
```

沒有 OpenUPM CLI？將作用域登錄新增到 `Packages/manifest.json`，然後在**視窗 → 套件管理員**中新增套件：

```json
{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.ivanmurzak", "extensions.unity"]
    }
  ]
}
```

**.unitypackage 檔案**

下載安裝程式，並用**Assets → Import Package → Custom Package…**匯入。它會將 OpenUPM 登錄與套件新增到你的專案，之後的更新即可從套件管理員取得。

[⬇ 下載 AI-Game-Dev-Installer.unitypackage](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage)

03

## 開啟視窗並登入

開啟 AI Game Developer 視窗，並用你的帳號登入一次。

1. 在 Unity 中選擇**Window → AI Game Developer — MCP**（`Ctrl+Alt+A`，或在 macOS 上使用 `Cmd+Option+A`）。
2. 將**連線**開關保持在**雲端**，然後按一下**授權**。
3. 瀏覽器會開啟 ai-game.dev 登入頁面並顯示一組短代碼。確認代碼相符後核准。
4. Unity 狀態會變成**已連線**。

登入狀態會儲存在整台電腦上：如果你已使用應用程式或 `unity-mcp-cli login` 登入，編輯器會沿用，你可以跳過此步驟。

04

## 連接你的 AI 用戶端

一個指令，或在視窗中按一下，就能寫入用戶端設定。

在視窗中，按一下 AI 代理旁的**設定**，或從終端機執行 `setup-mcp`。兩者都會將專案固定的 URL 與專案金鑰寫入用戶端設定，讓它立即連線：

```bash
# Claude Code — use your agent's id (cursor, codex, gemini, vscode-copilot, …)
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
```

設定變更後，請重新啟動 AI 用戶端。其他用戶端與手動設定，請參閱[連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unity/connecting-ai-clients)與[MCP 端點頁面](https://ai-game.dev/zh-hant/mcp-endpoint-info)。

05

## 新增擴充功能（選用）

動畫、Cinemachine、地形、時間軸等 — 只安裝你需要的項目。

每個擴充功能都是獨立的 Unity 套件。安裝後，它會透過 RQL 讓 AI 代理學會 Unity 的某個領域。以下是幾個熱門的：

- [AI Animation](https://ai-game.dev/docs/extensions/unity/animation) 3 項功能
  ```bash
  openupm add com.ivanmurzak.unity.mcp.animation
  ```
- [AI Cinemachine](https://ai-game.dev/docs/extensions/unity/cinemachine) 4 項功能
  ```bash
  openupm add com.ivanmurzak.unity.mcp.cinemachine
  ```
- [AI Terrain](https://ai-game.dev/docs/extensions/unity/terrain) 4 項功能
  ```bash
  openupm add com.ivanmurzak.unity.mcp.terrain
  ```
- [AI Timeline](https://ai-game.dev/docs/extensions/unity/timeline) 5 項功能
  ```bash
  openupm add com.ivanmurzak.unity.mcp.timeline
  ```

[所有 10 個 Unity 擴充功能 →](https://ai-game.dev/docs/extensions/unity)

?

## 疑難排解

最常遇到問題的修正方式。更多內容請見 [Unity 疑難排解指南](https://ai-game.dev/zh-hant/docs/wiki/unity/troubleshooting)。

**我的 AI 用戶端已連線，但未顯示任何工具**

確認 Unity 狀態顯示為 **已連線**，然後重新連線用戶端（在 Claude Code 中為 `/mcp`）或重新啟動。若仍未列出任何工具，請再次為你的 AI 代理點選 **設定**，並重新啟動用戶端。

**AI Game Developer 視窗沒有出現**

此外掛程式只會在專案編譯完成後載入。請檢查主控台中專案任一處的編譯錯誤，然後重新開啟編輯器。缺少 McpPlugin 或 ReflectorNet 的類型，通常表示第一次匯入尚未完成：請稍候，或使用 **工具 → AI Game Developer → 相依性 → 強制解析 NuGet DLL**。

**自訂模式：本機 MCP 伺服器沒有啟動**

在自訂模式中，此外掛程式會將 `gamedev-mcp-server` 下載到 `Library/mcp-server/<platform>/`。若被防火牆或代理伺服器封鎖，視窗會顯示伺服器錯誤，並附有 **下載 / 重試** 按鈕。在雲端模式中則不需要本機伺服器。

**自訂模式中的連接埠衝突**

每個專案都會依路徑取得 20000 到 29999 之間的固定本機連接埠。若該連接埠已被其他處理程序使用，伺服器會顯示為 **外部**：請停止該處理程序，或在 **伺服器 URL** 中輸入其他連接埠，然後再次點選 **設定**。

**套件管理員回報此套件需要較新版本的 Unity**

此外掛程式需要 Unity 2022.3 或更新版本。請升級專案，或使用 `unity-mcp-cli install-unity` 安裝較新的編輯器。

### 下一步

[**Unity 維基 →** 設定、工具與 RQL、自訂工具、CLI 參考，以及更多內容。](https://ai-game.dev/zh-hant/docs/wiki/unity) [**Unity 工具 →** AI 代理在 Unity 中能做的一切，並附範例。](https://ai-game.dev/docs/tools/unity) [**最佳實務 →** 如何向 AI 代理提出它擅長處理的工作。](https://ai-game.dev/docs/best-practices/unity)

---

Source (HTML): https://ai-game.dev/zh-hant/docs/unity-plugin-setup

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