Que fait GénérerSprite2D ?
Utilisez cette compétence pour des assets de sprites ou d'animations 2D autonomes dans l'environnement app-builder sandbox (TanStack Start + jeux navigateur).
Lorsqu'un jeu ou prototype jouable plus vaste nécessite des sprites, utilisez cette compétence pour générer les assets visibles et conservez l'assemblage runtime / jeu séparé (intégration dans Phaser / Canvas / DOM après export). Ne remplacez pas les assets de sprites demandés par des placeholders codés.
Environnement App-builder / Grok
| Élément | Valeur |
|---|---|
| Répertoire de la compétence | .grok/skills/generate2dsprite/ |
| Scripts | python3 .grok/skills/generate2dsprite/scripts/<script>.py … |
| Outils d'image | imagine_text_to_image / imagine_image_to_image (basé sur les chemins ; voir la compétence imagine pour l'art du prompt) |
| Inspection des images | read_file sur le chemin du PNG (pas Codex view_image) |
| Chemin de l'image générée | imagine_text_to_image retourne un file_path du bac à sable ; copiez ce chemin dans votre répertoire d'exécution avant le traitement |
| Dépendances Python | Pillow + numpy (préinstallées dans l'image) |
| Répertoire de sortie | Préférez assets/sprites/<nom>/ sous /workspace pour que l'application puisse les importer |
| Cible du moteur | Navigateur : Canvas 2D, Phaser, ou DOM/<img> — pas Godot/Unity sauf demande explicite |
Compétences associées : imagine (utilisation des outils d'image), game-asset-core (+
game-animation-frames / game-character-consistency pour le contrôle qualité et les paramètres par défaut prêts pour le moteur), generate2dmap (cartes / accessoires), video2dsprite (mouvement plus dense via imagine_image_to_video), building-games (boucle de jeu / intégration).
Paramètres
Déduisez-les de la demande utilisateur :
asset_type:player|npc|creature|character|spell|projectile|impact|prop|summon|fxaction:single|idle|cast|attack|shoot|jump|hurt|combat|walk|run|hover|charge|projectile|impact|explode|deathview:topdown|side|3/4sheet:auto|2x2|2x3|2x4|3x3|3x4|4x4|5x5|custom_grid|strip_1x3|strip_1x4frames:autoou nombre explicitebundle:single_asset|unit_bundle|spell_bundle|combat_bundle|line_bundle|hero_action_bundle|engine_atlaseffect_policy:all|largestanchor:center|bottom|feetmargin:tight|normal|safeart_style: pixel_art | clean_hd | pixel_inspired | retro_pixel | map_style | project-nativereference:none|attached_image|generated_image|local_filelayout_guide:none|optional|recommendedprompt: le thème ou la direction visuelle de l'utilisateurrole: uniquement lorsque l'asset est clairement un rôle de PNJname: slug de sortie optionnel
Consultez references/modes.md lorsque la demande est ambiguë.
Règles de l'agent
- Décidez vous-même du plan d'asset. N'obligez pas l'utilisateur à préciser la taille de la feuille, le nombre de frames ou la structure du bundle lorsque la demande les implique déjà.
- Ne regroupez pas des actions non liées dans une seule feuille générée brute juste pour satisfaire un format
4x4,5x5ou atlas moteur personnalisé. Une feuille générée brute doit représenter une famille d'actions, une séquence continue, une feuille de déplacement directionnel canonique ou un pack d'accessoires / assets. - Pour les héros contrôlables, personnages principaux et assets joueurs de grande valeur avec plusieurs actions, générez d'abord des feuilles de grille par action séparées, contrôlez la qualité de chaque action, puis assemblez de manière déterministe l'atlas moteur demandé uniquement après que les grilles aient passé la revue visuelle.
- Pour les héros contrôlables, personnages principaux et actions corporelles de grande valeur, définissez par défaut les feuilles d'attaque / tir / incantation sur le corps uniquement. N'incluez pas de grands arcs de coupure, flashs de bouche, projectiles, rafales d'impact, poussières, longues traînées ou FX larges détachés dans la feuille corporelle. Générez-les comme des feuilles
fx,projectileouimpactséparées et superposez-les dans le jeu. - N'incluez des FX d'attaque larges dans la même feuille corporelle brute que lorsque le runtime cible prend explicitement en charge des cellules par action plus larges avec métadonnées d'origine / ancrage par action. Sinon, une boîte englobante FX large forcera le corps à rétrécir dans la cellule fixe.
- Écrivez vous-même le prompt artistique. Ne vous basez pas par défaut sur le script de construction de prompt.
- Utilisez
imagine_text_to_imageintégré pour chaque image brute. - Ne créez pas d'art sprite brut avec Three.js, Canvas, SVG, dessin HTML/CSS, dessin PIL de formes, géométrie procédurale, primitives de placeholder, ou captures d'écran rendues par code. Le code runtime peut afficher les assets finis générés, et les scripts peuvent créer des guides de mise en page ou post-traiter des images générées, mais l'art sprite demandé doit provenir de
imagine_text_to_imageintégré. - Lorsque l'utilisateur fournit ou implique une référence visuelle, passez le
file_pathdans le bac à sable de cette référence àimagine_image_to_image(l'outil lit le fichier). Lisez aussi la référence locale avecread_filepour pouvoir la voir ; un chemin mentionné uniquement dans le prompt n'est pas une entrée visuelle. - N'imposez pas le pixel art lorsque l'asset est un accessoire de carte pour
$generate2dmapou lorsque l'utilisateur / le projet demande un style différent. Faites correspondre le style de la carte ou de la référence en premier. - Utilisez le script uniquement comme processeur déterministe : nettoyage magenta, découpage de frames, filtrage de composants, mise à l'échelle, alignement, métadonnées QC, export de feuille transparente et export GIF.
- N'utilisez pas les scripts pour générer le prompt créatif de l'image. Si une commande de construction de prompt héritée existe, traitez-la comme une compatibilité historique uniquement, pas comme le flux de travail normal de la compétence.
- Les guides de mise en page sont autorisés uniquement comme références géométriques déterministes pour la génération d'images. Ils peuvent montrer le nombre d'emplacements, l'espacement, le centrage et le padding de sécurité, mais ne doivent jamais définir la direction artistique créative.
- Traitez les drapeaux de script comme des primitives d'exécution choisies par l'agent, pas comme un flux de travail codé en dur orienté utilisateur.
- Si une feuille générée touche les bords des cellules, dérive en échelle, ou brise une boucle de projectile / impact, soit retraitez-la avec de meilleurs paramètres de primitives, soit régénérez la feuille brute.
- N'utilisez pas de feuilles brutes à une seule ligne comme
1x4,1x6,1x8ou1xNpour les personnages, joueurs, héros contrôlables, créatures, PNJ, ennemis, invocations, accessoires animés ou tout asset où un corps / sujet doit rester centré. La génération brute à une seule ligne a trop tendance à dériver horizontalement et à recadrer de manière incohérente. - Pour les assets corporels animés, utilisez une grille multi-lignes par défaut : 4 frames ->
2x2, 6 frames ->2x3, 8 frames ->2x4, 9 frames ->3x3, 12 frames ->3x4ou4x3, 16 frames ->4x4. - Si un moteur de jeu a besoin d'une bande finale à une seule ligne ou d'un atlas mixte, générez et contrôlez d'abord l'action comme une grille multi-lignes, puis assemblez la bande / l'atlas de livraison de manière déterministe.
- Dans chaque prompt de grille corporelle animée, exigez que le corps du sujet reste centré dans chaque cellule, corps entier dans la zone de sécurité centrale de 60 % à 70 %, échelle cohérente entre les cellules, ligne d'ancrage stable des pieds / bas lorsque applicable, et aucun membres, armes, cheveux, capes, poussières, flashs de bouche ou FX détachés ne traversant les bords des cellules.
- Pour les prompts de corps d'attaque de héros, exigez explicitement que la hauteur du corps et l'échelle du corps correspondent aux feuilles d'idle / course acceptées, ancre stable des pieds / bas, arme suffisamment proche pour ne pas élargir la boîte englobante du corps, et pas d'arc de coupure détaché ou d'effet d'attaque en espace écran.
- Pour les packs d'accessoires de carte, classez les accessoires avant de choisir une grille. Les packs carrés
2x2,3x3et4x4sont réservés aux accessoires compacts. Ne mettez pas de plates-formes, sols, ponts, murs, échelles, portes, portails, longs dangers, objets larges / hauts, objets porteurs de collision, ou pièces de tileset / bande dans des packs d'accessoires carrés ; utilisez un par un, des bandes1x3/1x4, des cellules larges personnalisées, ou un atlas de type tileset. - Maintenez la règle du fond
#FF00FFsolide sauf si l'utilisateur souhaite explicitement un flux de traitement différent.
Flux de travail
1. Déduire le plan d'asset
Choisissez la plus petite sortie utile.
Exemples :
- héros contrôlable avec quatre directions ->
player+player_sheet - héros contrôlable vue de côté avec idle / course / tir / saut ->
player+hero_action_bundle- feuille de grille idle, généralement
2x2pour 4 frames - feuille de grille course, généralement
2x2ou2x3selon le nombre de frames nécessaire - feuille de grille tir avec corps / arme uniquement, généralement
2x2 - feuille de grille saut, généralement
2x2 - projectile / flash de bouche en tant qu'assets séparés si nécessaire
- atlas moteur assemblé optionnel après contrôle qualité par action
- feuille de grille idle, généralement
- héros contrôlable vue de côté avec attaque au corps à corps ->
player+hero_action_bundle- feuille de grille corporelle d'attaque, généralement
2x2ou2x3, corps uniquement - arc de coupure / traînée d'arme comme feuille
fxséparée lorsque l'attaque a besoin d'un effet visuel large - étincelle d'impact comme feuille
impactséparée lorsque les coups ont besoin de retour
- feuille de grille corporelle d'attaque, généralement
- PNJ soigneur monde ouvert ->
npc+single_assetouunit_bundle - boucle d'idle de grand boss ->
creature+idle+3x3 - sorcier lançant un orbe magique ->
spell_bundle- feuille d'incantation du lanceur
- boucle de projectile
- rafale d'impact
- demande de ligne de monstres ->
line_bundle- planifiez 1 à 3 formes
- par forme, créez les feuilles dont la demande a réellement besoin
2. Écrire le prompt manuellement
Utilisez references/prompt-rules.md.
Choisissez art_style avant d'écrire le prompt :
- Utilisez
pixel_artouretro_pixelpour les sprites classiques, les acteurs RPG 16 bits et les demandes qui exigent explicitement du pixel art. - Utilisez
clean_hdpour les accessoires de carte ou les assets destinés à correspondre à des cartes HD peintes à la main et propres. - Utilisez
pixel_inspireduniquement lorsque l'utilisateur souhaite un aspect proche du pixel sans le côté rétro grossier. - Utilisez
map_styleouproject-nativelorsqu'une carte, un jeu ou une référence existante doit définir le style.
Si une référence est impliquée :
- Intégrez la référence dans l'appel : passez son
file_pathdu bac à sable àimagine_image_to_image— ou la liste de chemins àimagine_reference_to_imagepour 2+ références (les images générées ont déjà unfile_path; les fichiers locaux utilisent leur chemin du bac à sable). Lisez aussi les références locales avecread_filepour pouvoir les voir. - Indiquez explicitement le rôle de la référence : préserver l'identité / le style, créer une feuille d'animation pour le même sujet, créer une évolution / variante, ou dériver un accessoire / FX correspondant.
- Préservez les marqueurs d'identité stables de la référence : silhouette, palette, traits du visage / des yeux, marques de costume, accessoires majeurs et langage des matériaux.
- Seule l'action ou l'évolution demandée peut changer. Ne reconcevez pas le sujet sauf demande explicite de l'utilisateur.
- Exigez toujours une forme de feuille exacte, un fond magenta solide, un confinement des frames et la même échelle entre les frames.
Gardez les parties strictes :
- fond
#FF00FFsolide - forme de feuille exacte
- même identité de personnage ou d'asset entre les frames
- même boîte englobante et même échelle en pixels entre les frames
- confinement explicite : rien ne peut traverser les bords des cellules
Garde-fou de l'atlas d'actions mixtes :
- Ne demandez pas à
imagine_text_to_imagede générer des lignes d'actions non liées dans une seule feuille brute, commeligne 1 idle, ligne 2 course, ligne 3 tir, ligne 4 saut, pour un héros contrôlable ou un personnage principal. - Ne demandez pas à
imagine_text_to_imagede générer des bandes d'action brutes à une seule ligne comme1x4 idle,1x4 course,1x4 tirou1x4 sautpour un héros contrôlable, un personnage, une créature, un PNJ, un ennemi, une invocation ou un accessoire animé. - Si un moteur a besoin d'un atlas combiné
4x4,5x5personnalisé, ou d'un format de livraison en bande de lignes, générez les grilles d'actions séparément, traitez-les et contrôlez-les séparément, puis assemblez l'atlas de livraison de manière déterministe. - Les exceptions sont les feuilles de déplacement directionnel canoniques, une séquence d'action longue continue, les packs d'accessoires, les atlas de type tileset et les feuilles de combat ennemi compactes à faible enjeu. Celles-ci nécessitent néanmoins un prompt cohérent et un contrôle visuel.
- Gardez les projectiles, flashs de bouche, impacts, traînées de poussière et FX détachés dans des feuilles séparées, sauf s'ils font intentionnellement partie de la même silhouette d'action et restent étroitement attachés.
- Pour les héros contrôlables et les personnages principaux, « étroitement attaché » ne suffit pas lorsque l'effet rend la boîte englobante de l'action beaucoup plus large ou plus haute que l'idle / la course. Séparez les arcs de coupure larges, les flashs de bouche, les longues traînées d'arme, les nuages de poussière et les rafales d'impact dans des feuilles FX séparées par défaut.
Garde-fou de la grille corporelle animée :
- Les
1x4et autres feuilles brutes à une seule ligne ne sont pas des valeurs par défaut valides pour les corps animés. Cela inclut les joueurs, héros contrôlables, créatures, PNJ, ennemis, invocations, accessoires animés et actions de combat attachées au corps. - Utilisez
2x2pour les actions corporelles de 4 frames. C'est la valeur par défaut pour les actions idle, attaque courte, corps de tir, saut, blessure, survol et course / marche compacte en vue de côté. - Utilisez
2x3pour les actions corporelles de 6 frames telles que l'incantation, l'attaque, l'invocation, la course, la charge ou la transformation. - Utilisez
2x4,3x3,3x4ou4x4pour les actions corporelles plus longues. Préférez une grille compacte à une longue ligne. - Pour la marche en vue de dessus à 4 directions,
4x4peut rester une forme de génération brute car il s'agit d'une feuille de déplacement directionnel canonique, et non de quatre lignes d'actions non liées. - Si le runtime final a besoin d'une bande de lignes, assemblez-la après le contrôle qualité à partir des frames de la grille multi-lignes traitée.
- Gardez le personnage centré dans chaque cellule. La ligne médiane du corps doit rester près du centre de la cellule, l'ancre des pieds / bas doit rester sur la même position y lorsque visible, et le sujet ne doit occuper que la zone de sécurité centrale avec un padding magenta généreux.
- Pour les actions corporelles d'attaque, tir, incantation, charge, etc., la hauteur du corps doit rester proche de la hauteur du corps idle / course acceptée. Si un runtime à cellules fixes est utilisé, rejetez la sortie de l'action corporelle lorsque le corps apparaît environ 10 à 15 % plus petit que l'idle / course, même si
edge_touch_framesest vide.
Garde-fou du pack d'accessoires de carte :
- Utilisez des packs d'accessoires bruts carrés
2x2,3x3et4x4uniquement pour les accessoires compacts tels que rochers, arbustes, barils, caisses, lampes, petits panneaux, pots, débris et petits ornements. - N'utilisez pas de packs d'accessoires carrés pour des objets de carte larges ou critiques pour les collisions : sols, plates-formes, corniches, morceaux de terrain, ponts, sections de mur, échelles, routes, rails, tuyaux, pièges à pointes longs, portes, portails, bâtiments, grands arbres, points de contrôle, sorties ou pads de construction.
- Utilisez une génération un par un pour les accessoires uniques, grands, importants, hauts, irréguliers ou alignés aux collisions.
- Utilisez des bandes
1x3ou1x4pour les assets de plate-forme / sol répétables, avec capuchon gauche, milieu répété, capuchon droit, et variante optionnelle de pente / coin / extrémité. - Utilisez des cellules larges personnalisées pour plusieurs petites variantes avec pondération de hauteur constante.
- Préférez un atlas de type tileset lorsque l'accessoire est destiné à un éditeur de niveau ou à une grille de carte.
- N'utilisez jamais de packing automatisé de type TexturePacker ou RectBin pour des packs d'accessoires de carte de grande valeur ; utilisez un placement déterministe explicite.
Garde-feu de l'atlas moteur :
- Pour les bundles
hero_action_bundle: générez chaque grille d'action séparément, contrôle qualité chaque grille, puis assemblez l'atlas de livraison uniquement après que toutes les grilles aient passé le contrôle visuel. - Pour les bundles
engine_atlasspécifiques à un moteur : comprenez d'abord la disposition de l'atlas du moteur cible. Vérifiez si le moteur utilise des cellules de taille fixe, des cellules par action ou une disposition de type spritesheet. Vérifiez si le moteur prend en charge les métadonnées d'ancrage par action ou uniquement un origine globale. Choisissez la disposition de la feuille générée qui correspond le mieux à ces exigences, puis assemblez l'atlas moteur final en conséquence. - Lorsque vous assemblez un atlas moteur à partir de feuilles de grille contrôlées, écrivez vous-même la transformation déterministe ; n'appelez pas de logiciel tiers ou de service externe dans la boîte. Utilisez la transformation d'image Python (Pillow / numpy) uniquement lorsque vous recadrez, mettez à l'échelle ou organisez des frames.
Scripts
Les scripts sont des exécuteurs déterministes, pas des sources d'art. Au moment de l'écriture, le répertoire scripts/ contient :
magenta_cleanup.py– Nettoyage du fond magenta + option de transparence alpha.split_frames.py– Découpage de feuilles de sprites en frames individuelles.sheet_grid.py– Assemblage de frames individuelles en feuille de grille.magenta_process.py– Nettoyage magenta pour les atlases assemblés.extract_action.py– Filtrage par composant (e.g., retirer les arcs d'attaque d'une feuille de corps).sheet_merge.py– Assemblage de feuilles à partir de frames individuelles traitées.gif_export.py– Export GIF animé à partir de frames ou de feuilles.qc_report.py– Métadonnées de rapport de contrôle qualité (nombre de frames, zone de sécurité, boîte englobante).
Directives de sortie
- Affichez l'image générée la plus importante en premier (en utilisant
read_filesur son chemin). - Lorsqu'un rapport de contrôle qualité existe, affichez-le ensuite pour confirmer que les frames sont dans la zone de sécurité.
- Annoncez le nombre de fichiers d'assets finaux et leur emplacement (chemin absolu du bac à sable).
- Incluez un exemple d'import de feuille de sprites dans le moteur cible si la demande utilisateur fait référence à un moteur spécifique.
Exemples de prompt
Le modèle de prompt par défaut contient :
Identité : [brève description de l'asset] Taille : [taille de frame en pixels]×[taille de frame en pixels] chacun dans une grille [rows]×[cols] sur fond magenta solide
#FF00FFExigences : sujet centré dans la zone de sécurité centrale de 60 % ; rien ne traverse les bords des cellules ; palette cohérente, échelle et hauteur de ligne d'ancrage entre les images ; arrière-plan magenta#FF00FFsolide dans les espaces vides Style : [art_style] – [directives spécifiques au style]