server-deploy/windows-dev-stack/godot-mcp-pro-v1.14.1/addons/godot_mcp/skills.zh.md

> **Language:** [English](skills.md) | [日本語](skills.ja.md) | [Português (BR)](skills.pt-br.md) | [Español](skills.es.md) | [Русский](skills.ru.md) | 简体中文 | [हिन्दी](skills.hi.md)

# Godot MCP Pro — AI 助手技能指南

> 将此文件复制到 Godot 项目根目录的 `.claude/skills.md`，以便 Claude Code 获得如何高效使用 Godot MCP Pro 的完整上下文。

## 什么是 Godot MCP Pro？

你可以使用 169 个 MCP 工具直接连接 Godot 4 编辑器。你可以创建场景、编写脚本、模拟玩家输入、检查运行中的游戏等等——所有操作都无需用户离开当前对话。每次更改都通过 Godot 的 UndoRedo 系统进行，因此用户随时可以 Ctrl+Z 撤销。

## 核心工作流

### 1. 探索项目

在进行更改之前，先了解项目全貌：

```
get_project_info          → 项目名称、Godot 版本、渲染器、视口大小
get_filesystem_tree       → 目录结构（可使用 filter: "*.tscn" 或 "*.gd"）
get_scene_tree            → 当前打开场景的节点层级
read_script               → 读取任意 GDScript 文件
get_project_settings      → 检查项目配置
```

### 2. 构建 2D 场景

```
create_scene   → 创建 .tscn 文件并指定根节点类型
add_node       → 添加带属性的子节点
create_script  → 编写游戏逻辑的 GDScript
attach_script  → 将脚本附加到节点
update_property → 设置 position、scale、modulate 等
save_scene     → 保存到磁盘
```

**示例——创建玩家：**
1. `create_scene` 设置 root_type 为 `CharacterBody2D`，path 为 `res://scenes/player.tscn`
2. `add_node` 类型 `Sprite2D` 并设置 texture 属性
3. `add_node` 类型 `CollisionShape2D`
4. `add_resource` 为 CollisionShape2D 分配形状（如 `RectangleShape2D`）
5. `create_script` 编写移动逻辑
6. `attach_script` 附加到根节点
7. `save_scene`

### 3. 构建 3D 场景

```
create_scene         → root_type: Node3D
add_mesh_instance    → 添加基础体（box、sphere、cylinder、plane）或导入 .glb/.gltf
setup_lighting       → 添加 DirectionalLight3D、OmniLight3D 或 SpotLight3D
setup_environment    → 天空、环境光、雾、色调映射
setup_camera_3d      → 摄像机（可选 SpringArm3D 实现第三人称视角）
set_material_3d      → PBR 材质（albedo、metallic、roughness、emission）
setup_collision      → 为物理体添加碰撞形状
setup_physics_body   → 配置质量、摩擦力、重力
```

### 4. 编写和编辑脚本

```
create_script  → 创建新的 .gd 文件（提供完整内容）
edit_script    → 修改现有脚本
  - 使用 `replacements: [{search: "old code", replace: "new code"}]` 进行定向编辑
  - 使用 `content` 完整替换文件
  - 使用 `insert_at_line` + `text` 插入代码
validate_script → 不运行即可检查语法错误
read_script    → 编辑前读取当前内容
```

### 5. 测试与调试

```
play_scene             → 启动游戏（mode: "current"、"main" 或文件路径）
get_game_screenshot    → 查看游戏当前画面
capture_frames         → 捕获多帧以观察运动/动画
get_game_scene_tree    → 检查运行时的场景树
get_game_node_properties → 读取运行时数值（position、health、state 等）
set_game_node_property → 修改运行中游戏的数值
simulate_key           → 按键（WASD、SPACE 等）并指定持续时间
simulate_mouse_click   → 在视口坐标处点击
simulate_action        → 触发 InputMap 动作（move_left、jump 等）
get_editor_errors      → 检查运行时错误
stop_scene             → 停止游戏
```

**测试循环：**
1. `play_scene` → 启动游戏
2. `get_game_screenshot` → 查看当前状态
3. `simulate_key` / `simulate_action` → 与游戏交互
4. `capture_frames` → 观察一段时间内的行为
5. `get_game_node_properties` → 检查特定数值
6. `stop_scene` → 完成后停止
7. 修复脚本问题 → 重复

### 6. 动画

```
# 确保场景中存在 AnimationPlayer 节点
create_animation       → 创建带时长和循环模式的新动画
add_animation_track    → 添加 property/transform/method 轨道
set_animation_keyframe → 在特定时间插入关键帧
get_animation_info     → 查看现有动画信息
```

**示例——弹跳精灵：**
1. `create_animation` name 为 `bounce`，length 为 `1.0`，loop_mode 为 `1`（线性循环）
2. `add_animation_track` track_path 为 `Sprite2D:position`，track_type 为 `value`
3. `set_animation_keyframe` time 为 `0.0`，value 为 `Vector2(0, 0)`
4. `set_animation_keyframe` time 为 `0.5`，value 为 `Vector2(0, -50)`
5. `set_animation_keyframe` time 为 `1.0`，value 为 `Vector2(0, 0)`

### 7. UI / HUD

```
add_node          → Control、Label、Button、TextureRect 等
set_anchor_preset → 定位 Control（full_rect、center、bottom_wide 等）
set_theme_color   → 修改 font_color 等
set_theme_font_size → 调整文字大小
set_theme_stylebox  → 背景、边框、圆角
connect_signal    → 连接 button 的 pressed、value_changed 等信号
```

