工具与 RQL — Unity · AI Game Developer Wiki

本页说明在连接 Unity MCP 之后，AI 智能体能在你的 Unity 项目中做什么：它能看到哪些工具，RQL 如何让它读取和修改编辑器中的几乎任何内容，以及哪些工具已安装但被隐藏。带参数的完整可搜索列表见 Unity 工具目录，查询语言的文档见 RQL 参考。

智能体默认看到的工具

从 1.0.0 版本起，插件让智能体的工具列表保持精简。安装后可见的是以下七个工具：

工具	功能
`rql-query`	用 RQL 查询读取编辑器数据：场景、GameObject、组件、资源、Console、设置、测试、性能分析器。
`rql-mutate`	用 RQL 修改编辑器数据或调用编辑器操作：创建、修改、移动和删除对象与资源，打开和保存场景。
`rql-schema`	描述 RQL 可用的来源、类型、成员和调用，并打印主题指南。智能体不确定时从这里开始。
`script-execute`	用 Roslyn 在编辑器中编译并运行 C# 代码，并返回结果。
`screenshot-isolated`	从选定角度单独渲染一个 GameObject，可选输出为 2x2 拼图，以便模型查看。
`tests-run`	运行 EditMode 或 PlayMode 测试，并返回每项测试的结果。
`unity-tool-list`	列出所有工具，以及智能体是否能看到它们。

精简的列表消耗更少的 token，给模型留出更多推理空间。其他工具仍然处于安装状态；参见隐藏的工具。

RQL：一种语言覆盖整个编辑器

RQL 是一种针对编辑器实时数据的查询语言。查询以来源开头，并通过以 | 分隔的阶段传递结果，例如 where、select、get、set 和 call。智能体不再为每个操作准备一个工具（旧的 gameobject-create、scene-save、console-get-logs 等几十个），而是编写一条查询。

读取已打开场景的完整层级：

roots | recurse children | select name active

查找玩家：

objects | where name == "Player" | select path name active

创建一个地面平面：

editor | call CreateGameObject({name: "Ground", primitive: "Plane"})

添加组件并保存：

objects | where name == "Player" | call AddComponent("Rigidbody")
editor | call SaveScenes()

只读取 Console 中的错误：

console | where logType == "Error"

每次 rql-mutate 调用都是一个撤销组，因此 Ctrl+Z 可以还原它；变更之后，被修改的资源、场景和打开中的预制体都会被保存。rql-mutate 还接受 dry_run 以预览将会发生的变化，以及 max_targets 来限制一次变更可触及的对象数量。

Unity 中的 RQL 来源

来源	内容
`scenes`、`roots`、`objects`	已加载的场景、它们的根 GameObject，以及其中的所有 GameObject。
`selection`	当前的编辑器选择。
`prefab`	在预制体模式下打开的预制体。
`editor`	编辑器操作：创建 GameObject、材质、文件夹和场景；打开并保存场景和预制体；复制、移动和删除资源；执行菜单项；播放模式状态。
`settings`	项目设置。
`console`	已捕获的编辑器日志条目。
`shaders`、`componentTypes`	可用的着色器和组件类型。
`tests`、`testResults`	测试树和最近一次的结果。
`profiler`	内存、渲染、脚本和帧数据；开始、停止、保存和加载采集。
`lighting`	活动场景的环境（环境光、雾、天空盒、太阳、反射）、Lighting Settings 以及烘焙。

资源用 unity.asset("Assets/…") 按路径寻址，或用 unity.assets("t:Material") 搜索。每个已安装的扩展都会添加自己的来源和类型，例如 tilemap 或 cinemachine。

由于 RQL 通过反射工作，智能体也能读取和设置你自己组件中的成员，而不只是 Unity 内置的组件。你可以通过自定义适配器让 RQL 了解你自己的类型。

脚本与 C# 执行

