godot-core

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