# 工具 — Godot · AI Game Developer Wiki

AI 智能体在 Godot 编辑器中使用的 Godot MCP 工具：针对节点、场景和资源的 RQL 查询，C# 与 GDScript 脚本，截图以及游戏内工具。

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

Godot MCP 内置 24 个工具，分为 9 个族。大多数编辑器操作都通过三个 RQL 工具完成，因此智能体只需一种查询语言就能处理节点、场景、资源、文件和编辑器状态，而不必使用几十个彼此独立的工具。本页介绍每个工具族以及智能体在何时使用它。带参数和示例提示词的可搜索列表见 [Godot tools catalog](https://ai-game.dev/docs/tools/godot)。

## 工具族

| 族 | 工具 | 用途 |
| --- | --- | --- |
| rql | `rql-query`, `rql-mutate`, `rql-schema` | 读取并修改正在运行的编辑器：节点、Godot 属性、场景、资源、文件、项目设置、输入映射、autoload、组、信号以及编辑器状态。 |
| script | `script-read`, `script-create`, `script-update`, `script-delete`, `script-attach-to-node`, `script-validate`, `script-build`, `script-execute` | C# 和 GDScript 文件、附加脚本、校验 GDScript、构建 C# 项目以及在编辑器中运行 C#。 |
| screenshot | `screenshot-viewport`, `screenshot-camera`, `screenshot-isolated` | 编辑器视口、某个摄像机或单独渲染的某个节点的 PNG 图像。 |
| console | `console-get-logs`, `console-clear-logs` | 正在运行的游戏输出的日志。在编辑器中对应 RQL 的 `console` 源。 |
| reflection | `reflection-method-find`, `reflection-method-call` | 在运行中的游戏里查找并调用 C# 方法。在编辑器中对应 RQL 的 `call`。 |
| runtime-errors | `runtime-errors-get`, `runtime-errors-clear` | 运行中的游戏内部抛出的错误。默认关闭。 |
| ping | `ping` | 就绪探测。属于系统工具，不会展示给智能体。 |
| skills | `godot-skill-create`, `godot-skill-generate` | 编写新的工具文件、重新生成技能文件。系统工具。 |
| session | `session-close` | 保存并退出由 `godot-cli` 启动的编辑器。系统工具。 |

系统工具通过服务器的 `/api/system-tools/` 路由访问（例如使用 `godot-cli run-system-tool ping`），不会列给 AI 智能体。console、reflection 和 runtime-errors 这三个族服务于你自己连接上的正在运行的游戏；参见 [Custom tools](https://ai-game.dev/zh-hans/docs/wiki/godot/custom-tools#runtime)。

## RQL：一种用于编辑器的查询语言

RQL（Reflection Query Language）是编辑器工具的数据层。查询从某个源开始，用 `|` 分隔的各个阶段对其进行过滤和塑形，而在 `rql-mutate` 中以 `set` 或 `call` 结尾。以下是智能体可能发送的一些示例：

```text
nodes | where class == "OmniLight3D" | select name props["light_energy"]
nodes | where name starts-with "Enemy" | set Visible = false
root | call AddChild("Node3D", "Props")
project | call AddInputAction("jump", ["Key:Space"])
files | sort size desc | first 5 | select path size importedSize
editor | call SaveScene()
```

- `rql-query` 是只读的，返回紧凑的行。
- `rql-mutate` 会修改内容。每个目标和值都会先经过校验，因此查询失败时不会改动任何东西。`dry_run` 可预览改动。每次调用都是一个撤销步骤（编辑器中的 Ctrl+Z）。
- `rql-schema` 列出所编辑场景中的源、函数和节点类，或某个类型的成员、方法和 Godot 属性。带上扩展名时，它会打印该扩展的指南。

源包括 `nodes`、`root`、`selection`、`scenes`、`files`、`folders`、`classes`、`console`、`editor`、`project`、`settings`、`inputActions`、`autoloads`、`groups`、`layers` 和 `tools`。Godot 属性既可以作为 C# 成员访问（`Position`、`Visible`），也可以通过 `props["snake_name"]` 中的 Godot 名称访问，其中也包含 GDScript 变量。RQL 还能处理信号、组、TileSet、Theme、ShaderMaterial 参数和 MeshLibrary。

编辑器调用覆盖场景和文件操作：`NewScene`、`OpenScene`、`SaveScene`、`SaveAllScenes`、`ReloadScene`、`CreateResource`、`MoveResource`、`DeleteResource`、`CreateFolder`、`DeleteFolder`、`Reimport`、`Undo`、`Redo`、`PlayScene` 和 `StopScene`。`gameLog` 源可读取从编辑器中启动的游戏所打印的内容。

场景编辑会像你自己的编辑一样把场景标记为未保存。被编辑的资源文件和 `project.godot` 会立即保存。

## 脚本：C# 和 GDScript

- `script-read`、`script-create`、`script-update`、`script-delete` 作用于 `.cs` 和 `.gd` 文件。
- `script-attach-to-node` 将脚本附加到节点上。
- `script-validate` 返回 GDScript 文件的解析和编译诊断信息；不提供路径时，它会检查 `res://` 下的所有 `.gd` 文件。
- `script-build` 运行 `dotnet build`（Debug），以便加载新的 C# 脚本。随后 Godot 会重新加载 C# 程序集，插件重新连接，构建结果（警告或错误）会在重新加载后返回。
- `script-execute` 使用 Roslyn 在编辑器中编译并运行 C# 代码。直接编写普通语句即可；最后一个表达式就是结果。它会返回该值以及代码打印的内容。代码片段默认在 30 秒后超时（最长 4 分钟），死循环会返回超时错误，而不会让编辑器卡死。

你也可以从终端调用 `script-execute`：

```bash
godot-cli exec 'EditorInterface.Singleton.GetEditedSceneRoot()?.Name' --path ./MyGodotProject
```

## 截图

截图工具会返回模型可以查看的 PNG 图像：`screenshot-viewport` 捕获编辑器视口，`screenshot-camera` 从相机节点渲染，`screenshot-isolated` 则从选定角度单独渲染某个节点。在做视觉改动之后要求截一张图，这样智能体就能检查自己的成果。

## 游戏内工具

`console-*`、`reflection-*` 和 `runtime-errors-*` 在你的游戏内部运行，而不是在编辑器中运行。除非你的代码主动启用并连接，否则游戏不会暴露任何内容；`runtime-errors-get` 还需要 `WithRuntimeErrorCapture()`。它会捕获 GDScript 运行时错误、`push_error` 和 `push_warning`、着色器错误（Godot 4.5 及更新版本）以及未处理的 C# 异常，这样智能体就能运行游戏并看到究竟哪里出了问题。设置方法见：[自定义工具](https://ai-game.dev/zh-hans/docs/wiki/godot/custom-tools#runtime)。

## 选择智能体可见的工具

每个工具在停靠面板（MCP features、Tools、Open）中以及 `godot-cli configure` 里都有一个 **Visible** 开关。隐藏某个工具会将它从智能体的工具列表中移除，从而节省上下文，但并不会阻止它被调用。参见[配置](https://ai-game.dev/zh-hans/docs/wiki/godot/configuration#mcp-features)。

## 更多工具

- [扩展](https://ai-game.dev/zh-hans/docs/wiki/godot/extensions) 让 RQL 了解 AnimationPlayer、CSG、GridMap、导航、粒子、TileMapLayer 以及 Beehave、Dialogic、Phantom Camera 和 Terrain3D 插件。
- [自定义工具](https://ai-game.dev/zh-hans/docs/wiki/godot/custom-tools) 介绍了如何用 C# 编写你自己的工具。
- [Godot 最佳实践](https://ai-game.dev/docs/best-practices/godot) 提供了能很好地运用这些工具的提示词模式。

---

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

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