# 安裝 — Godot · AI Game Developer Wiki

使用 AI Game Dev 應用程式、godot-cli、Godot Asset Library 或 release zip 安裝 Godot MCP 附加元件，並為你的 .csproj 加上正確的 NuGet 套件。

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

本頁說明將 Godot MCP 加入 Godot C# 專案的所有方法，以及每種方法各自替你做了什麼。如果你只想讓它能運作，請使用桌面應用程式或 `godot-cli`：兩者都會一步完成安裝附加元件、修改你的 `.csproj`，並啟用外掛。手動方式（Asset Library、release zip）還需要兩個容易漏掉的額外步驟。

## 需求

| 需求項目 | 說明 |
| --- | --- |
| Godot | Godot 4.3 或更新版本，且為 **.NET (mono) 版**。此附加元件以 `Godot.NET.Sdk` 4.3.0 作為最低建置基準；專案的 CI 會在 4.3、4.4、4.5、4.6 與 4.7 上啟動它。 |
| .NET | .NET 8 SDK（`net8.0`）。 |
| 專案 | 根目錄含有 C# `.csproj` 的 Godot 專案。 |
| `godot-cli`（選用） | Node.js `^20.19.0` 或 `>=22.12.0`。 |
| 作業系統 | Windows、macOS 或 Linux。 |

**警告**

Godot 標準版下載（僅 GDScript）無法編譯此附加元件。請下載 Godot 的 .NET 版本。如果你的專案還沒有 `.csproj`，可從 Godot 建立（Project、Tools、C#、Create C# solution），或用 `godot-cli create-project --dotnet` 建立新專案。

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

