Godot + Claude Code 游戏开发完全指南

最后更新: 2026-03-16

一、工具生态总览

三层工具栈（可共存）

层	工具	作用	安装方式
MCP Server	GDAI MCP	实时控制 Godot 编辑器（创建场景/节点/脚本、读错误）	`claude mcp add`
Skills（知识）	Godot-Claude-Skills	GDScript 模式、GdUnit4 测试、导出、CI/CD	复制到 `.claude/skills/`
Skills（生成）	godogen	从游戏描述生成完整项目 + 截图自检视觉QA	`publish.sh` 初始化

MCP 和 Skills 是不同机制，互不冲突。多个 Skills 也能共存。

其他可选工具

工具	说明	链接
Claude-GDSkill	Godot 4.5 专用 class skill	GitHub
Godot GDScript Patterns	架构模式、信号、状态机、性能优化	LobeHub
Godot Live Edit Skill	实时场景树操作、节点创建、属性修改	MCP Market
Godot 离线 API 文档 MCP	850+ Godot 类 API 参考	Godot Forum

二、安装步骤

1. GDAI MCP Server（推荐首选）

# Step 1: 在 Godot 项目中安装 GDAI MCP 插件
# 方式 A: Asset Library（在编辑器里搜 "GDAI MCP"）
# 方式 B: GitHub https://github.com/3ddelano/gdai-mcp-plugin-godot

# Step 2: 打开 Godot 编辑器 → 底部 GDAI MCP 标签页 → 复制 JSON 配置

# Step 3: 在 Claude Code 里添加
claude mcp add gdai-mcp -- uv run <路径从GDAI标签页复制>

# Step 4: Godot 编辑器设置
# Editor → Editor Settings → 开启:
#   - Auto Reload Scripts on External Change
#   - Auto Reload and Parse Scripts on Save

2. Godot-Claude-Skills

# 克隆到临时目录
git clone https://github.com/Randroids-Dojo/Godot-Claude-Skills.git /tmp/gcs

