# 工具 — Godot · AI Game Developer Wiki

AI 代理在 Godot 編輯器中使用的 Godot MCP 工具：以 RQL 查詢節點、場景與資源，處理 C# 與 GDScript 腳本、螢幕擷取與遊戲內工具。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/godot/tools)。

Godot MCP 內建 9 個系列、共 24 項工具。多數編輯器工作都經由三個 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` | 撰寫新的工具檔案、重新產生 skill 檔案。系統工具。 |
| 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-hant/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 同樣能處理訊號、群組、TileSets、Themes、ShaderMaterial 參數與 MeshLibraries。

編輯器呼叫涵蓋場景與檔案相關工作：`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-hant/docs/wiki/godot/custom-tools#runtime)。

## 選擇代理程式能看到哪些工具

每個工具在 dock（MCP features, Tools, Open）以及 `godot-cli configure` 中都有一個 **Visible** 開關。隱藏工具會把它從代理程式的工具清單中移除，可節省 context，但不會封鎖它。請參閱[設定](https://ai-game.dev/zh-hant/docs/wiki/godot/configuration#mcp-features)。

## 更多工具

- [擴充功能](https://ai-game.dev/zh-hant/docs/wiki/godot/extensions) 讓 RQL 認識 AnimationPlayer、CSG、GridMap、導覽、粒子、TileMapLayer，以及 Beehave、Dialogic、Phantom Camera 和 Terrain3D 外掛。
- [自訂工具](https://ai-game.dev/zh-hant/docs/wiki/godot/custom-tools) 說明如何用 C# 撰寫你自己的工具。
- [Godot 最佳實務](https://ai-game.dev/docs/best-practices/godot) 提供能妥善運用這些工具的提示詞模式。

---

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

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