開始使用
第一次連線 Unreal MCP，登入 ai-game.dev，接上你的 AI 用戶端，並在 Unreal Editor 中送出第一批 AI 提示。
本頁將帶你從已安裝外掛的狀態，一路做到在 Unreal Editor 中完成第一個由 AI 驅動的變更。內容假設你已完成安裝。
步驟 1：開啟 AI Game Developer 視窗
- 在 Unreal Editor 中開啟你的專案（從應用程式點選 Open Editor、使用
unreal-mcp-cli open ./YourProject，或依照你平常的方式開啟）。 - 開啟 Tools 選單，然後選擇 AI Game Developer。
這個視窗是外掛的主要操作中心。由上而下依序顯示記錄等級、開啟記錄資料夾的按鈕與外掛版本；Connection 區段；AI agent 區段；Extensions 區段；以及說明與錯誤回報的連結。
步驟 2：連線至伺服器
Connection 區段提供 Custom / Cloud 切換。Cloud 是預設值，也是大多數人正確的選擇：它使用位於 ai-game.dev 的託管伺服器，因此本機不需要執行任何東西。
- 確認已選取 Cloud。
- 點選 Authorize。視窗會顯示驗證連結與一組簡短的用戶代碼。
- 開啟該連結（或使用 Open verification page），登入 ai-game.dev，輸入代碼並核准。
- 視窗會回報 Authorized — signed in to AI Game Dev.
如果你已在這台機器上用 unreal-mcp-cli login 或 AI Game Dev 應用程式登入過，編輯器可以直接沿用該登入狀態。第一次核准之後，之後啟動編輯器都不需要再點任何按鈕即可重新連線。
請留意狀態列。綠色圓點旁的 Unreal: Connected 表示外掛、橋接器與伺服器都已連通。Unreal: Connecting… 在橋接器啟動時出現幾秒是正常的。
注意： 想讓所有東西都留在自己的機器上嗎？改選 Custom，並在本機執行 gamedev-mcp-server。連線 AI 用戶端說明了做法。
步驟 3：連線你的 AI 用戶端
AI agent 區段會替你設定 AI 用戶端。
- 從下拉式選單挑選你的代理，例如 Claude Code、Cursor、Visual Studio Code (Copilot)、Codex 或 Gemini。
- 點選 Configure。外掛會將 Unreal MCP 項目寫入該代理的 MCP 設定檔。
- 如果代理已在執行中，請重新啟動或重新載入，讓它載入新的伺服器。
你也可以在終端機中用 CLI 做同樣的事。以 Claude Code 為例：
unreal-mcp-cli setup-mcp claude-code --path ./YourProject這會在專案資料夾中寫入 .mcp.json。執行 unreal-mcp-cli setup-mcp --list 可查看所有支援的代理，以及各自的設定檔位置。所有選項請見連線 AI 用戶端。
代理連線後，會出現在 Connection 區段的 AI agents 列中。
步驟 4：檢查連線
向你的代理提出一個只有編輯器能回答的問題：
List the actors in the current level with their class names.代理應該會呼叫 rql-query，並以你目前開啟關卡中真實的 Actor 來回答。如果它說自己沒有 Unreal 工具，代表用戶端沒有載入 MCP 伺服器；請參閱疑難排解。
步驟 5：你的第一批正式提示
從小型且具體的任務開始。以下是幾個能展示不同工具家族的提示：
Spawn three cubes in a row and a point light above them.Create a new Actor Blueprint called BP_Coin with a static mesh component
using the engine sphere, compile it, and place three of them in the level.Take a screenshot of the viewport and tell me what you see.Create a C++ actor class called AHealthPickup with a float Heal property,
then compile the project and fix any errors.透過 RQL 進行的每一次編輯器變更都算一個復原步驟，因此在編輯器中按 Ctrl+Z 就能還原。編譯工具會回傳結構化的錯誤清單，所以「編譯它並修正所有錯誤」是個很好的後續提示。
提示： 截圖工具需要真正由 GPU 支援的編輯器。當編輯器以 -nullrhi 執行時，這些工具會回傳錯誤。
在 Unreal Editor 中使用 AI 的好習慣
- 把東西命名清楚。「把標記為 KeyLight 的燈光強度改掉」會比「改一下那盞燈」有效得多。
- 先請它查看現況。「先告訴我 BP_Door 有哪些元件，再動手修改」能讓代理取得所需的事實。
- 讓它自行驗證。 變更後請它截圖或進行編譯。
- 記得存檔。 在進行較大的變更前，請代理儲存關卡，或在編輯器中存檔。
- 讓每次工作階段保持聚焦。 一次對話只處理一項任務，能讓代理的上下文保持精簡且準確。
更多建議請見 Unreal 最佳實務。