# 复制 skills 到你的项目
cp -r /tmp/gcs/.claude/skills/* ~/your-game/.claude/skills/

包含内容：

GdUnit4 集成（单元测试、场景测试、输入模拟）
PlayGodot 自动化（E2E 测试）
Web/Desktop 导出脚本
CI/CD 配置（GitHub Actions / GitLab CI）
部署指南（Vercel / GitHub Pages / itch.io）
Python 辅助脚本（run_tests.py, export_build.py, validate_project.py）

3. godogen（全自动生成项目）

git clone https://github.com/htdt/godogen.git ~/tools/godogen
cd ~/tools/godogen

# 初始化新游戏项目
./publish.sh ~/my-game              # 用默认 CLAUDE.md
./publish.sh ~/my-game local.md     # 用自定义 CLAUDE.md

# 然后在 Claude Code 里打开项目，告诉它想做什么游戏
cd ~/my-game && claude

godogen 的两个核心 skill：一个规划架构，一个执行生成。内置 850+ Godot 类 API 文档。

三、项目结构最佳实践

my-game/
├── CLAUDE.md              # ← 最重要！项目规则和约定
├── .claude/
│   └── skills/            # Claude Code skills
├── project.godot          # Godot 项目文件
├── scenes/                # .tscn 场景文件
│   ├── main.tscn
│   ├── ui/
│   └── levels/
├── scripts/               # .gd 脚本文件
│   ├── autoload/          # 全局单例
│   ├── entities/          # 游戏实体
│   └── ui/                # UI 控制器
├── resources/             # .tres 资源文件
│   ├── themes/
│   └── data/
├── assets/                # 静态资源
│   ├── sprites/
│   ├── audio/
│   └── fonts/
├── tests/                 # GdUnit4 测试
│   ├── unit/
│   └── scene/
├── addons/                # Godot 插件
│   └── gdai_mcp/          # GDAI MCP 插件
└── export/                # 导出目录（gitignore）

核心原则：

逻辑 → .gd 文件
数据 → .tres 资源文件
场景结构 → .tscn 场景文件

四、CLAUDE.md 模板

# [游戏名称] - Godot 4.x 项目

## 引擎版本
Godot 4.3 (或你使用的版本)

## 代码规范

### GDScript 强制规则
- **严格类型标注**: `var speed: float = 100.0`，不允许无类型变量
- **使用 Godot 4 语法**: `@export`, `@onready`, `await`, 不用旧版 `yield`
- **信号驱动架构**: 节点间通信用信号，不要直接引用其他节点
- **类名注册**: 复用类用 `class_name XxxYyy` 注册
- **命名约定**:
  - 节点名: PascalCase (Player, EnemySpawner)
  - 脚本变量: snake_case (move_speed, health_points)
  - 信号: past_tense (health_changed, enemy_died)
  - 常量: UPPER_SNAKE (MAX_HEALTH, TILE_SIZE)

### 文件组织
- 每个场景对应一个同名脚本
- Autoload 单例放 scripts/autoload/
- 可复用资源用 .tres 文件，不要硬编码数据

### 场景文件
- 简单场景可以直接写 .tscn（Claude 可读写）
- 复杂场景（大量节点/动画）优先用 GDAI MCP 通过编辑器操作
- 不要手动编辑 .import 文件

### 测试
- 用 GdUnit4 写测试
- 每个核心系统至少一个测试
- 测试文件放 tests/ 目录

### 提交规范
- 每个功能一个 commit
- 至少每小时 commit 一次
- Conventional Commits 格式

## 游戏设计
[在这里描述你的游戏类型、核心玩法、目标平台等]

五、推荐工作流

日常开发流程

1. 规划（Plan Mode）
   └→ Claude Code 分析需求，拆解任务

2. 实现
   └→ 写 GDScript + .tscn
   └→ GDAI MCP 在编辑器里创建/修改节点

3. 验证
   └→ 通过 MCP 运行项目
   └→ 截图检查（手动或 godogen 视觉 QA）
   └→ 读取编辑器错误日志

4. 修复 & 迭代
   └→ 根据错误/截图修复
   └→ 重复 3-4

5. 提交
   └→ git commit（频繁！）

并行开发（进阶）

用 git worktree 同时跑多个 Claude Code session：

# 主线程做 gameplay
cd ~/my-game && claude

# 新 worktree 做 UI
git worktree add ../my-game-ui feature/ui
cd ../my-game-ui && claude

# 完成后合并
git merge feature/ui

六、踩坑经验

⚠️ LLM 对 GDScript 训练数据少

解决: 用 godogen 内置的 API 文档，或装离线 API MCP
解决: 在 CLAUDE.md 里写清楚 Godot 4 语法规则

⚠️ 复杂 .tscn 不要让 Claude 手写

.tscn 格式复杂（ext_resource、sub_resource 引用）
解决: 用 GDAI MCP 通过编辑器 API 操作，更安全

⚠️ 频繁 commit

AI 改错了需要回退
至少每小时 commit 一次，每完成一个功能就 commit

⚠️ 保持对代码的理解

有开发者全程让 Claude 写，最后完全看不懂自己的代码
建议: 每次 Claude 生成代码后花时间读懂，至少理解架构

⚠️ Godot 的优势

几乎所有 UI 操作都反映在版本控制的文本文件里
Claude 可以直接读写 .tscn/.tres/.gd，不需要 GUI
这是 Godot 相对 Unity/Unreal 的最大 AI 友好优势

七、参考链接

资源	链接
GDAI MCP 官方文档	https://gdaimcp.com/docs/installation
GDAI MCP GitHub	https://github.com/3ddelano/gdai-mcp-plugin-godot
godogen	https://github.com/htdt/godogen
Godot-Claude-Skills	https://github.com/Randroids-Dojo/Godot-Claude-Skills
Claude-GDSkill	https://github.com/Kothulhu94/Claude-GDSkill
Godot Asset Library MCP	https://godotengine.org/asset-library/asset/4767
RTS 开发实战分享	https://dev.to/datadeer/part-1-building-an-rts-in-godot-what-if-claude-writes-all-code-49f9
并行 worktree 开发	https://dev.to/datadeer/part-2-running-multiple-claude-code-sessions-in-parallel-with-git-worktree-165i
Claude Code 最佳实践	https://code.claude.com/docs/en/best-practices
GDScript Patterns Skill	https://lobehub.com/skills/haniakrim21-everything-claude-code-godot-gdscript-patterns

interfacekun/godot-claude-code-guide.md

Select an option

No results found

Select an option

No results found

Godot + Claude Code 游戏开发完全指南

一、工具生态总览

三层工具栈（可共存）

其他可选工具

二、安装步骤

1. GDAI MCP Server（推荐首选）

2. Godot-Claude-Skills

3. godogen（全自动生成项目）

三、项目结构最佳实践

四、CLAUDE.md 模板

五、推荐工作流

日常开发流程

并行开发（进阶）

六、踩坑经验

⚠️ LLM 对 GDScript 训练数据少

⚠️ 复杂 .tscn 不要让 Claude 手写

⚠️ 频繁 commit

⚠️ 保持对代码的理解

⚠️ Godot 的优势

七、参考链接