> **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`