Gerar Sprites 2D

O que Gerar Sprites 2D faz?

Crie o menor pacote de assets que o jogo precisa, no seu tamanho real de exibição, câmera e estilo. A lógica do jogo (colisão, dano, tempo) permanece independente da arte.

Quando usar

• Um personagem, criatura, adereço, item, ícone ou efeito visual (FX) é necessário como uma imagem mestre estática, uma folha de sprites ou clipes.
• Quadros já existem (gerados, pintados, desenhados por código) e precisam de clipes, paletas ou uma exportação para o motor.

Quando não usar

• Mapas, tiles, terreno, parallax ou placas de cena: generate2dmap.
• Animação de um personagem: aprove uma imagem mestre aqui, depois video2dsprite faz um clipe por ação (video-handoff.md).
• Arte desenhada por código que o usuário pediu: codeart2d. Apenas uma chamada de API ou CLI: generate2dmedia.

Verificação de capacidade (uma vez por sessão)

Execute python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json, onde <tools> lista as ferramentas de mídia na sua própria lista de ferramentas (image_gen, image_edit, image_to_video) ou none. O bloco ROUTES mostra quais chaves de API estão configuradas (sim ou não), a prontidão local e a ordem resolvida. Se encoding.stdout falhar, defina PYTHONUTF8=1.

Fonte de arte

A geração de imagem é a fonte de arte padrão para personagens, criaturas, adereços, ícones e efeitos visuais. Registre-a como art_source (api, host_image, existing ou code apenas sob solicitação) e nomeie a rota na sua resposta. Uma rota que o usuário nomeie explicitamente vence.

1. API, quando uma chave está configurada: OpenAI (OPENAI_API_KEY), Google Gemini (GEMINI_API_KEY), xAI (XAI_API_KEY), BytePlus Seedream (ARK_API_KEY) ou fal.ai (FAL_KEY), no ambiente ou no arquivo de configuração do usuário (route-media.md). A chave configurada é o consentimento do proprietário, portanto não há pergunta por chamada.
2. Local: sua própria ferramenta de imagem (Codex image_gen, ferramenta nativa do Grok) quando você tiver uma, caso contrário o Codex CLI do usuário conectado, depois o Grok CLI.
3. codeart2d apenas quando o usuário pedir explicitamente por arte desenhada por código, ou quando route_media.py imprimir no-route (código de saída 3). Então diga "desenhado por código, sem modelo de imagem".

FX do tipo hibit são a única exceção: fx_pixelfx.py check os envia para o pixelfx quando o usuário o tem instalado (rota A, FX de terceiros desenhados por código, creditados e divulgados), caso contrário para a rota de imagem (rota B). Veja hibit.md.

Toda imagem passa por um comando: python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <novo>. Ele escolhe a rota nessa ordem e imprime uma linha JSON com route, artifact, sha256 e estimateUsd; resolve --kind image diz qual rota seria executada. Arte existente fornecida pelo usuário é sempre bem-vinda. Nunca afirme uma geração que não aconteceu; mantenha o prompt e o contrato e reporte uma capacidade ausente.

• Acabamento: HD é o padrão: cor total, alfa limpo, um registro e um redimensionamento de área pré-multiplicada para a altura do jogo. O acabamento pixel (uma paleta compartilhada, alfa binário, sem dither) é uma opção quando o usuário pede arte pixel; o acabamento hibit (arte plana sem contornos do modelo, depois uma paleta por personagem, um redimensionamento por voto majoritário e uma cor de contorno retirada da imagem) quando eles querem o visual hi-bit (hibit.md). Nunca peça a um modelo de imagem uma grade lógica de pixels; o visual pixel vem do acabamento.
• Personagens: aprove uma imagem mestre estática por personagem, depois anime-a com video2dsprite: um clipe de imagem-para-vídeo por ação, tudo a partir dessa mestre (sprite_set.py). Mantenha a altura do corpo de cada ação a partir da pose de descanso da mestre.
• Folhas são para FX, ícones e adereços (e quadros fornecidos pelo usuário), não para animação de personagens.

Imagem mestre (toda animação de personagem começa aqui)

Uma imagem mestre estática aprovada por personagem, depois um clipe de imagem-para-vídeo por ação a partir dela (video2dsprite); folhas são para FX, ícones e adereços. Texto: prompt-rules.md; comandos, enquadramento e master.json: master-still.md.

