Godogen: Claude Code 및 Codex를 활용한 Godot 및 Bevy용 자율 게임 개발

데모 시청하기 · 프롬프트 (Prompts)

게임을 설명하세요. Godogen이 게임을 계획하고, 코드를 작성하며, 에셋 (assets)을 생성하고, 엔진을 실행하며, 스크린샷을 확인하고, 잘못되어 보이는 부분을 수정합니다.

이 저장소 (repo)는 게임이 아닙니다. 게임을 생성하는 생성기 (generator)의 소스입니다: godogen -> 게임 저장소 (game repo) -> 게임입니다. 엔진과 호스트 에이전트 (host-agent) 유형을 선택하여 새로운 게임 저장소에 기술 (skills)을 게시하면, 에이전트가 해당 저장소 내부에서 실행되어 실제 게임을 구축합니다.

소스 레이아웃 (Source layout)

소스는 엔진 축을 따라 구성됩니다:

• shared/ — 엔진에 무관한 (engine-agnostic) godogen 단계, 에셋 생성 도구 (asset-generation tooling), 공유 중단 훅 (shared stop hook), 그리고 공통 게임 저장소 지침
• godot/ — Godot 전용 godogen 단계, Godot 캡처 도우미 (capture helpers), 그리고 godot-api 기술 (skill)
• bevy/ — Bevy 전용 godogen 단계, Bevy 캡처 도우미 (capture helpers), 그리고 bevy-help 기술 (skill)

Claude Code와 Codex의 선택은 게시 시점의 렌더링 선택 사항이며, 별도의 소스 트리 (source tree)가 아닙니다. 루트의 publish.sh가 선택된 엔진과 호스트 에이전트에 맞는 올바른 런타임 레이아웃 (runtime layout)을 렌더링합니다.

기술 (skills)이 하는 일

• Godot 4 출력 (output) — 적절한 씬 트리 (scene trees), 씬 빌더 (scene builders), 스크립트 (scripts) 및 에셋 조직 (asset organization)을 갖춘 실제 C#/.NET 프로젝트를 생성합니다.
• Godot Android 내보내기 (export) — 사용자가 Android 앱을 요청할 때 디버그용 APK 내보내기 기능을 계속 사용할 수 있습니다.
• Bevy 출력 (output) — 코드 우선 씬 (code-first scenes), 로컬 Bevy 문서 조회, 결정론적 캡처 가이드 (deterministic capture guidance) 및 최종 증명 번들 (proof bundles)을 포함한 Rust/Bevy 프로젝트를 생성합니다.
• 에셋 생성 (Asset generation) — Gemini는 정밀한 참조 (references) 및 캐릭터를 생성하며, xAI Grok은 텍스처와 단순 객체를 처리하고, Tripo3D는 이미지를 3D 모델로 변환합니다. 애니메이션 스프라이트 (Animated sprites)는 루프 감지 (loop detection) 기능이 포함된 Grok 비디오 생성 기술을 사용합니다.
• Godot를 위한 C# / .NET 9 — Godot 출력물은 C#을 사용합니다. 왜 GDScript보다 C#인가를 참조하세요.
• 프레임 기반 자가 수리 (Frame-grounded self-repair) — 에이전트는 컴파일되는 코드가 아니라 캡처된 스크린샷을 통해 진행 상황을 판단하도록 세심하게 프롬프트(prompt)됩니다. 따라서 눈에 보이는 결함(클리핑 (clipping), 잘못된 스케일, 멈춘 동작, 누락된 에셋)이 합리화되어 무시되는 대신 다음 반복 (iteration)의 동력이 됩니다.
• Telegram 증명 푸시 (Telegram proof push) — 게시된 저장소 (repos)는 tg-push와 TG_* 환경 변수 (env vars)가 설정되었을 때 최신 screenshots/result/{N}/video.mp4를 Telegram으로 푸시하는 중지 훅 (stop hook)을 설치합니다. 그렇지 않으면 아무 작업도 수행하지 않습니다 (No-op).
• 범용 하드웨어에서 실행 (Runs on commodity hardware) — 관련 엔진 툴체인 (engine toolchain), Python 및 필요한 API 키가 있는 모든 기기에서 파이프라인 (pipeline)을 실행할 수 있습니다.

