# 安装 — Godot · AI Game Developer Wiki

通过 AI Game Dev 应用、godot-cli、Godot 资产库或发布 zip 安装 Godot MCP 插件，并为你的 .csproj 配上准确的 NuGet 包。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/godot/installation)。

本页介绍将 Godot MCP 添加到 Godot C# 项目的所有方式，以及每种方式能为你做什么。如果你只想让它跑起来，请使用桌面应用或 `godot-cli`：它们都能一步完成插件安装、修改 `.csproj` 并在编辑器中启用插件。手动方式（资产库、发布 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-hans/docs/wiki/app)可以把 Godot MCP 安装到你选定的项目中，然后打开已连接到你的账号的编辑器。它自带一份安装器副本，因此你不需要 Node.js 或 npm。该应用始终安装最新发布的插件，并执行与 `godot-cli install-plugin` 相同的三件事：把插件文件放入 `addons/godot_mcp/`，将 NuGet 包和扩展目录添加到你的 `.csproj`，并在 `project.godot` 中启用插件。

从[下载页面](https://ai-game.dev/zh-hans/download)下载该应用。如何安装它以及如何选择项目见[应用安装](https://ai-game.dev/zh-hans/docs/wiki/app/installation)；应用的命令行在[应用 CLI](https://ai-game.dev/zh-hans/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-hans/docs/wiki/godot/cli)。

## 方式 3：Godot 资产库

1. 在 Godot 编辑器中，打开顶部的 **AssetLib** 标签页。
2. 搜索 **Godot-MCP** 并打开该资产。
3. 点击 **Download**，然后点击 **Install**。Godot 会把插件解包到 `res://addons/godot_mcp/`。
4. 将 NuGet 包和目录行添加到你的 `.csproj`（见下文）。
5. 启用插件（见下文）。

资产库条目始终指向某个已打标签的发布版本，因此你得到的是经过验证的快照。它只包含插件文件：第 4 步和第 5 步仍需你自行完成。

## 方式 4：GitHub 发布 zip 或源码副本

从 [Godot-MCP releases](https://github.com/IvanMurzak/Godot-MCP/releases/latest) 页面下载 `godot-mcp-addon-<version>.zip` 并解压到项目根目录。压缩包中已经包含 `addons/godot_mcp/`，因此文件会落在 `res://addons/godot_mcp/`。你也可以从仓库克隆中复制 `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# 编译器 |

版本必须与你安装的插件一致。每个版本都会在其 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 中构建），插件在编辑器时就会从 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-hans/docs/wiki/godot/getting-started)。

## 更新与移除

- 使用与安装时相同的工具进行更新：重新运行 `godot-cli install-plugin`（可选带上 `--version`），使用应用，或从 Asset Library 安装新版本并手动更新 NuGet 版本。
- 使用 `godot-cli update` 更新 CLI 本身。
- `godot-cli remove-plugin ./MyGodotProject` 会在 `project.godot` 中禁用该插件。它不会删除 `addons/godot_mcp/` 或 `.csproj` 中的条目；如果你想彻底移除它们，请手动删除。

## 导出的游戏

RQL、Code-Exec 和 Roslyn 包带有 `Condition`，使它们不会包含在 `ExportDebug` 和 `ExportRelease` 构建中，因此你导出的游戏不会携带它们。该插件的编辑器工具仅在编辑器中编译，永远不会进入游戏构建。从运行中的游戏暴露工具需要主动启用，相关说明见[自定义工具](https://ai-game.dev/zh-hans/docs/wiki/godot/custom-tools)。

---

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

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