# 工具 — Unreal Engine · AI Game Developer Wiki

27 个内置 Unreal MCP 工具——RQL、蓝图、C++ 源码、Python、截图与控制台，以及 Unreal Editor 中 AI 的示例提示词。

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

本页介绍 AI 智能体通过 Unreal MCP 在 Unreal Editor 中能做什么。该插件提供 **7 个类别共 27 个工具**。你很少需要按名称调用工具：用自然语言提出需求，智能体自会挑选合适的工具。了解这些类别，有助于你提出智能体真正能做到的请求。

每个工具的说明卡片和参数，请浏览 [Unreal 工具目录](https://ai-game.dev/docs/tools/unreal)。

## RQL：一种统一的编辑器数据查询语言

Unreal MCP 并不是为每种编辑器操作提供一个工具。编辑器数据统一通过 **RQL** 处理，这是一种查询语言，一次调用即可读取和修改 Actor、组件、资产、关卡和编辑器状态。

| 工具 | 功能 |
| --- | --- |
| `rql-query` | 对运行中的编辑器执行只读查询，返回紧凑的表格结果 |
| `rql-mutate` | 以 `set` 或 `call` 结尾的查询；全有或全无、只算一步撤销，并支持 `dry_run` 预览 |
| `rql-schema` | 列出数据源、函数和类；指定类型时，列出该类型的成员和方法 |

几个 RQL 写法示例（由智能体为你编写）：

```text
actors | where $ is PointLight | select $ref Label Intensity
actors | where Label == "Door_01" | set Location = "(0, 0, 100)"
editor | call SpawnActor("PointLight")
console | where Verbosity == "Error"
```

除了 Actor 和组件，RQL 还能操作：

- \*\*资产与关卡：\*\*创建、复制、移动、删除和导入资产，创建文件夹和材质实例，打开、创建和保存关卡，添加流送子关卡。
- \*\*编辑器状态：\*\*选中项、Play In Editor 状态、撤销历史、编辑器日志。
- \*\*DataTable：\*\*读取和编辑行（`Rows["Sword"].Damage`），添加、删除、重命名和复制行。
- \*\*Gameplay 标签：\*\*列出、添加、删除和重命名标签。
- \*\*Project Settings 与 Editor Preferences：\*\*读取和修改配置属性，并保存到对应的 `.ini` 文件中。
- \*\*蓝图图表：\*\*添加函数调用、变量、事件、类型转换、分支和循环，连接引脚，然后 `call Compile()`。
- \*\*控件蓝图：\*\*遍历和编辑控件树，添加控件并设置布局。
- \*\*用户自定义结构体：\*\*添加、删除和重命名字段。
- \*\*关卡序列：\*\*绑定 Actor，添加轨道和关键帧。

每次修改都是一个编辑器事务，因此 **Ctrl+Z** 即可撤销。智能体通过 `unreal-rql` 技能学习这门语言，该技能还会列出已安装的[扩展](https://ai-game.dev/zh-hans/docs/wiki/unreal/extensions)所新增的内容。

示例提示词：

- “列出关卡中每个点光源及其强度，然后把较暗的那些强度翻倍。”
- “以 5 乘 4 的网格生成 20 个立方体，彼此间隔 200 单位。”
- “向 DT\_Weapons DataTable 添加一行 Bow，Damage 为 7。”
- “将游戏默认地图设置为 /Game/Maps/Arena。”

## 蓝图工具族

蓝图编写是 Unreal 主要的脚本编写方式，智能体可以获得完整的反馈闭环：创建、编辑、编译、读取错误、修复。

| 工具 | 功能 |
| --- | --- |
| `blueprint-create` | 基于父类创建蓝图类 |
| `blueprint-get` | 汇总蓝图信息：变量、组件、函数与事件、父类链 |
| `blueprint-add-component` | 向构造脚本添加组件 |
| `blueprint-remove-component` | 移除组件 |
| `blueprint-add-variable` | 添加带类型的成员变量 |
| `blueprint-modify-variable` | 修改成员变量 |
| `blueprint-set-default` | 设置类默认属性 |
| `blueprint-add-function` | 添加函数存根 |
| `blueprint-add-event` | 添加事件，例如 BeginPlay 或 Tick |
| `blueprint-compile` | 编译并返回结构化的错误与警告列表 |
| `blueprint-spawn` | 在关卡中放置该蓝图的实例 |

示例：“创建一个 Actor 蓝图 BP\_Door，带一个静态网格体组件和布尔变量 IsOpen，编译它并在原点放置一个实例。”

## 源码 / C++ 工具族

| 工具 | 功能 |
| --- | --- |
| `source-read` | 分片读取项目中的 C++ 文件 |
| `source-create-class` | 搭建新的 C++ 类（头文件和源文件） |
| `source-update` | 编辑源文件 |
| `source-delete` | 删除源文件 |
| `source-list` | 列出模块的源文件 |
| `source-compile` | 在 Live Coding 启用时用它编译，否则使用 Unreal Build Tool，并返回结构化的错误报告 |

所有文件操作都限于 `<Project>/Source/`。示例：“创建一个 C++ 组件 UHealthComponent，包含 MaxHealth 和一个 TakeDamage 函数，编译并修复所有错误。”

## Python 工具族

| 工具 | 功能 |
| --- | --- |
| `python-execute` | 在编辑器中运行 Python，并预先导入 `unreal` 模块 |

最后一个表达式会作为结果返回，`print` 的输出会以日志形式回传，错误会指向出错的那一行。`include` 会从 `<Project>/.ai-game-dev/snippets` 中添加辅助文件或文件夹，`timeout`（默认 30 秒）可终止失控的脚本。该插件会启用 Unreal 的 Python Editor Script Plugin；Python 仅在编辑器内可用，绝不会打包进游戏。蓝图图表连线未向 Python 开放；如需操作请使用蓝图工具或 RQL。

你也可以在终端中通过 `unreal-mcp-cli exec` 运行 Python，参见 [CLI 参考](https://ai-game.dev/zh-hans/docs/wiki/unreal/cli#exec)。

## 截图工具系列

| 工具 | 作用 |
| --- | --- |
| `screenshot-viewport` | 捕获当前活动的编辑器视口 |
| `screenshot-game-view` | 捕获 Play In Editor 游戏视图 |
| `screenshot-camera` | 从相机 Actor 渲染 |
| `screenshot-isolated` | 单独渲染一个 Actor |

图像以 PNG 内容返回，模型可以直接查看，默认 1024 像素，每边最多 2048 像素。这些工具需要由 GPU 支持的编辑器；在 `-nullrhi` 下会返回错误。示例：“从 CameraActor\_Main 截图，并告诉我光照是否太暗。”

## 控制台与工具列表

| 工具 | 作用 |
| --- | --- |
| `console-run-command` | 执行 Unreal 控制台命令或设置控制台变量 |
| `unreal-tool-list` | 列出所有工具（包括隐藏工具），可附带过滤条件、描述和输入参数 |

读取日志、Play In Editor 状态和当前选择都通过 RQL 完成。

## 代理看不到的工具

少数**系统工具**用于支撑 CLI 和应用本身，不会展示给 AI 代理：

- `ping`：检查插件、桥接和服务端链路。
- `unreal-skill-generate`：为每个工具在技能文件夹（默认 `.claude/skills`）中写入一个 `SKILL.md`；**Generate skill files** 按钮就是调用它。
- `unreal-skill-create`：在插件的编辑器模块中生成一个新的 C++ 工具文件。这需要源码安装的插件，并且要重新构建编辑器后该工具才能生效。
- `editor-quit`：保存并关闭由 CLI 会话启动的编辑器。

## 提示与资源

该插件还提供一个 MCP 提示 `level-design-brief`（根据主题生成关卡设计简报），以及两个资源：`unreal://project/levels`（当前世界及其关卡的 JSON 快照）和 `unreal://project/icon`。

## 控制代理能看到什么

在 **MCP Tools** 窗口中隐藏不需要的工具，或通过 `UNREAL_MCP_TOOLS` 只提供固定的一组工具。参见 [配置](https://ai-game.dev/zh-hans/docs/wiki/unreal/configuration#tool-visibility)。要添加能力，可安装[扩展](https://ai-game.dev/zh-hans/docs/wiki/unreal/extensions)或编写[自定义工具](https://ai-game.dev/zh-hans/docs/wiki/unreal/custom-tools)。

## 仅限编辑器

全部 27 个工具都用于驱动编辑器。其中一些功能很强（`rql-mutate`、`console-run-command`、`python-execute`），因此它们都不会被编译进打包后的游戏。选择启用[运行时连接](https://ai-game.dev/zh-hans/docs/wiki/unreal/custom-tools#runtime)的游戏只会暴露它自己注册的工具。

关于如何充分利用这些工具的提示，见 [Unreal 最佳实践](https://ai-game.dev/docs/best-practices/unreal)。

---

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

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