1. Especificação (--spec <json> e/ou flags): --name, --subject, --identity (longo e preciso), --facing left|right|front|back, --class hero|mob|boss|prop, --finish hd|pixel|hibit (HD padrão; pixel ou hibit apenas quando solicitado; hibit torna a imagem plana e sem contornos), --identity-ref (PRIMEIRA imagem, copiada exatamente), --style-ref (SEGUNDA: um sprite peer aprovado, apenas estilo e enquadramento), --key (padrão #FF00FF; verde ou azul para designs roxos e rosa).
2. Gerar: python "<skill-dir>/scripts/master_still.py" generate --spec <json> --takes 3 --output-dir <novo>. Cada take passa pelo generate2dmedia route_media.py (primeiro a chave da API, depois o daemon local); takes.png os mostra lado a lado. Código de saída 3 significa sem rota: diga isso; codeart2d é o fallback ("desenhado por código, sem modelo de imagem"). Com a ferramenta de imagem do host: execute master_still.py prompt e anexe as referências listadas nessa ordem.
3. Escolha olhando: identidade, facing, nada tocando uma borda, sem texto.
4. Corrija um quase-acerto por edição, nunca por re-roll: master_still.py edit --run <dir> --take N --change "<uma mudança>" --output-dir <novo> (ou --master <dir>).
5. Aprove: master_still.py approve --run <dir> --take N --output-dir <novo> (uma imagem de outro lugar: --still <png> --route <o que a fez>). Ele define a cor-chave na imagem, corta com uma margem de 6 px, redimensiona com LANCZOS para o enquadramento de classe em 1024x1024 (herói 788 px de altura, margem superior 138 px) e escreve master.png (opaco, key puro), master_rgba.png e master.json (generate2dsprite.master.v1).
6. As etapas de movimento leem master.json (identity_recap, facing, finish, class, framing, key, files, transform, route) e nunca remedecem a imagem; todo prompt de clipe começa com "O mesmo <identity_recap>".

Reporte a rota de master.json route. Um aviso FORGE_ROUTE_MEDIA_FAKE significa que a imagem não é uma geração real.

Notas do host

• Codex: image_gen é sua própria ferramenta de imagem; sem uma chave configurada, use-a e veja os resultados com view_image. Uma imagem feita nesta sessão que não está no projeto: python "<skill-dir>/../generate2dmedia/scripts/cli_media.py" adopt --codex-thread <id-da-thread> --output-dir <novo>, depois processe generated.png. codeart2d e generate2dmedia são explícitos: abra o SKILL.md deles quando esta skill rotear para lá.
• Claude Code: nenhum gerador de imagem embutido: route_media.py pega a API ou os CLIs locais. Veja cada PNG que você fizer com Read; execute ferramentas com Bash; <skill-dir> é ${CLAUDE_SKILL_DIR}.
• Grok: suas ferramentas nativas de imagem e vídeo são suas próprias ferramentas; use o esquema real delas.

Comandos

Execute cada ferramenta como uma linha única a partir da raiz do projeto do usuário: python "<skill-dir>/scripts/<ferramenta>.py" .... <skill-dir> é a pasta desta skill; skills irmãs ficam ao lado dela (<skill-dir>/../video2dsprite). Mantenha entradas e saídas dentro do projeto. Toda ferramenta escreve um novo --output-dir: ela recusa um existente, prepara ao lado e publica somente após suas verificações (--strict-qc / --strict não publica nada em caso de falha). Sucesso imprime uma linha JSON; erros imprimem error: ... e saem com código 1; erros de uso saem com código 2. Precisa de Python 3.10+, numpy e Pillow (scipy recomendado). --help lista todas as flags.

Planeje o asset

Registre identidade e referência, câmera e facing, estilo, tamanho de exibição do jogo, acabamento (HD por padrão, pixel sob solicitação), lista de ações e fases, loop ou one-shot, envelope de movimento, raiz compartilhada e formato de saída. Mantenha uma imagem mestre aceita e uma escala fonte-para-exibição por personagem; mobs não são mais altos que o herói a menos que planejado. Uma grade não é suavidade: espaçamento de poses, tempo, a costura do loop e o contato com o chão importam mais. Poses, pernas NEAR/FAR e tempo: animation-planning.md.

• Alfa: native_alpha mantém transparência real (um tabuleiro de xadrez pintado não é alfa); chroma_key usa magenta plano apenas quando o sujeito não tem nenhum; opaque mantém imagens inteiras (assemble_frames.py).
• Amostragem: lanczos ou um redimensionamento de área pré-multiplicada para arte gerada; nearest apenas para uma grade de pixels verificada. Uma pintura de alta resolução que parece pixel não é arte limpa de 32 px.
• Uma raiz compartilhada não é um fundo alfa-bbox por quadro: mantenha saltos intencionais, voo, balanço e recuo.

Gerar (rotas de imagem)

Escreva o prompt você mesmo (prompt-rules.md; grades, fases e predefinições em action-recipes.md). Anexe referências através de --reference (ou a entrada de imagem real da sua ferramenta); um caminho em prosa não é uma referência. Mantenha a imagem mestre aceita em toda geração e descreva fases absolutas, não edições encadeadas; uma correção é uma edição da imagem aprovada que nomeia a única mudança. Gere uma família de ações por vez e mantenha cortes largos, rastros e projéteis fora da folha do corpo. Verifique a rota real, o modelo e o tamanho retornado; nunca os afirme a partir do prompt.

Pipeline

Folhas (FX, ícones, adereços): sheet_qc.py spill na folha bruta, depois generate2dsprite.py process, depois sheet_qc.py frames, depois scale_frames.py, depois build_animation_clips.py, depois export_engine.py. Ações de personagens voltam do video2dsprite como clipes empacotados.

Necessidade	Rota
Planejar uma folha para uma ferramenta de imagem (aspecto, grade, guia, prompt)	plan_guide.py --frames N --cycle run --output-dir <novo>; anexe guide.png, cole prompt.txt. Escala fixa e linha dos pés: make_anchor_layout.py; quadro seguro vazio: make_layout_guide.py
Verificar uma folha bruta antes de fatiar	sheet_qc.py spill --input <folha> --rows R --cols C --output-dir <novo>; partes cruzadas significam regenerar com mais margem ou fatiar por propriedade, nunca um filtro de maior componente
Definir cor-chave, fatiar e registrar uma folha	generate2dsprite.py process --input <folha> --target asset --mode <modo> --rows R --cols C --output-dir <novo> --strict-qc (geometria v2; processing.md)
Arte pixel desenhada a M px fonte por px de arte	process --resampler nearest --logical-pixel M --pixel-scale N (apenas escalas inteiras)
Saltos, balanço ou recuo em um ponto de registro	process --scale-strategy registered (ou --anchor-px X,Y)
Escala de um personagem entre ações	process --write-scale-profile <p.json> na referência de base, depois --scale-profile <p.json> --max-profile-scale-drift 0.08
Tela não divide na grade; outra ordem de linhas	process --grid-rounding nearest ou --pad-to-grid; --direction-order down,up,left,right (modes.md)
Identidade, alternância NEAR/FAR, desvio, linhas de base	sheet_qc.py frames --sheet <folha> --rows R --cols C --cycle run --output-dir <novo>; um meio ciclo duplicado significa regenerar a segunda metade. Em quadros desenhados por código (art_source=code) identity_residual e torso_drift são consultivos
Tamanho do jogo em uma tela e raiz, nunca limitado	scale_frames.py --frames <pngs> --root-lock torso-x --row-baseline --emit-clips --ticks N --output-dir <novo>; ações posteriores adicionam --profile <primeiro>/scale-frames.json --action-padding L,T,R,B
Clipes com tempo, eventos, transições	build_animation_clips.py --manifest clips.json --output-dir <novo>; leia os lints e review/ (frames-and-clips.md)
Quadros inteiros ou um loop de cena (sem definição de cor-chave)	assemble_frames.py (--key chroma, --slice ownership; --loop-overlap K --ambient apenas para loops ambientes)
Paleta compartilhada, travas, variantes, flicker (acabamento pixel)	palette_tool.py build, apply, lock, quantize-seq, variants, luts; grade lógica estrita: pixel_reduce.py (palette-and-pixels.md)
Exportação para motor	export_engine.py --clips <animation-clips.json> --target all --output-dir <novo>; Sprite3D: --target godot-sprite3d --world-height <unidades> (engine-export.md)
Reproduzir clipes em um jogo (passo, hit-stop, transições)	runtime-integration.md
Sprites, rigs ou FX desenhados por código, apenas sob solicitação	codeart2d render_pixelspec.py, rig_animate.py ou fx_build.py com --build-clips (nunca process), depois export_engine.py; divulgue-os como desenhados por código
FX para um jogo hibit	fx_pixelfx.py check escolhe a rota (uma rota que o usuário nomeia vence). A, pixelfx instalado (recomendado): fx_pixelfx.py render --pixelfx <checkout> --id <efeito> --ramp ... --snap <palette.json>, pixelfx por Patch (MIT, um projeto separado que o usuário clona), envie CREDITS.txt e divulgue como desenhado por código pelo pixelfx. B, caso contrário: uma folha FX 2x2 da rota de imagem, process --scale-strategy registered --cell-size 512, depois hibit_fx.py pixelize --palette <palette.json> (hibit.md)

Aceitação

• Revise no tamanho do jogo: silhueta e identidade, contato e voo, costura do loop ou recuperação one-shot, alfa sobre claro e escuro, extremidades, escala entre ações, raiz e colisor.
• Cite números para alegações de qualidade: pipeline-meta.json matte.qa (um aviso key_ring_spill: adicione --despill-radius 1 ou --key-quality soft), sheet-qc.json, os lints do construtor de clipes. QC numérico encontra sintomas; nunca aprova anatomia ou movimento.
• Reporte toda verificação WARN ou FAIL textualmente (id, valor, limite, arquivos) de cada envelope de QA publicado; nunca diga "todas as verificações passaram" quando qualquer envelope publicado tiver um warn.
• Entregue arte fonte aceita, quadros ou clipes de runtime, pré-visualização, prompt e proveniência (rota, modelo, estimateUsd), QA e limites restantes. Mantenha o último pacote aceito ao revisar.

Referências

processing.md (flags de processo, switches legados), modes.md, prompt-rules.md, action-recipes.md, frames-and-clips.md, palette-and-pixels.md, engine-export.md, runtime-integration.md, animation-planning.md, master-still.md, [video-handoff.md](reference