Video2dsprite (solo para Grok Build)

¿Qué hace Video2dsprite (solo para Grok Build)?

Convierte una imagen base de un personaje 2D en sprites de animación densos usando las herramientas nativas de video de Grok Build.

Entorno de App-builder / Grok

Elemento	Valor
Directorio de la habilidad	.grok/skills/video2dsprite/
Scripts	python3 .grok/skills/video2dsprite/scripts/video2dsprite.py …
Herramientas de video	imagine_image_to_video — animar una file_path base (verificar que existe)
Inspeccionar	read_file sobre imágenes fijas/fotogramas; reportar rutas de los videos
Dependencias	ffmpeg + Pillow + numpy (preinstalados en la imagen de app-builder)
Directorio de salida	assets/sprites/video2dsprite/<nombre>/ dentro de /workspace
Predeterminado	Preferir generate2dsprite para héroes de producción; esta es la ruta de movimiento más denso

imagen base fija → imagine_image_to_video (movimiento en el lugar) → extraer fotogramas → croma → muestrear/normalizar → tira / cuadrícula / GIF

Plataforma (leer primero)

Entorno	¿Soportado?
Grok Build (xAI)	Sí — requiere un generador de imágenes + una herramienta de imagen→video
Codex / Claude / otros agentes	No — carecen de las herramientas de video de Grok. Informar al usuario que esta habilidad es solo para Grok Build y ofrecer $generate2dsprite como alternativa

Actuar según la capacidad, no el nombre exacto de la herramienta. La generación de imágenes aparece como imagine_text_to_image / imagine_image_to_image; el video como imagine_image_to_video o (heredado) generate_video. Usar el par que tenga la lista de herramientas. Detenerse y explicar solo cuando no se tenga ninguna herramienta de imagen→video. No fingir movimiento con fotogramas dibujados mediante código.

Esta habilidad es una ruta opcional de movimiento más denso. No reemplaza a $generate2dsprite:

Usar $generate2dsprite cuando…	Usar $video2dsprite cuando…
Hojas de sprites nítidas, cuadrículas fijas, héroes con identidad crítica	El usuario desea poses intermedias más densas / bucles de sensación más suave
Hojas de cuerpo de ataque/lanzamiento, paquetes de accesorios, atlas de motor	Experimentar con movimiento de carrera/caminata/inactivo basado en video
Predeterminado de producción para la mayoría de sprites de juegos	El usuario pide explícitamente video → fotogramas → sprites

El video suaviza los píxeles, desvía la identidad y deja restos de croma. Siempre hacer control de calidad; para héroes de producción, preferir $generate2dsprite a menos que el usuario quiera el aspecto de video.

Parámetros

Inferir a partir de la solicitud del usuario:

• subject: descripción del personaje / criatura, o ruta a una imagen fija existente
• action: run (correr) | walk (caminar) | idle (inactivo) | attack (atacar) | frase de movimiento personalizada
• view: normalmente side (lateral, para scroll lateral). topdown (vista superior) es más difícil — advertir y mantener la cámara fija
• duration: 6 (predeterminado) o 10 segundos
• frame_counts: conjuntos densos a exportar, predeterminado 8,16,24,48
• cell_size: tamaño de celda del sprite de salida, predeterminado 128
• anchor: feet (pies, predeterminado para locomoción lateral) | center
• bg: sólido #FF00FF (requerido para croma)
• name: slug de salida
• out_dir: carpeta de trabajo (predeterminado ./sprites/video2dsprite/<nombre>/ o relativo al proyecto)

Reglas del agente

