設定

大多數專案不需要任何設定：安裝外掛、登入，然後為你的代理點選 Configure。本頁說明 AI Game Developer 視窗中每個設定的作用、設定儲存的位置、如何為自動化覆寫這些設定，以及外掛在 CI 與播放器組建中的行為。

AI Game Developer 視窗#

使用 Window > AI Game Developer — MCP（Ctrl+Alt+A，macOS 上為 Cmd+Option+A）或 Scene View 工具列中的 AI 按鈕開啟。由上而下包含：

• Log Level、Timeout (ms) 與 Tool timeout (ms)，以及外掛版本。
• Connection：Custom / Cloud 切換與所選模式的設定。
• 連線時間軸：Unity（含 Connect / Disconnect 按鈕）、MCP server 與 AI agent。
• AI agent 下拉選單，附有各用戶端的設定器：Model Context Protocol (MCP) 搭配 Configure / Remove，以及 Skills 搭配 Auto-generate 與 Generate。
• Tools、Prompts 與 Resources 計數，各自附有 Open 按鈕。
• Extensions：安裝選用的工具組（請參閱 Extensions）。
• 說明連結：Help / Talk（Discord）、Bug Report（GitHub issues），以及用於序列化診斷的 Check 按鈕。

連線模式#

Cloud（預設）#

此外掛會連線到位於 https://ai-game.dev/mcp 的託管伺服器。不會啟動本機伺服器，且 URL 無法編輯。Cloud 模式需要登入：點選 Cloud Token 旁的 Authorize，並在瀏覽器中核准裝置代碼，或使用 unity-mcp-cli login 或 AI Game Dev 應用程式登入一次。Revoke 會登出該機器上所有 AI Game Dev 工具。

Custom（本機或你自己的伺服器）#

此外掛會連線到 Server URL 中的 URL。預設是位於 http://localhost:<port> 的本機伺服器，外掛會為你下載、啟動與停止伺服器（gamedev-mcp-server）。你也可以輸入你所架設之遠端 MCP 伺服器的 URL。只有在 Unity 與伺服器中斷連線時，Server URL 才可編輯。

Custom 模式會新增下列設定：

• MCP server：Start / Stop 按鈕與狀態（Running、Starting、Stopping、Downloading，或當其他程序已佔用該連接埠時顯示 External）。若二進位檔下載失敗，會出現 Download / Retry server。
• Transport：http（建議）或 stdio。使用 http 時，代理會連線到執行中的伺服器，多個代理可以共用，伺服器也可在另一台機器上執行。使用 stdio 時，代理會將伺服器啟動為自己的子程序，一次只能有一個代理連線，且 Start / Stop 按鈕會停用。
• Authorization Token：none、oauth 或 token。
  • none：伺服器接受任何連線。僅在連接埠無法從其他機器存取時才安全。
  • oauth：代理以其 ai-game.dev 帳號登入；伺服器會線上驗證權杖。
  • token：共用密鑰，完全離線。點選 New 產生權杖，然後按 Configure（或手動將權杖複製到代理的設定中）。

連接埠#

本機連接埠不是像 8080 這樣的固定值。它是由你的專案資料夾推導而來：將正規化後的專案路徑取 SHA-256 雜湊，再對應到 20000 到 29999 的範圍。同一個專案永遠取得相同的連接埠，不同的專案則取得不同的連接埠，因此多個 Unity 執行個體可以並行運作。CLI 使用相同的公式，因此其命令不需額外旗標就能找到正確的伺服器。

若要使用其他連接埠，請先中斷連線，然後在 Server URL 中輸入（例如 http://localhost:25000）。設定器會將你輸入的連接埠寫入代理設定。

設定檔#

設定會以每位使用者為單位儲存在 UserSettings/AI-Game-Developer-Config.json，於首次啟動時建立。主要鍵值如下：

Cloud 認證資料不會儲存在這裡；它們位於 ~/.ai-game-dev/credentials.json。若要重新開始，請使用 Tools > AI Game Developer > Reset Config，它會還原預設值並重新載入指令碼。

工具、提示與資源#

Tools 計數顯示代理能看到多少已安裝的工具，以及它們在 AI 上下文中大約佔用的權杖數。點選 Open 可顯示或隱藏個別工具；MCP Prompts 與 MCP Resources 視窗的運作方式相同。

隱藏的工具不會被刪除：它會從代理的工具清單中消失，但以名稱呼叫時仍會執行。可見的工具越少，就能留給推理更多上下文。你也可以用 tool-set-visibility 工具或在終端機中變更可見性：

unity-mcp-cli configure ./MyUnityProject --enable-tools screenshot-scene-view,script-read
unity-mcp-cli configure ./MyUnityProject --list

環境變數與命令列覆寫#

針對 CI 與指令碼化啟動，外掛會在啟動時讀取這些變數（或對應的 Unity 命令列引數）。覆寫只套用於記憶體中，永遠不會寫入設定檔。

命令列引數優先於環境變數。以下是批次模式編輯器連線到本機伺服器的範例：

Unity -batchmode -projectPath ./MyUnityProject \
  -UNITY_MCP_CLOUD_URL=http://localhost:8080 \
  -UNITY_MCP_KEEP_CONNECTED=true \
  -UNITY_MCP_AUTH_OPTION=token \
  -UNITY_MCP_TOKEN=my-secret-token

unity-mcp-cli open 會為你設定這些變數；請參閱 CLI 參考文件。

在 CI 中停用 Unity MCP#

此外掛會偵測 CI 環境，然後跳過伺服器下載與自動連線。若要在一般的 CI 測試工作中完全關閉它，可使用下列兩種退出方式之一：

• UNITY_MCP_DISABLE=1（或 true），設定在啟動 Unity 之程序的環境中。此外掛會略過啟動、工具註冊、伺服器下載、NuGet 解析及其編輯器掛鉤。其程式碼仍會編譯，因此專案仍必須能編譯。
• UNITY_MCP_EXCLUDE_FROM_COMPILATION，作為 Project Settings > Player > Other Settings 中的 Scripting Define Symbol。這會將所有外掛組件（以及更新後的第一方擴充功能）排除於編譯之外。你自己參考外掛型別的程式碼需要加上 #if !UNITY_MCP_EXCLUDE_FROM_COMPILATION。

這兩者都不會因為 -batchmode 或 -runTests 而自動啟用，因為無頭 MCP 工作階段需要此外掛。

播放器組建與執行階段#

此外掛的執行階段組件會為每個平台編譯，因此除非你用上述的定義符號排除它，它都會包含在你的播放器組建中。組建永遠不會自行連線：在遊戲中，你需在程式碼中透過 UnityMcpPluginRuntime.Initialize(...) 選擇啟用，這就是將遊戲內工具開放給 AI 的方式（例如 AI 西洋棋對手）。請參閱 Custom tools。

自行架設 MCP 伺服器#

該伺服器是共用的 GameDev-MCP-Server，同時也以 Docker 映像 aigamedeveloper/mcp-server 發布：

docker run -p 8080:8080 aigamedeveloper/mcp-server

接著將外掛設為 Custom，並將 Server URL 設為 http://localhost:8080（或你的主機），再讓你的代理指向相同位址。伺服器接受 --port、--client-transport、--authorization 與 --idle-timeout-seconds 等設定，或對應的 MCP_PLUGIN_* 環境變數；伺服器文件 列出了全部。

相關頁面#

• 連接 AI 用戶端 說明代理設定與登入。
• 疑難排解 說明連線問題。