# 擴充套件 — Godot · AI Game Developer Wiki

安裝選用的 Godot MCP 擴充套件，涵蓋 AnimationPlayer、CSG、GridMap、導覽、粒子、TileMapLayer、Beehave、Dialogic、Phantom Camera 與 Terrain3D。

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

擴充套件是選用的 NuGet 套件，能讓 Godot MCP 認識更多 Godot 的各個部分，以及熱門的 Godot 外掛。只安裝你的專案需要的那些即可。本頁列出這些擴充套件、說明它們的運作方式，並示範三種安裝方式。每個擴充套件的說明與範例都在本站的 [Godot 擴充套件](https://ai-game.dev/docs/extensions/godot) 頁面。

## 擴充套件的運作方式

每個擴充套件都是一個 RQL 模組。它本身不新增任何 MCP 工具，而是以新的來源、經過驗證的屬性與呼叫來擴充核心的 `rql-query`、`rql-mutate` 和 `rql-schema` 工具，並在代理程式的 `godot-rql` 技能中新增一份指南。你的代理程式工具清單大小維持不變，代理程式則透過 `rql-schema` 學習新的領域：

```text
rql-schema "Particles"
```

這些套件包含 C# 原始碼與建置設定，並會針對你專案自己的 GodotSharp 進行編譯。每個擴充套件都有自己的版本與發行。

## 可用的擴充套件

| 擴充套件 | 套件識別碼 | 新增內容 | 需求 |
| --- | --- | --- | --- |
| Animation 工具 | `com.IvanMurzak.Godot.MCP.Animation` | AnimationPlayer 函式庫、動畫、軌道與關鍵影格 | Godot 4.3+ |
| Beehave 工具 | `com.IvanMurzak.Godot.MCP.Beehave` | 列出行為樹及其節點 | Beehave 外掛、Godot 4.3+ |
| CSG 工具 | `com.IvanMurzak.Godot.MCP.CSG` | 經過驗證的 CSG 基本體尺寸與 `rootShape` | Godot 4.3+ |
| Dialogic 工具 | `com.IvanMurzak.Godot.MCP.Dialogic` | 列出並建立時間軸與角色，附加時間軸文字 | Dialogic 外掛、Godot 4.4+ |
| GridMap 工具 | `com.IvanMurzak.Godot.MCP.GridMap` | GridMap 設定、儲存格列與儲存格編輯 | Godot 4.3+ |
| Navigation 工具 | `com.IvanMurzak.Godot.MCP.Navigation` | 2D 與 3D 導覽代理程式、區域、連結與區域烘焙 | Godot 4.3+ |
| Particles 工具 | `com.IvanMurzak.Godot.MCP.Particles` | 2D 與 3D 的 GPU 粒子：經過驗證的發射器設定與重新啟動 | Godot 4.3+ |
| PhantomCamera 工具 | `com.IvanMurzak.Godot.MCP.PhantomCamera` | 列出虛擬攝影機與宿主，設定跟隨與注視目標 | Phantom Camera 外掛、Godot 4.4+ |
| Terrain3D 工具 | `com.IvanMurzak.Godot.MCP.Terrain3D` | 地形來源、區域大小變更與材質建立 | Terrain3D 外掛、Godot 4.4+ |
| Tilemap 工具 | `com.IvanMurzak.Godot.MCP.Tilemap` | TileMapLayer 已使用儲存格列與儲存格編輯 | Godot 4.3+ |

每個擴充套件也都需要一個具備 RQL 工具的核心外掛（0.28.0 之後的任何版本）。

**注意**

安裝程式只會加入擴充套件套件。若要用 Beehave、Dialogic、Phantom Camera 與 Terrain3D，請先自行將該第三方外掛安裝到你的專案中。

## 使用 godot-cli 安裝

```bash
godot-cli install-extension com.IvanMurzak.Godot.MCP.CSG ./MyGodotProject
godot-cli build ./MyGodotProject
```

`install-extension` 會在擴充套件目錄中查詢該識別碼，先比對套件識別碼，再比對名稱，且不分大小寫（所以 `"CSG Tools"` 也可以）。接著它會在你專案的 `.csproj` 中新增或更新 `<PackageReference>`：

- 尚未參考：加入參考；
- 參考的是較舊版本：更新它；
- 已是最新版本：不做任何變更。

若未指定 `--version`，參考版本會浮動至 NuGet 上的最新穩定版（`Version="*"`）。使用 `--version <x.y.z>` 可要求確切的版本。安裝後請建置專案，讓 Godot 還原並編譯此套件；Godot 沒有自動還原的步驟。

## 從 dock 安裝

AI Game Developer dock 的 **Extensions** 區段會列出相同的目錄，並提供 **Install** 與 **Update** 按鈕。它修改 `.csproj` 的方式與 CLI 相同。之後請重新建置。如果 dock 顯示找不到 `.csproj`，表示此外掛不在 Godot C# 專案內。

## 從 AI Game Dev 應用程式安裝

對於 Godot 專案，[AI Game Dev 應用程式](https://ai-game.dev/zh-hant/docs/wiki/app) 會在側邊欄顯示 **Extensions** 按鈕，開啟相同的目錄，並透過與 `godot-cli` 相同的程式碼進行安裝。它的斜線命令 `/install-extension` 也能在應用程式的聊天中做到同樣的事：不帶參數時會列出目錄，帶識別碼時則安裝到目前的專案。引擎擴充套件與應用程式本身的套件並不相同。

## 擴充套件目錄

擴充套件清單位於 `addons/godot_mcp/extensions.catalog.json`，隨外掛一起提供。dock、`godot-cli` 與應用程式都讀取這同一個檔案。dock 是從你編譯後的專案讀取，因此你的 `.csproj` 必須內嵌它：

```xml
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>
```

`godot-cli install-plugin` 與應用程式會替你加入這一行。如果你是以手動方式安裝，而 Extensions 清單是空的，就是少了這一行；請加入後重新建置。參見 [安裝](https://ai-game.dev/zh-hant/docs/wiki/godot/installation#nuget-packages)。

## 使用擴充套件

建置完成後，直接提出要求即可。例如，安裝了 CSG Tools 之後：

- 「建立一個 CSG 組合器，使用 3x3x3 的方塊，並從中減去半徑 1.8 的球體。」
- 「列出場景中每個 CSG 形狀，以及它的操作和尺寸。」

代理會用 `rql-mutate` 建立節點（每次呼叫都是一個可復原的步驟），並用 `rql-query` 檢查結果。無效的值（例如負的半徑）會讓整筆變更失敗，場景維持不變。

## 撰寫你自己的擴充功能

Godot-MCP 儲存庫內含一份擴充功能範本（`templates/extension/`），以及一份說明如何建置、測試與發佈模組的 monorepo 指南。若只是單次使用的專案工具，直接採用[自訂工具](https://ai-game.dev/zh-hant/docs/wiki/godot/custom-tools)會更簡單。

---

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

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