1. Solo Grok. Rechazar en entornos que no sean Grok con una breve explicación + alternativa $generate2dsprite.
2. Imagen fija → video, nunca texto a video solo. Crear el fotograma 1 como una imagen fija limpia con imagine_text_to_image (a partir de un prompt, o de una file_path de referencia). Luego llamar a imagine_image_to_video con la file_path de esa imagen fija.
3. Movimiento en el lugar. Solicitar carrera/caminata en el lugar mirando en una dirección fija. Sin paneo de cámara, sin desplazamiento de fondo, sin cambio de escena. El sujeto permanece aproximadamente centrado.
4. Fondo magenta sólido en la imagen base y preservado en el prompt de video (#FF00FF / magenta puro). Requerido para el croma de relleno por inundación.
5. No inventar arte con PIL/Canvas. El arte base proviene de imagine_text_to_image o de una imagen fija del usuario/local. Los scripts solo realizan postprocesamiento.
6. No colocar salidas experimentales en el juego a menos que el usuario lo solicite para integrar.
7. Preferir un ciclo de locomoción para uso en juegos. El muestreo denso en un clip completo de 6s con múltiples ciclos es aceptable para previsualizaciones; para hojas de motor, opcionalmente remuestrear un solo ciclo (12–16 fotogramas) después del control de calidad visual.
8. Reportar rutas absolutas del video, fotogramas limpiados, tiras y GIFs de previsualización al finalizar.

Flujo de trabajo

1. Planificar

Elegir la ejecución más pequeña útil:

• Bucle de carrera/caminata lateral → esta habilidad
• Kit de héroe con múltiples acciones → seguir usando $generate2dsprite por acción; usar video solo para locomoción si se solicita
• Paquetes de FX / proyectiles / accesorios → $generate2dsprite, no video

Crear:

<out_dir>/
  base/
  video/
  frames-raw/
  frames-clean/
  sprite/          # conjunto predeterminado de 8 fotogramas + conjuntos más densos x16/x24/x48
  prompt-used.txt
  pipeline-meta.json
  README.txt

2. Construir la imagen base

Opciones:

• A. Sprite existente: leer la imagen, componer sobre fondo #FF00FF sólido si es necesario, luego pasar esa ruta del sandbox a imagine_image_to_image / imagine_image_to_video
• B. Nuevo personaje: imagine_text_to_image con fondo magenta sólido, cuerpo completo, vista lateral, centrado
• C. Coincidir referencia: imagine_image_to_image con la file_path de referencia, colocándolo sobre magenta y preservando la identidad

Requisitos de la imagen base:

• Cuerpo completo visible, margen magenta generoso
• Vista lateral para carrera/caminata (perfil o 3/4 lateral), pies cerca del tercio inferior
• Mismo estilo artístico que el resto del proyecto cuando exista una referencia
• Sin texto, UI, marca de agua ni segundo personaje

Copiar la file_path devuelta y guardarla como <out_dir>/base/<nombre>-base.png; mantener la file_path base para la llamada de video.

Escribir el prompt de imagen exacto en prompt-used.txt.

3. Animar con imagine_image_to_video

Llamar a imagine_image_to_video de Grok:

• ruta de origen: <file_path de la imagen base> (ruta del sandbox devuelta por T2I / I2I)
• duration: 6 (predeterminado) o 10
• resolution_name: 480p a menos que el usuario pida 720p
• prompt: una toma corta en tiempo presente (ver references/prompt-rules.md)

Restricciones de movimiento obligatorias en el prompt:

• El sujeto corre/camina en el lugar (estilo cinta de correr)
• Cámara fija — sin paneo, zoom ni órbita
• El fondo permanece plano magenta sólido
• Identidad, vestimenta, paleta estables durante toda la toma
• Solo una acción continua

Copiar la file_path del video devuelto a <out_dir>/video/<nombre>-<duracion>s.mp4.

Si las herramientas de video no están disponibles, detenerse (restricción de plataforma).

4. Extraer + croma + muestrear (script local)

Ejecutar el procesador (ffmpeg + Pillow + numpy):

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

Notas:

• --fps 0 = extraer cada fotograma decodificado (usar fps de origen)
• Relleno por inundación magenta desde las esquinas + despill
• Muestreo uniforme para cada conteo en --frame-counts
• Celdas normalizadas por pies, tira horizontal, cuadrícula, GIF de bucle por conteo

Opcional: solo remuestrear conjuntos más densos a partir de fotogramas limpios 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. Control de calidad

Verificar visualmente:

• El GIF de previsualización hace bucle sin cambios bruscos
• El magenta ha desaparecido (sin bloques rosa sólido); los bordes sobrantes son aceptables o re-aplicar croma
• Los pies permanecen en una línea base estable (sin saltos por recorte incorrecto)
• La identidad es aproximadamente estable (cara/ropa no cambian en cada fotograma)
• La acción es en el lugar (no deslizándose fuera del encuadre)
• Para uso en juegos: elegir un conteo (a menudo 16 o 24) o recortar un ciclo verdadero

Si la identidad se desvía mucho o los píxeles son demasiado suaves, recurrir a $generate2dsprite para las hojas de producción y mantener el conjunto de video solo como referencia de movimiento.

6. Entregar

Reportar solo las rutas (a menos que el usuario solicite integrar en un juego):

• Video: video/*.mp4
• Sprites densos: sprite/x16|x24|x48/
• Tiras / cuadrículas / GIFs: sprite/run-strip-N.png, run-grid-N.png, run-preview-N.gif
• Meta: pipeline-meta.json

No modificar el código del juego a menos que se solicite.

Valores predeterminados

• Duración: 6s
• Acción: carrera lateral en el lugar, mirando a la derecha
• Conteos de exportación: 8, 16, 24, 48
• Celda: 128², altura del cuerpo ~100, pies en y≈118
• Fondo: #FF00FF
• Preferir imagine_image_to_video de un solo activo sobre múltiples referencias (componer múltiples referencias con imagine_text_to_image primero si es necesario)

Compensaciones (informar al usuario una vez)

Ventajas: intermedias más densas → a menudo se sienten más suaves que 4–8 poses generadas discretamente.
Desventajas: píxeles más suaves, deriva de identidad, bordes de croma, clips de 6s con múltiples ciclos no son un bucle perfecto único, activos más pesados.
Regla general: 8→16→24 generalmente gana suavidad; 48 suele tener rendimientos decrecientes; 145 fotogramas sin procesar son para muestreo, no todos para tiempo de ejecución.

Recursos

• references/prompt-rules.md — prompts de imagen base + video
• references/pipeline.md — diseño de carpetas, ffmpeg, estrategia de muestreo
• scripts/video2dsprite.py — extraer, croma, normalizar, exportar

Relación con otras habilidades

• $generate2dsprite — pipeline principal de hojas (Codex y Grok cuando existe generación de imágenes)
• $generate2dmap — mapas; no se usa aquí
• $video2dsprite — exclusivo de Grok Build ruta de densificación de movimiento
• $game-asset-core / $game-animation-frames — bucle/prueba de inversión/leyes de movimiento y valores predeterminados listos para motor; seguir usando los scripts de esta habilidad para ejecución en sandbox (base magenta + croma), no un color de fondo libre