[AI Game Dev 應用程式](https://ai-game.dev/zh-hant/docs/wiki/app) 可以將 Godot MCP 安裝到你選擇的專案，然後開啟已連線到你帳號的編輯器。它自帶安裝程式副本，因此你不需要 Node.js 或 npm。應用程式一律安裝最新發行的附加元件，並執行與 `godot-cli install-plugin` 相同的三件事：把附加元件檔案放到 `addons/godot_mcp/`、將 NuGet 套件與擴充目錄加入你的 `.csproj`，並在 `project.godot` 中啟用外掛。

從[下載頁面](https://ai-game.dev/zh-hant/download)下載應用程式。安裝方式與如何選擇專案請見[應用程式安裝](https://ai-game.dev/zh-hant/docs/wiki/app/installation)；應用程式的命令列說明請見 [App CLI](https://ai-game.dev/zh-hant/docs/wiki/app/cli)。

## 選項 2：godot-cli（終端機）

`godot-cli` 是 Godot MCP 的 npm 套件。它的 `install-plugin` 指令是完整的安裝程式，而且可以安全地重複執行：第二次執行不會有任何變更。

```bash
npm install -g godot-cli
godot-cli install-plugin ./MyGodotProject
```

`install-plugin` 依序執行的工作：

1. 從 Godot-MCP GitHub release 下載 `godot-mcp-addon-<version>.zip`（僅透過 HTTPS、僅限 github.com），並放到 `res://addons/godot_mcp/`。版本預設為 CLI 本身的版本。
2. 將已安裝附加元件所需的 NuGet `PackageReference` 加入你的 `.csproj`，版本取自附加元件本身，並修正過期的版本。
3. 加入擴充目錄的 `<EmbeddedResource>`，並設定 `<EnableDynamicLoading>true</EnableDynamicLoading>`。
4. 在 `project.godot` 的 `[editor_plugins]` 區段中啟用外掛。

實用的變化用法：

```bash
# A specific addon release
godot-cli install-plugin --version 0.34.0 ./MyGodotProject

# Offline or development install from a local copy of the addon
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject

# No project yet: scaffold a Godot C# project first
godot-cli create-project --dotnet ./MyGodotProject
```

你也可以不全域安裝直接執行：`npx godot-cli install-plugin ./MyGodotProject`。所有旗標都列在 [godot-cli 參考文件](https://ai-game.dev/zh-hant/docs/wiki/godot/cli)。

## 選項 3：Godot Asset Library

1. 在 Godot 編輯器中，開啟上方的 **AssetLib** 分頁。
2. 搜尋 **Godot-MCP** 並開啟該資源。
3. 依序點擊 **Download**、**Install**。Godot 會將附加元件解壓縮到 `res://addons/godot_mcp/`。
4. 將 NuGet 套件與 catalog 那行加入你的 `.csproj`（見下文）。
5. 啟用外掛（見下文）。

Asset Library 的項目一律指向某個已標記的發行版本，因此你會拿到已知良好的快照。它只包含附加元件檔案：第 4 步與第 5 步仍須由你完成。

## 選項 4：GitHub release zip 或原始碼複本

從 [Godot-MCP releases](https://github.com/IvanMurzak/Godot-MCP/releases/latest) 頁面下載 `godot-mcp-addon-<version>.zip` 並解壓縮到專案根目錄。壓縮檔中已包含 `addons/godot_mcp/`，因此檔案會落在 `res://addons/godot_mcp/`。你也可以從儲存庫的 clone 複製 `addons/godot_mcp/` 資料夾。接著執行下方兩個手動步驟。

## 手動步驟：NuGet 套件與擴充目錄

Godot 會把專案中每個 `.cs` 檔編譯成單一組件，因此你的 `.csproj` 必須參考與附加元件相同的 NuGet 套件，否則附加元件無法編譯。請將以下內容加入你的 `.csproj`（這些是附加元件 0.34.0 的版本）：

```xml
<ItemGroup>
  <PackageReference Include="com.IvanMurzak.ReflectorNet" Version="5.5.1" />
  <PackageReference Include="com.IvanMurzak.McpPlugin" Version="8.14.0" />
</ItemGroup>

<!-- Editor-only: exported games ship no RQL and no Roslyn. -->
<ItemGroup>
  <PackageReference Include="com.IvanMurzak.Rql" Version="0.3.0" Condition="'$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease'" />
  <PackageReference Include="com.IvanMurzak.CodeExec" Version="0.4.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
  <PackageReference Include="com.IvanMurzak.CodeExec.Roslyn" Version="0.4.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
  <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
</ItemGroup>

<!-- Without this line the dock's Extensions list is empty. -->
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>
```

| 套件 | 版本（附加元件 0.34.0） | 用途 |
| --- | --- | --- |
| `com.IvanMurzak.ReflectorNet` | 5.5.1 | 反射與序列化核心 |
| `com.IvanMurzak.McpPlugin` | 8.14.0 | 將編輯器連線到伺服器的 MCP 用戶端 |
| `com.IvanMurzak.Rql` | 0.3.0 | RQL，編輯器工具背後的查詢語言（僅限編輯器） |
| `com.IvanMurzak.CodeExec` | 0.4.0 | 為 `script-execute` 執行 C# 片段（除非你主動啟用，否則僅限編輯器） |
| `com.IvanMurzak.CodeExec.Roslyn` | 0.4.0 | Code-Exec 的 Roslyn 轉接器 |
| `Microsoft.CodeAnalysis.CSharp` | 4.12.0 | Roslyn C# 編譯器 |

版本必須與你安裝的 addon 相符。每個發行版都會在 README 中列出這些版本，而發行版 zip 也會將它們放在 `addons/godot_mcp/nuget-deps.json` 中；`godot-cli install-plugin` 會讀取該檔案，因此它絕不會弄錯版本。開發分支已將 `com.IvanMurzak.McpPlugin` 推進到 8.18.0，所以更新時請再確認一次。

另外，請在你的 `.csproj` 的 `<PropertyGroup>` 中保留 `<EnableDynamicLoading>true</EnableDynamicLoading>`。Godot 自己的 C# 範本就有這一行。少了它，用 Play 啟動的遊戲就無法建立任何 C# 腳本。

你不需要複製 DLL。執行 `dotnet restore`（或從 Godot 建置），addon 在編輯器階段就會從你的 NuGet 快取中找到這些套件。

## 手動步驟：啟用外掛

開啟 **Project, Project Settings, Plugins** 並啟用 **Godot-MCP**。建置 C# 專案（編輯器中的 Build 按鈕，或 `godot-cli build`）。載入成功時，Output 面板會印出：

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

**AI Game Developer** 停駐面板會出現在右上方的停駐區。接著請繼續閱讀[開始使用](https://ai-game.dev/zh-hant/docs/wiki/godot/getting-started)。

## 更新與移除

- 用你當初安裝時所用的同一個工具來更新：重新執行 `godot-cli install-plugin`（可選擇加上 `--version`）、使用應用程式，或從 Asset Library 安裝新版本並手動更新 NuGet 版本。
- 用 `godot-cli update` 更新 CLI 本身。
- `godot-cli remove-plugin ./MyGodotProject` 會在 `project.godot` 中停用該 addon。它不會刪除 `addons/godot_mcp/` 或 `.csproj` 中的項目；若想移除這些內容，請手動刪除。

## 匯出的遊戲

RQL、Code-Exec 和 Roslyn 套件帶有 `Condition`，會讓它們不被納入 `ExportDebug` 與 `ExportRelease` 建置，因此你匯出的遊戲不會包含它們。addon 的編輯器工具只在編輯器中編譯，永遠不會進入遊戲建置。從執行中的遊戲公開工具屬於選用功能，詳見[自訂工具](https://ai-game.dev/zh-hant/docs/wiki/godot/custom-tools)。

---

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

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