video2dsprite

Video2dsprite (Grok Build apenas)

Converta uma imagem base de personagem 2D em sprites de animação densos usando as ferramentas de vídeo nativas do Grok Build.

Ambiente App-builder / Grok

Item	Valor
Diretório da skill	.grok/skills/video2dsprite/
Scripts	python3 .grok/skills/video2dsprite/scripts/video2dsprite.py …
Ferramentas de vídeo	imagine_image_to_video — anima um file_path base (verificar se existe)
Inspecionar	read_file nos stills/frames; reportar caminhos dos vídeos
Dependências	ffmpeg + Pillow + numpy (pré-instalados na imagem do app-builder)
Pasta de saída	assets/sprites/video2dsprite/<nome>/ dentro de /workspace
Padrão	Preferir generate2dsprite para heróis de produção; este é o caminho de movimento mais denso

still base → imagine_image_to_video (movimento no lugar) → extrair frames → chroma key → amostrar/normalizar → strip / grid / GIF

Gatilho de plataforma (leia primeiro)

Runtime	Suportado?
Grok Build (xAI)	Sim — requer um gerador de imagem + uma ferramenta imagem→vídeo
Codex / Claude / outros agentes	Não — não possuem as ferramentas de vídeo do Grok. Informe ao usuário que esta skill é apenas para Grok Build e ofereça $generate2dsprite como alternativa

Gatilho pela capacidade, não pelo nome exato da ferramenta. Geração de imagem aparece como imagine_text_to_image / imagine_image_to_image; vídeo como imagine_image_to_video ou (legado) generate_video. Use o par que sua lista de ferramentas tiver. Pare e explique apenas quando não houver nenhuma ferramenta imagem→vídeo. Não simule movimento com frames desenhados por código.

Esta skill é um caminho opcional de movimento mais denso. Ela não substitui $generate2dsprite:

Use $generate2dsprite quando…	Use $video2dsprite quando…
Folhas de pixel nítidas, grids fixos, heróis com identidade crítica	Usuário quer poses intermediárias mais densas / loops com sensação mais suave
Folhas de corpo de ataque/feitiço, pacotes de props, atlas de engine	Experimentando com movimento de corrida/caminhada/parado originado de vídeo
Padrão de produção para a maioria dos sprites de jogo	Usuário explicitamente pede vídeo → frames → sprites

O vídeo suaviza pixels, desvia a identidade e deixa franjas de chroma. Sempre faça controle de qualidade; para heróis de produção, prefira $generate2dsprite a menos que o usuário queira o visual de vídeo.

Parâmetros

Inferir da solicitação do usuário:

• subject: descrição do personagem/criatura, ou caminho de um still existente
• action: run | walk | idle | attack | frase de movimento personalizada
• view: geralmente side (side-scroller). topdown é mais difícil — avisar e manter câmera travada
• duration: 6 (padrão) ou 10 segundos
• frame_counts: quais conjuntos mais densos exportar, padrão 8,16,24,48
• cell_size: célula do sprite de saída, padrão 128
• anchor: feet (padrão para locomoção lateral) | center
• bg: sólido #FF00FF (obrigatório para chroma)
• name: slug de saída
• out_dir: pasta de trabalho (padrão ./sprites/video2dsprite/<nome>/ ou relativo ao projeto)

Regras do agente

