NextAgentX/pipeline-producao-jogos

Pipeline de Produção de Jogos de Ponta a Ponta

Leve uma ideia até um build compilável + um plano de lançamento. Cada estágio possui artefatos obrigatórios, caminhos fixos e gateways executáveis; não é permitido pular estágios.

As funções a seguir são opcionais e divisíveis: utilize-as apenas se o ambiente atual suportar e permitir delegação; caso contrário, o assistente atual deve realizar as tarefas diretamente. Escolha o escopo de trabalho de acordo com a autorização real do usuário e a fase do projeto. Os scripts de status verificam apenas títulos de documentos e TODOs; eles não verificam automaticamente recursos, builds reais ou validação em dispositivos reais; essas verificações devem ser executadas separadamente e os resultados registrados.

Para ver os cinco estágios de produção, os marcos G1–G5, os ciclos de Sprint e o ajuste de tamanho da equipe, consulte references/production-cycle.md. A tabela a seguir lista os sete estágios de artefatos de documento com sub-gateways; eles não correspondem um a um com os marcos de produção.

Estágios e Artefatos

Estágio	Saída	Função Responsável
brief	docs/00-brief.md Cartão de Projeto	Produtor (você mesmo)
gdd	docs/01-gdd.md	game-narrative-designer
tech	docs/02-tech.md	cocos-engineer, unity-engineer ou godot-engineer
art	docs/03-art.md + docs/art-style-bible.md + Arte final + assets/manifest.json	game-art-director
audio	docs/04-audio.md + Áudio final	game-audio-designer
qa	docs/05-qa.md	game-qa-engineer
release	docs/06-release.md	game-release-operator

Os esqueletos estão todos em templates/docs/ no plugin; copie-os para docs/ no projeto e preencha. Os gateways não liberam a passagem enquanto os [TODO] no esqueleto não forem preenchidos.

Ferramentas (incluídas no plugin, chamadas diretamente com Python)

Diretório de scripts = raiz do plugin em scripts/. Se não tiver certeza do caminho absoluto, primeiro execute codex plugin list para encontrar o caminho do plugin.

Propósito	Comando
Inicializar estado	python scripts/omni_state.py init --root . --engine godot --platforms web,android
Verificar progresso do estágio	python scripts/omni_state.py status --root .
Validar um estágio	python scripts/omni_state.py check --root . --stage gdd
Avançar estágio (com gateway)	python scripts/omni_state.py advance --root .
Gerar arte placeholder (somente para validar pipeline)	python scripts/gen_placeholder_art.py --manifest assets/manifest.json --root .
Criar roadmap	Copie templates/docs/07-production-roadmap.md para docs/
Planejamento e revisão de Sprint	Copie templates/docs/08-sprint-review.md, registre a versão integrada, testes e feedback a cada ciclo
Revisão de gateway	Copie templates/docs/09-milestones.md, registre as avaliações G1–G5 e pós-lançamento
Pós-processamento de arte	python scripts/process_art.py --in raw/x.png --out assets/art/x.png --size 256x64 --key-color "#FFFFFF" --check-nine --nine-slice 24
Corte de quadros de animação por IA	python scripts/split_sprite_sheet.py --input raw/sheet.png --cols 4 --rows 2 --fps 12 --loop --out-dir assets/animation/run --backup-dir doc/temp/run-frames
Imagem / GIF por IA	python scripts/gen_ai_image.py --prompt "single game icon" --format png --out assets/art/icon.png --backup-dir doc/temp --dry-run
Efeito sonoro por IA	python scripts/gen_ai_audio.py sfx --prompt "short sci-fi pickup" --duration 1 --out assets/audio/pickup.mp3
Música por IA	python scripts/gen_ai_audio.py music --prompt "gentle space exploration" --duration 30 --instrumental --out assets/audio/main.mp3
Gerar BGM (chiptune)	python scripts/gen_music.py --style upbeat --out assets/audio/bgm_main.wav --tempo 132 --bars 16
Sintetizar efeito sonoro	python scripts/gen_sfx.py --preset hit --out assets/audio/sfx_hit.wav
Compressão de áudio	python scripts/compress_audio.py --dir assets/audio --check
Empacotar atlas	python scripts/pack_atlas.py --input assets/art/ui --out-sheet assets/art/ui_atlas.png --out-data assets/art/ui_atlas.json
Validar lista de assets	python scripts/validate_assets.py --manifest assets/manifest.json --root .
Inspeção final antes do release	python scripts/validate_assets.py --manifest assets/manifest.json --final --strict-license
Verificação/validação de build	python scripts/build_check.py --project . → Adicione --run para build real

