# 安裝 — Unreal Engine · AI Game Developer Wiki

使用 AI Game Dev 應用程式或 unreal-mcp-cli，在 Unreal Engine 5.5+ 安裝 Unreal MCP 外掛。包含需求、更新、移除與 Fab 狀態。

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

本頁說明如何將 Unreal MCP（Unreal Engine 的 AI Game Developer 外掛）安裝到專案中。請選擇一種安裝方式，依照步驟操作，然後繼續閱讀[開始使用](https://ai-game.dev/zh-hant/docs/wiki/unreal/getting-started)。

## 需求

| 需求項目 | 詳細資訊 |
| --- | --- |
| Unreal Engine | 5.5 或更新版本。發行版已針對 5.5、5.6、5.7 與 5.8 驗證。 |
| 專案類型 | **C++ Unreal 專案**。此外掛包含會針對你的專案編譯的編輯器模組，因此專案必須能夠建置 C++。 |
| C++ 工具鏈 | 你的 Unreal Engine 版本在你的平台上所需的編譯器工具鏈（例如 Windows 上的 Visual Studio、macOS 上的 Xcode）。 |
| 作業系統 | Windows (x64)、macOS（Apple silicon 與 Intel）以及 Linux (x64)。發行版會為上述每個平台提供橋接程式組建。 |
| Node.js | 僅限 `unreal-mcp-cli`：`^20.19.0` 或 `>=22.12.0`。桌面應用程式不需要。 |
| .NET 9 SDK | 僅在從原始碼建置橋接器時需要。封裝安裝版會一併包含。 |

此外掛不會在外掛描述檔中鎖定確切的引擎版本，因此同一個外掛也能在較新的引擎版本上載入。

**注意：** 純 Blueprint 專案需要先有 C++ 模組，才能建置外掛。請在 Unreal Editor 中加入任何 C++ 類別（Tools、New C++ Class），將它轉為 C++ 專案，或使用 `unreal-mcp-cli create-project` 建立全新的 C++ 專案。

## 選項 1：AI Game Dev 桌面應用程式

桌面應用程式是最簡單的方式。它內含安裝邏輯，因此你不需要 Node.js、npm 或終端機。

1. 從[下載頁面](https://ai-game.dev/zh-hant/download)安裝 AI Game Dev。[應用程式安裝指南](https://ai-game.dev/zh-hant/docs/wiki/app/installation)會逐步說明。
2. 使用你的 ai-game.dev 帳戶登入。
3. 選擇 **Open folder…**，然後選取你的 Unreal 專案資料夾（包含 `.uproject` 檔案的資料夾）。應用程式會將其辨識為 Unreal 專案。或者使用 **Create new project** 建立新專案；外掛隨後會自動安裝。
4. 在側邊欄中點擊 **Install Package**。應用程式會安裝最新發行的 Unreal MCP 版本，並先驗證下載內容。如果已安裝的外掛版本較新，應用程式會保留它。
5. 點擊 **Open Editor**，以你已登入的工作階段啟動 Unreal Editor，讓外掛能透過 ai-game.dev 連線，而不需要手動權杖。

在應用程式的 CLI 中，相同動作對應的命令是 `/install-plugin` 與 `/open`。應用程式也能安裝選用的[擴充功能](https://ai-game.dev/zh-hant/docs/wiki/unreal/extensions)。詳細資訊請參閱[專案與引擎](https://ai-game.dev/zh-hant/docs/wiki/app/projects-and-engines)。

## 選項 2：unreal-mcp-cli

`unreal-mcp-cli` 發佈於 npm，可在 Windows、macOS 與 Linux 上運作。它不需要複製儲存庫，也不需要自行執行建置步驟。

全域安裝 CLI：

```bash
npm install -g unreal-mcp-cli
```

或者不安裝，直接執行任何命令一次：

```bash
npx unreal-mcp-cli@latest status
```

接著安裝外掛、登入並開啟編輯器：

```bash
# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject
```

這些命令的作用如下：

- `install-plugin` 會下載與 CLI 版本相符的外掛原始碼（來自 GitHub release 的 `unreal-mcp-plugin-source-<version>.zip`），並在解壓縮前檢查其簽章。遭竄改或未簽署的下載會遭到拒絕。適用於你平台的橋接器會包含在該套件中。
- `login` 會將你的認證儲存在整台機器的儲存區（`~/.ai-game-dev/credentials.json`），與應用程式及其他引擎 CLI 共用。
- `open` 會從專案的 `EngineAssociation` 找到正確的引擎，必要時先建置原生編輯器模組，並在已知的 Unreal 啟動提示（例如「Missing Modules」）仍出現時自動關閉它們。

**提示：** 安裝或更新外掛前，請先關閉 Unreal Editor。Unreal 無法取代執行中的編輯器已載入的外掛。

## 選項 3：從原始碼手動安裝

手動安裝適用於貢獻者與外掛開發。

1. 將 [Unreal-MCP 儲存庫](https://github.com/IvanMurzak/Unreal-MCP)中的 `UnrealMCP/` 資料夾複製到 `<YourProject>/Plugins/UnrealMCP/`。
2. 原始碼簽出版本不會隨附橋接器。請使用 `unreal-mcp-cli bootstrap-local ./YourProject` 建置一個（需要 .NET 9 SDK），或將 `UNREAL_MCP_BRIDGE_PATH` 指向你建置的橋接器。
3. 開啟專案。Unreal 會在首次啟動時編譯此外掛的模組。

若需進行即時開發，`unreal-mcp-cli install-plugin --junction` 會以連結資料夾的方式取代複製外掛資料夾（Windows）。

## Fab / Epic Marketplace

Fab 上架計畫正在進行中，但**尚未上線**。在上架前，Fab 上沒有可供安裝的內容；請使用應用程式或 CLI。

## 檢查安裝

編輯器啟動時，Output Log 會印出：

```text
[Unreal-MCP] plugin loaded
```

你也可以執行 `unreal-mcp-cli status --path ./YourProject` 來查看套件、專案、外掛與連線狀態。

接著外掛就會以 **AI Game Developer** 之名出現在編輯器的 **Tools** 選單下。請繼續閱讀[開始使用](https://ai-game.dev/zh-hant/docs/wiki/unreal/getting-started)。

## 更新外掛

- **應用程式：** 有較新的外掛版本時，側邊欄會顯示 **Update Package**。
- **CLI：** 執行 `unreal-mcp-cli update ./YourProject`。版本變更時，它會刪除已安裝外掛的 `Intermediate/` 資料夾及其編譯後的 C++ `Binaries/`，讓 Unreal 進行一次乾淨的重新建置，同時保留內建的 bridge。加上 `--force` 可重新安裝相同版本，加上 `--no-clean` 則保留建置快取。
- **手動複製：** 關閉編輯器，刪除 `Plugins/UnrealMCP/Intermediate/` 與 C++ 的 `Binaries/`（保留 `Binaries/ThirdParty/`），然後重新開啟專案。

建置快取過舊是更新看起來沒有生效最常見的原因。請參閱[疑難排解](https://ai-game.dev/zh-hant/docs/wiki/unreal/troubleshooting#stale-build)。

## 移除外掛

```bash
unreal-mcp-cli remove-plugin ./YourProject
```

或者在編輯器關閉的情況下刪除 `<YourProject>/Plugins/UnrealMCP/`。

## 讓外掛不進入打包後的遊戲

如果你只是要在編輯器中用 Unreal MCP 取得 AI 協助，請在**你的專案**的 `.uproject` 外掛項目中將它排除於打包建置之外：

```json
{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}
```

如此一來，外掛在編輯器中仍保持啟用，但它的任何部分（包括 bridge）都不會被編譯或暫存到打包後的遊戲中。請勿將任何 `UnrealMcp*` 模組加入遊戲模組 `Build.cs` 的相依項目：直接相依會覆寫拒絕清單。若想在執行中的遊戲內使用 AI 工具，請參閱[遊戲內工具](https://ai-game.dev/zh-hant/docs/wiki/unreal/custom-tools#runtime)。

---

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

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