# 安裝 — Unity · AI Game Developer Wiki

透過桌面應用程式、unity-mcp-cli、OpenUPM 或 .unitypackage 安裝程式，在 Unity 專案中安裝 Unity MCP（AI Game Developer）。

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

本頁說明把 Unity MCP 外掛加入 Unity 專案的所有方式、每種方式會對你的專案做什麼，以及如何再次移除外掛。所有路徑都會從 OpenUPM registry 安裝同一個套件 `com.ivanmurzak.unity.mcp`，因此你可以挑選最適合自己工作流程的方式。

## 需求

- **Unity 2022.3 或更新版本。** 套件宣告的最低版本為 `2022.3`；支援 Unity 6 各版本。
- **專案路徑不能包含空格。** `C:/Projects/MyGame` 沒問題，`C:/My Projects/My Game` 則不行。若路徑包含空格，外掛會在啟動時記錄錯誤。
- **在 Windows 上使用較短的專案路徑。** 外掛會把它的 NuGet DLL 複製到 `Assets/Plugins/NuGet`。若產生的路徑會超過 Windows 的 260 字元上限，安裝就會中止，並請你把專案移到較短的資料夾。
- **首次開啟時需要網際網路連線。** 外掛會從 NuGet 下載它的 .NET 相依套件，並在 Custom 模式下從 GitHub 下載它的 MCP 伺服器執行檔。
- 僅限 `unity-mcp-cli`：需要 **Node.js** `^20.19.0` 或 `>=22.12.0`。

## 選項 1：AI Game Dev 桌面應用程式（建議）

