# 扩展 — Unity · AI Game Developer Wiki

Unity MCP 扩展为 Animation、Cinemachine、Input System、Navigation、ProBuilder、Splines、Terrain、Tilemap、Timeline 和粒子系统添加 AI 支持。

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

扩展是可选的 Unity 包，用于让 AI 代理了解特定的 Unity 功能，例如 Cinemachine 相机、ProBuilder 网格或 2D Tilemap。只安装你的项目用到的那些。本页列出十个官方扩展、每个扩展新增的内容以及如何安装。每个扩展在 [Unity 扩展目录](https://ai-game.dev/docs/extensions/unity) 中还设有单独的详情页。

## 扩展的工作原理

从 Unity MCP 1.0.0（以及扩展版本 2.0.0）起，扩展**不新增任何 MCP 工具**。取而代之的是，它贡献一个 **RQL 模块**：新的数据源、函数和类型适配器，现有的 `rql-query` 和 `rql-mutate` 工具都能理解它们。代理的工具列表规模保持不变，而扩展的指南会被加入生成的 `unity-rql` skill 中，因此只要安装好包并重新生成 skills，代理就能学会新的语法。

例如，安装 AI Tilemap 后，代理可以通过 RQL 绘制瓦片：

```text
objects | get components | where $ is Tilemap | call BoxFill("Assets/Tiles/Grass.asset", -5, -3, 5, 3)
```

每个扩展都依赖于核心插件 `com.ivanmurzak.unity.mcp`，以及它所基于的 Unity 包。安装扩展会同时引入这两者。它们都支持 Unity 2022.3 及更高版本。

## 官方扩展

| 扩展 | 包 id | 基于 | RQL 新增内容 |
| --- | --- | --- | --- |
| AI Animation | `com.ivanmurzak.unity.mcp.animation` | Animation 模块 | `animation` 数据源；AnimationClip、AnimatorController 和 Animator 类型 |
| AI Cinemachine | `com.ivanmurzak.unity.mcp.cinemachine` | `com.unity.cinemachine` | `cinemachine` 数据源；CinemachineCamera、CinemachineBrain |
| AI InputSystem | `com.ivanmurzak.unity.mcp.inputsystem` | `com.unity.inputsystem` | `input` 数据源；InputActionAsset |
| AI Navigation | `com.ivanmurzak.unity.mcp.navigation` | `com.unity.ai.navigation` | `navigation` 数据源；NavMeshSurface、NavMeshLink、NavMeshAgent |
| AI Particle System | `com.ivanmurzak.unity.mcp.particlesystem` | Particle System 模块 | ParticleSystem 及其各个模块、曲线和渐变 |
| AI ProBuilder | `com.ivanmurzak.unity.mcp.probuilder` | `com.unity.probuilder` | `probuilder` 数据源和函数；ProBuilderMesh |
| AI Splines | `com.ivanmurzak.unity.mcp.splines` | `com.unity.splines` | `splines` 数据源；SplineContainer |
| AI Terrain | `com.ivanmurzak.unity.mcp.terrain` | Terrain 模块 | `terrain` 数据源；高度函数；Terrain、TerrainData |
| AI Tilemap | `com.ivanmurzak.unity.mcp.tilemap` | Tilemap 模块和 2D Tilemap Extras | `tilemap` 数据源和函数；Tilemap、RuleTile |
| AI Timeline | `com.ivanmurzak.unity.mcp.timeline` | `com.unity.timeline` | `timeline` 数据源；TimelineAsset、轨道、剪辑、PlayableDirector |

每个模块具体的数据源、函数和调用都列在其 [目录页](https://ai-game.dev/docs/extensions/unity) 上，在编辑器内则位于 `rql-schema` 中。

## 从 AI Game Developer 窗口安装

1. 打开 **Window > AI Game Developer — MCP**。
2. 滚动到 **Extensions**。
3. 点击所需扩展旁边的 **Install**。

该窗口会把 OpenUPM 作用域注册表和该包（取 OpenUPM 上的最新版本）添加到 `Packages/manifest.json`。随后 Unity 会解析并导入它。

## 使用 unity-mcp-cli 安装

```bash
unity-mcp-cli install-extension --list
unity-mcp-cli install-extension Tilemap ./MyUnityProject
```

该 id 可以是目录名称（`Tilemap`、`Cinemachine`、`ProBuilder`……），也可以是包 id（`com.ivanmurzak.unity.mcp.tilemap`），匹配时忽略大小写。路径默认为当前文件夹。该命令会解析最新的 OpenUPM 版本，绝不会降级已安装的更高版本，如果扩展已是最新则不做任何操作。可用 `--extension-version <version>` 固定版本（不要用 `--version`，它打印的是 CLI 版本）。之后请打开或切换到 Unity，以便 Package Manager 解析它。

## 使用 OpenUPM 安装

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

每个扩展在 [Unity-MCP 仓库](https://github.com/IvanMurzak/Unity-MCP/tree/main/extensions) 中的 README 还给出了该扩展的 `.unitypackage` 安装包链接，其用法与 [核心安装器](https://ai-game.dev/zh-hans/docs/wiki/unity/installation#installer) 相同。

## 使用桌面应用安装

[AI Game Dev 应用](https://ai-game.dev/docs/app) 也可以把 Unity 扩展安装到当前打开的项目中。它使用每个扩展各自的 OpenUPM 版本，与核心插件版本相互独立。参见 [应用文档](https://ai-game.dev/zh-hans/docs/wiki/app)。

## 安装之后

- 重新生成 skills（在窗口中 **Skills > Generate**，或执行 `unity-mcp-cli setup-skills <agent>`），使代理的 `unity-rql` skill 包含新模块。
- 如果代理似乎不认识新类型，就让它从 `rql-schema` 入手，例如“先用 rql-schema 看看 cinemachine 数据源提供了什么，然后为 Player 添加一个跟随相机”。
- 旧教程中的工具名（如 `tilemap-set-tile` 或 `cinemachine-camera-create`）已不复存在。每个扩展的 README 都给出了它们对应的 RQL 写法。

## 更新与移除

扩展的版本与核心插件相互独立。可在 Package Manager 中更新它们，或重新运行 `install-extension`。移除时像其他任何包一样在 Package Manager 中操作即可。请让核心插件与扩展一同保持在当前版本：扩展会声明其所需的最低核心版本。

## 编写你自己的扩展

你的项目代码可以直接添加工具（参见 [自定义工具](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools)），也可以通过 [自定义 RQL 适配器](https://ai-game.dev/docs/rql/custom-adapters) 让 RQL 认识你自己的类型。仓库中的 [扩展指南](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/dev/extensions.md) 介绍了官方扩展是如何构建和测试的。

## 相关页面

- [Unity 扩展目录](https://ai-game.dev/docs/extensions/unity) 和 [所有扩展](https://ai-game.dev/docs/extensions)。
- [工具与 RQL](https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql)。

---

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

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