video2dsprite

Video2dsprite (Grok Build uniquement)

Convertir une image de personnage 2D de base en sprites d'animation denses à l'aide des outils vidéo natifs de Grok Build.

Environnement app-builder / Grok

Élément	Valeur
Répertoire de la compétence	.grok/skills/video2dsprite/
Scripts	python3 .grok/skills/video2dsprite/scripts/video2dsprite.py …
Outils vidéo	imagine_image_to_video — animer un file_path de base (vérifier sa présence)
Inspection	read_file sur les images fixes/ trames ; signaler les chemins pour les vidéos
Dépendances	ffmpeg + Pillow + numpy (préinstallés dans l'image app-builder)
Dossier de sortie	assets/sprites/video2dsprite/<name>/ sous /workspace
Par défaut	Préférer generate2dsprite pour les héros de production ; ceci est le chemin de mouvement plus dense

image fixe de base → imagine_image_to_video (mouvement sur place) → extraire trames → incrustation chroma → échantillonner/normaliser → bande / grille / GIF

Barrière de plateforme (lire d'abord)

Environnement d'exécution	Pris en charge ?
Grok Build (xAI)	Oui — nécessite un générateur d'image + un outil image→vidéo
Codex / Claude / autres agents	Non — ils ne disposent pas des outils vidéo Grok. Informez l'utilisateur que cette compétence est réservée à Grok Build et proposez $generate2dsprite à la place

Filtrez sur la capacité, pas sur le nom exact de l'outil. La génération d'image apparaît sous les noms imagine_text_to_image / imagine_image_to_image ; la vidéo sous imagine_image_to_video ou (ancien) generate_video. Utilisez la paire disponible dans votre liste d'outils. Arrêtez-vous et expliquez uniquement lorsque vous ne disposez d'aucun outil image→vidéo. N'inventez pas de mouvement avec des trames dessinées par code.

Cette compétence est un chemin optionnel de mouvement plus dense. Elle ne remplace pas $generate2dsprite :

Utiliser $generate2dsprite quand…	Utiliser $video2dsprite quand…
Feuilles de pixels nettes, grilles fixes, héros à identité critique	L'utilisateur souhaite des poses intermédiaires plus denses / des boucles à sensation plus fluide
Feuilles de corps d'attaque/incantation, packs d'accessoires, atlas de moteur	Expérimenter avec un mouvement de course/marche/idle basé sur vidéo
Défaut de production pour la plupart des sprites de jeu	L'utilisateur demande explicitement vidéo → trames → sprites

La vidéo adoucit les pixels, fait dériver l'identité et laisse des franges chroma. Toujours faire un contrôle qualité ; pour les héros de production, préférez $generate2dsprite sauf si l'utilisateur souhaite le rendu vidéo.

Paramètres

Déduire de la demande de l'utilisateur :

• subject : description du personnage / créature, ou chemin vers une image fixe existante
• action : run | walk | idle | attack | phrase de mouvement personnalisée
• view : généralement side (défilement latéral). topdown est plus difficile — avertir et garder la caméra verrouillée
• duration : 6 (par défaut) ou 10 secondes
• frame_counts : quels ensembles plus denses exporter, par défaut 8,16,24,48
• cell_size : cellule de sprite de sortie, par défaut 128
• anchor : feet (par défaut pour la locomotion latérale) | center
• bg : #FF00FF solide (obligatoire pour l'incrustation chroma)
• name : slug de sortie
• out_dir : dossier de travail (par défaut ./sprites/video2dsprite/<name>/ ou relatif au projet)

Règles de l'agent

1. Grok uniquement. Refuser sur les environnements d'exécution non-Grok avec une brève explication + l'alternative $generate2dsprite.
2. Image fixe → vidéo, jamais text-to-video seul. Préparer la trame 1 comme une image fixe propre avec imagine_text_to_image (à partir d'une invite, ou d'un file_path de référence). Ensuite appeler imagine_image_to_video avec le file_path de cette image fixe.
3. Mouvement sur place. Demander une course/marche sur place face à une direction fixe. Pas de panoramique de caméra, pas de défilement d'arrière-plan, pas de changement de scène. Le sujet reste globalement centré.
4. Arrière-plan magenta solide sur l'image de base et conservé dans l'invite vidéo (#FF00FF / magenta pur). Obligatoire pour l'incrustation chroma par remplissage.
5. Ne pas inventer d'art avec PIL/Canvas. L'art de base provient de imagine_text_to_image ou d'une image fixe utilisateur/locale. Les scripts ne font que post-traiter.
6. Ne pas mettre les sorties expérimentales dans le jeu sauf si l'utilisateur demande de les intégrer.
7. Préférer un cycle de locomotion pour une utilisation dans le jeu. Un échantillonnage dense sur un clip complet de 6s multi-cycles est acceptable pour les aperçus ; pour les feuilles de moteur, ré-échantillonner optionnellement un seul cycle (12–16 trames) après un contrôle qualité visuel.
8. Signaler les chemins absolus de la vidéo, des trames nettoyées, des bandes et des GIFs d'aperçu une fois terminé.

Flux de travail

1. Planifier

Choisir la plus petite exécution utile :

• Boucle de course/marche vue latérale → cette compétence
• Kit de héros multi-action → utiliser encore $generate2dsprite par action ; utiliser la vidéo uniquement pour la locomotion si demandé
• Packs d'effets / projectiles / accessoires → $generate2dsprite, pas la vidéo

Créer :

<out_dir>/
  base/
  video/
  frames-raw/
  frames-clean/
  sprite/          # ensemble par défaut de 8 trames + plus denses x16/x24/x48
  prompt-used.txt
  pipeline-meta.json
  README.txt

2. Construire l'image fixe de base

Options :

• A. Sprite existant : lire l'image, composer sur fond #FF00FF si nécessaire, puis passer ce chemin bac à sable à imagine_image_to_image / imagine_image_to_video
• B. Nouveau personnage : imagine_text_to_image avec fond magenta solide, corps complet, vue latérale, centré
• C. Correspondre à une référence : imagine_image_to_image avec le file_path de référence, en le déplaçant sur magenta et en préservant l'identité

Exigences de base :

• Corps complet visible, marge magenta généreuse
• Vue latérale pour la course/marche (profil ou 3/4 côté), pieds près du tiers inférieur
• Même style artistique que le reste du projet lorsqu'une référence existe
• Pas de texte, d'interface utilisateur, de filigrane ou de second personnage

Copier le file_path retourné et l'enregistrer sous <out_dir>/base/<name>-base.png ; conserver le file_path de base pour l'appel vidéo.

Écrire l'invite d'image exacte dans prompt-used.txt.

3. Animer avec imagine_image_to_video

Appeler imagine_image_to_video de Grok :

• chemin source : <file_path de l'image fixe de base> (chemin bac à sable retourné par T2I / I2I)
• duration : 6 (par défaut) ou 10
• resolution_name : 480p sauf si l'utilisateur demande 720p
• prompt : un court plan au présent (voir references/prompt-rules.md)

Contraintes de mouvement obligatoires dans l'invite :

• Le sujet court/marche sur place (style tapis roulant)
• Caméra verrouillée — pas de panoramique, zoom ou orbite
• L'arrière-plan reste plat magenta solide
• Identité, costume, palette stables pour tout le plan
• Action continue unique uniquement

Copier le file_path vidéo retourné vers <out_dir>/video/<name>-<duration>s.mp4.

Si les outils vidéo ne sont pas disponibles, arrêter (barrière de plateforme).

4. Extraire + incrustation chroma + échantillonnage (script local)

Exécuter le processeur (ffmpeg + Pillow + numpy) :

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

Notes :

• --fps 0 = extraire chaque trame décodée (utiliser les fps source)
• Remplissage magenta depuis les coins + despill
• Échantillonnage uniforme pour chaque compte dans --frame-counts
• Cellules normalisées aux pieds, bande horizontale, grille, GIF de boucle par compte

Optionnel : seulement ré-échantillonner des ensembles plus denses à partir de trames nettoyées existantes :

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. Contrôle qualité (QC)

Vérifier visuellement :

• Le GIF d'aperçu boucle sans sauts importants
• Magenta disparu (pas de blocs roses solides) ; franges acceptables ou re-incrustation
• Les pieds restent sur une ligne de base stable (pas de saut dû à un mauvais recadrage)
• Identité globalement stable (visage/vêtements ne se transforment pas à chaque trame)
• L'action est sur place (ne glisse pas hors du cadre)
• Pour une utilisation dans le jeu : choisir un compte (souvent 16 ou 24) ou couper un vrai cycle

Si l'identité dérive fortement ou si les pixels sont trop mous, revenir à $generate2dsprite pour les feuilles de production et conserver l'ensemble vidéo comme référence de mouvement uniquement.

6. Livrer

Signaler les chemins uniquement (sauf si l'utilisateur demande de les intégrer dans un jeu) :

• Vidéo : video/*.mp4
• Sprites denses : sprite/x16|x24|x48/
• Bandes / grilles / GIFs : sprite/run-strip-N.png, run-grid-N.png, run-preview-N.gif
• Métadonnées : pipeline-meta.json

Ne pas modifier le code du jeu sauf si demandé.

Valeurs par défaut

• Durée : 6s
• Action : course latérale sur place, face à droite
• Comptes d'exportation : 8, 16, 24, 48
• Cellule : 128², hauteur du corps ~100, pieds à y≈118
• Arrière-plan : #FF00FF
• Préférer imagine_image_to_video mono-actif plutôt que multi-référence (composer multi-référence avec imagine_text_to_image d'abord si nécessaire)

Compromis (informer l'utilisateur une fois)

Avantages : intermédiaires plus denses → souvent plus fluides que 4–8 poses générées discrètes.
Inconvénients : pixels plus mous, dérive d'identité, franges chroma, clips multi-cycles de 6s ne sont pas une seule boucle parfaite, ressources plus lourdes.
Règle empirique : 8→16→24 gagne généralement en fluidité ; 48 a souvent des rendements décroissants ; 145 trames brutes sont destinées à l'échantillonnage, pas toutes à l'exécution.

Ressources

• references/prompt-rules.md — invites d'image fixe de base + vidéo
• references/pipeline.md — disposition des dossiers, ffmpeg, stratégie d'échantillonnage
• scripts/video2dsprite.py — extraction, incrustation chroma, normalisation, exportation

Relation avec les autres compétences

• $generate2dsprite — pipeline principal de feuilles (Codex + Grok lorsque la génération d'image existe)
• $generate2dmap — cartes ; non utilisé ici
• $video2dsprite — exclusif Grok Build chemin de densification de mouvement
• $game-asset-core / $game-animation-frames — lois de boucle/test de retournement/mouvement et valeurs par défaut prêtes pour le moteur ; utiliser toujours les scripts de cette compétence pour l'exécution en bac à sable (base magenta + incrustation chroma), pas une couleur d'arrière-plan libre.