Godogen 学习教程

/godogen 做一个简单的弹球游戏

Godogen 学习教程

一、快速开始

1.1 什么是 Godogen？

Godogen 是一个 AI 驱动的游戏生成流水线，能够从一行文本描述生成完整的 Godot 4 游戏：

"做一个赛车游戏，有 AI 对手，赛道上有障碍物"
                    ↓
         ┌─────────────────────┐
         │   Godogen Pipeline  │
         │  • 架构设计          │
         │  • 代码生成          │
         │  • 资产生成          │
         │  • 视觉测试          │
         └─────────────────────┘
                    ↓
         ┌─────────────────────┐
         │  完整 Godot 4 项目   │
         │  • 可直接运行        │
         │  • 结构清晰          │
         │  • 可进一步编辑      │
         └─────────────────────┘

1.2 核心能力

能力	说明
架构设计	自动设计场景树、组件结构
代码生成	生成完整的 GDScript 代码
2D 资产	Gemini 生成精灵图、纹理
3D 资产	Tripo3D 转换 3D 模型
视觉 QA	自动检测并修复视觉问题

1.3 5 分钟上手

# 1. 安装前置依赖
# - Godot 4 (添加到 PATH)
# - Claude Code
# - Python 3

# 2. 克隆 Godogen
git clone https://github.com/htdt/godogen.git
cd godogen

# 3. 创建游戏项目
./publish.sh ~/my-first-game

# 4. 进入项目，启动 Claude Code
cd ~/my-first-game
claude

# 5. 描述你想要的游戏
> /godogen 做一个简单的弹球游戏

二、安装配置

2.1 系统要求

要求	说明
操作系统	Linux (Ubuntu/Debian 推荐)，macOS 需要额外配置
Godot 4	无头模式或编辑器模式
Claude Code	已安装并配置
Python 3	pip 包管理
GPU	推荐 T4/L4 或更高（截图捕获需要）

2.2 安装 Godot 4

Linux (Ubuntu/Debian)：

# 方法一：直接下载
wget https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip
unzip Godot_v4.3-stable_linux.x86_64.zip
sudo mv Godot_v4.3-stable_linux.x86_64 /usr/local/bin/godot
chmod +x /usr/local/bin/godot

# 方法二：Snap
sudo snap install godot-4

# 验证安装
godot --version

macOS：

# Homebrew
brew install --cask godot

# 或手动下载
# https://godotengine.org/download/macos/

2.3 安装 Claude Code

# npm 安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 登录配置
claude auth login

2.4 配置 API Keys

# 添加到 ~/.bashrc 或 ~/.zshrc

# Google API Key (必需，用于 Gemini 图像生成和视觉 QA)
export GOOGLE_API_KEY="your_google_api_key"

# Tripo3D API Key (3D 游戏必需)
export TRIPO3D_API_KEY="your_tripo3d_api_key"

# 使配置生效
source ~/.bashrc  # 或 source ~/.zshrc

获取 API Keys：

服务	获取方式
Google API	https://aistudio.google.com/apikey
Tripo3D	https://platform.tripo3d.ai/

2.5 安装 Godogen

# 克隆仓库
git clone https://github.com/htdt/godogen.git
cd godogen

# 安装 Python 依赖
pip install -r requirements.txt

# 验证安装
ls -la .claude/skills/

三、基础使用

3.1 创建游戏项目

# 使用默认模板 (teleforge.md)
./publish.sh ~/my-game

# 使用自定义模板
./publish.sh ~/my-game local.md

# 查看帮助
./publish.sh --help

publish.sh 做了什么：

创建目标目录
复制 .claude/skills/ 到目标目录
生成 CLAUDE.md 配置文件
初始化 Git 仓库

3.2 项目结构

生成后的项目结构：

