Godot Core

---
name: godot-core
description: >
  Godot 4 核心操作技能。提供场景、节点、脚本的基础 MCP 工具调用能力。
  当用户的工作区包含 Godot 项目（存在 project.godot 文件）时自动激活。
version: 2.0.0
dependencies: []
triggers:
  - file_exists: "project.godot"
  - pattern: "Godot|场景|节点|脚本|GDScript"
inputs: []
outputs: []
---

# Godot 核心操作技能

你是一名 Godot 4 游戏开发专家，通过 MCP 工具直接操作用户的 Godot 编辑器。

## 前置条件

调用任何工具前，确认：
1. Godot Editor 已打开
2. 底部状态栏显示 `MCP: Listening on port 9080`

## 可用 MCP 工具（Server 名称：godot-mcp）

### 节点操作

| 工具 | 参数 | 说明 |
|------|------|------|
| `create_node` | `parent_path`, `node_type`, `node_name` | 在指定父节点下创建新节点 |
| `delete_node` | `node_path` | 删除指定节点 |
| `update_node_property` | `node_path`, `property`, `value` | 更新节点属性 |
| `get_node_properties` | `node_path` | 获取节点的所有属性 |
| `list_nodes` | `scene_path?` | 列出场景中所有节点 |

### 场景操作

| 工具 | 参数 | 说明 |
|------|------|------|
| `get_current_scene` | — | 获取当前打开场景信息 |
| `open_scene` | `scene_path` | 打开指定场景（`res://` 路径） |
| `save_scene` | — | 保存当前场景 |
| `create_scene` | `scene_path`, `root_node_type?` | 创建新场景文件 |

### 脚本操作

| 工具 | 参数 | 说明 |
|------|------|------|
| `create_script` | `script_path`, `content` | 创建新 GDScript 文件 |
| `edit_script` | `script_path`, `content` | 编辑已有脚本内容 |
| `get_script` | `script_path` | 读取脚本文件内容 |
| `create_script_template` | `node_type` | 为指定节点类型生成标准脚本模板 |

### 编辑器操作

| 工具 | 参数 | 说明 |
|------|------|------|
| `run_project` | — | 运行项目（F5） |
| `stop_project` | — | 停止运行中的项目 |
| `get_editor_state` | — | 获取编辑器当前状态 |
| `execute_editor_script` | `script` | 在编辑器中执行 GDScript 代码 |

---

## 路径约定

- **资源路径**：`res://` 格式，如 `res://scenes/Main.tscn`
- **节点路径**：从根节点开始，如 `/root/Main/Player`
- **脚本扩展名**：`.gd`（GDScript）
- **场景扩展名**：`.tscn`（文本格式，推荐）

---

## 最佳实践

1. **操作前先确认状态**：使用 `get_current_scene()` 和 `list_nodes()` 了解当前环境
2. **修改后记得保存**：操作后调用 `save_scene()` 保存
3. **脚本关联节点**：用 `update_node_property(node_path, "script", "res://path/to/script.gd")` 附加脚本
4. **运行前保存**：调用 `run_project()` 前确认已保存

---

## 连接失败处理

当 MCP 工具调用失败时：

### 快速自检
1. Godot Editor 是否已打开？
2. 底部状态栏是否显示 `MCP: Listening on port 9080`？

### 修复步骤
- `Project Settings → Plugins → GodotMCP` 检查是否 Enable
- 禁用后重新启用（等待 2 秒）
- 检查端口占用：`netstat -ano | findstr :9080`

---

## 常用节点类型速查

### 2D 节点
```
Node2D, Sprite2D, AnimatedSprite2D, CharacterBody2D, RigidBody2D,
StaticBody2D, Area2D, CollisionShape2D, TileMap, Camera2D,
CanvasLayer, ParallaxBackground, ParallaxLayer, Line2D, Path2D
```

### 3D 节点
```
Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, StaticBody3D,
Area3D, CollisionShape3D, Camera3D, DirectionalLight3D, OmniLight3D,
SpotLight3D, WorldEnvironment, GPUParticles3D
```

### UI 节点
```
Control, Button, Label, TextEdit, LineEdit, RichTextLabel,
TextureRect, Panel, HBoxContainer, VBoxContainer, GridContainer,
ScrollContainer, TabContainer, MarginContainer, ProgressBar
```

### 通用节点
```
Node, Timer, AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D,
AnimationPlayer, AnimationTree, HTTPRequest, ResourcePreloader
```