시작하기 (Getting started)

사전 요구 사항 (Prerequisites)

• Godot 프로젝트를 위한 PATH에 설정된 Godot 4 (.NET 빌드)
• Bevy 프로젝트를 위한 Rust/Cargo 및 로컬 Bevy 문서 (docs)
• pip가 포함된 Python 3
• 환경 변수로 설정된 API 키:
  • GOOGLE_API_KEY — Gemini 이미지 생성을 위한 Google AI Studio
  • XAI_API_KEY — 이미지/비디오 생성을 위한 xAI Grok
  • TRIPO3D_API_KEY — 3D 생성을 위한 Tripo3D
• setup.md에 명시된 시스템 패키지: vulkan-tools, xvfb, ffmpeg, imagemagick 및 플랫폼별 추가 패키지
• Ubuntu, Debian, macOS에서 테스트 완료
• Claude Code 또는 Codex

게임 리포지토리 게시하기 (Publish a game repo)

엔진과 호스트 에이전트(host agent)를 선택하세요:

./publish.sh --engine godot --agent claude --out ~/my-game  # CLAUDE.md + .claude/skills/
./publish.sh --engine godot --agent codex  --out ~/my-game  # AGENTS.md + .agents/skills/
./publish.sh --engine bevy  --agent claude --out ~/my-game
...

게시하기 전에 대상 위치의 기존 콘텐츠를 삭제하려면 --force를 전달하세요. 이전 실행 결과 위에 다시 게시할 때 이 옵션을 사용합니다.

Bevy 문서 설정 (Bevy docs setup)

Bevy 생성 작업을 수행하는 경우, 클론(clone) 후 한 번만 공유 Bevy 문서 폴더를 구성하고 채워 넣으세요:

./setup_bevy_docs.sh /absolute/or/user/path/to/bevy-docs

설정 스크립트는 bevy/skills/bevy-help/docs/를 해당 폴더에 연결하고, 새로운 캐시를 위한 얕은(shallow) Bevy 문서 소스 체크아웃을 생성하며, 현재 안정 버전(stable release)에 대한 로컬 rustdoc을 빌드합니다. 기본 경로는 가정되지 않습니다. 전체 워크스테이션 설정은 setup.md를 참조하세요.

서버에서 실행하기 (Running on a server)

전체 생성 프로세스는 몇 시간이 걸릴 수 있으므로, 이를 서버로 오프로드(offload)하는 것이 편리합니다. 엔진 렌더링과 비디오 캡처는 하드웨어 가속을 사용할 때 훨씬 빠르기 때문에 GPU 인스턴스를 사용하는 것이 이상적입니다.

• tmux 또는 screen을 사용하여 SSH 연결이 끊어져도 세션을 유지하세요.
• tg-push를 설치하세요: 중단 훅 (stop hook)이 작업 완료 시 최종 증명 비디오를 Telegram으로 자동 전송합니다.
• 원격 제어 (remote control)를 활성화하여 어떤 기기에서든 실행 상태를 확인하고 제어할 수 있도록 하세요 — Claude Code와 Codex 모두 공식 원격 제어 인터페이스를 제공합니다.

기술 향상시키기

전체 생성 세션이 끝난 후, 사용했던 에이전트 (agent)에게 파이프라인 (pipeline)이 어떻게 수행되었는지 검토하도록 요청하세요:

이 세션을 분석해 주세요. 지시 사항 (instructions)이 최적이었나요? 너무 당연하거나, 누락되었거나, 오해의 소지가 있었던 부분을 표시해 주세요. 어떤 도구들이 노이즈 (noise)로 컨텍스트 (context)를 오염시켰나요? 캡처 루프 (capture loop)가 실제 문제들을 제대로 포착했나요? 도구의 실패나 우회 방법 (workarounds)이 있었나요?

변경 이력

CHANGELOG.md를 참조하세요.

진행 상황 팔로우: @alex_erm