my-game/
├── .claude/
│   ├── skills/
│   │   ├── godogen/        # 主技能
│   │   ├── planner/        # 规划技能
│   │   └── executor/       # 执行技能
│   └── settings.json
├── CLAUDE.md               # 项目配置
├── .git/
│   └── ...
└── (游戏文件将在生成时创建)

3.3 启动游戏生成

cd ~/my-game
claude

# 在 Claude Code 中
> /godogen 做一个太空射击游戏，玩家控制飞船，有敌人波次

3.4 生成过程

生成过程通常包含以下阶段：

┌─────────────────────────────────────────────────────────────┐
│  阶段 1: 需求分析与架构设计                                   │
│  • 解析游戏描述                                              │
│  • 设计场景树结构                                            │
│  • 规划组件和脚本                                            │
├─────────────────────────────────────────────────────────────┤
│  阶段 2: 资产生成                                            │
│  • 生成 2D 精灵图 (Gemini)                                   │
│  • 转换 3D 模型 (Tripo3D, 如果需要)                          │
│  • 生成音频资源                                              │
├─────────────────────────────────────────────────────────────┤
│  阶段 3: 代码编写                                            │
│  • 创建 Godot 项目文件                                       │
│  • 编写 GDScript 脚本                                        │
│  • 配置场景和节点                                            │
├─────────────────────────────────────────────────────────────┤
│  阶段 4: Visual QA                                           │
│  • 运行游戏并截图                                            │
│  • Gemini 分析视觉效果                                       │
│  • 发现问题并自动修复                                        │
├─────────────────────────────────────────────────────────────┤
│  阶段 5: 完成                                                │
│  • 输出完整的 Godot 项目                                     │
│  • 可以在 Godot 编辑器中打开继续开发                         │
└─────────────────────────────────────────────────────────────┘

四、游戏生成流程

4.1 游戏描述最佳实践

好的描述示例：

# 2D 游戏
做一个平台跳跃游戏，玩家可以左右移动和跳跃，收集金币，躲避尖刺陷阱，
到达终点旗帜过关，有 3 个关卡，关卡难度递增。

# 3D 游戏
做一个第一人称迷宫探索游戏，玩家在迷宫中寻找钥匙，找到钥匙后可以
打开出口门，有简单的光照效果，迷宫由程序生成。

# 物理 game
做一个愤怒的小鸟风格的弹弓游戏，玩家拖拽发射小鸟，击倒各种结构的
积木和敌人，需要计算角度和力度。

不好的描述示例：

# 太模糊
做一个好玩的游戏

# 太复杂
做一个 MMORPG，有 10 个职业，500 个技能，开放世界，实时战斗

4.2 游戏类型支持

类型	支持程度	说明
2D 平台跳跃	⭐⭐⭐⭐⭐	最佳支持
2D 射击	⭐⭐⭐⭐⭐	最佳支持
2D 物理	⭐⭐⭐⭐	弹弓、弹球等
3D 动作	⭐⭐⭐⭐	支持 Tripo3D
3D 赛车	⭐⭐⭐	已有成功案例
卡牌游戏	⭐⭐⭐	UI 密集型
策略游戏	⭐⭐⭐	复杂逻辑需要调整

4.3 生成时间估算

游戏复杂度	预计时间	API 成本
简单 2D 游戏	30-60 分钟	~$2-3
中等 2D 游戏	1-2 小时	~$5
简单 3D 游戏	2-3 小时	~$5-8
复杂游戏	3-5 小时	~$10+

五、高级配置

5.1 CLAUDE.md 配置文件

# CLAUDE.md 示例

## 项目信息
- 游戏类型: 2D 平台跳跃
- 目标平台: Web / Desktop
- Godot 版本: 4.3

## 开发偏好
- 代码风格: 注释详细，函数拆分清晰
- 场景结构: 单一入口，场景分离
- 资源管理: 统一 resources 目录

## 生成限制
- 最大场景数: 10
- 最大脚本数: 20
- 纹理分辨率: 512x512

