pygame-genre-forge

name	pygame-genre-forge
description	Gera jogos em Pygame por gênero (ação, aventura, rpg, shooter, estratégia, puzzle, corrida, esportes, simulação, sandbox) usando templates e scaffold. Use quando o usuário pedir para criar/gerar um jogo Pygame, prototipar um gênero, criar um mini-game jogável, ou quando quiser validar automaticamente um jogo gerado (smoke test, screenshots).
license	MIT
compatibility	Claude Code (project skill). Requer Python 3.10+ e pygame instalados. Para CI/headless, pode usar SDL_VIDEODRIVER=dummy ou Xvfb.

Pygame Genre Forge

Objetivo

Você é um gerador de jogos Pygame por gênero. Sempre produza:

1. Um mini GDD (Game Design Doc) curto e objetivo;
2. Um blueprint (JSON) com parâmetros do jogo;
3. Código Pygame jogável, aderente ao gênero, com loop completo e controles responsivos;
4. Uma validação automática (smoke test + 1 screenshot) e um relatório.

Siga a ordem: (GDD) → (Blueprint) → (Código) → (Validação) → (Correções).

Primeiro Passo: Setup do Ambiente

Antes de gerar qualquer jogo, sempre execute o setup do ambiente:

python .claude/skills/pygame-genre-forge/scripts/setup_env.py

Isso irá:

• Detectar o sistema operacional (Linux/Windows/macOS)
• Criar um ambiente virtual .venv se não existir
• Instalar todas as dependências necessárias (pygame, Pillow)
• Validar que tudo funciona corretamente

Comandos (slash)

/pygame-genre-forge <genero> <pitch>

Gera um jogo novo dentro de generated_games/<slug>/.

Exemplos:

• /pygame-genre-forge shooter "nave no espaço, tiros coloridos, ondas, powerups simples"
• /pygame-genre-forge puzzle "um puzzle de empurrar caixas estilo sokoban em 10 fases pequenas"
• /pygame-genre-forge sports "pong com física simples e placar até 7"

/pygame-genre-forge remix <path-do-projeto> <mudanca>

Aplica mudanças ao jogo existente, mantendo estilo e estrutura.

/pygame-genre-forge validate <path-do-projeto>

Roda validação (timeout, smoke, screenshot) e salva artefatos em _artifacts/.

Perguntas mínimas (se faltarem dados)

Pergunte apenas o essencial, em no máximo 5 perguntas:

1. Qual é o gênero (um dos 10: action, adventure, rpg, shooter, strategy, puzzle, racing, sports, simulation, sandbox)?
2. Tema/ambientação?
3. Objetivo (win/lose)?
4. Controles (teclado/mouse) e plataforma alvo?
5. Complexidade: MVP (simples) / v1 (médio) / v2 (avançado)?

Regras de geração (padrão)

• Pygame puro; evitar depender de imagens/sons externos no MVP.
• Resolução padrão: 800×600.
• O jogo deve encerrar com ESC e tratar QUIT.
• Deve existir pelo menos: HUD mínimo (score/tempo/vida), condição de vitória/derrota, e feedback visual claro.
• Use formas geométricas (retângulos, círculos) e cores vibrantes ao invés de sprites externos.
• O código deve ser bem comentado em português e seguir PEP 8.
• Usar delta time para movimento e animação (independente de FPS).
• Tratar colisões adequadamente ao gênero.

Estrutura esperada do output

generated_games/<slug>/
├── main.py            # ponto de entrada do jogo
├── game.json          # blueprint com parâmetros
├── README.md          # como jogar + descrição
└── _artifacts/        # gerado pela validação
    ├── screenshots/
    ├── video/
    └── validation_report.json

Fluxo de geração passo a passo

1. Setup: Executar setup_env.py se .venv não existir
2. GDD: Criar mini Game Design Document com:
   • Nome, gênero, pitch, mecânicas, controles, win/lose condition
3. Blueprint: Criar game.json com parâmetros estruturados
4. Código: Gerar main.py usando templates e engine:
   • Importar componentes do engine (src/genre_forge/engine/)
   • Seguir padrão do gênero (src/genre_forge/genres/<genero>/)
   • Aplicar regras de geração
5. Validação: Executar validate_game.py:
   • Rodar jogo por 10s com timeout
   • Capturar screenshot
   • Gerar relatório
6. Correção: Se falhar, corrigir e revalidar uma vez

Onde buscar templates e referências

• Templates por gênero: src/genre_forge/templates/
• Specs de gênero: src/genre_forge/genres/
• Catálogo de gêneros: references/genre_catalog.md
• Regras de geração: references/prompting_rules.md
• Troubleshooting: references/troubleshooting.md
• Exemplos mínimos: examples/

Engine disponível

O engine em src/genre_forge/engine/ oferece:

• core_loop.py — Game loop com delta time e hooks
• input_map.py — Mapeamento de teclas/mouse
• collision.py — Detecção de colisão (AABB, círculo)
• math2d.py — Vetores 2D e utilitários
• scene_manager.py — Stack de cenas (menu, jogo, pause, game over)
• ui/ — HUD, menus, botões
• rendering/ — Sprites, efeitos, câmera