工具
27 个内置 Unreal MCP 工具——RQL、蓝图、C++ 源码、Python、截图与控制台，以及 Unreal Editor 中 AI 的示例提示词。
本页介绍 AI 智能体通过 Unreal MCP 在 Unreal Editor 中能做什么。该插件提供 7 个类别共 27 个工具。你很少需要按名称调用工具：用自然语言提出需求，智能体自会挑选合适的工具。了解这些类别，有助于你提出智能体真正能做到的请求。
每个工具的说明卡片和参数，请浏览 Unreal 工具目录。
RQL：一种统一的编辑器数据查询语言
Unreal MCP 并不是为每种编辑器操作提供一个工具。编辑器数据统一通过 RQL 处理，这是一种查询语言，一次调用即可读取和修改 Actor、组件、资产、关卡和编辑器状态。
| 工具 | 功能 |
|---|---|
rql-query | 对运行中的编辑器执行只读查询，返回紧凑的表格结果 |
rql-mutate | 以 set 或 call 结尾的查询；全有或全无、只算一步撤销，并支持 dry_run 预览 |
rql-schema | 列出数据源、函数和类；指定类型时，列出该类型的成员和方法 |
几个 RQL 写法示例（由智能体为你编写）：
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 技能学习这门语言，该技能还会列出已安装的扩展所新增的内容。
示例提示词：
- “列出关卡中每个点光源及其强度，然后把较暗的那些强度翻倍。”
- “以 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 参考。
截图工具系列
| 工具 | 作用 |
|---|---|
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 只提供固定的一组工具。参见 配置。要添加能力，可安装扩展或编写自定义工具。
仅限编辑器
全部 27 个工具都用于驱动编辑器。其中一些功能很强（rql-mutate、console-run-command、python-execute），因此它们都不会被编译进打包后的游戏。选择启用运行时连接的游戏只会暴露它自己注册的工具。
关于如何充分利用这些工具的提示，见 Unreal 最佳实践。