## Visual QA
- 启用: true
- 截图间隔: 5 秒
- 最大迭代: 3

5.2 云端 VM 配置

推荐配置（Google Compute Engine）：

# 创建 VM 实例
gcloud compute instances create godogen-vm \
  --machine-type=n1-standard-4 \
  --accelerator=type=nvidia-tesla-t4,count=1 \
  --image-family=ubuntu-2204-lts \
  --image-project=ubuntu-os-cloud \
  --boot-disk-size=50GB

# SSH 连接
gcloud compute ssh godogen-vm

# 安装依赖
sudo apt update
sudo apt install -y python3 python3-pip
# ... 安装 Godot、Claude Code 等

5.3 Teleforge 远程监控

Teleforge 是一个轻量级的 Telegram 桥接工具，可以从手机监控生成进度：

# 配置 Teleforge
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

# 使用 Teleforge 模板
./publish.sh ~/my-game teleforge.md

# 生成过程中会发送进度消息到 Telegram

六、Visual QA 详解

6.1 Visual QA 工作原理

┌─────────────────────────────────────────────────────────────┐
│                    Visual QA 流程                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 构建游戏                                                 │
│     godot --headless --build                                │
│                                                             │
│  2. 运行游戏并截图                                           │
│     godot --path . --resolution 1280x720                    │
│     → 截图保存到 .qa/screenshots/                           │
│                                                             │
│  3. Gemini Flash 分析                                       │
│     • 检测 z-fighting (模型闪烁)                             │
│     • 检测缺失纹理 (粉红色方块)                              │
│     • 检测物理异常 (穿墙、飞天)                              │
│     • 检测 UI 问题 (文字重叠、按钮位置)                      │
│     • 检测光照问题 (过暗、过亮)                              │
│                                                             │
│  4. 生成修复建议                                             │
│     • 描述问题                                              │
│     • 建议修复方案                                          │
│     • 优先级排序                                            │
│                                                             │
│  5. 自动应用修复                                             │
│     → 修改 GDScript 代码                                    │
│     → 调整场景配置                                          │
│     → 重新生成资产                                          │
│                                                             │
│  6. 循环验证                                                 │
│     → 回到步骤 1，直到通过或达到最大迭代次数                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

6.2 常见检测问题

问题	视觉表现	常见原因
z-fighting	模型表面闪烁	两个面在同一位置
缺失纹理	粉红/紫色方块	纹理路径错误
物理穿透	物体穿过墙壁	碰撞体配置错误
UI 重叠	文字/按钮覆盖	锚点配置错误
黑屏	完全黑暗	光源缺失或被遮挡

6.3 手动触发 Visual QA

# 在 Claude Code 中
> /godogen:qa

# 或指定截图
> /godogen:qa --screenshot .qa/screenshots/scene_001.png

七、自定义与扩展

7.1 自定义技能

创建自定义技能来扩展 Godogen：

# .claude/skills/custom-godogen/skill.md

---
name: custom-godogen
description: 自定义游戏生成技能
trigger: /custom-game
---

## 角色定义
你是一个专门生成 [特定类型] 游戏的 AI 助手。

## 生成规则
1. 始终使用 [特定架构模式]
2. 代码风格遵循 [特定规范]
3. 资源使用 [特定格式]

## 模板
[你的自定义模板]

7.2 添加自定义资源生成器

# asset-tools/custom-generator/generator.py

from google import genai

def generate_sprite(prompt: str, style: str = "pixel_art") -> bytes:
    """生成自定义风格的精灵图"""
    client = genai.Client()

    full_prompt = f"""
    Generate a {style} style game sprite.
    Description: {prompt}
    Requirements:
    - Transparent background
    - 64x64 pixels
    - Smooth edges
    """

    response = client.models.generate_image(full_prompt)
    return response.image_data

7.3 集成其他 AI 模型

# 使用其他视觉模型进行 QA

