# 扩展 — Godot · AI Game Developer Wiki

安装可选的 Godot MCP 扩展：AnimationPlayer、CSG、GridMap、导航、粒子、TileMapLayer、Beehave、Dialogic、Phantom Camera 和 Terrain3D。

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

扩展是可选的 NuGet 包，它们让 Godot MCP 了解 Godot 的更多部分以及常用的 Godot 插件。只安装你的项目需要的那些。本页列出这些扩展，说明它们如何工作，并介绍三种安装方式。每个扩展的说明和示例都在本站的 [Godot extensions](https://ai-game.dev/docs/extensions/godot) 页面上。

## 扩展如何工作

每个扩展都是一个 RQL 模块。它本身不添加任何 MCP 工具，而是用新的数据源、经过校验的属性和调用扩展核心的 `rql-query`、`rql-mutate` 和 `rql-schema` 工具，并在 agent 的 `godot-rql` 技能中添加一份指南。你的 agent 的工具列表大小保持不变，agent 通过 `rql-schema` 了解新的领域：

```text
rql-schema "Particles"
```

这些包包含 C# 源码和构建设置，会针对你项目自己的 GodotSharp 编译。每个扩展都有自己的版本和发布节奏。

## 可用的扩展

| 扩展 | 包 id | 新增内容 | 依赖 |
| --- | --- | --- | --- |
| Animation Tools | `com.IvanMurzak.Godot.MCP.Animation` | AnimationPlayer 的库、动画、轨道和关键帧 | Godot 4.3+ |
| Beehave Tools | `com.IvanMurzak.Godot.MCP.Beehave` | 列出行为树及其节点 | Beehave 插件、Godot 4.3+ |
| CSG Tools | `com.IvanMurzak.Godot.MCP.CSG` | 经过校验的 CSG 图元尺寸和 `rootShape` | Godot 4.3+ |
| Dialogic Tools | `com.IvanMurzak.Godot.MCP.Dialogic` | 列出并创建时间线和角色，向时间线追加文本 | Dialogic 插件、Godot 4.4+ |
| GridMap Tools | `com.IvanMurzak.Godot.MCP.GridMap` | GridMap 设置、单元格行和单元格编辑 | Godot 4.3+ |
| Navigation Tools | `com.IvanMurzak.Godot.MCP.Navigation` | 2D 和 3D 导航代理、区域、链接以及区域烘焙 | Godot 4.3+ |
| Particles Tools | `com.IvanMurzak.Godot.MCP.Particles` | 2D 和 3D 的 GPU 粒子：经过校验的发射器设置和重启 | Godot 4.3+ |
| PhantomCamera Tools | `com.IvanMurzak.Godot.MCP.PhantomCamera` | 列出虚拟相机和宿主，设置跟随与注视目标 | Phantom Camera 插件、Godot 4.4+ |
| Terrain3D Tools | `com.IvanMurzak.Godot.MCP.Terrain3D` | 地形数据源、区域尺寸更改和材质创建 | Terrain3D 插件、Godot 4.4+ |
| Tilemap Tools | `com.IvanMurzak.Godot.MCP.Tilemap` | TileMapLayer 已使用单元格的行和单元格编辑 | Godot 4.3+ |

每个扩展还需要一个包含 RQL 工具的核心插件（0.28.0 之后的任何版本）。

**说明**

安装器只添加扩展包。对于 Beehave、Dialogic、Phantom Camera 和 Terrain3D，请先把对应的第三方插件自行安装到你的项目中。

## 使用 godot-cli 安装

```bash
godot-cli install-extension com.IvanMurzak.Godot.MCP.CSG ./MyGodotProject
godot-cli build ./MyGodotProject
```

`install-extension` 会在扩展目录中查找该 id，先按包 id 查找，再按名称查找，且不区分大小写（因此 `"CSG Tools"` 也可以）。然后它会在你项目的 `.csproj` 中添加或更新 `<PackageReference>`：

- 尚未引用：添加该引用；
- 引用了较旧的版本：更新它；
- 已是最新：不做任何更改。

不加 `--version` 时，引用会浮动到 NuGet 上的最新稳定版本（`Version="*"`）。使用 `--version <x.y.z>` 指定确切版本。安装后请构建项目，以便 Godot 还原并编译该包；Godot 没有自动还原步骤。

## 从停靠面板安装

AI Game Developer 停靠面板的 **Extensions** 区域列出相同的目录，并提供 **Install** 和 **Update** 按钮。它以与 CLI 相同的方式编辑 `.csproj`。之后请重新构建。如果停靠面板提示找不到 `.csproj`，说明该插件不在 Godot C# 项目中。

## 从 AI Game Dev 应用安装

对于 Godot 项目，[AI Game Dev app](https://ai-game.dev/zh-hans/docs/wiki/app) 会在侧边栏显示 **Extensions** 按钮，点击后打开相同的目录，并通过与 `godot-cli` 相同的代码执行安装。它的斜杠命令 `/install-extension` 在应用聊天中做同样的事：不带参数时列出目录，带 id 时安装到当前项目。引擎扩展与应用自身的包并不是一回事。

## 扩展目录

扩展列表位于随插件一起发布的 `addons/godot_mcp/extensions.catalog.json` 中。停靠面板、`godot-cli` 和应用读取的都是这同一个文件。停靠面板是从你已编译的项目中读取它的，因此你的 `.csproj` 必须将它嵌入：

```xml
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>
```

`godot-cli install-plugin` 和应用会为你添加这一行。如果你是手动安装的，而 Extensions 列表是空的，说明缺少这一行；添加它并重新构建。请参阅 [Installation](https://ai-game.dev/zh-hans/docs/wiki/godot/installation#nuget-packages)。

## 使用扩展

构建之后，直接提问即可。例如，在安装了 CSG Tools 之后：

- “用 3x3x3 的立方体构建一个 CSG 组合器，并从中减去一个半径为 1.8 的球体。”
- “列出场景中每个 CSG 形状及其运算方式和尺寸。”

智能体使用 `rql-mutate` 创建节点（每次调用是一个可撤销的步骤），并用 `rql-query` 检查结果。无效的值（例如负的半径）会导致整个更改失败，并让场景保持不变。

## 编写你自己的扩展

Godot-MCP 仓库包含一个扩展模板（`templates/extension/`）以及一份关于构建、测试和发布模块的 monorepo 指南。对于一次性的项目工具，普通的[自定义工具](https://ai-game.dev/zh-hans/docs/wiki/godot/custom-tools)更简单。

---

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

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