script-execute 用 Roslyn 编译一段 C# 代码片段并在编辑器中运行。它接受代码以及可选的 className、methodName、额外的 usings 和要 include 的辅助文件。它是 RQL 未覆盖之处的应急出口。在终端中，unity-mcp-cli exec 调用同一个工具：

unity-mcp-cli exec 'Application.unityVersion'

若要写入文件而不是运行代码，隐藏工具 script-read、script-update-or-create 和 script-delete 可以管理项目中的 .cs 文件。更改后 Unity 会重新编译；连接会在域重载期间短暂断开，然后自行恢复。

测试

tests-run 运行 EditMode 或 PlayMode 测试（testMode，默认 EditMode）。可按程序集、命名空间、类或方法过滤，或者传入基于 tests 来源的 RQL 选择，把选中的测试作为一次运行执行。结果可以用 RQL 基于 testResults 过滤。选项控制是否包含通过的测试、消息、堆栈跟踪和 Console 日志，从而让输出保持精简。

unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'

截图

screenshot-isolated 默认可见。另外三个是隐藏的：screenshot-scene-view、screenshot-game-view 和 screenshot-camera。图像最长边被限制为 3840 像素，以便通过 MCP 传输。截图需要图形设备：以 -nographics 启动的编辑器会返回错误，而不是空白图像。

隐藏的工具

这些工具已经安装，但不在智能体的列表中。隐藏的工具在被按名称调用时仍会运行。

截图：screenshot-scene-view、screenshot-game-view、screenshot-camera。
脚本：script-read、script-update-or-create、script-delete。
包：用于 Unity Package Manager 的 package-list、package-search、package-add、package-remove。
工具管理：tool-set-visibility，以及其已弃用的别名 tool-set-enabled-state。

在 AI Game Developer 窗口中显示它们（Tools > Open），或用 tool-set-visibility 工具，或使用：

unity-mcp-cli configure ./MyUnityProject --enable-tools package-add,package-list

提示词与技能

插件还附带 46 个 MCP 提示词（斜杠命令模板，例如 setup-basic-scene 或 add-event-system），分为六组：脚本编写、GameObject 与组件、场景、调试与测试、资源管理、动画与时间轴。它们默认隐藏；在 Prompts > Open 中启用你需要的那些。

Skills 是插件生成到你的智能体技能文件夹中的 Markdown 文件。它们包括 unity-rql 指南，内含 Unity 及每个已安装扩展的 RQL 语法，以及安装和 CLI 说明。可在窗口中通过 Skills > Auto-generate 开启，或运行 unity-mcp-cli setup-skills <agent>。

旧教程中的工具名称

\1.0.0 版本移除了“一个操作一个工具”的工具。如果某篇教程提到了其中之一，请改用 RQL：

gameobject-create、gameobject-find、gameobject-modify、gameobject-destroy、gameobject-component-*：针对 objects、roots 和 selection 使用 set 和 call 的 RQL。
scene-create、scene-open、scene-save：editor | call NewScene(…)、OpenScene(…)、SaveScenes()。
assets-*、assets-prefab-*、assets-material-create：unity.asset(…)、unity.assets(…) 以及 editor 调用，例如 CreateMaterial、CopyAsset、InstantiatePrefab。
console-get-logs、console-clear-logs：console 来源和 editor | call ClearConsole()。
editor-application-*、editor-selection-*：editor 的成员，例如 isPlaying 和 selection。
reflection-method-find、reflection-method-call、type-get-json-schema：RQL call 和 rql-schema。
profiler-*：profiler 来源。

Unity 工具目录与 RQL 参考。
自定义工具，用于添加你自己的工具。
Unity 最佳实践，用于撰写提示词。

智能体默认看到的工具#

RQL：一种语言覆盖整个编辑器#

Unity 中的 RQL 来源#

脚本与 C# 执行#

测试#

截图#

隐藏的工具#

提示词与技能#

旧教程中的工具名称#

相关页面#