### 8. TileMap

```
tilemap_get_info      → 检查图块集来源和图集布局
tilemap_set_cell      → 放置单个图块
tilemap_fill_rect     → 填充矩形区域
tilemap_get_used_cells → 查看已放置的内容
tilemap_clear         → 清除所有单元格
```

### 9. 音频

```
add_audio_bus        → 创建音频总线（SFX、Music、UI）
set_audio_bus        → 调整音量、独奏、静音
add_audio_bus_effect → 添加混响、延迟、压缩器等
add_audio_player     → 添加 AudioStreamPlayer(2D/3D) 节点
```

### 10. 项目配置

```
set_project_setting  → 修改视口大小、物理设置等
set_input_action     → 定义输入映射（move_left → KEY_A 等）
add_autoload         → 注册 autoload 单例
set_physics_layers   → 命名碰撞层（player、enemy、world 等）
```

## 重要规则与注意事项

### 属性值
属性会从字符串自动解析。使用以下格式：
- Vector2: `"Vector2(100, 200)"`
- Vector3: `"Vector3(1, 2, 3)"`
- Color: `"Color(1, 0, 0, 1)"` 或 `"#ff0000"`
- Bool: `"true"` / `"false"`
- 数字: `"42"`、`"3.14"`
- 枚举: 使用整数值（例如第一个枚举值用 `0`）

### 不要直接编辑 project.godot
Godot 编辑器会不断覆盖 `project.godot`。修改项目设置请务必使用 `set_project_setting`。

### GDScript 类型注解
在对无类型数组使用 `for` 循环时，请使用显式类型注解：
```gdscript
# 错误——会导致报错
for item in some_untyped_array:
    var x := item.value  # 类型推断失败

# 正确
for i in range(some_untyped_array.size()):
    var item: Dictionary = some_untyped_array[i]
    var x: int = item.value
```

### 脚本更改需要重新加载
创建或大幅修改脚本后，使用 `reload_project` 确保 Godot 识别更改。在 `create_script` 之后尤其重要。

### simulate_key 技巧
- 精确移动使用**短持续时间**（0.3-0.5 秒）
- 长持续时间（1 秒以上）会导致过冲
- 游戏测试时，如果已定义 InputMap 动作，优先使用 `simulate_action` 而非 `simulate_key`

### simulate_mouse_click
- 默认 `auto_release: true` 会同时发送按下和释放事件——UI 按钮必须如此
- UI 按钮在释放时触发，因此两个事件都必不可少

### execute_game_script 限制
- 不支持嵌套函数（`func` 中的 `func`）——会导致编译错误
- 动态访问请使用 `.get("property")` 而非 `.property`
- 运行时错误会暂停调试器（会自动继续，但尽量避免）

### 碰撞与拾取区域
- 可收集物品请使用 Area3D/Area2D 并设置半径 >= 1.5
- 较小的半径几乎无法通过模拟输入触发

### 经常保存
进行重大更改后请调用 `save_scene`。未保存的更改可能在编辑器重新加载时丢失。

## 分析与调试工具

出现问题时，使用以下工具进行排查：

```
get_editor_errors          → 检查脚本错误和运行时异常
get_output_log             → 读取 print() 输出和警告
analyze_scene_complexity   → 查找性能瓶颈
analyze_signal_flow        → 可视化信号连接
detect_circular_dependencies → 查找脚本/场景的循环引用
find_unused_resources      → 清理未使用的文件
get_performance_monitors   → FPS、内存、绘制调用、物理统计
```

## 测试与 QA

```
run_test_scenario   → 定义并运行自动化测试序列
assert_node_state   → 验证节点属性是否匹配预期值
assert_screen_text  → 验证文本是否显示在屏幕上
compare_screenshots → 视觉回归测试（使用文件路径，不要用 base64）
run_stress_test     → 生成大量节点以测试性能
```

## 高级模式

### 跨场景操作
```
cross_scene_set_property → 修改当前未打开场景中的节点
find_node_references     → 查找引用某个模式的所有文件
batch_set_property       → 为某类型的所有节点设置属性
```

### 着色器工作流
```
create_shader        → 编写类 GLSL 的着色器代码
assign_shader_material → 应用到节点
set_shader_param     → 在运行时调整 uniform 参数
get_shader_params    → 查看当前值
```

### 导航（3D）
```
setup_navigation_region → 定义可行走区域
bake_navigation_mesh   → 生成导航网格
setup_navigation_agent → 为角色添加寻路功能
```

### AnimationTree 与状态机
```
create_animation_tree           → 使用状态机或混合树设置 AnimationTree
add_state_machine_state         → 添加状态（idle、walk、run、jump）
add_state_machine_transition    → 定义状态之间的过渡
set_tree_parameter              → 控制混合参数
```

## 推荐工作流顺序

从零开始构建新游戏时：

1. **项目设置** — `get_project_info`、`set_project_setting`（视口、物理）
2. **输入映射** — `set_input_action` 定义所有玩家控制
3. **主场景** — `create_scene`，设为主场景
4. **玩家** — 创建包含精灵、碰撞、脚本的玩家场景
5. **关卡/世界** — 构建环境（TileMap、3D 网格等）
6. **游戏逻辑** — 敌人、道具、UI 的脚本
7. **音频** — 设置总线、添加音频播放器
8. **测试** — `play_scene`，使用模拟输入测试，修复 bug
9. **打磨** — 动画、粒子、着色器、主题
10. **导出** — `list_export_presets`、`export_project`