1. Apenas Grok. Recusar em runtimes que não sejam Grok com uma breve explicação + alternativa $generate2dsprite.
2. Still → vídeo, nunca texto-para-vídeo sozinho. Criar o frame 1 como um still limpo com imagine_text_to_image (a partir de um prompt, ou de um file_path de referência). Então chamar imagine_image_to_video com o file_path desse still.
3. Movimento no lugar. Prompt para correr/caminhar no lugar voltado para uma direção fixa. Sem panorâmica de câmera, sem rolagem de fundo, sem mudança de cena. O sujeito permanece aproximadamente centralizado.
4. Fundo magenta sólido na base e preservado no prompt de vídeo (#FF00FF / magenta puro). Obrigatório para chroma flood-fill.
5. Não inventar arte com PIL/Canvas. A arte base vem de imagine_text_to_image ou de um still do usuário/local. Scripts apenas pós-processam.
6. Não colocar saídas experimentais no jogo a menos que o usuário peça para integrar.
7. Preferir um ciclo de locomoção para uso no jogo. Amostragem densa em um clipe completo de 6s com múltiplos ciclos é aceitável para prévias; para folhas de engine, opcionalmente re-amostrar um único ciclo (12–16 frames) após controle visual de qualidade.
8. Reportar caminhos absolutos do vídeo, frames limpos, strips e GIFs de pré-visualização quando concluído.

Fluxo de trabalho

1. Planejar

Escolher a execução mais útil e menor:

• Loop de corrida/caminhada lateral → esta skill
• Kit de herói com múltiplas ações → ainda usar $generate2dsprite por ação; usar vídeo apenas para locomoção se solicitado
• Pacotes de FX / projectile / prop → $generate2dsprite, não vídeo

Criar:

<out_dir>/
  base/
  video/
  frames-raw/
  frames-clean/
  sprite/          # conjunto padrão de 8 frames + conjuntos mais densos x16/x24/x48
  prompt-used.txt
  pipeline-meta.json
  README.txt

2. Construir o still base

Opções:

• A. Sprite existente: ler a imagem, compor sobre #FF00FF sólido se necessário, então passar esse caminho do sandbox para imagine_image_to_image / imagine_image_to_video
• B. Novo personagem: imagine_text_to_image com fundo magenta sólido, corpo inteiro, visão lateral, centralizado
• C. Combinar referência: imagine_image_to_image com o file_path da referência, movendo-o para magenta e preservando a identidade

Requisitos da base:

• Corpo inteiro visível, margem magenta generosa
• Visão lateral para corrida/caminhada (perfil ou 3/4 lateral), pés próximos ao terço inferior
• Mesmo estilo de arte do restante do projeto quando existir uma referência
• Sem texto, UI, marca d'água ou segundo personagem

Copiar o file_path retornado e salvar como <out_dir>/base/<nome>-base.png; manter o file_path base para a chamada de vídeo.

Escrever o prompt exato da imagem em prompt-used.txt.

3. Animar com imagine_image_to_video

Chamar imagine_image_to_video do Grok:

• caminho de origem: <file_path do still base> (caminho do sandbox retornado por T2I / I2I)
• duration: 6 (padrão) ou 10
• resolution_name: 480p a menos que o usuário peça 720p
• prompt: uma curta tomada no presente (ver references/prompt-rules.md)

Restrições obrigatórias de movimento no prompt:

• Sujeito corre/caminha no lugar (estilo esteira)
• Câmera travada — sem panorâmica, zoom ou órbita
• Fundo permanece magenta sólido liso
• Identidade, roupa, paleta estáveis durante toda a cena
• Apenas ação contínua única

Copiar o file_path do vídeo retornado para <out_dir>/video/<nome>-<duração>s.mp4.

Se as ferramentas de vídeo estiverem indisponíveis, parar (gatilho de plataforma).

4. Extrair + chroma + amostrar (script local)

Executar o processador (ffmpeg + Pillow + numpy):

python3 .grok/skills/video2dsprite/scripts/video2dsprite.py process \
  --video <out_dir>/video/<nome>-6s.mp4 \
  --out-dir <out_dir> \
  --name <nome> \
  --frame-counts 8,16,24,48 \
  --cell-size 128 \
  --body-height 100 \
  --foot-y 118 \
  --fps 0

Notas:

• --fps 0 = extrair cada frame decodificado (usar o fps de origem)
• Chroma flood-fill magenta a partir dos cantos + despill
• Amostragem uniforme para cada contagem em --frame-counts
• Células normalizadas pelos pés, strip horizontal, grid, GIF de loop por contagem

Opcional: apenas re-amostrar conjuntos mais densos a partir de frames limpos existentes:

python3 .grok/skills/video2dsprite/scripts/video2dsprite.py sample \
  --clean-dir <out_dir>/frames-clean \
  --out-dir <out_dir> \
  --frame-counts 16,24,48 \
  --cell-size 128

5. Controle de qualidade

Verificar visualmente:

• GIF de pré-visualização faz loop sem saltos grandes
• Magenta removido (sem blocos rosa sólidos); franjas aceitáveis ou re-chavear
• Pés permanecem em uma linha de base estável (sem pulos de corte ruim)
• Identidade aproximadamente estável (rosto/roupas não estão mudando a cada frame)
• Ação está no lugar (não deslizando para fora do frame)
• Para uso no jogo: escolher uma contagem (geralmente 16 ou 24) ou cortar um ciclo verdadeiro

Se a identidade desviar muito ou os pixels estiverem muito suaves, voltar para $generate2dsprite para folhas de produção e manter o conjunto de vídeo apenas como referência de movimento.

6. Entregar

Reportar caminhos apenas (a menos que o usuário peça para integrar no jogo):

• Vídeo: video/*.mp4
• Sprites densos: sprite/x16|x24|x48/
• Strips / grids / GIFs: sprite/run-strip-N.png, run-grid-N.png, run-preview-N.gif
• Meta: pipeline-meta.json

Não modificar código do jogo a menos que solicitado.

Padrões

• Duração: 6s
• Ação: corrida lateral no lugar, voltado para a direita
• Contagens de exportação: 8, 16, 24, 48
• Célula: 128², altura do corpo ~100, pés em y≈118
• Fundo: #FF00FF
• Preferir imagine_image_to_video com um único ativo em vez de múltiplas referências (compor múltiplas referências com imagine_text_to_image primeiro se necessário)

Compensações (informar o usuário uma vez)

Prós: intermediários mais densos → geralmente parece mais suave que 4–8 poses geradas discretas. Contras: pixels mais suaves, deriva de identidade, franja de chroma, clipes de 6s com múltiplos ciclos não são um loop perfeito único, ativos mais pesados. Regra prática: 8→16→24 geralmente ganha suavidade; 48 frequentemente tem retornos decrescentes; 145 frames brutos são para amostragem, não para todos em tempo de execução.

Recursos

• references/prompt-rules.md — prompts de still base + vídeo
• references/pipeline.md — layout de pastas, ffmpeg, estratégia de amostragem
• scripts/video2dsprite.py — extrair, chroma, normalizar, exportar

Relação com outras skills

• $generate2dsprite — pipeline primário de folhas (Codex e Grok quando houver geração de imagem)
• $generate2dmap — mapas; não usado aqui
• $video2dsprite — exclusivo do Grok Build caminho de densificação de movimento
• $game-asset-core / $game-animation-frames — leis de loop/flip-test/motion e padrões prontos para engine; ainda usar os scripts desta skill para execução no sandbox (base magenta + chroma), não uma cor de fundo livre