Godot4 Runtime MCP

🚀 示例 Godot 項目

本項目是一個簡單的 Godot 4 示例，旨在演示 MCP 插件的使用方法，幫助開發者快速上手該插件。

🚀 快速開始

項目結構

ExampleProject/
├── project.godot          # Godot 項目配置
├── addons/
│   └── mcp_client/        # MCP 插件（從上級目錄複製）
├── scenes/
│   ├── main.tscn          # 主場景
│   └── player.tscn        # 玩家場景
└── scripts/
    └── Player.cs          # 玩家腳本

如何使用

1. 創建 Godot 項目

在 Godot 編輯器中按以下步驟操作：

1. 新建項目
2. 選擇 C# 作為腳本語言
3. 保存項目

2. 安裝 MCP 插件

# 從項目根目錄
cp -r GodotPlugin ExampleProject/addons/mcp_client

你也可以手動複製 GodotPlugin 文件夾到 ExampleProject/addons/mcp_client。

3. 啟用插件

1. 在 Godot 編輯器中打開項目
2. 點擊“項目” -> “項目設置” -> “插件”
3. 啟用 "MCP Client"

4. 創建測試場景

主場景 (main.tscn)

創建如下節點結構：

Main (Node2D)
├── Player (CharacterBody2D)
│   └── Sprite2D
└── Camera2D

玩家腳本 (Player.cs)

using Godot;

public partial class Player : CharacterBody2D
{
    [Export]
    public float Speed { get; set; } = 200.0f;
    
    [Export]
    public int Health { get; set; } = 100;

    public override void _PhysicsProcess(double delta)
    {
        Vector2 velocity = Velocity;
        Vector2 direction = Input.GetVector("ui_left", "ui_right", "ui_up", "ui_down");
        
        if (direction != Vector2.Zero)
        {
            velocity = direction * Speed;
        }
        else
        {
            velocity = Vector2.Zero;
        }

        Velocity = velocity;
        MoveAndSlide();
    }
    
    public void TakeDamage(int damage)
    {
        Health -= damage;
        GD.Print($"Player took {damage} damage. Health: {Health}");
        
        if (Health <= 0)
        {
            Die();
        }
    }
    
    public void Heal(int amount)
    {
        Health += amount;
        GD.Print($"Player healed {amount}. Health: {Health}");
    }
    
    private void Die()
    {
        GD.Print("Player died!");
        // 可以在這裡添加死亡邏輯
    }
}

5. 運行和測試

1. 啟動 MCP 服務器

./start-server.sh

2. 在 Godot 中運行遊戲 (F5)
3. 在 Claude 中測試 MCP 工具

💻 使用示例

基礎操作

1. 查看場景樹

獲取當前場景樹結構

2. 查看玩家信息

獲取節點 /root/Main/Player 的詳細信息

3. 查看玩家屬性

獲取 /root/Main/Player 的 Speed 和 Health 屬性

修改操作

4. 修改速度

將玩家的 Speed 屬性設置為 500

5. 修改位置

將玩家位置設置為 (400, 300)

6. 調用方法

調用 /root/Main/Player 的 TakeDamage 方法，參數為 [20]

高級操作

7. 創建新節點

在 /root/Main 下創建一個名為 "Enemy" 的 CharacterBody2D 節點

8. 性能監控

獲取當前的性能統計信息

9. 截圖

截取當前遊戲畫面並保存

📚 詳細文檔

預期結果

場景樹輸出

{
  "path": "/root",
  "name": "root",
  "type": "Window",
  "children": [
    {
      "path": "/root/Main",
      "name": "Main",
      "type": "Node2D",
      "children": [
        {
          "path": "/root/Main/Player",
          "name": "Player",
          "type": "CharacterBody2D",
          "children": [...]
        }
      ]
    }
  ]
}

節點信息輸出

{
  "path": "/root/Main/Player",
  "name": "Player",
  "type": "CharacterBody2D",
  "properties": {
    "position": {"x": 0, "y": 0},
    "Speed": 200,
    "Health": 100
  },
  "methods": ["TakeDamage", "Heal", "_PhysicsProcess", ...],
  "signals": [...]
}

故障排除

插件未加載

• 檢查插件文件是否在正確位置
• 確保 plugin.cfg 格式正確
• 重新啟動 Godot 編輯器

無法連接到 MCP 服務器

• 確認 MCP 服務器正在運行
• 檢查端口 7777 未被佔用
• 查看 Godot 控制檯錯誤信息

節點路徑錯誤

• 使用 get_scene_tree 確認正確的節點路徑
• 節點路徑區分大小寫
• 確保使用絕對路徑（以 /root 開頭）

擴展練習

1. 創建多個敵人
   • 使用 create_node 創建 5 - 10 個敵人
   • 為每個敵人設置隨機位置
2. 性能優化
   • 監控 FPS
   • 使用 get_scene_tree 找出節點數量
   • 嘗試刪除不必要的節點
3. 遊戲平衡調整
   • 動態調整玩家速度
   • 測試不同的 Health 值
   • 即時調整遊戲難度
4. 調試工作流
   • 在遊戲運行時修改變量
   • 測試邊界情況
   • 驗證遊戲邏輯

下一步

• 創建更復雜的場景
• 添加更多遊戲邏輯
• 使用 MCP 工具進行 AI 輔助開發
• 探索自動化測試可能性