[AI Game Dev 應用程式](https://ai-game.dev/docs/app)會為你安裝並連線外掛，不需要終端機，也不需要在你機器上安裝 Node.js。

1. [下載應用程式](https://ai-game.dev/zh-hant/download)，並使用你的 ai-game.dev 帳號登入。
2. 在應用程式中開啟你的 Unity 專案資料夾。應用程式會偵測到這是 Unity 專案。
3. 點擊 **Install Package**。應用程式會以 OpenUPM 上最新的發行版本，把外掛加入 `Packages/manifest.json`，而且絕不會降級你已經擁有的較新版本。從應用程式建立的專案會自動取得此外掛。
4. 從應用程式開啟 Editor。應用程式會傳遞你的工作階段，因此外掛可透過 ai-game.dev 連線，無須另外登入。

應用程式也會安裝擴充功能並自行執行 AI 代理，因此你不需要額外的 MCP 用戶端。詳細資訊請見應用程式 wiki：[安裝](https://ai-game.dev/zh-hant/docs/wiki/app/installation)與[專案與引擎](https://ai-game.dev/zh-hant/docs/wiki/app/projects-and-engines)。

## 選項 2：unity-mcp-cli

`unity-mcp-cli` 會直接編輯 `Packages/manifest.json`，因此 Unity 不需要開啟：

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

你也可以不進行全域安裝直接執行：

```bash
npx unity-mcp-cli install-plugin ./MyUnityProject
```

`install-plugin` 會加入 OpenUPM scoped registry（範圍為 `com.ivanmurzak` 與 `extensions.unity`），以最新的 OpenUPM 版本把 `com.ivanmurzak.unity.mcp` 加入 `dependencies`，而且絕不會降級已安裝的較高版本。傳入 `--plugin-version <version>` 可固定版本。若你在專案資料夾中執行命令，路徑為選填。

CLI 也能先安裝 Unity 並建立專案：

```bash
unity-mcp-cli install-unity
unity-mcp-cli create-project ./MyUnityProject
```

若缺少 Unity Hub，CLI 會安裝它。之後請在 Unity 中開啟專案，讓 Package Manager 解析套件。所有命令請見 [CLI 參考](https://ai-game.dev/zh-hant/docs/wiki/unity/cli)。

## 選項 3：OpenUPM

安裝 [OpenUPM CLI](https://openupm.com/) 後，在專案資料夾中執行：

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

若沒有 OpenUPM CLI，請自行把 registry 與相依套件加入 `Packages/manifest.json`。請使用 [OpenUPM 套件頁面](https://openupm.com/packages/com.ivanmurzak.unity.mcp/)上顯示的版本：

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

把這些項目合併到現有的檔案中；不要取代其他相依套件。

## 選項 4：.unitypackage 安裝程式

1. 下載 [AI-Game-Dev-Installer.unitypackage](https://github.com/IvanMurzak/Unity-MCP/releases/latest/download/AI-Game-Dev-Installer.unitypackage)。
2. 在 Unity 中開啟你的專案。
3. 連點該檔案，或使用 **Assets > Import Package > Custom Package** 並選取它。
4. 點擊 **Import**。

安裝程式是一個小型的編輯器腳本。它會把 OpenUPM scoped registry 與外掛相依套件加入 `Packages/manifest.json`，然後從 `Assets` 中刪除自己。接著 Package Manager 會下載真正的套件。

## 首次開啟時會發生什麼事

套件送達後，外掛會自行準備：

- 它會從 NuGet 把所需的 .NET 程式庫（MCP 外掛程式庫、ReflectorNet、RQL、SignalR、System.Text.Json 等）下載到 `Assets/Plugins/NuGet`，快取則位於 `Library/NuGetCache`，Unity 會重新編譯一次。若這些 DLL 曾不同步，請使用 **Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs**。
- 它會從 GitHub 把適用於你平台的 `gamedev-mcp-server` 執行檔下載到 `Library/mcp-server/<platform>/`（例如 `win-x64`、`osx-arm64` 或 `linux-x64`）。只有在使用 HTTP 傳輸的 Custom 模式下才會啟動伺服器；預設的 Cloud 模式不會啟動任何本機伺服器。
- **AI Game Developer** 視窗會出現在 **Window > AI Game Developer — MCP** 底下（快速鍵 Ctrl+Alt+A，macOS 上為 Cmd+Option+A）。Scene View 工具列也會多出一個可開啟它的 **AI** 覆蓋按鈕。

`Library/` 預設會被排除在版本控制之外，因此伺服器執行檔永遠不會被提交。在 CI 環境中，外掛會略過伺服器的下載與啟動。

## 更新外掛

當 OpenUPM 上有較新版本時，外掛會在 Editor 啟動時顯示更新彈出視窗。你可以用 **Tools > AI Game Developer > Updates > Check for Updates** 手動檢查。若要更新，請在 Package Manager 中變更版本、重新執行 `unity-mcp-cli install-plugin`（它會安裝最新版），或讓桌面應用程式更新它。

若團隊中由一個人負責外掛版本，請開啟 **Edit > Project Settings > AI Game Developer** 並啟用 **Disable update notifications for the entire team**。此設定會儲存在 `ProjectSettings/AI-Game-Developer-UpdateSettings.asset`；請提交該檔案。同樣的開關也位於 **Tools > AI Game Developer > Updates > Disable Update Notifications (Team)**。

## 解除安裝

1. 開啟 **Window > Package Manager**，選取 **AI Game Developer — MCP** 並點擊 **Remove**，或執行 `unity-mcp-cli remove-plugin ./MyUnityProject`。CLI 會保留 scoped registry，因為其他套件可能會用到它。
2. 關閉 Unity，並刪除 `Assets/Plugins/NuGet` 資料夾及其 `Assets/Plugins/NuGet.meta` 檔案。

## 後續步驟

- [開始使用](https://ai-game.dev/zh-hant/docs/wiki/unity/getting-started)：連線 AI 用戶端並執行你的第一個提示。
- [擴充功能](https://ai-game.dev/zh-hant/docs/wiki/unity/extensions)：加入適用於 Cinemachine、ProBuilder、Tilemap 等工具包。
- 若安裝過程中發生問題，請參閱[疑難排解](https://ai-game.dev/zh-hant/docs/wiki/unity/troubleshooting)。

---

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

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