# 扩展 — Unreal Engine · AI Game Developer Wiki

Unreal MCP 的可选扩展：Control Rig、Enhanced Input、GAS、Landscape 与 Water、Niagara 和 PCG。各自的作用及安装方法。

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

扩展让 Unreal MCP 了解更多的引擎系统。每个扩展都是一个独立的、可选的 Unreal 插件，拥有各自的版本和发布节奏。只安装你的项目用得到的那些。

所有扩展都位于 [Unreal-MCP 仓库](https://github.com/IvanMurzak/Unreal-MCP)中，并在 [Unreal 扩展页面](https://ai-game.dev/docs/extensions/unreal)上列出。

## 扩展的工作原理

每个扩展都是一个 **RQL 模块**。它不会添加自己的 MCP 工具，而是向核心的 `rql-query`、`rql-mutate` 和 `rql-schema` 工具添加源、操作和成员（参见[工具](https://ai-game.dev/zh-hans/docs/wiki/unreal/tools#rql)），并在 `unreal-rql` 技能中添加一节内容，教智能体如何使用它。这样智能体的工具列表保持简短，能力范围却不断扩大。

反射机制已经能暴露每个已加载引擎类型的属性，所以即使没有扩展，智能体也能（例如）设置 Niagara 组件的资产。扩展补充的是反射无法呈现的内容，比如列出 Niagara 系统及其发射器，或雕刻地形。

## 要求

- Unreal Engine **5.7 或更高版本**（扩展测试套件验证了 5.7 和 5.8）。
- 同一项目中安装 Unreal MCP **0.26.0 或更高版本**。
- 一套 C++ 工具链。扩展以源码形式分发，需要针对你的项目和引擎进行编译。
- 每个扩展所依赖的引擎插件。安装器会自动为你启用它。

没有任何扩展依赖其他扩展。

## 六个扩展

| 扩展 | 扩展 ID | 引擎插件 | 新增内容 |
| --- | --- | --- | --- |
| AI ControlRig | `com.ivanmurzak.unreal-ai-control-rig` | ControlRig | 创建带骨骼、控制器和双骨骼 IK 求解器的 Rig；查询 Control Rig 蓝图和组件 |
| AI EnhancedInput | `com.ivanmurzak.unreal-ai-enhanced-input` | EnhancedInput | 查询 Input Action 和 Mapping Context，创建动作和上下文，映射按键 |
| AI GAS | `com.ivanmurzak.unreal-ai-gas` | GameplayAbilities | 查询技能、效果和属性集类以及已授予的技能，向 Actor 授予技能 |
| AI Landscape | `com.ivanmurzak.unreal-ai-landscape` | Water | 创建、雕刻和绘制地形；查询地形、水体和水分区 |
| AI Niagara | `com.ivanmurzak.unreal-ai-niagara` | Niagara | 查询 Niagara 系统及其发射器，将系统放置到关卡中 |
| AI PCG | `com.ivanmurzak.unreal-ai-pcg` | PCG | 查询 PCG 图表和组件，添加组件并运行生成 |

每个扩展的当前版本为 0.2.0。

### 每个 RQL 模块包含的内容

| 扩展 | 源 | 操作 |
| --- | --- | --- |
| AI ControlRig | `controlRigs`、`controlRig` | `CreateRig`、`AddBone`、`AddControl`、`AddTwoBoneIK` |
| AI EnhancedInput | `inputActions`、`inputContexts`、`enhancedInput` | `CreateAction`、`CreateContext`、`AddMapping`、`RemoveMapping`、`AddActionEvent`、`AddMappingContextOnBeginPlay` |
| AI GAS | `gasAbilities`、`gasEffects`、`gasAttributeSets`、`gas` | `GrantAbility` |
| AI Landscape | `landscapes`、`waterBodies`、`waterZones`、`landscape` | `Create`、`Sculpt`、`Paint`、`CreateLayerMaterial` |
| AI Niagara | `niagaraSystems`、`niagara` | `SpawnSystem` |
| AI PCG | `pcgGraphs`、`pcg` | `AddComponent`、`Generate` |

你不需要记住这些名称。智能体会从 `rql-schema` 和技能中读取它们。当你阅读智能体的查询时，它们会派上用场。

## 使用 unreal-mcp-cli 安装

先关闭 Unreal 编辑器，然后：

```bash
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-niagara ./YourProject
```

该命令会：

1. 在扩展索引中查找该扩展 ID，并找到其最新的 GitHub 发布版本。
2. 将插件放到 `<project>/Plugins/<PluginName>/`（例如 `Plugins/UnrealAINiagara/`）。
3. 在你的 `.uproject` 中启用该扩展及其引擎插件。
4. 把编译留到下次启动编辑器时进行，或使用 `--build` 立即编译。

重复运行是安全的：如果相同版本已安装并启用，则不会有任何改动。除非你指定版本，否则它绝不会降级已安装的扩展。

常用参数：

- `--version 0.2.0` 安装指定的确切版本。
- `--build` 立即编译（Windows、macOS 和 Linux）。
- `--source <dir>` 从本地文件夹安装，适用于离线机器和 CI。
- `--force` 即使已是最新也重新安装。

你可以通过扩展 ID、显示名称或插件文件夹名称来安装。

## 从编辑器或应用中安装

- **在编辑器中：** AI Game Developer 窗口的 **Extensions** 区域会列出已安装的扩展，点击 **Refresh catalog** 后还会列出可用的扩展。**Install** 和 **Update** 会下载扩展；新扩展在编译完成前会显示“Installed · needs editor restart to compile”，或者你可以使用 **Compile (Live Coding)**。
- **在 AI Game Dev 应用中：** 使用侧边栏的扩展操作（或应用 CLI 中的 `/install-extension`）。应用会选择最新的发布版本。参见[项目与引擎](https://ai-game.dev/zh-hans/docs/wiki/app/projects-and-engines#extensions)。

## 启用或停用扩展

Extensions 区域中每个已安装的扩展都有一个启用开关。关闭它会立即从智能体中移除其新增内容，无需重启编辑器。该选择会在编辑器会话之间保留。

## 示例提示词

- “列出项目中的每个 Niagara 系统，并显示 NS\_Fire 的发射器。”（AI Niagara）
- “创建一个 Boolean Input Action IA\_Jump 和一个 Mapping Context IMC\_Default，并把空格键映射到它。”（AI EnhancedInput）
- “向 Hero 这个 Actor 授予 GA\_Fireball。”（AI GAS）
- “创建一个地形，并在上面绘制草地层。”（AI Landscape）
- “向 ForestVolume 这个 Actor 添加一个带 PCG\_Forest 的 PCG 组件并生成它。”（AI PCG）
- “创建一个带三骨骼链的 Rig，并在其上添加双骨骼 IK。”（AI ControlRig）

## 编写你自己的扩展

任何 Unreal 插件都可以添加自己的 RQL 模块、工具、提示词或资源，而无需 fork Unreal MCP。参见[自定义工具](https://ai-game.dev/zh-hans/docs/wiki/unreal/custom-tools)。

---

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

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