## OpenAI GPT-4V
```bash
export OPENAI_API_KEY="your_key"
export QA_MODEL="gpt-4-vision-preview"

Claude Vision

export ANTHROPIC_API_KEY="your_key"
export QA_MODEL="claude-3-opus"


---

## 八、常见问题

### 8.1 安装问题

**Q: Godot 不在 PATH 中**

```bash
# 添加到 PATH
export PATH=$PATH:/path/to/godot

# 或创建符号链接
sudo ln -s /path/to/Godot_v4.* /usr/local/bin/godot

Q: API Key 无效

# 验证 API Key
curl -H "Authorization: Bearer $GOOGLE_API_KEY" \
  https://generativelanguage.googleapis.com/v1/models

# 检查环境变量
echo $GOOGLE_API_KEY

8.2 生成问题

Q: 生成卡住不动

# 检查 Claude Code 日志
tail -f ~/.claude/logs/latest.log

# 检查 Godot 进程
ps aux | grep godot

# 手动终止并重试
pkill -f godot

Q: Visual QA 失败

# 检查截图目录
ls -la .qa/screenshots/

# 手动运行 Godot
godot --path . --headless

# 检查 Vulkan 支持
vulkaninfo | head -20

8.3 输出问题

Q: 生成的游戏无法运行

# 检查项目文件
godot --path . --editor

# 查看错误日志
godot --path . 2>&1 | tee game.log

Q: 资源缺失

# 检查资源目录
ls -la assets/

# 重新生成资源
> /godogen:assets --regenerate

8.4 macOS 特定问题

Q: 截图捕获失败

macOS 需要使用原生截图方法：

# 安装依赖
brew install imagemagick

# 配置使用原生截图
export QA_CAPTURE_METHOD=native

九、最佳实践

9.1 描述游戏的技巧

明确核心玩法：描述主要机制
说明输入方式：键盘、鼠标、触摸
描述视觉风格：像素、卡通、写实
设定范围：简单开始，逐步扩展

9.2 生成过程管理

监控进度：使用 Teleforge 或定期检查
保留快照：重要节点提交 Git
并行开发：复杂游戏分模块生成
人工介入：发现问题及时调整

9.3 生成后优化

代码审查：检查生成的 GDScript
性能优化：检查资源大小和加载
测试覆盖：补充测试用例
文档完善：添加代码注释

9.4 成本控制

明确需求：避免反复生成
限制迭代：设置最大 QA 迭代次数
选择性 3D：只在必要时使用 Tripo3D
监控用量：跟踪 API 调用次数

十、速查表

10.1 常用命令

命令	说明
`./publish.sh ~/game`	创建新游戏项目
`claude`	启动 Claude Code
`/godogen [描述]`	开始生成游戏
`/godogen:qa`	手动触发 Visual QA
`/godogen:assets`	重新生成资源
`godot --path .`	运行生成的游戏

10.2 环境变量

变量	必需	说明
`GOOGLE_API_KEY`	✅	Gemini 图像生成和 QA
`TRIPO3D_API_KEY`	3D 游戏	Tripo3D 3D 模型转换
`TELEGRAM_BOT_TOKEN`	可选	Teleforge 通知
`TELEGRAM_CHAT_ID`	可选	Teleforge 通知

10.3 文件位置

文件/目录	位置
技能文件	`.claude/skills/`
项目配置	`CLAUDE.md`
QA 截图	`.qa/screenshots/`
游戏场景	`scenes/`
游戏脚本	`scripts/`
游戏资源	`assets/`

参考资源

GitHub 仓库：https://github.com/htdt/godogen
Demo 视频：https://www.youtube.com/watch?v=eUz19GROIiY
Godot 官方文档：https://docs.godotengine.org/
Claude Code 文档：https://docs.anthropic.com/claude-code
Gemini API 文档：https://ai.google.dev/docs
Tripo3D 文档：https://platform.tripo3d.ai/docs

教程生成时间：2026-03-22