Comprehensive breakdown of the AI-driven Godot game generation system.
Godogen is a Claude Code skills collection for automated Godot game development. It transforms natural language game descriptions into complete, playable Godot projects through a multi-stage orchestration pipeline.
The system uses a two-skill orchestration pattern:
godogen(main thread) — High-level orchestratorgodot-task(fork context) — Individual task executor
At its core, godogen is an autonomous game development system that uses Claude Code's skill framework to generate complete Godot games from natural language descriptions.
-
You describe a game in plain English (e.g., "make a platformer with a jumping character")
-
The orchestrator (
godogen) breaks this down into a plan:- Generates a
reference.png— a visual style guide that all assets must match - Creates
PLAN.md— a task dependency graph with specific goals and verification criteria - Designs
STRUCTURE.md— the architecture (scenes, scripts, signals) - Generates necessary assets (PNGs, 3D models, spritesheets) using AI services
- Generates a
-
For each task in the plan, the orchestrator forks a
godot-taskagent:- The task agent has a clean, isolated context (no pollution from previous tasks)
- It generates scenes (
.tscn) and scripts (.gd) using headless Godot - It captures screenshots and verifies them against the task's Verify criteria
- It performs Visual QA by comparing against
reference.png - Reports back success or failure
-
The orchestrator commits each successful task and moves to the next
-
Result: A complete, playable Godot project with consistent art style
| Feature | Why It Matters |
|---|---|
| Visual-first verification | Every task produces screenshots; no "it works on my machine" — you can see if it worked |
| Forked task execution | Each task runs in isolation; failures don't corrupt the whole project |
| Reference image | reference.png ensures visual consistency across all assets and scenes |
| Git checkpointing | Every completed task is committed; you can always roll back |
| Memory accumulation | MEMORY.md persists learnings (workarounds, quirks) across the entire pipeline |
| Non-interactive design | Built for Telegram bot integration; no terminal prompts |
┌────────────────────────────────────┐
│ Main Thread (Claude) │
│ ┌─────────────────────────────┐ │
│ │ SKILL: godogen │ │
│ │ • Parse user request │ │
│ │ • Create PLAN.md │ │
│ │ • For each task: │ │
│ │ ┌──────────────────┐ │ │
│ │ │ FORK CONTEXT │ │ │
│ │ │ Skill(godot-task)│ │ │
│ │ │ • Generate code │ │ │
│ │ │ • Screenshot │ │ │
│ │ │ • Verify │ │ │
│ │ │ • Report back │ │ │
│ │ └──────────────────┘ │ │
│ │ • Commit if success │ │
│ │ • Move to next task │ │
│ └─────────────────────────────┘ │
└────────────────────────────────────┘
The orchestrator handles the big-picture logic: planning, asset generation, sequencing, and recovery. The task executor handles the nitty-gritty: writing GDScript, compiling scenes, debugging parse errors, and visual verification.
Assets aren't just downloaded — they're generated from prompts:
| Asset Type | Tool | Cost |
|---|---|---|
| 2D sprites/textures | Gemini Flash image generation | 5-15¢ |
| Animated spritesheets | Gemini + template-guided 4x4 grid | 7¢ |
| 3D models | Image → Tripo3D GLB conversion | 30-60¢ |
Background removal uses rembg with alpha matting for clean edges. Spritesheets are sliced and processed based on use case (animation frames vs. item collections).
Unlike code generation tools that just spit out files, godogen:
- Verifies visually — Screenshots are captured and checked against requirements
- Maintains consistency — The
reference.pngacts as an art director - Handles failure gracefully — Failed tasks can be retried, replanned, or escalated
- Accumulates knowledge —
MEMORY.mdgrows with each task, recording what worked - Commits incrementally — Git history shows the evolution of the game
┌─────────────────────────────────────────────────────────────────────────────────┐
│ GODOGEN PIPELINE │
│ AI-Driven Godot Game Generation System │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 0: INPUT │
│ ─────────────────────────────────────────────────────────────────────────────── │
│ User Request: "Make a platformer game with a jumping character" │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 1: RESUME CHECK & VISUAL TARGET [SKILL: godogen] │
│ ─────────────────────────────────────────────────────────────────────────────── │
│ │
│ ┌─────────────┐ NO ┌──────────────────────────────────────┐ │
│ │ PLAN.md │──────────▶│ 📄 visual-target.md │ │
│ │ exists? │ │ ↓ │ │
│ └──────┬──────┘ │ Generate reference.png │ │
│ │ YES │ + ASSETS.md (art direction) │ │
│ ▼ └──────────────────────────────────────┘ │
│ ┌────────────────┐ │
│ │ Read PLAN.md │ ┌─────────────────────────────────────────┐ │
│ │ STRUCTURE.md │───>│ Skip to Task Execution (Stage 5) │ │
│ │ MEMORY.md │ └─────────────────────────────────────────┘ │
│ └────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 2: DECOMPOSITION [SKILL: godogen] │
│ ─────────────────────────────────────────────────────────────────────────────── │
│ 📄 decomposer.md │
│ ↓ │
│ Create PLAN.md ──► Task DAG with: │
│ ┌──────────┬─────────────┬────────────────────┬─────────────────────┐ │
│ │ Task ID │ Status │ Goal │ Verify Criteria │ │
│ ├──────────┼─────────────┼────────────────────┼─────────────────────┤ │
│ │ 1 │ pending │ Create player │ Player visible │ │
│ │ 2 │ pending │ Add platforms │ Can jump between │ │
│ │ ... │ ... │ ... │ ... │ │
│ └──────────┴─────────────┴────────────────────┴─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 3: ARCHITECTURE [SKILL: godogen] │
│ ─────────────────────────────────────────────────────────────────────────────── │
│ 📄 scaffold.md │
│ ↓ │
│ Create: │
│ ├── STRUCTURE.md (scene/script mappings, signals, autoloads) │
│ ├── project.godot (Godot project config) │
│ └── scenes/, scripts/, test/, assets/ (folder stubs) │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 4: ASSET PLANNING & GENERATION [SKILL: godogen] │
│ ─────────────────────────────────────────────────────────────────────────────── │
│ │
│ Budget provided? ──► 📄 asset-planner.md ──► 📄 asset-gen.md │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ TOOLS (Python Scripts) │ │
│ ├─────────────────────────────────────────────────────────────────────────┤ │
│ │ 🔧 asset_gen.py │ Main orchestrator │ │
│ │ ├─► image │ Generate PNGs (Gemini Flash) │ │
│ │ │ ↓ │ 5-15 cents per image │ │
│ │ │ 🔧 rembg_matting.py│ Remove background │ │
│ │ │ │ │ │
│ │ ├─► spritesheet │ Generate 4x4 animation sheets │ │
│ │ │ ↓ │ 7 cents per sheet │ │
│ │ │ 🔧 spritesheet_ │ Slice & process sheets │ │
│ │ │ template.py │ (keep-bg / clean-bg / split) │ │
│ │ │ slice.py │ │ │
│ │ │ │ │ │
│ │ └─► glb │ Convert image → 3D model (Tripo3D) │ │
│ │ ↓ │ 30-60 cents per model │ │
│ │ 🔧 tripo3d.py │ API integration │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Output: assets/ directory with PNGs, GLBs, spritesheets │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 5: TASK EXECUTION LOOP [SKILL: godogen] │
│ ─────────────────────────────────────────────────────────────────────────────── │
│ │
│ Find next ready task (pending + deps done) │
│ │ │
│ ▼ │
│ Update PLAN.md: status → in_progress │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ FORK: Skill(godot-task) with task block │ │
│ │ ───────────────────────────────────────────────────────────────────── │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ [SKILL: godot-task] (isolated fork context) │ │ │
│ │ ├─────────────────────────────────────────────────────────────────┤ │ │
│ │ │ Step 1: Analyze Targets │ │ │
│ │ │ • scenes/*.tscn → generate scene builder │ │ │
│ │ │ • scripts/*.gd → generate runtime script │ │ │
│ │ │ • Both → scenes FIRST, then scripts │ │ │
│ │ │ │ │ │
│ │ │ Step 2: Load Docs Progressively │ │ │
│ │ │ 📄 quirks.md - Godot gotchas │ │ │
│ │ │ 📄 gdscript.md - Syntax reference │ │ │
│ │ │ 📄 scene-generation.md - Build .tscn files │ │ │
│ │ │ 📄 script-generation.md - Write .gd files │ │ │
│ │ │ 📄 capture.md - Screenshot capture │ │ │
│ │ │ 📄 visual-qa.md - Automated comparison │ │ │
│ │ │ 📄 doc_api/*.md - 860 Godot class references │ │ │
│ │ │ │ │ │
│ │ │ Step 3: Import Assets │ │ │
│ │ │ $ godot --headless --import │ │ │
│ │ │ (Generates .import files for textures/GLBs) │ │ │
│ │ │ │ │ │
│ │ │ Step 4: GENERATE & VALIDATE LOOP │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ • Write scene builder (build_*.gd) │ │ │ │
│ │ │ │ $ godot --headless --script build_*.gd │ │ │ │
│ │ │ │ ↓ produces scenes/*.tscn │ │ │ │
│ │ │ │ • Write runtime scripts (scripts/*.gd) │ │ │ │
│ │ │ │ • Validate: $ godot --headless --quit │ │ │ │
│ │ │ │ • Fix parse errors (repeat until clean) │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ Step 5: Test Harness │ │ │
│ │ │ Write test/test_{task_id}.gd implementing Verify scenario │ │ │
│ │ │ │ │ │
│ │ │ Step 6: Capture Screenshots │ │ │
│ │ │ Run test with --write-movie → PNG frames │ │ │
│ │ │ GPU display or xvfb fallback │ │ │
│ │ │ │ │ │
│ │ │ Step 7: Visual Verification │ │ │
│ │ │ • Check vs Verify description (task goal) │ │ │
│ │ │ • Check vs reference.png (visual consistency) │ │ │
│ │ │ • Check for obvious bugs (clipping, floating, overlap) │ │ │
│ │ │ │ │ │
│ │ │ Step 8: Visual QA │ │ │
│ │ │ Automated comparison → visual-qa/{N}.md report │ │ │
│ │ │ verdict: pass / warning / fail │ │ │
│ │ │ │ │ │
│ │ │ Step 9: Update MEMORY.md │ │ │
│ │ │ Record discoveries, workarounds, technical specifics │ │ │
│ │ │ │ │ │
│ │ │ REPORT BACK: screenshots/, VQA report, success/failure │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Mark task in PLAN.md: done / done (partial) / skipped │
│ │ │
│ ▼ │
│ $ git add . && git commit -m "Task N: {description}" │
│ │ │
│ ▼ │
│ More tasks? ──► YES (loop back) ──► NO (complete) │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STAGE 6: OUTPUT │
│ ─────────────────────────────────────────────────────────────────────────────── │
│ • Complete Godot game in target folder │
│ • project.godot, scenes/, scripts/, assets/ │
│ • PLAN.md, STRUCTURE.md, MEMORY.md for future updates │
│ • Final task: Presentation video (~30s MP4 showcasing gameplay) │
└─────────────────────────────────────────────────────────────────────────────────┘
| Symbol | Meaning |
|---|---|
📄 {name}.md |
Skill sub-module documentation |
🔧 *.py |
Python tool script |
📜 *.sh |
Shell script |
🎲 godot |
Godot Engine CLI invocation |
🎮 godogen |
Main orchestrator skill (main context) |
⚙️ godot-task |
Task executor skill (forked context) |
Location: skills/godogen/
Purpose: Main orchestrator that generates and updates Godot games from natural language.
| File | Purpose |
|---|---|
SKILL.md |
Main orchestration pipeline |
visual-target.md |
Generate reference.png anchoring art direction |
decomposer.md |
Decompose game into PLAN.md (task DAG) |
scaffold.md |
Design architecture → STRUCTURE.md + project skeleton |
asset-planner.md |
Decide assets within budget |
asset-gen.md |
Orchestrate PNG/GLB generation |
Tools (tools/ directory):
| Tool | Purpose |
|---|---|
asset_gen.py |
Main asset generator (Gemini images, Tripo3D GLBs) |
tripo3d.py |
3D model generation via Tripo3D API |
spritesheet_template.py |
Generate 4x4 grid templates |
spritesheet_slice.py |
Crop/split spritesheets (keep-bg / clean-bg / split modes) |
rembg_matting.py |
Background removal with alpha matting |
requirements.txt |
Python dependencies |
Location: skills/godot-task/
Purpose: Execute a single Godot development task — generate scenes/scripts, verify visually.
| File | Purpose | When to Read |
|---|---|---|
SKILL.md |
Task execution workflow | Entry point |
quirks.md |
Known Godot gotchas | Before writing code |
gdscript.md |
GDScript syntax reference | Before writing code |
scene-generation.md |
Building .tscn files |
Targets include .tscn |
script-generation.md |
Writing runtime .gd scripts |
Targets include .gd |
coordination.md |
Ordering scene + script generation | Both .tscn and .gd |
test-harness.md |
Writing verification scripts | Before writing test |
capture.md |
Screenshot/video capture | Before capturing |
visual-qa.md |
Automated comparison | When reference.png exists |
doc_api/_common.md |
128 common Godot classes | API reference |
doc_api/_other.md |
732 remaining classes | API reference |
doc_api/{ClassName}.md |
Full class API | Specific class lookup |
Tools (tools/ directory):
| Tool | Purpose |
|---|---|
ensure_doc_api.sh |
Bootstrap Godot API docs |
godot_api_converter.py |
Convert Godot docs to markdown |
class_list.py |
Generate class lists |
After running godogen, the target directory contains:
| File/Directory | Purpose |
|---|---|
project.godot |
Godot engine configuration |
reference.png |
Visual target for art direction |
STRUCTURE.md |
Architecture reference (scenes, scripts, signals) |
PLAN.md |
Task DAG with goals/requirements/verify criteria |
ASSETS.md |
Asset manifest with art direction |
MEMORY.md |
Accumulated discoveries from execution |
scenes/ |
Compiled .tscn files |
scripts/ |
Runtime .gd files |
test/ |
Visual test harnesses |
assets/ |
Generated images, GLBs, spritesheets (gitignored) |
screenshots/ |
Per-task captured frames (gitignored) |
visual-qa/ |
Automated visual QA reports |
-
Minimal task count — A standard 2D game rarely exceeds 3 tasks; only algorithmically risky features get isolated tasks.
-
Visual-first verification — Every task must produce verifiable screenshots. The
Verifycriteria inPLAN.mddefines what success looks like. -
Forked execution — Each task runs in an isolated
godot-taskfork context. Failures are contained; successes are committed. -
Memory accumulation —
MEMORY.mdpersists learnings across tasks (workarounds, Godot quirks, asset details). -
Art consistency —
reference.pngis generated once and used for visual QA throughout. All assets and screenshots are compared against it. -
Git checkpointing — Each completed task is committed:
git add . && git commit -m "Task N done" -
Non-interactive — Designed for Telegram bot integration. No terminal/stdin input required.
-
No hand-holding — Skills don't give obvious guidance. The agent is a highly capable LLM.
# Generate image (5-15 cents)
python3 skills/godogen/tools/asset_gen.py image \
--prompt "description" \
--size 1K \
--aspect-ratio 16:9 \
-o assets/img/background.png
# Generate spritesheet (7 cents, 4x4 = 16 cells)
python3 skills/godogen/tools/asset_gen.py spritesheet \
--prompt "Animation: knight swinging sword" \
--bg "#4A6741" \
-o assets/img/knight_raw.png
# Remove background
python3 skills/godogen/tools/rembg_matting.py \
assets/img/knight_raw.png \
-o assets/img/knight.png
# Slice spritesheet
python3 skills/godogen/tools/spritesheet_slice.py clean-bg \
assets/img/knight_raw.png \
-o assets/img/knight.png
# Generate 3D model (30-60 cents)
python3 skills/godogen/tools/asset_gen.py glb \
--image assets/img/car.png \
--quality medium \
-o assets/glb/car.glb# Import assets (MUST run before scene builders)
timeout 60 godot --headless --import
# Compile scene builder (produces .tscn)
timeout 60 godot --headless --script build_scene.gd
# Validate all scripts
timeout 60 godot --headless --quit 2>&1| Operation | Preset | Cost |
|---|---|---|
| Image (512) | --size 512 |
5¢ |
| Image (1K) | --size 1K |
7¢ |
| Image (2K) | --size 2K |
10¢ |
| Image (4K) | --size 4K |
15¢ |
| Spritesheet | — | 7¢ |
| GLB | lowpoly | 40¢ |
| GLB | medium | 30¢ |
| GLB | high | 40¢ |
| GLB | ultra | 60¢ |
Typical costs:
- Full 3D asset (image + GLB medium): 37¢
- Texture/image asset: 7¢
- Animated sprite (16 frames): 7¢
- Asset kit (16 items, consistent style): 7¢ (vs 112¢ for individual)
The publish.sh script creates a ready-to-develop game folder:
./publish.sh <target_dir> [claude_md]It:
- Creates
.claude/skills/in the target directory - Copies all skills from this repository
- Copies
teleforge.md(or custom CLAUDE.md) to the target - Creates a
.gitignorefor Godot projects - Initializes a git repository
If a task reports failure:
- Read
MEMORY.md— Contains discoveries from previous tasks - Check screenshots — Look in
screenshots/{task_folder}/ - Validate project — Run
timeout 30 godot --headless --quit 2>&1 - Review VQA report — Read
visual-qa/{N}.mdfor automated comparison results
CLAUDE.md— Repository documentationteleforge.md— CLAUDE.md template for published projectsskills/godogen/SKILL.md— Orchestrator skill definitionskills/godot-task/SKILL.md— Task executor skill definition