# 開始使用 — Godot · AI Game Developer Wiki

將 Godot MCP 連上雲端、接好 Claude Code 等 AI agent、確認連線，並在 Godot 編輯器中執行你的第一批 AI 提示。

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

本頁帶你從已安裝的 addon 一路走到能編輯 Godot 場景的 AI agent。這裡假設 addon 已經在你的專案裡；如果還沒，請先從 [Installation](https://ai-game.dev/zh-hant/docs/wiki/godot/installation) 開始。以下步驟採用預設的 Cloud 模式，編輯器與你的 agent 都會連到 [ai-game.dev](https://ai-game.dev)，你只需登入一次。

## 步驟 1：開啟專案

用 CLI 開啟專案：

```bash
godot-cli open ./MyGodotProject
```

`open` 會先建置 C# 組件，然後才啟動編輯器。首次開啟時這個建置很重要：Godot 會立刻載入已啟用的 addon，若沒有建置好的組件，它會回報無法載入 `GodotMcpPlugin.cs` 並停用該 addon。如果你改從 Godot 專案管理員開啟專案，請先建置一次（編輯器的 Build 按鈕或 `godot-cli build`），並在 Godot 把外掛關掉時重新啟用它。

addon 載入後，編輯器的 Output 面板會印出 `[Godot-MCP] plugin loaded`，且右上角的 dock 區域會出現 **AI Game Developer** 面板。

## 步驟 2：登入

Cloud 模式需要你的 ai-game.dev 帳號。以下方式任選一種：

- 在 dock 中讓模式保持在 **Cloud**，然後點擊 **Authorize**。瀏覽器會開啟並顯示一組簡短代碼；用你的 ai-game.dev 帳號核准即可。
- 從終端機執行 `godot-cli login`。它使用相同的 OAuth 裝置流程，並把憑證存到 `~/.ai-game-dev/credentials.json`，編輯器會自行讀取。

每台機器只需登入一次。同一份憑證可供 Godot MCP、Unity MCP、Unreal MCP、各引擎 CLI 以及 AI Game Dev 應用程式使用。這個工作階段會出現在你帳號的已連結裝置中，你可以在那裡撤銷它。詳情請見：[Authentication](https://ai-game.dev/docs/auth)。

## 步驟 3：連接你的 AI agent

為你使用的 agent 撰寫 MCP 設定。以 Claude Code 為例：

```bash
godot-cli setup-mcp claude-code ./MyGodotProject
```

這會在專案中寫入 `.mcp.json`，其中的 URL 固定指向這個專案，因此即使你同時開了好幾個編輯器，agent 也能連到這個編輯器。你也可以在 dock 中做同樣的事：在 **AI agent** 區塊選擇你的 agent，然後點擊 **Configure**。其他 agent（Cursor、VS Code Copilot、Codex、Gemini 等）列在 [Connecting AI clients](https://ai-game.dev/zh-hant/docs/wiki/godot/connecting-ai-clients)。

設定寫好之後，請重新啟動 agent，或重新載入它的 MCP 伺服器。若設定檔放在專案資料夾中，請從該專案資料夾啟動 agent（Claude Code 會從它啟動所在的資料夾讀取 `.mcp.json`）。

## 步驟 4：確認連線

dock 的 **Connection** 區塊會顯示三個點組成的一列：Godot、MCP 伺服器與 AI agent。當編輯器已連線且有 agent 工作階段進行中時，三個點都會亮起，且 agent 那一列會顯示用戶端名稱。你也可以從終端機等待編輯器回應：

```bash
godot-cli wait-for-ready ./MyGodotProject
godot-cli status ./MyGodotProject
```

`wait-for-ready` 會持續輪詢就緒探測（`ping`）直到它回應，預設最多等待兩分鐘。`status` 會回報該專案是否有編輯器正在執行，以及伺服器是否有回應。

在你的 agent 中，請它列出可用的工具，或在 Claude Code 中執行 `/mcp`。你應該會看到 `rql-query`、`rql-mutate`、`script-create` 和 `screenshot-viewport` 等工具。

## 步驟 5：第一批提示

在你的 agent 聊天室中試試以下提示。每一個都對應到真實工具，因此你可以在編輯器中看著場景改變：

- 「新增一個含有 Camera3D 與 MeshInstance3D 立方體的 Node3D 場景，然後存成 Main.tscn。」
- 「以半徑 2 圍成一圈建立 3 個立方體。」
- 「列出場景中所有的 OmniLight3D 及其 energy。」
- 「為地板建立一個 StandardMaterial3D，並把它的 albedo 顏色設為灰色。」
- 「建立一個含有 public float Speed 的 Player.cs 腳本，將它掛到 Player 節點上並建置專案。」
- 「新增一個名為 jump 的輸入動作，綁定 Space 鍵。」
- 「擷取 viewport 的螢幕截圖，並告訴我你看到什麼。」

agent 所做的場景編輯都可以復原：在編輯器按 Ctrl+Z 就能逐步退回，跟你自己的編輯完全一樣。場景變更會把場景標記為未儲存，所以請 agent 儲存，或自己儲存。更多提示靈感請見 [Best practices for Godot](https://ai-game.dev/docs/best-practices/godot)。

## agent 看得見與看不見什麼

agent 是透過 addon 提供的工具來工作。它可以經由 RQL 讀取場景樹、Godot 屬性（包含 GDScript 變數）、資源、檔案、專案設定、輸入對應、autoload、主控台與編輯器狀態，也可以查看螢幕截圖。它無法在編輯器 UI 中點擊。完整清單請見 [Tools](https://ai-game.dev/zh-hant/docs/wiki/godot/tools) 與 [Godot tools catalog](https://ai-game.dev/docs/tools/godot)。

## 想完全離線使用嗎？

你可以改用在自己的電腦上執行 MCP 伺服器，而不透過雲端。在 dock 中將模式切換為 **Custom** 並點擊 **Start Server**：外掛會從 GitHub 下載對應的伺服器版本、啟動並連線。接著讓你的代理指向本機 URL。請參閱 [Connecting AI clients](https://ai-game.dev/zh-hant/docs/wiki/godot/connecting-ai-clients#custom-mode)。

## 後續步驟

- [Configuration](https://ai-game.dev/zh-hant/docs/wiki/godot/configuration)：dock、日誌等級，以及代理能看到哪些工具。
- [Extensions](https://ai-game.dev/zh-hant/docs/wiki/godot/extensions)：新增 AnimationPlayer、CSG、導覽、tilemap 與外掛支援。
- [Troubleshooting](https://ai-game.dev/zh-hant/docs/wiki/godot/troubleshooting)：當上述步驟無法運作時。

---

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

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