Ordem de Execução

0. Estrutura do Projeto no Disco

cp -r <plugin>/templates/godot4/* .        # ou unity / cocos3
mkdir -p docs assets/art assets/audio doc/temp
cp <plugin>/templates/docs/*.md docs/
cp <plugin>/templates/assets-manifest.json assets/manifest.json
python scripts/omni_state.py init --root . --engine godot --platforms web,android
python scripts/omni_state.py checkpoint --root . --task "Inicialização" --next "Escrever brief"

Antes de começar, leia .omni/active.md (se existir): ele contém a tarefa atual e os pontos de bloqueio da sessão anterior; é mais confiável do que o histórico da conversa após compressão ou troca de sessão.

Os três templates têm níveis de maturidade diferentes; você deve informar o usuário honestamente:

Template	Status	Passos manuais necessários
godot4	Executável diretamente (testado: importado + cena principal funciona)	Nenhum
unity	Abre, mas a cena precisa ser gerada	Menu Tools ▸ Omni ▸ Create Main Scene
cocos3	Código e configuração prontos	Criar nova cena → anexar GameRoot ao Canvas → definir como cena inicial

1. Inicialização e Conceito (G1)

Esclareça cinco pontos: experiência principal, prioridade de plataforma, escopo do MVP, monetização e conformidade, assets existentes e engine. Preencha docs/00-brief.md e docs/01-gdd.md, registre hipóteses a serem validadas e a decisão Go / No-Go. Estime orçamento e marcos com base no tamanho da equipe e anote as incertezas.

2. GDD

Delegue para game-narrative-designer. Exigências: valores numéricos específicos, cada item deve ser verificável, incluir uma seção separada sobre "requisitos para a engine". Após preencher, execute advance.

3. Pré-produção e Vertical Slice (G2)

Delegue de acordo com a engine para cocos-engineer, unity-engineer ou godot-engineer. Exigências: primeiro forneça dados de análise, depois otimizações; as configurações de build por plataforma devem ser específicas, incluindo formatos de textura e estratégias de empacotamento. Implemente um protótipo jogável o mais cedo possível para validar o loop central.

4. Arte (Assets Finais)

Delegue para game-art-director produzir docs/03-art.md e assets/manifest.json, e execute de acordo com a skill game-art-production:

1. Primeiro, crie a bíblia de estilo docs/art-style-bible.md: um texto âncora de estilo fixo + paleta de cores + itens proibidos
2. Gere assets um por um: use a ferramenta de imagem da sessão atual ou uma API de IA configurada, gere variações conforme necessário; solicite saída com fundo transparente quando necessário, respeite as regras de backup de imagens do projeto. Para animações, use game-animation-production para gerar GIFs ou sprite sheets e verifique o corte de quadros.
3. Pós-processe para as especificações:

python scripts/process_art.py --in raw/btn_raw.png --out assets/art/ui/ui_btn_primary.png \
  --size 256x64 --mode fit --key-color "#FFFFFF" --key-tolerance 14 \
  --nine-slice 24 --check-nine

4. Registre no manifest: tier: "final" + source + license + commercial_ok + ai_generated
5. Inspeção final: validate_assets.py --final --strict-license

Antes do G2, crie uma vertical slice completa, mas de escopo pequeno, integrando programação, design, arte e áudio na engine alvo; teste na prática a qualidade visual, o pipeline de assets, o build e o desempenho. Não programe a produção em massa com base em uma demo antes que a fatia vertical prove que a abordagem é repetível e o custo é aceitável. Os scripts de estado no plugin verificam apenas documentos; eles não validam este gateway para você.

5. Produção de Áudio

Delegue para game-audio-designer produzir docs/04-audio.md e, de acordo com a skill game-audio-production, escolha uma rota:

• Rota A (Gerado por IA): priorize ferramentas de geração de áudio disponíveis atualmente; ou use gen_ai_audio.py com a API ElevenLabs, veja detalhes em game-audio-production. As chaves, permissões, custos e licenças do serviço devem ser esclarecidos com antecedência.
• Rota B (8-bit, offline e gratuito):

python scripts/gen_music.py --style upbeat --out assets/audio/bgm_main.wav --tempo 132 --bars 16
python scripts/gen_sfx.py --list
python scripts/gen_sfx.py --preset hit --out assets/audio/sfx_hit.wav

• Compressão obrigatória: python scripts/compress_audio.py --dir assets/audio --bitrate 96k; se não houver ffmpeg, siga as instruções do script e use a compressão na importação da engine (Godot QOA / Unity Vorbis / Cocos mp3-ogg)
• Diferenças de plataforma devem ser documentadas: jogos em miniaplicativos precisam ser reproduzidos após interação, silencioso no iOS, política de reprodução automática na Web

Produção em Massa (G3) e Ciclo de Sprint

Somente após o G2 ser aprovado, planeje a produção em massa com base na capacidade real demonstrada pela vertical slice. Preencha docs/07-production-roadmap.md; a cada ciclo, selecione um objetivo verificável do backlog de design, programação, arte ou áudio, e use docs/08-sprint-review.md para registrar o escopo, responsável, build integrado, testes, feedback e retrospectiva. O ciclo deve ser definido de acordo com a capacidade da equipe, geralmente 2–4 semanas, podendo ser mais curto para equipes pequenas. A cada ciclo, revise com uma versão jogável real; trabalho que falhou ou não foi integrado deve ser claramente marcado.

6. Testes e Polimento (G4 / G5)

Delegue para game-qa-engineer elaborar o plano de testes. Após o Alpha, entre em Beta com conteúdo congelado; por padrão, novas funcionalidades são proibidas. Se for absolutamente necessário adicionar uma funcionalidade, registre o impacto no cronograma, escopo de teste e gateways, e reavalie. Antes de preparar o Gold, você DEVE executar um build real e dar uma olhada na tela:

python scripts/build_check.py --project .                            # Primeiro veja o comando
python scripts/build_check.py --project . --run --capture g4-beta     # Build + iniciar + capturar tela
python scripts/omni_state.py check --root . --stage qa --evidence     # Valida documento + evidências juntos
python scripts/omni_state.py advance --root . --to release            # Sem evidências, será bloqueado

As capturas de tela ficam em docs/qa/evidence/<nome>/, e receipt.json registra o sha256 dos arquivos cobertos. Qualquer alteração posterior tornará essa evidência expirada — capturas expiradas não contam como evidência; tire uma nova.

A análise não significa que o build funciona; funcionar não significa que a tela está correta: texto cortado, painéis estourando, elementos que não aparecem — só a imagem revela. Unity e Cocos não têm capacidade integrada de captura de tela não supervisionada; o script retornará NOT ASSESSED honestamente. Nesse caso, use --capture-cmd para fornecer um comando, ou afirme claramente "a tela não foi verificada"; não trate como aprovado. Se precisar avançar mesmo assim, use --no-evidence, mas ao entregar, informe que a tela não foi vista.

Se o build falhar, entregue o log exatamente como está para o engenheiro da engine correspondente; não tente adivinhar. Registre os testes reais, compatibilidade de plataforma e evidências dos pacotes candidatos; convide o responsável para revisar antes de confirmar Gold / Release. O comando advance não aprova automaticamente Alpha, Beta, Gold ou a assinatura de release.

Use docs/09-milestones.md para registrar os responsáveis, caminhos de evidência e decisões para G1–G5. Alpha = funcionalidades completas, Beta = conteúdo congelado, Gold = candidato a release para as plataformas alvo aprovado na revisão; esses status precisam ser confirmados manualmente com base em evidências reais, não podem ser inferidos a partir do estágio do documento.

7. Lançamento e Operação

Delegue para game-release-operator produzir docs/06-release.md. Todos os números de plataforma devem incluir "consulte a versão oficial mais recente" e um ponto de verificação.

Após o lançamento, registre problemas em produção, métricas de crash/negócio, feedback dos jogadores e status de hotfix; realimente o backlog e o roadmap da próxima versão. Inicie o próximo ciclo de Sprint conforme necessário; done significa apenas que os artefatos deste ciclo estão concluídos, não que a operação deve parar.

Ao Entregar para o Usuário

## Estágio Atual
Estágio em state.json + status do gateway

## Artefatos Produzidos
Lista de docs/ e assets/, destacando quantos ainda são placeholder

## Build e Evidências
Resultado do build_check: sucesso / falha / não executado; se há capturas de tela, quais arquivos elas cobrem, se estão expiradas

## Lacunas Reais Incompletas
Informe claramente o que ainda precisa ser feito por humanos

Regras de Ferro

1. Não pule estágios: advance vai bloquear; não contorne; pular significa uma entrega não confiável
2. Documentos não são o fim: após o estágio tech, você DEVE realmente produzir arquivos de código e recursos; entregar apenas documentos não conta como concluído
3. Build deve ser executado de verdade: no estágio qa, sem um resultado de build, não é permitido entrar em release; o script de estado não bloqueia automaticamente, é necessário verificação manual
4. Rascunho não conta como concluído: recursos com tier: "draft" não podem entrar no release; a inspeção final --final vai bloquear. Ao entregar, informe quantos rascunhos ainda existem
5. Números com origem: limites de tamanho de pacote, capacidades da engine — sempre marque a versão e a forma de verificação
6. Cada Sprint entrega um build jogável: o número de tarefas concluídas não substitui build, testes e revisão
7. Gateway depende de evidências de revisão: omni_state.py verifica apenas títulos de documentos e TODOs; não pode validar automaticamente jogabilidade, build, dispositivos ou aprovação de publicação
8. Produto antes de narrativa: se uma função delegada afirma ter escrito um arquivo, verifique se o caminho existe. Se não existir, é PHASE FAILED — não avance, não resuma como concluído. Um discurso fluido "eu vou..." não é evidência; o arquivo no disco é
9. Após qa, deve haver captura de tela: sem uma captura de tela utilizável em docs/qa/evidence/, não é permitido entrar em release; advance vai bloquear. NOT ASSESSED não é aprovação

O que este Pipeline NÃO Faz

• Modelos 3D e animação esquelética: este pipeline foca em 2D; os resultados quadro a quadro da IA precisam ser verificados e podem exigir ajustes.
• Música e efeitos sonoros por IA: requer ferramentas de geração disponíveis ou um serviço externo com permissão; síntese procedural não equivale a geração por IA.
• Fontes comerciais: apenas fontes open source com licença OFL; fontes comerciais exigem que o usuário compre a licença.
• Assinar, publicar ou aprovar por você: só fornece listas e cronogramas; não pode clicar nos botões de back-end.
• Validação de compatibilidade em dispositivos reais: requer dispositivos reais.
• Garantir que o código não tenha bugs: build bem-sucedido não significa funcionalidade correta; funcionalidade correta não significa que o jogo é divertido.